omnigraph/docs/releases/v0.4.2.md

# Omnigraph v0.4.2

Omnigraph v0.4.2 is a concurrency, admission-control, and release-hygiene
release. It removes the server-global write lock, lets disjoint writers make
progress concurrently, adds per-actor admission limits, hardens branch and
mutation races with snapshot-isolation fences, and documents the release in
public open-source terms.

## Highlights

- **Unlocked server engine handle**: the HTTP server now holds the engine behind
  a shared handle instead of a server-global write lock. Concurrent handlers can
  call engine APIs directly while the engine serializes only the resources that
  actually conflict.
- **Engine-owned writer queues**: same `(table, branch)` writers are serialized
  by per-table writer queues inside the engine, while disjoint table/branch
  writes can run concurrently. This narrows contention without relying on route
  handlers to know storage-level ordering rules.
- **Per-actor admission control**: mutating HTTP handlers are gated by a
  `WorkloadController` with per-actor in-flight request and estimated-byte
  budgets. Rejections use HTTP 429 with `code: too_many_requests` and a
  `Retry-After` header, so noisy actors back off without blocking unrelated
  actors.
- **Admission coverage for all mutating handlers**: `/change`, `/ingest`,
  `/schema/apply`, branch create/delete, and branch merge now flow through the
  admission controller. Read-only endpoints are not admission-gated.
- **Op-kind-aware version checks**: mutation commit-time drift checks distinguish
  append-like inserts from strict update/delete work. Inserts remain permissive
  enough for safe concurrent append patterns; updates and deletes get stricter
  stale-view rejection.
- **Read-time drift checks for strict mutations**: staged mutations compare the
  manifest pin captured when the query opened against the manifest snapshot
  captured under table-queue ownership. If a concurrent writer moved the table
  after the query read, the stale writer returns a structured
  `manifest_conflict` 409 instead of staging work computed against an old
  snapshot.
- **Inline-delete recovery coverage**: delete-only mutations still use Lance's
  inline delete path, but their recovery sidecar is now written before the
  manifest-version rejection path can return. If a delete moves Lance HEAD and a
  concurrent manifest update makes the query stale, the next read-write open can
  roll the residual back rather than leaving a head-ahead-of-manifest table.
- **Branch-operation race hardening**: branch creation and branch merge avoid
  coordinator swap-restore races that could expose the wrong active branch to
  concurrent work. Concurrent branch merges are serialized by a merge mutex.
- **Branch-merge target revalidation**: merges re-check target table versions
  after acquiring target write queues. A stale merge plan returns a structured
  conflict instead of overwriting concurrent target-branch changes or adopting a
  source table over newly appended target rows.
- **Schema refresh deadlock fix**: recovery refresh releases the write guard
  before schema reload, preventing a refresh/schema-apply deadlock.
- **Lean admission API**: removed the unused global rewrite admission pool,
  `service_unavailable` error variant, related 503 documentation, and benchmark
  flag. The public server surface now reflects only admission behavior that is
  wired to handlers.
- **Open-source release hygiene**: this release adds guidance for public-facing
  documentation, release notes, and version bumps. Release docs now avoid
  private issue tracker references and use stable public descriptions instead.

## Behavior changes

- Disjoint mutating HTTP requests can now make progress concurrently instead of
  queueing behind one process-wide engine write lock.
- Mutating handlers may return HTTP 429 when an actor exceeds per-actor in-flight
  or estimated-byte budgets. Clients should respect `Retry-After` and retry
  later.
- Concurrent update/delete and merge races now return structured
  `manifest_conflict` 409 responses in more stale-view cases instead of relying
  on later publisher-CAS detection or allowing a stale plan to proceed.
- Concurrent branch merge × change on the same target branch may return either
  success or a clean 409 conflict, depending on which operation wins the queue.
- `OMNIGRAPH_GLOBAL_REWRITE_MAX` is no longer recognized. Remove it from
  deployment manifests; use the per-actor in-flight and byte-budget admission
  settings for the currently wired server controls.

## Upgrade Notes

- No repository migration is required. Existing v0.4.1 repos can be opened
  directly with v0.4.2.
- Clients should treat `manifest_conflict` 409 responses as retryable stale-view
  conflicts. This was already the documented contract, but this release uses it
  in more concurrent-write paths.
- Clients should handle HTTP 429 from every mutating endpoint, not only
  `/change`. Honor the `Retry-After` header.
- Operators should remove stale references to global rewrite admission and 503
  rewrite-pool exhaustion from local runbooks.
- If you maintain public docs or release notes, use public identifiers and
  user-facing descriptions rather than private tracker IDs.

## Tests added or strengthened

- Regression tests for update read-your-writes under in-process concurrency.
- HTTP tests for same-key insert snapshots, disjoint `/change` concurrency, and
  `/ingest` admission 429 + `Retry-After`.
- Branch-operation regression tests for branch-create swap-restore races,
  concurrent `/change` + branch-merge interleavings, branch-merge swap-restore
  races, branch-op matrix coverage, and post-reopen consistency.
- Failpoint-backed regression coverage for inline-delete recovery sidecar
  creation before version-mismatch rejection.
- Admission tests use injectable `WorkloadController` state instead of mutating
  process environment.

## Included Changes

- Shared server engine state and per-actor admission on mutating endpoints.
- Per-(table, branch) writer queues and op-kind-aware manifest drift checks.
- Strict read-time version checks for updates/deletes.
- Branch create/merge race hardening and branch-merge target snapshot
  revalidation under queue ownership.
- Retry-after support for admission rejections and OpenAPI updates for reachable
  429 responses.
- Actor-isolation benchmark harness updates for the current admission controller.
- Removal of the unwired global rewrite admission / 503 server surface.
- Version bump to `0.4.2` across workspace crates, `Cargo.lock`, and
  `openapi.json`.
- Public release-note cleanup and new OSS best-practice guidance in `AGENTS.md`.