Repository navigation
Conversation
Add docs/dev/contract.md: the boundary, state, operations, named guarantee clauses, interfaces and assumptions Omnigraph promises, and a dated hypothesis of the agentic knowledge work it serves. Wire it into AGENTS.md required reading, the developer index, the invariants review checklist and the systems guide.
There was a problem hiding this comment.
🔍 Devin Review: 1 flag
Not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)
…oday table Consolidate the guarantees into atomicity, isolation, merge, integrity, durability and outcomes, history, and data independence with identity and policy. Each clause is the target; every place current behavior falls short is one row of a today-and-target table with what is wanted instead. Add entity identity, merge semantics and its isolation level, sessions, availability, change-feed delivery, erasure, delegated dependencies, a latency hypothesis and what the work optimizes for. Mechanism detail moves out to the area guides.
ragnorc
left a comment
There was a problem hiding this comment.
Review of #1425 at b781bd1
Recommendation: merge after adding the missing rows in B1. This PR changes only docs, so it adds no code risk. The page's value is that a design or review can cite a clause, so each clause must be true, and the "today" table must be as complete as it says it is.
What and why
The PR adds docs/dev/contract.md, Omnigraph's observable contract and a dated hypothesis of the workload. AGENTS.md, the developer index, the invariants checklist and systems.md link to it. b781bd1 restructures the page into seven target clauses (atomicity, isolation, merge, integrity, durability and outcomes, history, data independence with identity and policy). Each clause ends with its guide and test owners. Every place where today's behavior falls short of a clause is a row of one "today and the target" table. The commit also adds entity identity, the merge's isolation level (snapshot isolation between branches, with write skew stated), sessions, availability, erasure, delegated dependencies, a latency hypothesis and an optimization order.
Impact on liability
- Removes: guarantee claims spread over many guides with no single name. The restructure removes the main liability of the first version. Mechanism detail (retry counts, permit lists, the search ladder, error-detail names) moved back to the guides, so mechanism PRs such as #1407 no longer need contract edits. Each clause now names tests that can fail.
- Adds: one page that must stay true while nothing checks it automatically. The "today" table is the right shape for that: a gap is one row with a wanted state, not a qualifier inside a clause. But it only works if it is complete, which is B1.
- The "today" table as a design: I agree with it. "Target plus explicit deltas" lets a change say "this removes row N" or "this adds a row" and keeps the clauses short. After five more changes it stays readable, as long as each change that opens or closes a gap edits its row in the same PR. Consider saying that in "How to use this page".
- Context cost:
@docs/dev/contract.mdputs about 30 KB into every agent session, on top of about 146 KB already imported (invariants, Lance, testing). The required-reading list already links the page; the import is a choice to weigh.
Blocking
B1. The "today" table says it lists every gap, but it misses verified ones. The page says "A clause with no row there holds as written, validated against the code on 2026-11-16." Each item below was checked at b781bd1.
- Clause 7 and B (one semantics across doors):
accessand a direct write disagree on a cluster graph.omnigraph accesson a cluster root reads the graph's applied policy bundle (crates/omnigraph-cli/src/commands/targets/access.rs:185-230). But no CLI path installs a policy on the handle: the only production callers ofOmnigraph::with_policy/with_runtime_bindingsare the server and cluster deployment. Soaccesscan report an actor as denied while the same actor's directload --aspublishes. Clause 7's "Not promised: any policy on the CLI's direct handle" covers the write. It does not cover a door that reports grants the write does not enforce. #1423 closes this gap. Until it merges, this needs a row. After it merges, clause 7's "not promised" sentence and its "trusted as the operator" reason need an update for cluster graphs, in whichever PR lands second. - Clause 3: "Conflicts are reported per entity." Cardinality and value-constraint merge conflicts carry no entity id (
row_id: Noneatcrates/omnigraph/src/validate/kernels.rs:697andcrates/omnigraph/src/validate.rs:95). They are typed per type, and the entity is named only in the message. Either say "per entity, or per type forcardinality_violationandvalue_constraint_violation", or add a row. - Clause 5: "Work is bounded … within declared limits." A served request may raise four settings (
traversal_work_limit,query_memory_bytes,write_max_bytes,load_source_max_bytes) up toserver.max(default)(crates/omnigraph-server/src/lib.rs:1180-1223). So when an operator sets a budget below the built-in default, a request can raise it back up to the default. Work is still bounded, but not by the operator's declared limit. This is a row: "a request can raise a lowered server budget to the default", wanted "the server's value is the ceiling". - I: "The three doors share … one error code set and one
dispositionobject." The embedded engine returnsOmniErrorwithCompletionEvidence(crates/omnigraph-core/src/error.rs:12-31). The code set and the disposition are built in the server crate, and the CLI reuses them for its embedded writes (crates/omnigraph-cli/src/command_outcome.rs:422-434). HTTP, MCP and CLI share them; the embedded Rust API does not until that mapping. Say "HTTP, MCP and the CLI share …", or add a row if one shared type is the target.
Optional
O1. Alignment with open PRs.
- #1405 (group commit RFC) lets one commit hold several writes from several actors, with
actor_idempty when they differ. Clause 1's "becomes visible as one graph commit" and the one-line "every change is one atomic, durable, attributed graph commit" would then be false. "Becomes visible in exactly one commit, wholly or not at all" is true today and survives that design. #1405 should then name clause 1 and the identity bullet of clause 7 as the clauses it changes. - #1302 / #1316 (GQ 3) replace the query language that O and I name. This is not a defect here, but by this page's rule #1302 is the RFC for a contract change and should name the clauses it changes (O's result semantics, I).
- #1322 (bind
--unauthenticatedto loopback) narrows the deliberate Open-mode row of clause 7. That row should name it when it lands.
O2. Writers per branch in W. The Coordinate row says "one writer per branch by construction of the work", and the Rate row says "tens of live branches … and one writer" and revises on "several writers on one branch". But programs write "to shared state directly", one per system of record, every few minutes, while agents merge into the same branch. The new Targets row already says "bursts on shared state from merges and syncs". That is several writers on the shared branch by design, and it is the workload #1405 is built for. Suggested text: "one writer per task branch; the shared branch takes merges and several independent sync writers". The Rate row's revision trigger should then read "several writers on one task branch".
O3. Small precision points.
- Clause 2: "either that is the head it read, or it was prepared again on the newer head, or it is refused" leaves out the carry-over: a write whose head moved only by commits that changed no row (optimize, an index build) publishes on the newer head without being prepared again. It is observably the same, but "or carried over commits that changed no row" makes the list complete.
- The clause 2 row on reads waiting lists schema apply, branch create and handle open. The process-local exclusive permit is also taken by the system-column upgrade,
sync_branchandrefresh. "Behind exclusive schema and branch-control operations" covers them without a list. - The Targets row (line 356) follows a blank line and has no header or delimiter row, so GitHub renders it as a paragraph with pipe characters, not as a table row. Remove the blank line so it joins the Quantities table.
- Found while checking, outside this PR:
docs/user/mutations/conditional.md:16-18says an embedded--if-commitmismatch exits 1. The code andcrates/omnigraph-cli/tests/integration/cli_data.rs:729("an embedded mismatch exits 4") say 4. That user doc is stale. It needs a separate one-line fix.
Checked and correct at b781bd1
- New clause 3 merge base: the lowest common ancestor sorts by summed distance from both heads, then highest generation, then smallest commit id (
crates/omnigraph-catalog/src/commit_graph.rs:1025,:1355,:1457,:1541-1545). This is the rule the page states. - No property-level merge: classification looks at row presence on base, source and target; any other difference is
divergent_update(crates/omnigraph/src/exec/merge.rs:3349-3368). - O, sort ties: a sort breaks ties by binding metadata columns in binding order, and an aggregate gets no tiebreak (
crates/omnigraph-planner/src/optimizer.rs:1160-1168,logical.rs:542-551). This matches the new aggregate row. - Today rows:
- An empty load still publishes a commit (
crates/omnigraph/tests/integration/changes.rs:1966). - The load fork can end
effects: partial(loader/mod.rs:557-611). - The engine, storage and catalog crates contain no
sync_all/sync_datacall, which is consistent with the local-fsync row. I did not readobject_store's local writer. - Open mode and the static-token read opt-in match
crates/omnigraph-server/src/settings.rs:570-571andhandlers.rs:678-680.
- An empty load still publishes a commit (
- Clause 7 policy: branch scopes are
Any,ProtectedandUnprotected(crates/omnigraph-policy/src/lib.rs:200-204).maintain,reclaimandbranch_claimare checked before effects. A static token cannot take theprincipal:prefix. - Owners: every test file the clauses name exists.
- Carried from the first version and confirmed:
- Snapshot reads resolve once, and delete-only mutations remove the union of matches (
mutation.rs:2219-2222). - Conditional writes are never carried, optimize included (
db/omnigraph.rs:2264-2273). cleanupneeds--keepor--older-than, and no HTTP or MCP route runs it.- The writer-epoch claim is engine-only.
FullTextIndexRequiredandFullTextIndexRebuildRequiredboth exist.- The CLI, not the engine, refuses direct schema apply on a cluster graph.
- Snapshot reads resolve once, and delete-only mutations remove the union of matches (
Head change during review
I first reviewed a0632af. My draft for that head had found:
fast_forwarddescribed as decided table by table, when one graph-wide flag decides it (merge.rs:5544);- error codes named by their detail fields (
precondition_failure,key_conflict,merge_conflict); - a resource-ceiling sentence stronger than the code;
- Open mode left out;
- off-by-one retry counts;
- mechanism lists inside clauses;
- no test owners and no clause anchors.
b781bd1, pushed during the review, removes or moves all of them into the "today" table, except the items now in B1 and O3. I rechecked the delta: every new claim above, and every row of the table.
Validation
- Clean detached worktree at b781bd1 (merge base 4f7c207;
main8ab6571 is one README commit ahead). bash scripts/check-agents-md.sh: OK (69 links, 65 docs).python3 scripts/check-docs.pyin a venv withscripts/requirements-docs.txt: OK (530 Markdown files).typosis not installed on this host, so not run locally.- CI at b781bd1 when checked: 14 passed, 1 pending, 14 skipped, none failed.
- Clause check: code inspection only. Four independent read passes on a0632af plus my own pass on the b781bd1 delta. I rechecked each B1 item at its cited lines.
- No tests run: the PR has no behavior change, and the GQT regression rule does not apply (no bug fix).
- No
Decision neededcomments. The only prior review is Devin's, at a0632af.
Readers learn the head from storage, so any number of always-fresh reader processes may serve one root. Record that read replicas are unsupported today, the one-writer and N-reader topology, and read capacity as the reason in the workload hypothesis.
Agents issue analytical reads while retrieving context, and import whole structured and unstructured sources. State both in the activity and quantity tables and in what the work optimizes for, and require in AGENTS.md that every design is checked against the contract.
Unpack each category into the contract, mechanism and workload claims it bundles, and state where Omnigraph matches each claim and where it does not.
ragnorc
left a comment
There was a problem hiding this comment.
Review of #1425 at 9fc0033 (delta since b781bd1)
Recommendation: merge after one more sentence in clause 2 (B2) and the open items of B1 from my review at b781bd1. The PR is docs only, so it adds no code risk.
What changed since my last review
Three commits, b781bd15..9fc00339, +58 −19 in docs/dev/contract.md and AGENTS.md:
- Reader scale-out as a target. Clause 2 gets a "Readers scale out" bullet: a read learns the head from storage, any number of reader processes may serve one root, none coordinates with the writer, and each is fresh. The Topology assumption becomes "one writer, any number of stateless readers", with the reader half marked as wanted. A new today row says read replicas are not supported, because a served process takes the cluster's writer admission.
- The work. Retrieve now has a lookup mode and an analytical mode. Acquire covers whole-source imports up to 10^7 records and 10^4 documents. "Answer" becomes "Report". A new "Read capacity" row says reads need several processes. The optimization order puts analytical reads after lookups and says read capacity scales out by adding readers.
- Categories. The "category shorthand" paragraph becomes a table that places Omnigraph against OLTP, OLAP, HTAP and LTAP.
- Change discipline.
AGENTS.mdnow asks every design, RFC and non-trivial change to name the clauses it keeps, the workload row it serves, and the today row it moves.
Impact on liability
- Removes: an unstated scaling direction. Before this delta, nothing said whether more read load means a bigger server or more processes. Now a design can cite one target, and the today row shows the gap. The two retrieve modes also stop the page from saying analytical reads are "occasional" while the work needs them on a step's critical path.
- Adds: one more target clause that must stay consistent with the others, and one more process rule in
AGENTS.md. The rule is cheap: it reuses the page's clause and row names, so a PR adds one or two sentences. After five more PRs it gives reviewers a fixed question to ask. It also settles O1 of my last review: #1405 and #1302 would now be asked to name the clauses they change. - The reader target fits the code. It does not need a new mechanism for freshness. A warm read already checks the head with one storage request: a HEAD of the held manifest version (
crates/omnigraph/tests/integration/warm_read_cost.rs:27-38). The missing part is a serving mode, which the today row names correctly. B2 is the one rule the target still leaves out.
Blocking
B2. "Readers scale out" does not say what happens when cleanup removes the commit that a reader is reading. Clause 2 says a read "sees exactly that commit, every type together, for its whole life". The new bullet says reader processes do not coordinate with the writer. Clause 6 says history stays readable until cleanup removes it. With no coordination, a writer's cleanup can delete files that a read in another process still needs. Nothing in Omnigraph or Lance prevents this:
cleanupretains by--keep Nand--older-thanonly (docs/user/operations/maintenance.md:219-220). With--keepalone, a commit outside the newest N is removed whatever its age (:233-234).- The pinned Lance 13.0.0 cleanup has no reader lease. It lists and then deletes, and it tolerates only another cleanup running at the same time (
lance-13.0.0/src/dataset/cleanup.rs:584,:861). - The pinned commit in "Sessions" ("pins a commit id") has the same exposure across requests.
This already happens today, without the new topology. Read-only CLI commands take no admission (crates/omnigraph-cli/src/admission.rs:50-66), and a direct cleanup takes the writer admission. So when no server runs, a direct cleanup can run under an in-flight direct read. The today table has no row for this.
The fix is one sentence in the target and one today row. One option that keeps "none coordinates": "A read whose commit cleanup removes before the read ends is refused with a typed error, never answered from part of the commit; the operator chooses a retention longer than the longest read." Another option is a reader lease that cleanup honors, but that is coordination and would change the bullet. Either way, a design for read replicas needs this rule before it starts. Without it, the design would cite a clause that clause 6 contradicts.
B1 (from my review at b781bd1) is still open. The delta does not touch its four items, and #1423 is still open. At 9fc0033 these lines are unchanged: "Conflicts are reported per entity" (clause 3), "one error code set and one disposition object" (I), and the today table has no row for access against a direct write or for request-raised server budgets. The page still says "A clause with no row there holds as written".
Optional
O4. "A lookup is never slowed to serve one" reads as an isolation promise. The new HTAP row says there is "no isolation of the two kinds of work from each other". The optimization paragraph says "a lookup is never slowed to serve one" (an analytical read). As a priority rule this is right: a design must not make lookups slower to make analytical reads faster. But a reader can take it as a runtime promise, which the HTAP row says Omnigraph does not make. Suggested text: "no design makes lookups slower to make analytical reads faster".
O5. LTAP has no source. The category paragraph cites systems for these names. systems.md covers OLTP, OLAP and HTAP (:20, :436-437) but not LTAP, and no other doc uses the term. Add a source for the definition the table gives, or a row in the systems appendix. Otherwise the table defines the category and then compares Omnigraph against its own definition.
O6. Small points.
- "Answer" is now "Report", but the paragraph about people still lists "and answer" (
contract.md:344). - The "Sessions" bullet's first line is no longer wrapped like the others (
:125-126). - O3 from my last review is still open: the Targets row follows a blank line, so GitHub shows it as a paragraph with pipes, not as a table row.
Checked and correct at 9fc0033
- Read replicas row. The server takes cluster admission with purpose
Servebefore it opens any graph (crates/omnigraph-cluster/src/serve.rs:133-149, called fromcrates/omnigraph-server/src/settings.rs:369-371). The CLI takesGraphOperationadmission only before its writable opener (crates/omnigraph-cli/src/admission.rs:72-95). Read commands "never acquire writer admission" and open read-only (:50-66). So "one server serves a cluster, and only read-only CLI commands read beside it" is correct. - "A read learns the head from storage." The warm read path makes one freshness request, and a warm reader still sees commits from other processes (
warm_read_cost.rs:1-6,:27-38). The embedded writer-epoch exception already has its own today row. - Topology. The writer half matches the support boundary in
docs/dev/invariants.md:166-192. - OLAP and HTAP rows. These match how
systems.mduses the terms. HTAP names a mix of work, not a promise that the two kinds of work do not slow each other (systems.md:339).
Selection and head
- At selection, #1425 had had no review of its head since 23:11Z: three commits after my review at b781bd1, and no other review or comment since.
- There are no
Decision neededcomments.
Validation
- Clean detached worktree at 9fc0033. Merge base 4f7c207, the same as at b781bd1, so the delta is only the PR's own three commits.
bash scripts/check-agents-md.sh: OK (69 links, 65 docs).python3 scripts/check-docs.pyin a venv withscripts/requirements-docs.txt: OK (530 Markdown files).git diff --check 4f7c2076..9fc00339: clean.typosis not installed on this host, so I did not run it.- CI at 9fc0033: 16 passed, 14 skipped, none failed.
- Every claim above comes from reading the code at the lines cited. I did not run tests: the PR changes no behavior and fixes no bug, so the GQT regression rule does not apply.
State one branch as a linearizable object whose reads and commits are strictly serializable, name the four session guarantees, and correct the cross-branch level: merge resembles snapshot isolation but admits a lost update and exposes unmerged commits. Describe merge as a state-based keyed three-way merge with entity-level conflict detection, separate entity conflicts from constraint violations, and tie the merge checks to invariant confluence. Rewrite the category table against the sources, with LTAP as Databricks' 2026 architecture, and list the sources read.
Put the work first and derive the contract from one sentence: multiple agents sharing a typed world model to continuously retrieve and update context and coordinate work. Add the derivation table, give each clause its reason, and state each clause as the target the work requires, not as a description of the engine. Record as explicit today rows the targets the engine does not meet, marking those no RFC has decided as derived: conditions scoped to what was read, stale-premise detection at merge, property-level merge, schema change by branch, request identity, revert, commit intent, a waiting feed, and type and property policy scope.
Make sync an activity of its own, add react (agents and pipelines woken by a change), and carry both into the derivation, the history clause, the quantities and the optimization order.
Add what the evidence supports, what it argues against and what no source measures. Add speculation as an activity, make exploration of the schema a frequent read, and distinguish task branches from many short discarded ones. Carry the findings into the derivation and the clauses: an exclusive claim, a gated merge, a waiting feed with a condition, visible work in progress, valid time as the schema's job, and control outside the contract. State that a typed model is the page's bet, and list the sources.
ragnorc
left a comment
There was a problem hiding this comment.
Review of #1425 at 9445d47 (delta since 9fc0033)
Recommendation: revise before merge. The PR changes only docs, so it adds no code risk. But the page asks to be cited clause by clause, and it says that "a sentence of a clause with no row there holds today". At this head that is not true in six places: B3 is new in this delta, B1 is from my review at b781bd1 and B2 from my review at 9fc0033. Each fix is one or two sentences or one row.
What changed since my last review
Four commits, 9fc00339..9445d47f, +485 −208, all in docs/dev/contract.md:
- The work is now a list of activities. W gives each activity (orient, speculate, retrieve, acquire, sync, author, derive, coordinate, react, verify and correct, propose and review, look back, maintain, report) with its footprint on the graph. A new "What the evidence says" part checks the hypothesis against the literature. It also says what the literature does not support, for example that production systems mostly have one writing lead per task.
- A new R section derives the clauses from the work. "A clause is justified by a row here or it does not belong in the contract."
- New targets, each marked derived with a today row. These are: claims with one winner; conditions as narrow as the decision; merge-time checks of stale dependencies; property-level merge; gated merges; schema change on a branch; visible work in progress; task and reason on a commit; revert; a feed that waits on a condition; valid time; type and property policy scope. Clause 2 now also says that any number of writer processes may write one root.
- Sources. The terms are now tied to 30 sources: linearizability, strict serializability, session guarantees, snapshot isolation anomalies, invariant confluence, diff3 and Codd's data independence. The category table places LTAP as one vendor's architecture, with a source.
Impact on liability
- Removes: clauses that nobody can trace to a reason. With the R table, a reviewer can ask of each clause "which row of R needs this?", and of each design "which row does it serve?". The derived mark keeps a target from reading as a design decision, and the rule "a derived target is a requirement, not a design" keeps the page from deciding RFCs ahead of time. I agree with this structure.
- Adds: about twelve new target sentences. Each is true only as long as its today row exists. This makes the "today" table carry more weight. It is now the only thing between a target and a false description of the engine, so every missing row is a false statement. B1, B2 and B3 are all missing or stale rows of this kind.
- Context cost: the page is now 59 KB, about twice its size at b781bd1, and
AGENTS.md:27imports it into every agent session. The sources list and "What the evidence says" are about a sixth of it. They are needed for review, but not in every coding session. See O9. - After five more changes like this one: each change adds targets and rows, and the page stays coherent if each change edits A, the clause and the row together. B3 shows what happens when one of the three is missed.
Blocking
B3 (new). Clause 2 and A give two different writer targets.
- Clause 2 (
contract.md:328-330): "Any number of writer processes may write one root: writers of different branches never contend …". The today row at:539wants "Any number of writer processes". - A, Topology (
contract.md:588-592): "The target is one mutation-capable writer process per cluster and any number of stateless reader processes … The writer half is the supported topology today; the reader half is wanted."
A design for several writer processes can cite clause 2. A design that assumes one writer can cite A. Both are on the same page. Suggested text for A: "The target is any number of writer and reader processes over one root, added and removed freely. Today one mutation-capable writer process per cluster is supported (support boundaries), and readers beside it are only read-only CLI commands; see today and the target."
B1 (from my review at b781bd1) is still open, and two items changed.
- Clause 7 is false on
mainsince #1423 merged. #1423 merged at 54ced5d (01:40Z), before this delta. This PR is therefore the second to land, which my review at b781bd1 said must update clause 7. Onmain,admission::open_writablereads the policy bound to a cluster graph under admission and installs it on every writable direct handle (crates/omnigraph-cli/src/admission.rs:73-95at 25b5199). At this head clause 7 still says "Not promised: … any policy on the CLI's direct handle, whose caller is trusted as the operator" (contract.md:519-521). Suggested text: "Not promised: per-row policy, or policy on a direct handle to a standalone graph. A direct write to a cluster graph is checked against that graph's applied policy, for the actor the caller declares." Also change A, Trust (:595-596) to say that a direct caller is trusted to declare its actor, not that it bypasses policy. - Clause 3 is now wider and still wrong for constraint violations. The delta changed "Conflicts are reported per entity" to "Conflicts and violations are reported per entity" (
contract.md:402). Cardinality and value-constraint violations carry no entity id:row_id: Noneatcrates/omnigraph/src/validate/kernels.rs:697andcrates/omnigraph/src/validate.rs:95, unchanged onmain. They are typed per type, and the entity appears only in the message. Say "per entity, or per type forcardinality_violationandvalue_constraint_violation", or add a row. - Clause 5, "within declared limits" (
contract.md:448), is unchanged. A served request can still raisetraversal_work_limit,query_memory_bytes,write_max_bytesandload_source_max_bytesup toserver.max(default)(crates/omnigraph-server/src/lib.rs:1192-1211onmain). There is no row for this. - I, "The three doors share … one error code set and one
dispositionobject" (contract.md:569-570), is unchanged. The embedded Rust API returnsOmniError, and the code set and disposition are built in the server crate.
B2 (from my review at 9fc0033) is still open, and it now covers writers too. Clause 2 says that a read sees its commit "for its whole life", and that reader processes do not coordinate with the writer. Clause 6 says that history stays readable until cleanup removes it. Nothing stops a cleanup from removing the commit that an in-flight read uses: the pinned Lance cleanup has no reader lease (lance-13.0.0/src/dataset/cleanup.rs:584, :861), and read-only CLI commands take no admission. The new sentence "any number of writer processes may write one root" lets the cleanup run in yet another process. The today row at :539 names cleanup only as "safe only from one process", which is about writers, not readers. A read-replica or multi-writer design needs this rule before it starts. Add one sentence to the target, for example "a read whose commit cleanup removes before the read ends is refused with a typed error, never answered from part of the commit", and add a today row.
Optional
O7 (new). "Writers of different branches never contend" has an exception in one process today. Ordinary writes do not contend across branches: the writer gates are per (table_key, branch) (crates/omnigraph/src/db/write_queue.rs:1-7, :326-330). But a branch create, a schema apply or a system-column upgrade takes the schema permit exclusively. The gate is write-preferring, so writers on every branch wait behind it, and also behind the preparation of a re-prepared attempt (docs/dev/writes.md:427-434). The row at :538 names this wait for reads only. Suggested: widen it to "reads and writes on any branch can wait …", with "no read or write waits for a control write on another branch" as the wanted state.
O4 (from my review at 9fc0033) is still open. "A lookup is never slowed to serve one" (contract.md:165-166) still reads as a runtime isolation promise. The HTAP row says that this isolation "is unmeasured". Suggested: "no design makes lookups slower to make analytical reads faster".
O2 (from my review at b781bd1), half done. The Rate row now gives task branches one writer, which fixes it there. The Coordinate row (contract.md:65) still says "one writer per branch by construction of the work". But programs "write to shared state directly" (:75-76), and the Targets row expects "bursts on shared state from merges and syncs". Suggested: "one writer per task branch".
O9 (new). Context cost and one wording mismatch.
AGENTS.md:27imports all 59 KB into every session. Consider moving "Sources" and "What the evidence says" to a linked page (for examplecontract-sources.md) that the import does not include. The clause numbers and the R rows that designs cite would stay on the imported page.AGENTS.md:11-12calls the page "the observable contract Omnigraph promises". The page itself says that the clauses are targets, and that Omnigraph "aspires to promise" them (contract.md:17-18,:259-262). Say "the observable contract Omnigraph targets, and where it stands today".
Alignment with open PRs. #1405 (group commit) lets one commit carry several actors, with actor_id empty when they differ. The new clause 6 sentence "a commit records who made it and, when the caller says so, why: the task and the reason" makes that conflict larger, because a group commit would hold several tasks. By this page's own rule, #1405 should name clause 1, clause 6 and the identity bullet of clause 7 as the clauses it changes.
Resolved since 9fc0033
- O3: the Targets row now joins the Quantities table (
contract.md:123). - O5: LTAP has a source ([17]) and is called "one vendor's architecture", not a category of the literature.
- O6: the people paragraph says "and report" (
:73-75), and the Sessions bullet is wrapped like the others.
Checked and correct at 9445d47
- Every new derived target has its today row. I matched each one: claims
:544, narrow conditions:542, stale dependencies:545, property-level merge:546, gated merge:547, schema on a branch:549, request identity:550, feed condition, revert, task and reason:552, work in progress:553, valid time:543, type and property policy:554. - Cross-branch writes in storage. Commits are buffered in each branch's own
__manifestLance branch (crates/omnigraph-catalog/src/commit_graph.rs:108-147). So writers of different branches do not share one compare-and-swap object, which agrees with clause 2's target apart from O7. - Owners. Every test file and guide anchor that the clauses name exists at this head, including
architecture.md#concurrency-and-support-boundary.
Selection and head
- The trigger's only change was #1438, which the previous workflow run reviewed at its head. Every other open PR by ragnorc had the same head as at that run. #1425 was the oldest pending delta with no review of its head: four commits (02:14Z to 02:44Z) after my review at 9fc0033, and no other review or comment since.
- There are no
Decision neededcomments and no inline comments.
Validation
- Clean detached worktree at 9445d47. The merge base is 4f7c207.
mainis now 25b5199, six commits ahead, and includes #1423. GitHub reports the PR as mergeable with no conflicts. bash scripts/check-agents-md.sh: OK (69 links, 65 docs).python3 scripts/check-docs.pyin a venv withscripts/requirements-docs.txt: OK (530 Markdown files).git diff --check 4f7c2076..9445d47f: clean.typosis not installed on this host, so I did not run it.- CI at 9445d47: 16 passed, 14 skipped, none failed.
- Every claim above comes from reading the code at the lines cited, at this head or at
main25b5199 where stated. I did not run tests: the PR changes no behavior and fixes no bug, so the GQT regression rule does not apply. - Not checked: the external figures in W and the category table (for example "about half of all queries" [18], and the Delta Lake commit rate [15]), and the description of Databricks LTAP [17]. I did not read those sources.
What
Adds
docs/dev/contract.md, the page that fixes the first and third parts of "an observable contract, implemented by physical mechanisms, serving a distribution of work" for Omnigraph.Wires it in: required reading and the doc map in
AGENTS.md(with an@import), the developer index, one line in the invariants review checklist, and a pointer at the end ofsystems.md.Why
Agents and reviewers are asked to say which contract and which workload a change serves. Neither was written down in one place, so "safe" and "faster" had nothing to cite, and nothing separated what Omnigraph promises from what it does today.
How the claims were checked
Six independent reviewers validated the claims against production code with file and line evidence, in two rounds. Wrong or loose claims were corrected. Findings that are behavior, not wording, became rows of the today table. Among them: a local-filesystem root is not fsynced at acknowledgement;
bm25scores depend on full-text coverage;optimizedoes not guarantee that deleted bytes are rewritten; an unchanged upsert still publishes a commit; branch plus merge gives snapshot isolation, not serializability, between branches.Notes for review
changelog.dnote.Checks
bash scripts/check-agents-md.sh,python3 scripts/check-docs.pyandtypospass locally.