release: prepare omnigraph 0.4.2

AGENTS.md

@@ -16,7 +16,7 @@ Tools that support `@`-imports (Claude Code) auto-include all three files via th
 
 `CLAUDE.md` is a symlink to this file — there is exactly one source of truth. Edit `AGENTS.md`.
 
-**Version surveyed:** 0.4.1
+**Version surveyed:** 0.4.2
 **Workspace crates:** `omnigraph-compiler`, `omnigraph` (engine), `omnigraph-cli`, `omnigraph-server`
 **Storage substrate:** Lance 4.x (columnar, versioned, branchable)
 **License:** MIT
@@ -232,12 +232,15 @@ Rules:
 
 1. **Update in the same PR.** New endpoint, query function, CLI flag, env var, constant, schema construct, or invariant: update both the source code and the doc in the same change. Never split documentation drift into a follow-up.
 2. **Bump version on release.** When a release boundary crosses (e.g. v0.3.1 → v0.3.2), update the version line at the top of this file and add a `docs/releases/<version>.md` describing the user-visible delta. Update [docs/architecture.md](docs/architecture.md) only if the architecture itself changed.
-3. **Don't lie.** If a section becomes wrong but you can't rewrite it fully right now, replace the wrong line with `*(stale — needs update after <change>)*` rather than leaving silently incorrect text. Then fix it ASAP.
-4. **Re-verify before recommending.** If you cite a flag, env var, endpoint, or constant to the user or in code, grep for it in source first. Memory and docs go stale; the code is authoritative.
-5. **Keep AGENTS.md a map, not an encyclopedia.** New deep content goes into `docs/`. Add an entry to "Where to find each topic" instead of pasting prose into this file. The "Always-on rules" section is the exception — it's for invariants that should always be in scope.
-6. **Re-read on schema/query/IR changes.** Edits to `schema.pest`, `query.pest`, `ir/lower.rs`, `query/typecheck.rs`, or `query/lint.rs` should trigger a re-read of [docs/schema-language.md](docs/schema-language.md), [docs/query-language.md](docs/query-language.md), and [docs/execution.md](docs/execution.md) to confirm they still describe reality.
-7. **Always make smaller commits.** Each commit does one thing, compiles, and passes tests; mechanical refactors land separately from the behavior changes they enable.
-8. **Test-first for bug fixes.** When fixing an identified bug, write a regression test that reproduces the failure first. Confirm it fails against the current code with the predicted symptom (not an unrelated error). Then land the fix in a separate commit and confirm the test turns green. The test commit lands just before the fix commit so the red → green pair is visible in `git log` and a reviewer can check out the test commit alone and reproduce the failure.
-9. **Correct by design over symptomatic patches.** When a bug surfaces, identify the root cause and make the fix correct by construction. Don't patch the symptom. If the design admits the bug class, the fix is to close the class, not to add a guard around the latest instance. A symptomatic patch is acceptable only as a stop-gap, with an explicit note in the commit message and a follow-up issue tracking the design fix.
+3. **Write OSS-facing release notes.** Release docs are public project history. Describe capabilities, behavior changes, breaking changes, upgrade notes, and user impact; do not reference private ticket systems, internal codenames, or planning shorthand that an outside contributor cannot inspect.
+4. **Keep versioning coherent.** A release bump must update every published crate manifest, local path dependency constraint, `Cargo.lock`, generated API metadata such as `openapi.json`, and this file's surveyed version. Do not leave mixed package versions unless the release plan explicitly calls for them.
+5. **Keep docs audience-neutral.** Prefer stable public identifiers (versions, PR numbers, public issue links, crate names, endpoint names) over organization-specific labels. If internal context is useful for maintainers, translate it into a durable public rationale before committing it.
+6. **Don't lie.** If a section becomes wrong but you can't rewrite it fully right now, replace the wrong line with `*(stale — needs update after <change>)*` rather than leaving silently incorrect text. Then fix it ASAP.
+7. **Re-verify before recommending.** If you cite a flag, env var, endpoint, or constant to the user or in code, grep for it in source first. Memory and docs go stale; the code is authoritative.
+8. **Keep AGENTS.md a map, not an encyclopedia.** New deep content goes into `docs/`. Add an entry to "Where to find each topic" instead of pasting prose into this file. The "Always-on rules" section is the exception — it's for invariants that should always be in scope.
+9. **Re-read on schema/query/IR changes.** Edits to `schema.pest`, `query.pest`, `ir/lower.rs`, `query/typecheck.rs`, or `query/lint.rs` should trigger a re-read of [docs/schema-language.md](docs/schema-language.md), [docs/query-language.md](docs/query-language.md), and [docs/execution.md](docs/execution.md) to confirm they still describe reality.
+10. **Always make smaller commits.** Each commit does one thing, compiles, and passes tests; mechanical refactors land separately from the behavior changes they enable.
+11. **Test-first for bug fixes.** When fixing an identified bug, write a regression test that reproduces the failure first. Confirm it fails against the current code with the predicted symptom (not an unrelated error). Then land the fix in a separate commit and confirm the test turns green. The test commit lands just before the fix commit so the red → green pair is visible in `git log` and a reviewer can check out the test commit alone and reproduce the failure.
+12. **Correct by design over symptomatic patches.** When a bug surfaces, identify the root cause and make the fix correct by construction. Don't patch the symptom. If the design admits the bug class, the fix is to close the class, not to add a guard around the latest instance. A symptomatic patch is acceptable only as a stop-gap, with an explicit note in the commit message and a follow-up issue tracking the design fix.
 
 CI check: `scripts/check-agents-md.sh` verifies that every `docs/*.md` link in this file resolves and that every doc in the canonical set is linked. Run it locally before opening a PR if you've moved or renamed docs.

Cargo.lock

@@ -4596,7 +4596,7 @@ dependencies = [
 
 [[package]]
 name = "omnigraph-cli"
-version = "0.4.1"
+version = "0.4.2"
 dependencies = [
  "assert_cmd",
  "clap",
@@ -4616,7 +4616,7 @@ dependencies = [
 
 [[package]]
 name = "omnigraph-compiler"
-version = "0.4.1"
+version = "0.4.2"
 dependencies = [
  "ahash",
  "arrow-array",
@@ -4637,7 +4637,7 @@ dependencies = [
 
 [[package]]
 name = "omnigraph-engine"
-version = "0.4.1"
+version = "0.4.2"
 dependencies = [
  "arc-swap",
  "arrow-array",
@@ -4677,7 +4677,7 @@ dependencies = [
 
 [[package]]
 name = "omnigraph-server"
-version = "0.4.1"
+version = "0.4.2"
 dependencies = [
  "async-trait",
  "aws-config",

crates/omnigraph-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "omnigraph-cli"
-version = "0.4.1"
+version = "0.4.2"
 edition = "2024"
 description = "CLI for the Omnigraph graph database."
 license = "MIT"
@@ -13,9 +13,9 @@ name = "omnigraph"
 path = "src/main.rs"
 
 [dependencies]
-omnigraph = { package = "omnigraph-engine", path = "../omnigraph", version = "0.4.1" }
-omnigraph-compiler = { path = "../omnigraph-compiler", version = "0.4.1" }
-omnigraph-server = { path = "../omnigraph-server", version = "0.4.1" }
+omnigraph = { package = "omnigraph-engine", path = "../omnigraph", version = "0.4.2" }
+omnigraph-compiler = { path = "../omnigraph-compiler", version = "0.4.2" }
+omnigraph-server = { path = "../omnigraph-server", version = "0.4.2" }
 clap = { workspace = true }
 color-eyre = { workspace = true }
 serde = { workspace = true }

crates/omnigraph-compiler/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "omnigraph-compiler"
-version = "0.4.1"
+version = "0.4.2"
 edition = "2024"
 description = "Schema/query compiler for Omnigraph. Zero Lance dependency."
 license = "MIT"

crates/omnigraph-server/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "omnigraph-server"
-version = "0.4.1"
+version = "0.4.2"
 edition = "2024"
 description = "HTTP server for the Omnigraph graph database."
 license = "MIT"
@@ -19,8 +19,8 @@ default = []
 aws = ["dep:aws-config", "dep:aws-sdk-secretsmanager"]
 
 [dependencies]
-omnigraph = { package = "omnigraph-engine", path = "../omnigraph", version = "0.4.1" }
-omnigraph-compiler = { path = "../omnigraph-compiler", version = "0.4.1" }
+omnigraph = { package = "omnigraph-engine", path = "../omnigraph", version = "0.4.2" }
+omnigraph-compiler = { path = "../omnigraph-compiler", version = "0.4.2" }
 axum = { workspace = true }
 clap = { workspace = true }
 color-eyre = { workspace = true }

crates/omnigraph/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "omnigraph-engine"
-version = "0.4.1"
+version = "0.4.2"
 edition = "2024"
 description = "Runtime engine for the Omnigraph graph database."
 license = "MIT"
@@ -16,7 +16,7 @@ default = []
 failpoints = ["dep:fail", "fail/failpoints"]
 
 [dependencies]
-omnigraph-compiler = { path = "../omnigraph-compiler", version = "0.4.1" }
+omnigraph-compiler = { path = "../omnigraph-compiler", version = "0.4.2" }
 lance = { workspace = true }
 lance-datafusion = { workspace = true }
 datafusion = { workspace = true }
@@ -50,7 +50,7 @@ chrono = { workspace = true }
 arc-swap = { workspace = true }
 
 [dev-dependencies]
-omnigraph-compiler = { path = "../omnigraph-compiler", version = "0.4.1" }
+omnigraph-compiler = { path = "../omnigraph-compiler", version = "0.4.2" }
 tokio = { workspace = true }
 lance-namespace-impls = { workspace = true }
 serial_test = "3"

docs/releases/v0.3.0.md

@@ -20,7 +20,7 @@ A new `GET /schema` endpoint and matching CLI `schema get` command return the ac
 
 ### Stricter run-branch hygiene
 
-Internal `__run__…` branches, used for short-lived write staging, are now filtered out of user-visible branch listings and are deleted on every terminal state transition instead of accumulating over time (MR-670, MR-674).
+Internal `__run__…` branches, used for short-lived write staging, are now filtered out of user-visible branch listings and are deleted on every terminal state transition instead of accumulating over time.
 
 ## Breaking changes
 
@@ -36,7 +36,7 @@ The server refuses to open a repo that lacks persisted schema state (`_schema.pg
 - Add manually-dispatched Package workflow for CodeBuild image builds (default + aws variants)
 - Add `GET /schema` endpoint and `schema get` CLI command
 - Ship static `openapi.json` spec with CI auto-sync
-- Filter and delete ephemeral `__run__` branches (MR-670, MR-674)
+- Filter and delete ephemeral `__run__` branches
 - Switch Dockerfile base to ECR Public (avoid Docker Hub rate limits)
 - Raise `LANCE_MEM_POOL_SIZE` default to 1 GB for stable parallel tests
 - Automate Homebrew tap updates on release tags

docs/releases/v0.4.0.md

@@ -1,12 +1,12 @@
 # Omnigraph v0.4.0
 
 Omnigraph v0.4.0 demotes the Run state machine to commit metadata via the
-publisher's CAS, fixing the cancellation hole that motivated MR-771 and
-reducing the engine's surface area.
+publisher's CAS, fixing a write-cancellation hole and reducing the engine's
+surface area.
 
 ## Highlights
 
-- **Direct-to-target writes (MR-771)**: `mutate_as` and `load` write
+- **Direct-to-target writes**: `mutate_as` and `load` write
   directly to the target tables and call
   `ManifestBatchPublisher::publish` once at the end with
   `expected_table_versions`. No more `__run__<id>` staging branches, no
@@ -72,18 +72,17 @@ for the workaround.
 
 - **Stale `__run__*` branches and `_graph_runs.lance`** in legacy v0.3.x
   repos are *inert* — the engine no longer reads them — but they remain
-  on disk until production cleanup. MR-770 owns the destructive sweep;
-  this release deliberately does not touch legacy bytes.
+  on disk until production cleanup. This release deliberately does not touch
+  legacy bytes.
 - The `is_internal_run_branch` predicate is kept as a defense-in-depth
   guard against users naming a branch `__run__*`. It will be removed in
-  a follow-up alongside MR-770.
+  a follow-up cleanup.
 - External scripts hitting `/runs/*` will now receive 404. Migrate them
   to `/commits` for audit history; mutation status is implied by the
   HTTP response on `/change` itself.
 
 ## Included Changes
 
-- MR-771 — Demote Run: write directly to target via publisher
-- MR-766 — `ManifestBatchPublisher::publish` accepts per-table
-  `expected_table_versions` (landed earlier; this release wires it in
-  end-to-end)
+- Demote Run: write directly to target via publisher
+- `ManifestBatchPublisher::publish` accepts per-table
+  `expected_table_versions`

docs/releases/v0.4.1.md

@@ -9,7 +9,7 @@ mutation proceeds normally.
 
 ## Highlights
 
-- **Staged-write rewire (MR-794)**: `mutate_as` and `load` (Append /
+- **Staged-write rewire**: `mutate_as` and `load` (Append /
   Merge modes) accumulate insert/update batches into
   `MutationStaging.pending` per touched table. No Lance HEAD advance
   happens during op execution; one `stage_*` + `commit_staged` per
@@ -39,7 +39,7 @@ mutation proceeds normally.
   `ensure_node_id_exists`). The `swap_coordinator_for_branch` /
   `restore_coordinator` API and `CoordinatorRestoreGuard` are removed
   from `mutation.rs`. (`merge.rs` keeps its own swap pattern; that's
-  a separate workflow tracked in MR-793.)
+  a separate workflow.)
 - **`docs/invariants.md` §VI.25** flips from `aspirational/open` to
   `upheld for inserts/updates`. The within-query read-your-writes
   guarantee is now load-bearing for the publisher CAS contract.
@@ -67,11 +67,11 @@ mutation proceeds normally.
   D₂ keeps inserts/updates from coexisting with deletes, so the
   inline path remains atomic per op but not per query for delete-only
   cascades. Closing this requires Lance to expose
-  `DeleteJob::execute_uncommitted`; tracked in MR-793 / Lance-upstream.
+  `DeleteJob::execute_uncommitted`; tracked upstream with Lance.
 - **`schema_apply`, `branch_merge_internal`, `ensure_indices`** still
   use Lance's inline-commit APIs. The two-phase pattern is in
-  `mutate_as` and `load` only; hoisting it to a storage-trait
-  invariant covering all writers is MR-793.
+  `mutate_as` and `load` only; hoisting it to a storage-trait invariant
+  covering all writers remains future work.
 
 ## Tests added
 
@@ -110,7 +110,7 @@ mutation proceeds normally.
 - `docs/invariants.md` — §VI.25 status flipped to `upheld for
   inserts/updates`.
 - `docs/architecture.md` — added "Mutation atomicity — in-memory
-  accumulator (MR-794)" subsection; refreshed the engine + state
+  accumulator" subsection; refreshed the engine + state
   diagrams to drop `RunRegistry` and add `MutationStaging`.
 - `docs/execution.md` — rewrote the mutation flow sequence diagram
   for the staged-write path; updated the `LoadMode` table to call
@@ -118,7 +118,7 @@ mutation proceeds normally.
 - `docs/query-language.md` — documented the D₂ parse-time rule.
 - `docs/errors.md` — added the D₂ `BadRequest` rejection path.
 - `docs/storage.md` — dropped the live `_graph_runs.lance` reference
-  (legacy from MR-771) from the layout diagram and prose.
+  from the layout diagram and prose.
 - `docs/branches-commits.md` — moved `__run__<id>` to a legacy note;
   removed `publish_run` from the publish-trigger list.
 - `docs/audit.md` — current `_as` API list refreshed; legacy
@@ -128,16 +128,15 @@ mutation proceeds normally.
 - `docs/cli.md` — replaced the legacy `omnigraph run *` quickstart
   block with `omnigraph commit list/show`.
 - `docs/testing.md` — extended the `runs.rs` row to cover the new
-  MR-794 contract tests; added the `staged_writes.rs` row.
+  staged-write contract tests; added the `staged_writes.rs` row.
 - `AGENTS.md` (CLAUDE.md symlink) — updated the atomic-per-query
   description and the L2 capability matrix row.
 
 ## Included Changes
 
-- MR-794 step 2+ — rewire `mutate_as` and `load` via in-memory
-  `MutationStaging` + `stage_*` / `commit_staged` per touched table at
-  end-of-query.
-- (MR-794 step 1 shipped in v0.4.0's PR #67 — `StagedWrite`,
+- Rewire `mutate_as` and `load` via in-memory `MutationStaging` +
+  `stage_*` / `commit_staged` per touched table at end-of-query.
+- (The storage substrate shipped in v0.4.0's PR #67 — `StagedWrite`,
   `stage_append`, `stage_merge_insert`, `commit_staged`,
   `scan_with_staged`, `count_rows_with_staged` — and is the substrate
   this release builds on.)

docs/releases/v0.4.2.md

@@ -0,0 +1,61 @@
+# Omnigraph v0.4.2
+
+Omnigraph v0.4.2 is a correctness and operability release for concurrent
+writes. It closes snapshot-isolation lost-update windows, expands recovery
+sidecar coverage for inline deletes, and removes an unwired admission-control
+surface before it becomes public API.
+
+## Highlights
+
+- **Read-time drift checks for strict mutations**: staged mutations now 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 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-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.
+- **Lean admission API**: removed the unused global rewrite admission pool,
+  `service_unavailable` error variant, related 503 documentation, and benchmark
+  flag. The server keeps the wired per-actor inflight and byte-budget admission
+  gates.
+- **Regression coverage**: failpoint and server matrix tests now cover the
+  inline-delete sidecar race, merge × change target movement, and post-reopen
+  branch-op state.
+
+## Behavior changes
+
+- Some concurrent mutation and merge races now return `manifest_conflict`
+  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 remaining per-actor inflight 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.
+- Operators should remove stale references to global rewrite admission and 503
+  rewrite-pool exhaustion from local runbooks.
+
+## Included Changes
+
+- Per-table writer queues and read-time version checks for strict mutation
+  publishes.
+- Branch-merge target snapshot revalidation under queue ownership.
+- Inline-delete manifest-conflict recovery-sidecar regression test and fix.
+- Matrix coverage updates for merge × change concurrency and reopen
+  consistency.
+- Removal of the unwired global rewrite admission / 503 server surface.

openapi.json

@@ -7,7 +7,7 @@
       "name": "MIT",
       "identifier": "MIT"
     },
-    "version": "0.4.1"
+    "version": "0.4.2"
   },
   "paths": {
     "/branches": {