From 97c6490c1dd4e66ef5eeebb0507bca7de2a9e4a4 Mon Sep 17 00:00:00 2001 From: Ragnor Comerford Date: Wed, 29 Apr 2026 17:14:48 +0200 Subject: [PATCH] docs: post-merge code-review fixes (Cursor + cubic on PR #60 era) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two factual mismatches caught during code-grounded re-review: - docs/architecture.md: "13 cmd families" was stale — the CLI has 17 Command variants (Version, Embed, Init, Load, Ingest, Branch, Schema, Query, Snapshot, Export, Run, Commit, Read, Change, Policy, Optimize, Cleanup). Replaced the count with "command families" so the diagram doesn't drift again. - docs/execution.md: the mutation prose said "every mutation runs on a fresh __run__ branch", which over-claims. mutation.rs:555 short- circuits when the target is already a __run__ branch — the assumption there is the caller is managing the surrounding run lifecycle. Added a one-paragraph caveat noting the exception with the file:line citation. Both diagrams unchanged; only annotations / counts adjusted. --- docs/architecture.md | 2 +- docs/execution.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 1c47fd0..5bd252e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -225,7 +225,7 @@ Today, indexes are built explicitly via `ensure_indices`. Reads degrade graceful flowchart LR classDef l2 fill:#e8f4fd,stroke:#1e6aa8,color:#000 - cli[omnigraph CLI
13 cmd families]:::l2 + cli[omnigraph CLI
command families]:::l2 srv_in[Axum HTTP
REST + OpenAPI]:::l2 auth[Bearer auth
SHA-256 hashed tokens]:::l2 pol[Cedar policy gate
per request]:::l2 diff --git a/docs/execution.md b/docs/execution.md index 7897a9f..6bf55a5 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -141,7 +141,9 @@ sequenceDiagram - Run publish: `Omnigraph::publish_run` at `crates/omnigraph/src/db/omnigraph.rs:858` - Manifest commit primitive: `ManifestRepo::commit` at `crates/omnigraph/src/db/manifest.rs:280` (called from both per-statement `commit_updates` and the publish path) -Multi-statement mutations don't get atomicity from a single final `commit` — they get it from the **run-branch + publish_run** pattern. Every mutation runs on a fresh `__run__` branch (`begin_run`); each statement individually commits its sub-table updates to that run-branch. After all statements complete, an OCC pre-check verifies the target hasn't moved since the run started, then `publish_run` atomically promotes the run-branch into the target — either via the fast path (direct promotion if the target hasn't moved) or a three-way merge. That final publish is what gives multi-statement mutations their atomicity guarantee (per [`docs/invariants.md`](invariants.md) §VI.26). If anything fails mid-run, the run is failed and the run-branch is dropped without affecting the target. See [runs.md](runs.md) for the full run lifecycle. +Multi-statement mutations don't get atomicity from a single final `commit` — they get it from the **run-branch + publish_run** pattern. By default a mutation forks a fresh `__run__` branch (`begin_run`); each statement individually commits its sub-table updates to that run-branch. After all statements complete, an OCC pre-check verifies the target hasn't moved since the run started, then `publish_run` atomically promotes the run-branch into the target — either via the fast path (direct promotion if the target hasn't moved) or a three-way merge. That final publish is what gives multi-statement mutations their atomicity guarantee (per [`docs/invariants.md`](invariants.md) §VI.26). If anything fails mid-run, the run is failed and the run-branch is dropped without affecting the target. + +One exception: if the caller already targets a `__run__` branch (mutation.rs:555), the mutation runs directly on that branch with no nested run wrapping — the assumption is the caller is managing the surrounding run lifecycle themselves. See [runs.md](runs.md) for the full run lifecycle. ## Bulk loader (`loader/mod.rs`)