From fa3edf78a5a8d9f2c661c9f0ec9f422a2a0f685a Mon Sep 17 00:00:00 2001 From: Donna Box Date: Mon, 28 Sep 2026 22:12:19 -0700 Subject: [PATCH] BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * BDP bead-graph plan: seven-round converged design (v7, SOUND) The plan for implementing BDP natively in this repo, driven through seven adversarial review rounds at max effort. Headlines: - Pinned to BDP aee075f5 (the owned-Links rulings); spec-first enforced. - v0 Scope serves NATIVE beads/links only. The Issue/Dependency projection was withdrawn on proven counterexamples (rounds 3-5): no read-side mechanism can satisfy BDP's revision and identity laws over a store permitting timestamp ties, stale imports, arbitrary SQL, and identity resurrection. The counterexample record and §2b conflict inventory are preserved as the C-lane requirements list. - §2b: fifteen-row inventory of where BDP and the current stack disagree. - C lane sketched: funnel (C1 compat-shim-over-graph-storage → C3 cutover) vs observe (C2 storage-level trigger feed), all claims as verification tasks. - Native design: graph model + graphops trait, GraphReadSource resolution honoring the tree's decorator/telemetry discipline, persisted Type Descriptor store with installation lifecycle, allocation/tombstone ledger, replication participation matrix, provable P-1..P3 exits. - Twelve P-1 decisions enumerated for operator ruling. Co-Authored-By: Claude Fable 5 * Plan: the storage interfaces, concretely (operator request) Member-by-member attachment: Storage unchanged (GraphCapable as separate optional interface on DoltStore); no decorator forwarding (targeted-peel resolution, telemetry re-wrapped); the snapshot lease as the one new storage primitive (request-scoped transaction lifetime vs per-call withReadTx, pool/timeout design named); normal migration series; serve role-source entry with non-capable fallback; backend/ additive+gated; issueops/journal/sync untouched. Co-Authored-By: Claude Fable 5 * Plan: storage-interfaces round-8 fixes UOW lease cannot ride RunTxRead (it closes its unit of work on return) — OpenSnapshot owns a direct NewUOW, Close rolls back; telemetry wrapper does not promote inner methods — resolver inspects through it and explicitly re-wraps; capability contract closed (graphops.Store = read surface for v0, ErrGraphUnsupported vs operational failure, in-tree-only exposure); bd serve gets an optional graph field + conditional route seam, not a mandatory role-table entry, with absent/broken/uninitialized kept distinct; ScopeResolver named the one snapshot owner with detached bounded close (cancelled-context rollback burns the connection); conformance description corrected (RunUnsupportedContract proves refusals; GraphCapable becomes a completeness-guard root if opened). Co-Authored-By: Claude Fable 5 * Plan v8: round-9 reconciliation Resolver signatures unified on the error contract everywhere; graphops.Store defined (v0 alias of GraphReadSource, package ownership stated, UOW-to-Scope adaptation named); decision 12 kept open with the uninitialized state explicitly represented under either branch; serve assembly names both source-appropriate resolvers; header reflects the nine-round record. Co-Authored-By: Claude Fable 5 * Plan v8: round-10 reconciliation — resolver pair named everywhere; package ownership cycle-free Co-Authored-By: Claude Fable 5 * Plan v8: resolvers to neutral graphsource package — the actual cycle-free layout uow already imports storage, so the provider-arm resolver cannot live in package storage. Both resolvers move to internal/storage/graphsource, a separate assembly package importing storage+uow+graphops, consumed only by composition roots; GraphCapable stays in storage (leafward import of graphops). Signatures fully qualified. Co-Authored-By: Claude Fable 5 * Plan v8: align the remaining resolver sketch (package clause + qualified types) Co-Authored-By: Claude Fable 5 * Plan v9: ruling tranche 1 — terminology, charter, withdrawal, S1, Scope URL, authority model - Terminology block: 'graph beads / graph links / the graph store' replace 'native' (which reads as the existing implementation inside this repo); 'the bead graph' names ruling 1's union concept. Swept throughout. - Ruling 1 (charter): core; amendment follows working bits; scope = the bead graph expands to non-work-tracking information (wisps the example). - Ruling 5: projection withdrawal ratified (wisps included). - Ruling 2: substrate S1. - Ruling 7a: Scope URL mirrors BDP's pinned startup contract. - Ruling 9 (corrected model): the authority is the graph store as reached through the NORMALIZED STORAGE ABSTRACTION, whichever provider realizes it — not bd serve, not Dolt. Marker, serialized history, non-authority refusal, and the snapshot lease are contract obligations proven by the graph conformance suite; CLI verbs and the BDP handler are both clients. Consequence: the graph capability is part of the PUBLIC backend/ contract from P1 (flips the in-tree-only hedge); §4 reframed with Dolt as reference realization. Co-Authored-By: Claude Fable 5 * Plan v10: ruling tranche 2 — restore, lifecycle commands, ledger, journal, wisps, listener All twelve P-1 decisions are now ruled (one spelling open): - 11 restore vs identity: layered — restorable append-only ledger with provider-declared survival; Scope-URL + epoch rotation when preservation cannot be guaranteed (spec: identity-losing restore = different Scope). - 12 (replaces empty-at-birth): store/Scope/client — bd init initializes the graph store against the interfaces; bd serve mints the Scope on first serve under a configured URL and serves it honestly empty; a client-wiring command (spelling TBD) makes the CLI a BDP client of a designated server. New §4 'Lifecycle commands'. - 3 ledger: append-only allocation record; ID test is a keyed O(1)/O(log n) lookup as a contract obligation. - 8 journal/changefeed, 6 wisps (C-lane visibility), 7b listener (same middleware path; v0 view = whole Scope per bearer token): ratified. Co-Authored-By: Claude Fable 5 * Plan v11: close P-1 — client wiring is a bd init target that reroutes above the storage abstraction bd init --bdp-server joins --server/--shared-server/--proxied-server/ --team-server/--backend as an init target; unlike those (which select the provider/topology BELOW the normalized storage interfaces) it reroutes ABOVE them, at the CLI: graph verbs become a BDP client of the designated server. Config bdp.client store|server (explicit mode) + bdp.server; env/credentials/precedence mirror dolt.mode. All twelve P-1 decisions are now ruled. Co-Authored-By: Claude Fable 5 * Plan v12: bd bdp-serve as the isolated bootstrap path; related workstreams (W-arch, W1, W2, W3) Co-Authored-By: Claude Fable 5 * W-arch: graph architecture/design + detailed CLI and storage-interface spec Two companion writeups to the plan (operator request): - BDP_GRAPH_ARCHITECTURE.md: the shape — packages, imports, roles, a read end to end, where each ruling lands — and three corrections to the plan's §4 after reading the tree's role machinery: accessors on storage.Storage (house rule; promoted through decorators by interface embedding; breaking-change-with-changelog as Memories() was) replace GraphCapable + the graphsource resolver; one-role-call-one-transaction replaces the snapshot lease for P1 (cross-request continuation stays P2's ADR); accessors carry the layers, so no peel-and-rewrap policy. - BDP_GRAPH_CLI_AND_STORAGE_SPEC.md: the diff — bd init graph bootstrap, bd init --bdp-server (config/metadata/env/precedence), bd bdp-serve flags and behavior, bd graph restore/promote, reserved verbs and the three-route accessor fork; Storage accessors, the graphops public leaf, bodies per leg, migrations, decorators, backend/ aliases, conformance contracts and gates, bdpapi + DTO generation; what does not change; open implementation questions. Co-Authored-By: Claude Fable 5 * W-arch v2: answer the three-reviewer council; six ruling amendments proposed (pending) Architecture v2: mechanism corrections separated from ruling amendments; six roles (Reader, DescriptorReader, TypeInstaller, IdentityReader, ScopeBootstrapper, AuthorityRotator); DBTX-shaped shared bodies so the UOW leg (bd serve's primary path) shares one body; replicated Scope row + clone-local dolt-ignored authority half asserted inside every read transaction; BDP rows mounted inside internal/httpapi behind route(); bd bdp serve as a thin strict command; bd bdp namespace; laws in graphops; no backend/ aliases. CLI/storage spec v2: config.yaml single source for bdp.*; BEADS_BDP_TOKEN_FILE (no env token); credentials keyed by origin+scope path; identity state table; promote CAS + fencing by expectation; bd bdp restore branching on LedgerDurability; ledger export/import lane; full DDL with utf8mb4_bin collation, Scope-relative paths, LONGBLOB canonical JSON; three censuses and every embedding surface; conformance cases the council named; bts migration coupling; Part C2 (merge funnel, federation, bd sql) replaces v1's 'does not change' claims. Plan v13: superseded-mechanism banner on §4, amended lifecycle spellings, and a PENDING 'Amendments proposed by W-arch v2' block under §9 (A1–A6 plus the DML enforcement boundary and the replication/merge ADR). * W-arch v3: answer council round 2; plan v14 reopens P-1 for amendments A1-A8 Round 2 (Gemini/Codex/Claude on v2) disproved v2's A5 premise with a live Dolt probe: DOLT_BACKUP restore carries the working set, so a dolt-ignored authority table survives restore. v3: the clone-local authority half is a gitignored .beads/graph-authority.local.json carrying a ledger high-water mark, asserted in every transaction (clone/pull arrive without it; a restore keeps it but rewinds the ledger -> ErrStateRewound). Append-only graph_ledger_events with one global sequence; graph_allocations derived; bd bdp ledger snapshot|apply continuity lane. A7: promotion fenced at the remote (CAS + push, non-fast-forward fails) with bdp.authority_heartbeat. A8: constraint #1 scoped to behavior; out-of-tree backends stub six accessors. Also: BeadGraph* accessor names (GraphCounter clash); Admin role; OwnedLinks grouped by Type URL (the pinned schema's shape); opaque Cursor from P1; expectation on descriptor reads/installs; bd bdp serve inherits errServeReadonly; CommandPath-keyed root policy; --dev-local-test removed; BDP_SCOPE_URL honored via BindEnv; no token key in config; bd backup restore marks unverified; merge entry-point inventory corrected; bts coupling stated as a release-parity gate; provenance columns; LIMIT bound+1; statement counts pinned; wire artifact in future tense. Plan v14: status reopens P-1; section 9 block A1-A8 + two decisions; section 7 superseded-names note; section 8 W-arch bullet. * W-arch v4: answer council round 3 — store-owned witness, per-topology fencing, hash-chained ledger; plan v15 Round 3 converged on the authority mechanism. v4: the authority witness is STORE-OWNED (the accessor loads it from .beads/graph-authority.local.json under an advisory lock; no request type carries authority fields — a caller-supplied expectation was forgeable from replicated rows); the file is bound to a workspace key (hostname + real path, not the shared project id), written under an exclusive lock with monotone read-modify-write and directory fsync, and only once .beads/.gitignore carries the entry (all three doctor lists). The ledger is hash-chained (prev_hash/hash) with mint/install/promote/rotate/allocate/tombstone/refuse_url events; the witness records the head {seq, hash} so a restore or a different history is refused by exact-prefix identity. A7 fencing per topology: shared SQL server -> dolt-ignored graph_authority_lease (the leases/bd-lrgn1 precedent, ephemeral heartbeats); remote-backed embedded -> Mint/Promote are fetch -> compare -> CAS -> DOLT_COMMIT -> push with non-fast-forward reset, heartbeat compares (authority_id, epoch) and fails closed after a grace, P3 writes push-on-commit; no remote -> CAS alone. A8 presented as two options, not pre-empted. A6: bdp.scope_url in tracked config.yaml; bdp.client/server/ insecure_http in untracked config.local.yaml via bd bdp client (config.yaml is git-tracked by default). bd serve never refuses on account of the graph (legacy up, rows absent on non-authority clones); bd init bootstraps only on an unminted store or the authority workspace and is silent otherwise; CommandPath-keyed policy authoritative at every leaf-name call site (list may coincide); five statements per read with LIMIT remaining+1; validator singleflight; tree corrections (14 files, ReadyClaimer CHANGELOG precedent, -0.0 attribution, facade census file, provider-arm assembly). Plan v15: operative lifecycle items 2-3 rewritten as amended (pending), backup/restore matrix row, W2 bullet, section 9 block refreshed to v4. * W-arch v5: answer council round 4 — fences by hazard on the serving leg, sequence counter, two-phase transitions; plan v16 Round 4 (Gemini/Codex/Claude on v4) converged on the authority mechanism. v5 on the tree's precedents: a single-row graph_ledger_seq counter (the journal's bd_events_seq shape; Dolt's FOR UPDATE is a no-op); fences composed by hazard rather than storage mode — a shared database gets the dolt-ignored lease that every mutation must UPDATE with one affected row (a takeover is a serialization loser), a configured remote gets DOLT_FETCH -> ancestor check (DOLT_MERGE_BASE) -> scoped commit (DOLT_ADD graph tables, never -Am) -> DOLT_PUSH with a typed non-fast-forward classifier and reset to the recorded pre-op HEAD; both when both; embedded no-remote not promotable in place. Every serving workspace is a SQL-server workspace, so the serving leg is the UOW provider and the fences live there (doltSQLProvider gains beadsDir). Only bd bdp serve mints (tracked Scope URL); bd serve converts every graph failure into rows-absent + notice. No ledger event before mint: the built-in catalog is installed inside the Mint transaction; bd init installs nothing. Two-phase transitions (pending record, recovery on load) for mint/promote/rotate/ledger-apply; LedgerApply and restore carry their own recovery predicate. Installation key (per-installation id under the user config dir + canonical path) replaces the hostname. Graph-state version = per-table DOLT_HASHOF_TABLE hashes (DOLT_HASHOF_DB moves on every heartbeat); ErrStateChanged returned without validating in the held tx, validated under singleflight by the accessor. config.local.yaml/witness/lock in all three doctor lists; bd config set bdp.scope_url refused once minted; BDP_SCOPE_URL read first. Lease table via doltIgnorePatterns + main-series + ignored-series (0055/ignored 0012 shape). update event kind; provenance on allocations; per-method statement budgets; tree corrections from round 4. Plan v16: witness wording in the section 4 banner, config split in the lifecycle banner, mint trigger in lifecycle item 2, ruling 11 spelling, section 9 block refreshed to v5. * W-arch v6: answer council round 5 (Codex, Gemini); propose A9 simplification; plan v17 Lease predicate now carries the holder installation key, a per-process nonce, the epoch, and an unexpired expires_at by database time; an expired claim is never renewed. Every replicated graph mutation (mint, promote, rotate, install, ledger apply, seeds, P3 writes) runs through one provider primitive on hazard R: fetch -> ancestor check -> record remote graph roots -> fenced transaction -> scoped commit (new RunTxScopedResult; the UOW commit hardcodes -Am today) -> push classified by a typed lift of sync.go's pushRacePattern; on a race every remote graph root is compared (any graph delta fails closed; issue-plane-only divergence keeps the commit as ErrSyncRequired; other failures keep it unpublished). Undo is soft reset + per-table DOLT_CHECKOUT when HEAD is still the op commit (verified against Dolt 2.1.8), DOLT_REVERT otherwise — never a hard reset. Transitions are multi-phase (begun/local_committed/published/config_written) with resume-or- undo recovery. Installation id created O_EXCL 0600 in the directory UserConfigYamlPath chooses. v0 serves BDP only from SQL-server workspaces (registered backends' store arm has no fence; deferred behind a GraphPublication capability). bd bdp serve mints via a staged startup (exclusive gates through a temporary source, then shared). config set/ set-many/unset refuse bdp.scope_url once a witness is held (file check); rotate refused under an overriding BDP_SCOPE_URL. LedgerApply restores anti-reuse history only (reserved allocations; counter set). Graph-state version = ordered per-table hashes of the eight replicated tables (DOLT_HASHOF_TABLE verified to exist); one singleflight coordinator per provider; descriptor cache keyed by the descriptors table hash. A8's method-set reasoning corrected (required methods promote through interface-embedding wrappers; optional interfaces do not). A9 proposed: v0 authority requires a shared database; hazard R deferred. Plan v17: A7/A8 refreshed, A9 added, lifecycle item 2 notes registered backends and the staged mint. * W-arch v7: fold the Claude reviewer's probe-backed round 5 — fence cell, counter nonce, ledger-head comparisons; plan v18 Probed on Dolt 2.1.8: concurrent transactions merge cell by cell, so a lease UPDATE fences a takeover only when both rewrite the same cell with different values, and two 'next = next + 1' increments from the same value both commit with one increment landing. v7: every lease write (grant, steal, expiry reclaim, renewal, per-mutation fence) rewrites a random 'fence' cell and predicates on the value it read; the ledger counter writes a random allocation nonce ('next' is reserved; column is next_seq); the events PK is the second guard (it converges on byte-identical rows, which the nonce prevents). Push-race classification and the heartbeat compare the remote ledger head via AS OF 'origin/main', never the (authority_id, epoch) tuple (a VM-image twin shares it). No configured remote => not promotable in place on every topology (a copied data directory under a second sql-server is a different, unobservable database). Lease holder is the workspace (installation key); admin verbs other than restore/ledger apply take the shared gate and rely on the lease so they run beside a live server; plain bd serve never runs transition recovery. Installation id: user_config_path.go resolver, BEADS_INSTALLATION_ID_FILE, per-OS-user and ephemeral-home residuals. Fresh-remote and ref-spelling rules; timedProvider getter; domain/fs gitignore writer; check D warns without a base ref. * W-arch v8: fold council round 6 — self-regrant, A9 arbiter, gate model, undo unstage step, ref spelling; plan v19 Round 6 (Gemini/Codex/Claude on v7): the Claude reviewer's live Dolt 2.1.8 probes CONFIRM the fence cell (1213 on the versioned and ephemeral paths, read-then-mutate, and disjoint-column takeovers) and the counter nonce (byte-identical events conflict). v8 closes the residuals: an expired lease still naming this workspace self-regrants (renewal and mutation extend expires_at; reads carry no expiry term; promotion only when holder or epoch differ); the lease row Mint creates is the sole proof of 'minted here' and in-place Promote requires it (A9's arbiter; clones promote only with --rotate-url); promote/rotate/install take the shared gate, restore/ledger apply the exclusive gate, stated identically everywhere; staged bd bdp serve bypasses the generic pre-run gate and takes exclusive only when there is no Scope row; transition recovery is by evidence (durable op id in the ledger event; begun-with-committed-op detected; local-committed on a shared DB finalizes; remote classified pre-head / contains op / foreign); Advance is a descendant-aware compare-and-advance; the undo unstages before the per-table checkout (a bare checkout after a soft reset reverts nothing, probed) and restores the ignored lease row; push races compare the remote ledger head (ORDER BY seq DESC LIMIT 1 — MAX(seq),hash errors under ONLY_FULL_GROUP_BY) AND the graph tables' diff, against the workspace's witness; the ref is remotes//; the classifier lifts all of isPushRaceErr; DOLT_HASHOF_TABLE('') x 8 with a stated encoding; renewal-interval bound on fenced transactions; A9 cut sheet; doctor-list membership per list; tree corrections (uow_factory forwards beadsDir; no example backend package; jira stub is a flat implementer; config unset gains an explicit guard call; config.local.yaml merge wording). * W-arch v9: fold council round 7 — honest A9 arbiter, read-path expiry, op_id column, phased undo, one staged sequence; plan v20 Round 7 (Gemini, Codex; Claude probes pending): a dolt-ignored lease row is NOT proof of 'minted here' — DOLT_BACKUP restore and a directory copy carry the working set, and Dolt's @@server_uuid is per machine (probed: identical for a same-machine copy). v9: in-place promotion is self-regrant (the lease names this workspace) or an operator --steal (an assertion of 'same database', in the class of force-push); a foreign holder's expiry alone never grants a takeover; promote --rotate-url is the bootstrap that creates the lease row for clones, copies, and restores; physical database copies are the stated operator-managed hazard; the lease row is bound to scope_url and authority_id. Protected reads self-regrant ephemerally first and require an unexpired lease inside the read; request deadline below the remaining lease interval. op_id becomes an indexed, hash-covered ledger column; the SQL-free manager asks an evidence provider; no-remote recovery executes config_intent before finalizing; undo is phased (undo_started/versioned_undone/ lease_restored), pauses renewal, and restores the lease only on the reset path and only if it still names this workspace; Advance runs a provider-supplied prefix/ancestry verifier under the file lock; one normative staged-startup sequence with an explicit shared release before exclusive; every fenced transaction carries a deadline below TTL/3 with jittered, serialized renewal; types install is uniformly exclusive; hazard-R recovery reuses the delta classifier and the watcher recognizes a pending local op; A9 topology matrix keeps the default-branch rule; transaction-bound capabilities (StateVersioner, GraphPublication, LeaseClaim) move to internal/storage/graphcap. Plan v20 mirrors A1/A7/A9. * W-arch v9: op_id on the public LedgerEvent sketch * W-arch v10: fold council round 8 — one lease predicate, read path never writes the lease, A9 propagated, transition lock held; plan v21; held for rulings Round 8 (Gemini/Codex/Claude on v9): the residuals were text-level. v10: one lease predicate everywhere (a self-held lease CASes regardless of expiry; a foreign holder is replaced only by --steal; no row -> --rotate-url; every 'expired or --steal' and 'lease Mint created here' formulation removed, including the plan's unexpired-expires_at term); protected reads SELECT first and require an unexpired lease inside the transaction, never write it (the serving leg's watcher renews; a near-expiry read fails closed; a CLI read on its own expired lease regrants once, ephemerally, before a fresh read tx — probe-backed ordering); BDP rows carry their own per-row deadline below TTL/3 (the shared route() deadline of 60s exceeds the TTL); types install exclusive in every section and the TTL/3 deadline scoped to the shared-gate context; the file lock is held from Begin through Finalize/Abandon and recovery acquires it first; LedgerApply's crash evidence is the manifest (imported op_ids are never rewritten); recovery keyed on 'hazard R in force' (any remote under A9 takes the local path) with the delta-classifier precedence incl. issue-plane-only; the undo restores the lease on either path under the same-holder guard with a fresh fence (a revert restores the Scope epoch and would orphan the lease — probed); one staged-startup sequence everywhere; A9 propagated to A5's bracket, the embedded leg, and 'CLI-only'; concurrent mint under one tracked URL settled by the ADR (interim: earlier mint wins); ephemeral-home services pin BEADS_INSTALLATION_ID_FILE; rotate beside a live server exits 3; graphcap references; INDEX (op_id); ledger snapshot shared; commandNeedsExclusiveGate learns the new verbs; depguard allowlist gains uow/graphcap; UnstageTables; dolt_log AS OF for the remote pre-head; shared staging sweep stated; matching-head restore is not a rewind; metadata. * Materialize rulings A1–A7 and A9 (2026-09-07); re-pin BDP to bdp#18 merge 0b7d86e7; plan v22, W-arch v11 Operator rulings taken one decision at a time on 2026-09-07: A1 store-asserted witness replaces the snapshot lease (ruling 9); A2 BDP rows inside httpapi, only the strict serve mints, bd serve never refuses, intra-Scope references Scope-relative and a new base URL is a rotation (7b/12); A3 the root flag --graph-mode link|dependency replaces the bd bdp prefix (the mode names the graph by its edge kind; bd link creates the selected graph's edge; policy keyed on mode + command path); link-graph.route replaces bdp.client; A4 public graphops + BeadGraph* accessors; A5 witness file + hash-chained ledger + ledger lane + LedgerDurability (retained versions to the History lane); A6 config placement (tracked scope_url, local per-workspace keys, file tokens); A7 the shared-database fence (fence cell); A9 v0 authority requires a shared database, remote half of A7 deferred to the write-profile ADR. Also folded: bdp#18 (attribution, two statuses) merged and re-pinned in §0, attribution row restored in §2b; sjarmak's accepted inputs (typed incident index; the two §2 plane statements); migration slots start at 0068 (0067 is versioned-beads Phase 1) with a CLAIMED.md registration at P0; History's store_epoch vs the graph authority epoch stated as distinct. A8 and the two decisions remain pending. * A2: record the remount-is-rotation statement in the architecture row * Materialize A8 (option A, 2026-09-07): constraint #1 scoped to behavior; out-of-tree backends take the declared source break; plan v23, W-arch v12 * Materialize ruling 13 (D1, A+B, 2026-09-07): out-of-role DML out of contract; validator with ledger accounting; session-gated triggers on the eight replicated tables; plan v24, W-arch v13 * Materialize ruling 14 (D2, option B, 2026-09-07): replication/merge ADR gates P1 with a four-law charter; P0 open; plan v25, W-arch v14 * Docs: clear four stale proposed/pending markers left after rulings 13–14 (arch §2b heading; plan matrix header, wisps row, §8 W-arch bullet, ruling 11 spelling note) * Docs: record the P0 results — 40 pinned scenarios, generator decision (Part D.3), verification rows (i)-(iii) answered with their rules; fence census over dolt_schemas queued for ruling (Part D.7) * Docs (P0 council 2026-09-07): Link endpoints symmetric (external-source Links are in the pinned fixtures), pins variable-width, error home recorded, canonical-form and UTF-8 hashing rules stated * Docs (P0 council): P0 wire wording, JCS interop caveat, conformsTo sorted in the descriptor canonical form * Docs: migration slots 0069 and later (0068 claimed by versioned-beads Phase 2 attribution_status; CLAIMED.md row c53ef8810) * Docs: P0 implementation notes from council 11's fold (Scope-URL law split, WHATWG origin model, symmetric endpoints, ledger bounds, descriptor canonical form, strict wire decoding); P0 exit met * Docs: name the graph plane's epoch columns authority_epoch at P1 to keep them distinct from the History lane's store_epoch * Docs: record the bdp#1 rulings of 2026-09-08 — wildcard ownership entry (B2/B4) and complete-or-refuse historical reads (History lane) * Docs: wildcard ownership as implemented at P0 — reserved-key sum, max reading, present-only groups, pinned-wire tripwire * Docs: OW1 ruled A — the wildcard max bounds the whole owned set; explicit max never exceeds it * Docs: bdp#21 admission law in B4 — round-trip rule refuses at admission; ledger framing exempt * Docs: B4 — CheckBeadRecord enforces both owned-set bounds at acceptance; P1's LIMIT covers the whole-set bound only * Docs: A10 solo topology (ruled B), Part D.7 fence census (ruled A), authority_epoch confirmed — 2026-09-08 * engdocs: properties are opaque — references inside properties are data, never edges (bdp#1 item 5 as amended, ruled 2026-09-08) * docs: align graph design with current BDP and versioned beads (#6154) Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box * docs: wire graph alignment exits and clarify pinned sources (#6154) Preserve historical P0 results, assign current-wire and serving gates, and clarify selected-profile pins and future storage delta review. Fold adjudicated source and History precision corrections without changing the ruled graph plane or adding runtime claims. Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box * Align graph architecture with ruled solo topology (#6154) Carry A10 into the architecture and embedded-leg summaries, reconcile minting and registry references, and record merged Read/RU dependencies alongside the published TX draft and Jim's dated checks. Preserve the formal change-request hold and phase-specific implementation/evidence gates. Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box * Reconcile solo authority mechanisms and remaining graph review references Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box * docs: complete A10 solo authority consistency sweep Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box * docs: close approved graph review follow-up nits Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box * docs: reconcile graph adoption and remaining phase gates (#6154) Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box --------- Co-authored-by: Claude Fable 5 --- engdocs/BDP_BEAD_GRAPH_PLAN.md | 1467 +++++++++++++++++++++ engdocs/BDP_GRAPH_ARCHITECTURE.md | 422 ++++++ engdocs/BDP_GRAPH_CLI_AND_STORAGE_SPEC.md | 1262 ++++++++++++++++++ engdocs/DOC_INVENTORY.md | 4 + 4 files changed, 3155 insertions(+) create mode 100644 engdocs/BDP_BEAD_GRAPH_PLAN.md create mode 100644 engdocs/BDP_GRAPH_ARCHITECTURE.md create mode 100644 engdocs/BDP_GRAPH_CLI_AND_STORAGE_SPEC.md diff --git a/engdocs/BDP_BEAD_GRAPH_PLAN.md b/engdocs/BDP_BEAD_GRAPH_PLAN.md new file mode 100644 index 000000000..bd0170aed --- /dev/null +++ b/engdocs/BDP_BEAD_GRAPH_PLAN.md @@ -0,0 +1,1467 @@ +# BDP in beads: the bead-graph plan + +**Status:** Draft v28 — feat/bead-graph — W-arch amendments **A1–A9 and rulings 13–14 RULED 2026-09-07; A10 RULED 2026-09-08**; every P-1 decision is ruled; **P0 is open**. (Thirteen adversarial review rounds: +1–7 on the whole plan, SOUND at round 7; 8–13 on the storage-interfaces +section, SOUND-ADDITION at round 13; v6 withdrew the Issue projection from +v0 on review-round-5 counterexamples; v9–v11 record the P-1 ruling tranches — all +twelve decisions are ruled; v14–v21 reopened P-1 for the nine amendments; v22–v23 record all nine ruled; v24–v25 record rulings 13–14; v26 records the 2026-09-09 source alignment and council gate/traceability corrections; v27 carries the 2026-09-10 formal-review corrections and dependency refresh; v28 records P0 Read adoption on this owning design surface and the 2026-09-12 dependency refresh; P0 current-wire completion remains open) +**Date:** 2026-09-12 (v27: 2026-09-10; v26: 2026-09-09; v1: 2026-08-31; v25: 2026-09-02) +**Owners:** Donna Box (ruling), janet (drafting/implementation) +**References:** the BDP spec (gastownhall/bdp `docs/specs/bdp.md`), beads#6051, +this repo's `backend/` conformance surface, `engdocs/PROJECT_CHARTER.md`. + +## Terminology + +- **Graph beads / graph links** — Resources in the **graph store**: the + BDP-shaped tables (beads, links, Type Descriptors, allocation/tombstone + ledger, authority marker) reached through the normalized storage + abstraction and served over BDP. ("Native" was retired: inside this repo + it reads as the existing implementation, the opposite of what was meant.) +- **The graph store** — the graph contract realized by any storage provider + (Dolt in tree is the reference realization; other providers plug in + through the same `backend/` contract). +- **Issues / Dependencies / wisps** — the existing issue stack. Unchanged, + not served over BDP in v0. +- **The bead graph** — the union concept from ruling 1: the graph beads will + eventually hold work AND non-work information (wisps being the existing + example of non-work information) once the C lane lands. + +## 0. The BDP pin, and the spec-first dependency + +The original P0 wire input targeted the BDP spec **as of the owned-Links rulings**: +**BDP commit `0b7d86e7`** (the gastownhall/bdp PR #18 merge, 2026-09-07, carried attribution for #10; supersedes the `aee075f5` pin of PR #17), +schema bundle `schemas/bdp-v0.schema.json` at that commit, Read conformance +matrix `packages/conformance/matrices/read-v1.json` at that commit +(40 scenarios: 35 normative + 5 diagnostic, all profile `read` — counted at the pin +during P0 vendoring; earlier drafts said 38). +**No implementation phase begins until the pin is written here.** BDP remains +a draft; "matrix green" exits below mean green against the *pinned* matrix, +re-pinned deliberately, never against a moving `main`. + +### P0 Read adoption record (2026-09-10) + +The current P0 contract input supersedes the original pin above with the exact +BDP Read foundation merge `19923f5bb6cc3f4ee4c508e36df3bd4c5c52344b`. +The spec blob is `79049a703ef957e3eed7cbe56c093356c47b0658`. The vendored +27-definition schema SHA-256 is +`e4c4b7bebd75fe06cd4f7a39c5731c774bf23437dd7d01114819b436b624e4d3`; +Read catalog SHA-256 is +`8867d1eed53f9f37047e11835c0a5a2021d9ff3140f64245cd38735f754d9924`; +46-plan Read matrix SHA-256 is +`4e087ff545b514e9cc0608ffebc8ccd7deeb0a9baa2cdd67c5450a9ea9e0900a`. +The upstream ordered named Read projection is +`b4c13b1d8e78bd556ace7db9c65729f86ea43428c069168bc3aba84bbe073d1a`, +recorded in [`docs/design/evidence/read-cohort/read-v1.json`](https://github.com/gastownhall/bdp/blob/19923f5bb6cc3f4ee4c508e36df3bd4c5c52344b/docs/design/evidence/read-cohort/read-v1.json) +at `targets[].segments[].bindings.schemaReadProjection`. This is the SHA-256 +of canonical JSON/JCS bytes of the ordered `[name, definition]` pairs for the +27 sealed names, not a source-file hash. The pinned +[`projectReadSchemaBundle` recipe](https://github.com/gastownhall/bdp/blob/19923f5bb6cc3f4ee4c508e36df3bd4c5c52344b/packages/conformance/src/schema-read-projection.ts) +defines that order; the [cohort generator](https://github.com/gastownhall/bdp/blob/19923f5bb6cc3f4ee4c508e36df3bd4c5c52344b/scripts/generate-read-cohort.mts#L565-L569) +binds the digest and the [evidence gate](https://github.com/gastownhall/bdp/blob/19923f5bb6cc3f4ee4c508e36df3bd4c5c52344b/scripts/read-cohort-evidence.mjs#L332-L358) +recomputes it. +This is provenance of the adopted upstream Read input, not Go observation evidence. +All six verbatim files and 13 extracted examples have complete byte/blob/range +records in [the dated PROVENANCE snapshot on the published P0 branch](https://github.com/gastownhall/beads/blob/a4b0ff638b4a5cebbe1b2d504897ae1449bd308f/internal/httpapi/bdpwire/schema/PROVENANCE). + +Local source adoption is recorded by `4ab80d75f3a11a9c53c5404251899eb1d4d29170`; +`fdfb2738d58e107b714013a4c5a6eb4b19461c52` corrects Go/ECMAScript line-terminator +parity without changing those vendored bytes. The tests on the dated Beads base and seven +executed Dolt spikes are recorded in +[the dated P0 verification snapshot on that published source](https://github.com/gastownhall/beads/blob/a4b0ff638b4a5cebbe1b2d504897ae1449bd308f/engdocs/BDP_P0_VERIFICATION_ROWS.md#current-main-read-contract-refresh--2026-09-10). +The P0 tree's own verification copy supersedes that snapshot's Files/Rerun guidance. +The initial refresh passed 95 top-level / 192 including subtests, zero skips. +That adoption updated the vendored inputs and DTO parity together, replaced +the old wildcard-rejection tripwire with adoption checks, and ported #27's +narrow `resource-erased` pointer prohibition while preserving harmless +RFC 9457 extensions, as recorded in the dated verification snapshot. +These are contract and spike checks. Hosted review/readiness, P1 mechanisms, +P2 HTTP serving and P3 write-profile adoption remain separate gates. These +dated results do not establish current hosted review or merge readiness. + +Model laws this plan builds to (the baseline pin plus the dated #19/#20 +Mutation results correction, pinned in §0a): + +- A Link is first-class; its `id`, `type`, `source`, `target`, and pin are + immutable; repoint/re-pin is delete-and-create. +- **Owned Links:** a Bead Type may own outgoing Link Types; each owned Link — + target, pin, and properties — is part of the source Bead's versioned state; + every mutation of an owned Link (create, delete, property update) versions + the source. The record read serves an `ownedLinks` member: complete Link + records, keyed by owned Link Type URL, ascending code-unit id order. + Unowned incident Links are a view and version nothing. +- Revisions are opaque and equality-only. **Each surviving Resource whose + state actually changes receives a fresh opaque revision; a semantic no-op + (RFC 6902 §4.6 value comparison) changes none; and A→B→A is three + distinct revisions — a reverse transition never reuses one.** Deletion + mints nothing for the deleted Resource — its result reports the deleted + identity **including its final live revision**, in the shared + `deletedIdentity` schema, carried as the result's `deleted` member + (`{ resourceKind, resource: { id, type, revision } }`; #19 Mutation results + in §0a, shared with #20); an owned-Link deletion result + additionally reports the owning source's fresh revision. +- References: the URI is identity; a pin is provenance, echoed byte-identical, + equality-only, never validated in v0. In-Scope and external references have + different canonicalization duties — the Go model captures them as a sum, + not a naked pair. +- Authorization views are closed projections, closed over owned Links. +- The Read problem table is closed vocabulary (including `resource-pruned` + and `resource-erased` — merged in gastownhall/bdp#16). + +## 0a. Current BDP and versioned-beads alignment (2026-09-09) + +This dated alignment updates the historical survey and P3 dependencies without +changing the ruled v0 scope: **graph Beads/Links only; no Issue projection**. +The original §0 Read pin above this historical alignment was superseded by +the dated P0 adoption record above. Neither pin is a claim that it +contains subsequent rulings. Donna's 2026-09-09 continuation authorizes +materialization on the condition that this design and P0 track both evolving +BDP and Jim's versioned-beads work, as recorded in the [operator continuation](https://github.com/donnabox/agent-coordination/blob/4fd57836ae052dec41b66493b88954bdabbb4d0f/context/janet/beads-workstream-state.md). The following are read/verified source +pins; the continuation and History ACK below are operator records, not +implementation pins. These dependency records do not authorize implementation +against moving drafts or treat draft PRs as merged dependencies. Before P3 +begins, its owner records a reviewed pin for the selected write profile in §0: +spec, bundle, problem rows, catalog, illustrative fixtures and executable matrix +(or its explicit pending status). The claim-specific evidence exit remains +required; a source pin alone cannot discharge it. + +The following tables preserve the **2026-09-09 and 2026-09-10 source snapshots**. +The 2026-09-12 refresh below supersedes their dependency statuses. + +| Source | Exact pin | State / graph consequence | +| --- | --- | --- | +| BDP #19 Read+Update | `06ebabdb391d8ea730295f4e01ed00bc1206fe38` | Draft; singleton/sequence envelopes, durable admission/outcomes, aliases and shared deleted identity now exist; P3 must adopt their reviewed selected-profile successor under the explicit write pin. | +| BDP #20 Transactional | `5c3f3b10a2edbb77d914b7260cdf035008fc34c7` | Draft; T1–T65 ruled, including unresolved admission, bounded direct comparison and same-epoch retraction retry without deadline reset; T57 implementation/evidence work remains. | +| BDP #22 wildcard / #23 numeric | `c201cc28f74c6f71212aaf7f25966aabf55fb97e` / `2c537a6f8a4f42e4fef0fa5d47439bcb25d2efe7` | Draft sources for the domain rules already incorporated ahead of P0's old wire pin; reviewed wire integration remains required. | +| BDP #24 named Read projection / #27 Read erasure correction | `87de37f673f83ec54989fdff4891bacc05730ea6` / `d68cc698f63cc114a41d7d965a8b6bebbfda8b3c` | Draft; preserve named-projection/coverage law and genuine successor evidence; port the narrow erased-pointer rejection to the Go wire boundary. | +| Jim #6147 Phase 0 | `9c4e7a8f1959582f07db3b87641cb33863fda860` | Open; contract hooks remain nil/skipped, not a working CAS/History implementation. | +| Jim #6304 Phase 1 | merge `2bb1e20de0f0072d7600656ea3cb7f606929dcc6` | Merged 2026-09-08; migration 0067 includes issue/wisp shape parity, ignored-series twin and raw-SQL replay / CLI override. | +| Jim #6358 Phase 2 | `5fdfb92fe544c9a83feb098e83f2ccdd87b896c8` | Open; current writer/inventory, superseding older incomplete call-site reports; 0068 reserves attribution and byte-preserving storage, not the deferred durable-address migration. | + + + +### Historical dependency refresh (2026-09-10) + +That docs-only successor incorporated Beads main +`a690b0a8c4d1ddc4f0bd9bf767499625dd71bc96`. It preserves both dependencies: +**BDP #19/#20 and Jim's versioned-beads work**. The source/check observations +below describe that date, not current readiness. + +| Source | Exact current source | State and phase consequence | +| --- | --- | --- | +| BDP Read foundation #29 | merge `19923f5bb6cc3f4ee4c508e36df3bd4c5c52344b`, source head `599361130bfaa07c2b5d157f3ecbe44f0691cb9e` | Merged 2026-09-10. Adopted by the P0 successor in the dated §0 record above, including bundle/projection/matrix pins and current-base checks. Wildcard, numeric, named-projection and erased-pointer corrections from #22/#23/#24/#27 are incorporated ancestries. The earlier design-only refresh did not perform this adoption. | +| BDP #19 Read+Update | merge `6d88f857cb643fe4e5d77e1dc45038a7d2e5ebb5`, source head `a2531e43baa5c6b27f22149b214326d8736e6198` | Merged 2026-09-10 wire/spec, without RU runtime. A P3 RU realization adopts a reviewed selected-profile pin and its own evidence; it need not wait for TX-only runtime. | +| BDP #20 Transactional | published PR head `5c3f3b10a2edbb77d914b7260cdf035008fc34c7`; reviewed local correction `0166ff8ef57c481f9ee8fb1223f728f12f9c75f4` (unpushed; no fetchable source pin) | Open draft at the published head. The local correction contains the reviewed G1–G5 HTTP clarification; it is not the remote PR head or a merged dependency. Shared Read HTTP implementation and fresh observations remain a gate before #20 lands. | +| Jim #6147 Phase 0 | `9c4e7a8f1959582f07db3b87641cb33863fda860` | Open; snapshot shows 117 successful, two skipped and two failed checks (PR Core and CI Gate / Required). Nil-hook contract scaffolding is not graph CAS or History realization; these failures are not automatically P0 blockers. | +| Jim #6304 Phase 1 | source `162a47703bb702d43e3192c79b6b802cf650d31d`, merge `2bb1e20de0f0072d7600656ea3cb7f606929dcc6` | Merged 2026-09-08, including 0067. Its historical head had 119 successful and one skipped checks. | +| Jim #6358 Phase 2 | `5fdfb92fe544c9a83feb098e83f2ccdd87b896c8` | Open; snapshot shows 121 successful and two skipped checks, with both CI Gate / Required checks successful. This is its own check evidence, not graph conformance. Migration 0068 remains reserved; graph P1 rechecks its actual slot. | + +### Current dependency refresh (2026-09-12) + +The Beads base remains `a690b0a8c4d1ddc4f0bd9bf767499625dd71bc96`. +The following source updates change dependency status, not the adopted P0 +Read contract or its historical verification results: + +| Source | Exact current source | State and phase consequence | +| --- | --- | --- | +| BDP #20 Transactional | merge `741829b6423ed70fd23676576459ad9f6215d027` | Merged wire/spec, including the shared G1–G5 HTTP clarification. The earlier local `0166ff8e` correction is historical. This is not TX runtime or a Beads profile adoption. | +| BDP #30 History | merge `1fe8cf32afabd02ca62d86548409f82dd756e357` | The selected History wire/spec materialization is merged. Server/client/adapter realization, provider mapping and capability advertisement remain separate work. | +| BDP Read runtime through #40 | main `eac6017541895bb4cb1399e1a8056bb7375b185c` | [Dated BDP status and evidence boundaries](https://github.com/gastownhall/bdp/blob/eac6017541895bb4cb1399e1a8056bb7375b185c/STATUS.md) record subsequent shared Read work and its named-target qualifications. Those observations are not Beads evidence and do not re-pin this P0 to the later bundle or matrix. | +| Jim #6147 / #6358 | `9c4e7a8f1959582f07db3b87641cb33863fda860` / `5fdfb92fe544c9a83feb098e83f2ccdd87b896c8` | Both remain open. #6304 and migration 0067 are merged; Phase 2 claims 0068. Their checks do not establish graph conformance. | +| Advisory registry #6149 | `71b82aa02abd1284ce3b7b6bffc5952b6d66a4f8` | Still open, not a slot allocator. Its [current rows](https://github.com/gastownhall/beads/blob/71b82aa02abd1284ce3b7b6bffc5952b6d66a4f8/CLAIMED.md) propose Phase 3 at 0069–0070 and graph at 0071 if Donna agrees, while the graph row still says 0069+. This overlap is unresolved; P1 must recheck the actual slot after its ADR and owner coordination. No number is selected here. | + +The adopted P0 Read input is the explicit #29 merge, with the complete §0 +adoption pins, source/fixture provenance and current Go boundary checks recorded +above. The original pin and results remain historical. P0 proves contracts; P2 must prove live Go Read +serving, current-view/owned closure, HTTP behavior and stable cross-request +cursors. The preserved #29 cohort does not prove the later G1–G5 prose. +P1 retains its storage/replication ADR gate; P3 retains its selected write-profile +ADR and evidence gate. Neither full TX runtime nor Jim's remaining phases are +blanket prerequisites for P0. + +Current main already corrects the +old `docs/recovery/init-safety.md` freshness date; the earlier failed check was +a historical branch-base result, not a standing current-main failure. + +**BDP ownership and phase boundaries** (citations below preserve the historical +draft pins; the P3 adoption re-verifies owning text at its selected write pin). [#19 Mutation results](https://github.com/gastownhall/bdp/blob/06ebabdb391d8ea730295f4e01ed00bc1206fe38/docs/specs/bdp.md#L2814-L2843) +requires the deleted Resource's final live revision in the `deletedIdentity` +schema carried as `result.deleted`; no version is minted by deletion. The +owned-Link result's `source` is the source Bead's absolute canonical URL and +`sourceRevision` is that Bead's resulting revision on create, update and delete. [#20 admission/comparison](https://github.com/gastownhall/bdp/blob/5c3f3b10a2edbb77d914b7260cdf035008fc34c7/docs/specs/bdp.md#L1225-L1308) +requires a durable execution owner and immutable creator-attempt binding separate from +the graph authority lease. Direct unresolved comparisons wait outside the DB +transaction under one finite budget; sequence precedence remains nonwaiting. +The graph lease and allocation ledger do not implement receipts, exactly-once +admission or the TX projected erasure ledger. P3 owns that realization, and +Read+Update does not wait for TX-only implementation. Before P3 implementation, +its ADR audits the selected profile's storage and interface needs against P1: +migration additions, state-version coverage, fence triggers, replication +inspection and fence/decorator censuses, plus any declared source break and +CHANGELOG migration under A8. The initial eight-table P1 scope is not a promise +that every future profile fits it. This audit mandates neither new tables nor +another interface widening; shipped migrations stay frozen and any necessary +addition follows migration discipline. P1 need not wait for the full P3 design. [T65](https://github.com/gastownhall/bdp/blob/5c3f3b10a2edbb77d914b7260cdf035008fc34c7/docs/specs/bdp.md#L5532-L5542) +scopes persistent Event-consumer erasure claims to the existing changefeed/ +snapshot-ledger integration; Event delivery alone is not that assurance. +The same continuation also ACKed manifest-handle retrieval, same-epoch receipt- +page URL restart survival, body-less 406 negotiation refusal and the initial +receipt/finite-feed validator policy. At the historical #20 pin these five HTTP +choices were pending materialization. The merged #20 source and subsequent +BDP shared Read work are recorded in the 2026-09-12 refresh above. The graph +wire/serving phases must deliberately adopt the applicable reviewed contracts +and prove them at the Beads boundary, including shared Read consequences. + +**Jim's current contribution and limits.** The [current writer](https://github.com/gastownhall/beads/blob/5fdfb92fe544c9a83feb098e83f2ccdd87b896c8/internal/storage/issueops/version_history.go#L24-L65) +records dependency changes and final outgoing dependency state. The [current +inventory](https://github.com/gastownhall/beads/blob/5fdfb92fe544c9a83feb098e83f2ccdd87b896c8/VERSIONED-BEADS-WRITE-PATHS.md#L9-L49) +distinguishes 27 seam call sites, 46 must-mint entry points and 21 versioned +paths out of 34 listed live paths; these counts are not interchangeable. +Remaining limits include unchanged re-import minting, UOW's per-repository-write +`1+N+M` versions versus the direct-leg composite operation, and stranded +delete/rename/demote history. `current_revision` is a store-local ordinal; +`version_id` and participation migration steps are not implemented at this pin. +The allocator is single-writer **at a time**, even within one store. None of +these facts licenses substituting the Issue writer for graph operation-local +revision, identity, ownership or transaction guarantees. Future C-lane work +should build on this contributor work while proving its translation, rather +than citing the old uninstrumented-writer survey as current evidence. + +**Translation constraints.** On the normal Dolt write path, its JSON column +rounds metadata numbers before a version row is minted; the content token +describes the stored state. Jim's [correction](https://github.com/gastownhall/beads/pull/6422#issuecomment-5620982279) +withdraws the stronger normal-path history-collapse claim; a divergence is +reachable only off that path. Their admission follow-up after #6358 and the +cross-PR canonicalizer policy remain separate contributor-owned work. Jim's +writer preserves the resulting JCS bytes in LONGBLOB. The [BDP numeric rule](https://github.com/gastownhall/bdp/blob/2c537a6f8a4f42e4fef0fa5d47439bcb25d2efe7/docs/specs/bdp.md#L644-L661) +refuses inadmissible values before BDP mutation acceptance. An Issue-to-BDP +mapping must be established before allocating its BDP revision; it cannot +round or rewrite already-addressed BDP state. Random graph revisions, local +Issue ordinals, future durable UUID addresses, content tokens and TX erasure +digests remain distinct. Jim's empty actor plus `unknown` is not a valid +present BDP attribution with an empty principal: preserve truthful absence +or explicitly mapped nonempty attribution. Its current NULL agent/message +columns and writer timestamp do not implement BDP's new context contract. +Its [Phase 0 vocabulary](https://github.com/gastownhall/beads/blob/9c4e7a8f1959582f07db3b87641cb33863fda860/backend/conformance/expected_revision_contract.go#L26-L83) +has nil hooks and treats Unretained/disclosure as a later axis; BDP separates +incomplete reconstruction from authorization. Local Hold contracts are not +BDP wire holds, and product test shapes are not BDP conformance observations. + +**History direction selected; wire materialization merged, realization pending.** Donna +ACKed the earlier sixteen core choices and the final twenty-two initial-History +choices on 2026-09-09; the [durable ACK and consolidated choices](https://github.com/donnabox/agent-coordination/blob/4fd57836ae052dec41b66493b88954bdabbb4d0f/context/janet/history-tx-complete-ballot-20260909.md) +record the selected alternatives. This is a dependency record for the approved 38-unit +direction, not a competing normative definition. The historical pins did not +contain its resulting schemas; #30 now supplies the merged materialization +at the source in the current refresh. This realization must adopt and prove +that contract separately. The following preserves the selected direction: + +- Complete optional History on all three profiles, canonical Bead/Link + revision resolution and stable `view=versions` enumeration; retained + addresses survive restore, while other token fences remain. Enumerate + all retained versions, newest authority-order first, distinguishing + replacement lineage and incomplete bodies; omit erased and unauthorized + metadata rows. Authorized deleted-subject enumeration remains available. +- Subject-history-gated diagnoses, bounded missing-state diagnostics with + explicit completeness, no refusal windows, aggregate participation claims, + advance retention guarantees, sync hints or wire holds initially. + Participation requires positive knowledge; absence does not prove pruning. + Whole historical success requires current disclosure permission for its + owned state, with no partial record. Unauthorized subject-history callers + receive uniform `resource-not-found` / 404. Preserve known truthful direct + predecessor/successor relations on retained replaced records; an authorized + `latest-version` may name the current authority version. Do not invent + adjacency between replaced and current lineages. +- Immutable change context now: authority-observed **commit time**, one + instant per atomic transaction and separate instants for committed sequence + members; optional per-operation assisting agent/message copied to every + version that operation mints. Context accompanies version records, retained + rows and matching version-bearing Events under their authorization and + erasure rules. No-op comparison excludes context; legacy absence stays + truthful. This applies to versions minted under History capability, not a + retroactive requirement on unrelated non-History implementations. +- Initial local-store erasure assurance does not advertise generic persistent + consumer replication. Imported retained copies require positively + established erasure status; unestablishable copies are rejected/discarded. + Required Gone evidence and applicable permanent erasure ledgers survive + recovery. Generic pre-removal administration and extra import metadata are + deferred, as are exact-byte witnesses, extra scheme mapping and the + alternative surviving-citation deletion lifecycle. +- `revision-unrepresentable` is selected for positively established inability + to serve an existing bound BDP value faithfully, distinct from missing + pieces, unknown provenance and temporary I/O. `revision-allocation-unsafe` + is the selected write-only persistent repair-required conflict; transient + safety-inspection failure retains its existing temporary-failure behavior. + Their profile/schema fan-out is in the merged #30 materialization recorded + at `1fe8cf32` in the dated §0a dependency table; adoption and runtime proof + remain separate. + Historical resolution never makes an old token a current write guard: the + existing `expectedRevision` equality/current-state law still applies. + +**P0 completion gate.** Preserve the historical pin/provenance and review +records. The §0 adoption at `19923f5b` satisfied the selected Read pin, +coordinated vendored-input/DTO parity, wildcard-tripwire replacement and +narrow erased-pointer exits. Subsequent repins must again update the +bundle/examples/fixtures/matrix/DTO parity together, preserve the narrow +`resource-erased` prohibition and harmless RFC 9457 extensions, and honor +#24's named Read projection and actual successor provenance. Do not relabel +old evidence or blindly vendor the whole TX bundle. Hosted review and +landing remain separate, as do P1 mechanisms, P2 serving proof and P3 +selected-profile adoption under §7. A contracts-only P0 can precede full P3 +and Jim Phase 3. No graph capability, readiness or merge grant follows from +this alignment text or from Jim's versioning flag. + +## 1. Goal and constraints + +Implement BDP in this repo: a first-class graph store the +protocol (and eventually the CLI) is implemented in terms of, beside — not +instead of — the existing Issue/Dependency machinery. + +Hard constraints, in priority order: + +1. **Zero compatibility degradation, defined precisely (amended 2026-09-07, + A8 option A):** *same-version* legacy behavior is byte-identical — every + existing CLI verb, JSONL interchange shape, journal record, and sync path + behaves exactly as before on the same binary, with gate (non-TTY) output + byte-identical. Out-of-tree `backend/` implementations take the **source + break the storage interface already declares** (six one-line + `ErrUnsupported` stubs for the `BeadGraph*` accessors, called out in + CHANGELOG with the stub migration, the joint ReadyClaimer/BatchCloser + entry being the precedent); once stubbed they behave exactly as before. Schema + migrations keep their existing version discipline (an upgraded database + is "ahead" of an older binary, which refuses to open it — that is the + *current* contract, and this plan does not promise more than the repo + already does). Mixed-version rollout beyond that is out of scope unless + ruled otherwise. +2. **BDP fidelity** at the pin, provable by the pinned matrix under its + packaged/public-boundary and self-certified/in-process provenance + split. +3. **One seam per axis.** Two different seams exist and must not be + conflated: an outer **authority seam** (which workspace/store, which + authorization view, which read snapshot — `ScopeResolver`) selects + exactly one scope; the **representation seam** (graph store vs projected — + `unionscope`) is C-lane future work now that the v0 projection is + withdrawn (§5) — in v0 the resolver fronts the graph store directly. + Call sites see `graphops` interfaces; composites are the only + switches. + +## 2. What exists (survey — corrected after adversarial verification) + +- **Storage contract:** `internal/storage/storage.go` defines `Storage` as + **28 role accessors** (IssueLifecycle, IssueReader, IssueClaimer, + ReadyClaimer, BatchCloser, BatchCreator, DependencyEditor, Commenter, + Counter, Memories, …), each returning a role interface. Implementations: + `*dolt.DoltStore` under decorator chains (`hook_*.go`, telemetry) plus a + distinct **UOW/provider** chain. Documented policy: adding a required + `Storage` method breaks out-of-tree implementers. +- **Optional-capability idiom — with teeth:** bare type assertions on a + decorated store are a KNOWN BUG CLASS here: decorators embed an interface, + so methods outside it are not promoted; the repo requires `UnwrapStore` + peeling before optional assertions (`hook_decorator.go:160`) and carries a + regression test for exactly the silent-skip failure + (`cmd/bd/vc_recompute_test.go`). `bd serve` assembles a deliberately + narrow role source (drops hooks, keeps telemetry) — full unwrapping there + would change semantics. +- **Backends actually in tree:** server Dolt, embedded Dolt, and the + UOW/proxied path. **SQLite is gone** (`cmd/bd/backend_support.go`); + `backend/conformance` exists but `RunAll` openly does not exercise version + control, sync, or federation families. `backend/` has a completeness guard + requiring public aliases for every internal type reachable through the + contract. +- **Read paths are not snapshots, and not even read-only:** role reads open + a transaction per call (`dolt/store.go withReadTx`); issue paging is + offset-oriented and finalized above storage; and "ready" reads run an + advisory WRITE (waking expired defers) on server, embedded, and UOW paths; + even `OpenForReadOnlyCommand` returns a writable store. +- **Data model:** `Issue` (`internal/types/types.go:17–190`) is very wide + (well over 40 exported fields), `Metadata json.RawMessage` as extension + point, `RowVersion int64` equality-only with documented partial coverage. + `Dependency`: surrogate `ID` populated only by some read paths, endpoints, + `Type`, `Metadata` as **string**, `ThreadID`, **no revision**; + `depid.New(issueID, target)` keys on endpoints only — no type — so at most + one edge per (source, target) pair, and delete/recreate would reuse the + projected URL. +- **v0 REST precedent is narrow:** detail is the only **read** + representation carrying `revision` (`GET /v0/beads/issues/{id}`); + list/JSONL explicitly forbid it, while guarded **mutation** responses + (update, close) also return their resulting revision. The + HTTP layer maps ordinary typed errors to generated Problem DTOs centrally + (`internal/httpapi/problem.go`) — the house pattern this plan follows. +- **Auth today:** bearer tokens grant the whole surface and carry no user + identity or scopes (`internal/httpapi/auth.go`); routes run one + table-driven middleware path (auth, project identity, deadlines, + concurrency). Any BDP serving must preserve those semantics regardless of + listener choice. +- **Wisps:** same `Issue` struct routed to a second table by storage-class + flags; detail assembly carries `isWisp` explicitly and resolves + issue-then-wisp; the two tables share one logical ID space enforced by + transactional sibling checks (`cross_table_id_collision_test.go`). Wisps + are **private/transient: excluded from export and federation by default** — + so they are a policy decision for BDP serving, not a free rider. +- **The type shoehorn precedent:** `IssueType` is an open vocabulary + (decision, message, molecule, gate, event, plus `types.custom`); + `issue_type NOT IN` filters exist. Non-task semantics on the Issue chassis + is proven practice. +- **Memories:** `memoryops` is a separate key/value plane with its own role. + **Operator ruling 2026-09-01 (external to this tree): the memory system is + legacy** — successor is Memory-typed Beads on this graph; no new + investment. Note `Memories()` remains wired in `bd serve` today; retiring + it is future work outside this plan. +- **Charter tension, named honestly:** `engdocs/PROJECT_CHARTER.md` frames + beads as a focused issue tracker and prefers metadata over new schema for + extension concepts. A general graph store is a product-scope expansion. + **P-1 decision #1 is an explicit charter ADR** — this plan does not + proceed on implication. +- (Correction from v1: `internal/storage/domain` is UOW-specific machinery + over `types.Issue` and `.beads`-directory concerns, not a generic domain + landing zone. The graph package lands as its own leaf package.) + Two consequences, stated so "no new investment" is not misread: Memory-typed + Beads' change feed lands on the **graph plane** (ruling 8's changefeed, P3), + not on the journal; and the legacy `bd remember` / `bd recall` / + `bd memories` / `bd forget` surfaces survive as **projections over + `graphops` after P3**, which is the compatibility projection #5877 R24/R25 + describe. + +## 2b. Where BDP and the Issue/Dependency stack disagree + +The conflict inventory, consolidated. Each row is a law of the pinned BDP +spec set against behavior verified in the original survey; dated §0a +qualifications identify later contributor progress, not a retraction of the +historical observations; the last column says what the +conflict costs. This section is why the v0 projection was withdrawn (§5) +and is the requirements list for any C-lane path. + +| Area | BDP law (pinned) | Current Issue/Dependency stack | Consequence | +| --- | --- | --- | --- | +| Revision coverage | Every record read serves an opaque, equality-only revision; every state-changing operation on a surviving Resource mints a fresh one; a semantic no-op mints none | `RowVersion` has documented partial coverage (direct-UPDATE text paths bypass it); label writes touch only the labels table; revision is served on the detail read and mutation responses only — list/JSONL forbid it | No existing token can stand in for a BDP revision | +| Reverse transitions | A→B→A is three distinct revisions | `updated_at` is second-precision `DATETIME` with documented same-second ties; `bd import --allow-stale` restores old rows including timestamps | State-derived revisions are impossible (r5 blocker) | +| Out-of-band writes | (Implementation constraint, not spec text: BDP's revision/identity laws presuppose the authority observes every mutation) | `bd sql` permits arbitrary direct SQL; compaction rewrites text in place; backup/restore resurrects historical state | No complete mutation feed exists; only funnel (C1/C3) or storage-level observation (C2) can close it; for the graph tables, ruling 13's row-level fence plus the state-change validator | +| Identity non-reuse | Committed Resource URLs are never reassigned — surviving deletion and epoch changes | Same-ID delete/recreate is permitted; import UPSERTs over existing IDs and accepts caller-supplied historical `created_at`; rename (delete+create) can A→B→A-reactivate an ID | Legacy IDs cannot be BDP URLs without a durable allocation/tombstone mechanism the stack lacks | +| Attribution (bdp#18, merged 2026-09-07) | A carried per-version `attribution {principal, status ∈ claimed\|unknown}` — data, not evidence; supplied by every version-minting operation; outside `properties`; excluded from the no-op comparison | Issues carry `created_by` and per-field audit rows; no per-version carrier; bd's later versions cannot name their author | The bd realization maps `created_by` to a claimed principal with status `unknown` for later versions; the graph store carries the member natively (spec B4 attribution columns) | +| ID grammar | Creation-time canonical IDs, multi-segment supported, reject-don't-trim | Configurable prefix grammar + adaptive-length collision-probability IDs; validation checks prefix shape, not BDP path grammar | Eligibility/surrogate policy required before any legacy ID is served (C lane) | +| Type system | One immutable nominal declared Type per Resource; descriptors with `conformsTo`; a Type describes beads or links, never both | `issue_type` is an ordinarily mutable column; open string vocabulary via `types.custom`; no descriptors, no hierarchy | Type immutability is violated by ordinary updates (r5); descriptor catalog must be built | +| Edge multiplicity | Links are first-class; no uniqueness constraint on (type, source, target) | `depid.New(issueID, target)` — at most ONE edge per (source, target) pair, type excluded from the key | Dependencies structurally cannot represent BDP Links (S2 killer #1) | +| Edge versioning | Every Link carries its own revision; owned-Link mutations version the source | Historical survey: Dependencies carry no revision; dependency edits never touch the source Issue's `row_lock`; `Metadata` is a `string`, surrogate `ID` populated only on some read paths. Current-source qualification (2026-09-09, §0a): Jim versions the source through `current_revision` / `issue_versions`, a different witness from `row_lock`, including its outgoing dependency state | Dependencies still lack independent BDP revisions and endpoint-key multiplicity; source witnessing has progressed, but does not establish the BDP owned-Link contract | +| Snapshot reads | Collection cursors continue ONE logical projected snapshot across requests, bound to an authorization view | Per-call read transactions (`withReadTx`); offset pagination finalized above storage; "read-only" paths write (defer-wake); `OpenForReadOnlyCommand` returns a writable store | BDP Read semantics need a new snapshot port; existing role readers cannot serve it | +| Authorization | Per-request Authorization View — a closed projection, closed over owned Links; uniform 404 nondisclosure | Bearer token grants the whole surface; no identity, no scopes, no view concept | View mapping is a P-1 design, not a translation | +| Deletion lifecycle (Read profile) | Logical identity non-reuse survives deletion; `resource-pruned`/`resource-erased` disclosure vocabulary on reads | Deletion frees the ID for reuse; no disclosure vocabulary | The gone-family Read contract must be built in the graph store | +| Deletion lifecycle (Transactional) | Deletion results report deleted identity; tombstones and erasure records propagate on the changefeed | No tombstones; no erasure machinery | Transactional-profile obligations; arrive with P3 writes | +| Changefeed (Transactional profile) | Change Groups at Scope positions, projection advances, erasure records, no-Event erasures | The journal has a frozen vocabulary limited to Issue/Dependency/Comment payloads, emitted structurally inside issue mutations | Frozen journal stays untouched; the graph gets its own changefeed (§4 matrix) | +| Content model | One authored JSON properties OBJECT per Resource, schema-validated per Type | Typed columns (status enums, priority int, timestamps) plus a `Metadata` blob | The column→properties mapping is a design artifact (the C lane inherits §5's table) | +| Multi-writer history (Transactional/history contract) | One serialized serving authority per Scope; independently writable replicas and multi-authority merge of one Scope history are excluded | Independently writable Dolt clones merging later is a normal workflow | Decision 9: authority rule; foreign-clone graph merges out-of-contract | + +## 3. Thrust 1 — the abstract data model (Go) + +**What Go gives us:** structurally-satisfied interfaces — Java-interface +shape, Rust-trait spirit (implicit satisfaction, declared where consumed), +capability discovery by type assertion, composition by embedding. The repo's +role-accessor style is already exactly this idiom; `graphops` speaks it. + +Two layers, strictly separated (review Blocker 1/High 6): + +- **Wire DTOs are generated from the pinned BDP schema bundle** — the + protocol layer serializes those, and only the BDP handler maps domain + errors to generated Problem records. +- **Domain values are immutable and JSON-faithful:** + +```go +package graph + +// Properties is an immutable authored JSON OBJECT value (BDP properties +// are objects, not arbitrary documents): backed by copied raw bytes; +// rejects duplicate keys; preserves numbers (no float64 laundering); +// deterministic encoding; and provides the RFC 6902 §4.6 semantic-equality +// check that gates revision minting (a no-op write MUST NOT mint). +type Properties struct{ /* unexported: raw []byte + parsed index */ } + +// Ref is a sum, not a naked pair: an in-Scope reference (canonicalized at +// admission, resolvable locally) or an external one (opaque, preserved +// byte-identically). Both may carry an equality-only pin. +type Ref struct{ /* unexported discriminant; constructors enforce */ } + +type Revision string // opaque, equality-only + +type Bead struct { /* unexported fields; accessors */ } +// ID, Type (immutable), Revision, Properties. +// NOTE: ownedLinks is not physically duplicated inside the immutable +// authored Bead value — but it IS semantically covered Bead state. The +// port assembles it from the Links themselves, in the same snapshot, and +// EVERY record projection — singleton, collection item, selection item — +// returns a BeadRecord carrying the complete ownedLinks expansion, one +// entry per declared owned type, empty entries included. (Coverage — +// owned-Link mutations versioning the source — is a storage-transaction +// law, not a struct field.) + +type Link struct { /* unexported; ID, Type, Revision, Source, Target Ref, Properties */ } + +type TypeDescriptor struct { /* ID, Name, Describes, ConformsTo, PropertiesSchema, OwnsOutgoing{Label,Max}, endpoint constraints */ } +``` + +Laws in the package, tested once: canonical-ID grammar (reject-don't-trim), +canonical-URI ordering, owned-Link trigger law (as invariant checks the +storage transactions call), semantic no-op equality. BDP problem-code +constants live in the generated protocol layer, NOT here — the domain stays +transport-neutral and speaks typed Go errors. + +```go +package graphops + +// Scope answers Reads within ONE resolved (workspace, authorization view, +// read snapshot). Errors are ordinary typed Go errors — transport-neutral; +// the BDP handler maps them to Problems. +type Scope interface { + // BeadRecord = Bead + its complete ownedLinks expansion, assembled in + // the SAME snapshot. Collections return records too — for a Bead whose + // Type owns, the member is never elided from any projection (absent + // exactly when the Type owns nothing). Acceptance also asserts each + // inlined Link's type equals its entry key and source equals the + // containing Bead — mirroring the BDP parser's contextual laws. + // Plan-owned collection tests enforce all of it (the external matrix + // validates the schema but does not force the optional member's + // presence on every item). + Bead(ctx context.Context, id string) (graph.BeadRecord, error) + Link(ctx context.Context, id string) (graph.Link, error) + Beads(ctx context.Context, q CollectionQuery) (Page[graph.BeadRecord], error) + Links(ctx context.Context, q CollectionQuery) (Page[graph.Link], error) + IncidentLinks(ctx context.Context, bead string, d Direction) (Page[graph.Link], error) + Types(ctx context.Context) ([]graph.TypeDescriptor, error) +} +``` + +### The layering, in one picture + +```text +bd serve (HTTP/BDP) generated DTOs; error→Problem mapping + │ +ScopeResolver ← OUTER authority seam: picks workspace/store, + │ authorization view, and ONE ReadSnapshot +graphops.Scope (per snapshot) ← the "trait" + ├─ graphstore ← v0: S1 tables, the only realization + ├─ (unionscope + issueproj)← C-lane future, when Issues move into the graph store + └─ (tests, CLI later) +``` + +**ReadSnapshot is a first-class port**: one SQL transaction (or UOW unit) +backs all reads a request makes against the graph store. BDP cursors must +continue one logical projected snapshot; per-call `withReadTx` role reads +cannot provide that, so graph reads run their own snapshot-scoped queries. +Cursors bind (snapshot, view). Graph reads never call readiness roles and +never use writable "read-only command" opens (the defer-wake write is +exactly what a Read surface must not trigger). (Union cursors with per-leg +continuation are C-lane machinery, recorded in §5's historical record.) + +## 4. Thrust 2 — storage: additive, capability-resolved, no breaking change + +> **Superseded mechanisms (2026-09-02, W-arch v2).** The mechanisms this +> section proposes — `GraphCapable` as a separate optional interface, the +> `graphsource` resolvers, the `ReadSnapshot` lease, `backend/` aliases, +> and the `bd serve` optional graph field — are replaced by the house +> idiom in `BDP_GRAPH_ARCHITECTURE.md` §2a (role accessors on +> `storage.Storage`, `DBTX`-shaped shared bodies, per-call transactions +> asserting a store-owned authority witness, BDP rows mounted inside `httpapi`). +> The *rulings* this section serves are unchanged except where §9's +> "Amendments proposed by W-arch" block says otherwise. The text below is +> kept as the record of what was proposed and why. + +Not a bare assertion (review Blocker 3). One resolution policy with a +**typed** source — no `any` — and, per round 3, NO `UnwrapStore`: +`UnwrapStore` peels every `Unwrapper` including telemetry, which is exactly +what `bd serve` refuses ("never storage.UnwrapStore" — it performs one +concrete hook peel and keeps telemetry, `cmd/bd/serve.go:671`). Resolution +follows that model — targeted single-layer peels, each named in the result: + +```go +package graphsource // internal/storage/graphsource + +// graphops.GraphReadSource is what a plumbing stack must yield to serve +// graph reads: the snapshot opener plus the telemetry it must retain. +// (Full contract in "The storage interfaces, concretely" below: +// ErrGraphUnsupported = absence; any other error = operational failure.) +func ResolveGraphReadSource(s storage.Storage) (graphops.GraphReadSource, error) +func ResolveGraphReadSourceFromUOW(p uow.UnitOfWorkProvider) (graphops.GraphReadSource, error) +``` + +With regression tests mirroring `vc_recompute_test.go` for: hook+telemetry +chains (asserting telemetry RETAINED while exactly the hook layer peels), +the notifying UOW provider, and `bd serve`'s narrow role source. +(The resolver PAIR — `ResolveGraphReadSource` for the store arm, +`ResolveGraphReadSourceFromUOW` for the provider arm — is the name; P1 +uses both.) +Realization legs in tree — with the transport distinction the tree +enforces: **`bd serve` refuses embedded Dolt permanently** (its commit +protocol cannot satisfy the server's per-request atomicity contract, +`cmd/bd/serve.go:546`); it serves from server-Dolt/UOW **and registered +backends' store sources** (`serve.go:563`). **Embedded Dolt is a +storage-contract conformance leg, not a `bd serve` transport leg**; serving +BDP from an embedded workspace would need a separately ruled read-only +listener. (SQLite removed from the plan.) **And any registered provider +implementing the graph contract is a first-class leg** — proven by the same +conformance suite the Dolt realization must pass. Accordingly the graph +capability is part of the PUBLIC `backend/` contract from P1: `graphops` +types get public aliases, `GraphCapable` becomes a completeness-guard root, +and the graph suite is a conformance family from the start (ruling 9 flips +the earlier "in-tree-only until opened" hedge). + +Graph-store persistence (substrate S1): new `beads`/`links` tables in the normal +migration series, **plus the Type Descriptor store**: descriptors are +persisted rows (not compiled-in Go values), because every Read Scope must +advertise `types/` and mutation authorities must retain the pinned +descriptor contract closure. That means: descriptor bootstrap at graph +initialization, an operator installation mechanism for new Types, closure +validation with fingerprint retention on install, and acceptance coverage +in each phase (P1 persistence + serving, P2 the pinned Type scenarios, +P3 write-time contract validation). Revision minting gated on semantic +change (no-op preserves revision); owned-Link version coupling enforced in +the write transaction. +Where this plan says "ledger" it now means exactly one thing: the GRAPH-STORE +allocation/tombstone table written inside graph write transactions (the +journal-counter pattern the tree already demonstrates). Ruling 3's +condition is a contract obligation: testing whether a canonical ID was +ever allocated is a keyed point lookup — O(1) or O(log n) — never a scan; +the ledger is keyed by canonical URL. The deleted +read-time revision ledger does not return; no projection ledger exists +because no projection exists. + +### The storage interfaces, concretely + +**The level at which this is defined (ruling 9):** the graph contract lives +at the **normalized storage abstraction** — the `backend/`-level contract — +and any storage provider realizing it is the graph store for the Scopes it +holds. Everything below that names Dolt, `withReadTx`, `NewUOW`, or +`RunTxRead` is the **in-tree reference realization**, not the definition: +other providers (bts-rs's stores, out-of-tree backends) implement the same +contract and pass the same graph conformance suite. + +How the graph attaches to the existing storage architecture, member by +member — and what changes where: + +**What exists (verified):** + +```text +storage.Storage (interface, 28 role accessors) ← contract; adding a + IssueLifecycle() / IssueReader() / ... / Memories() required method BREAKS + ▲ implemented by out-of-tree stores +*dolt.DoltStore (concrete) + ▲ wrapped by (each embeds + forwards the interface) +HookFiringStore → telemetry.Storage → ... ← methods OUTSIDE the + ▲ or, separately embedded interface +uow.UnitOfWorkProvider (RunTxRead/RunTx) are NOT promoted + ▲ consumed by +cmd/bd/serve role-source table ← one concrete hook peel, + telemetry KEPT, never + storage.UnwrapStore +``` + +**What is added (and precisely what is not):** + +1. **`storage.Storage` does not change.** No new required method — the + documented breaking-change policy holds. The graph capability is a + separate, optional interface: + + ```go + package graphops + type Store = GraphReadSource // v0 alias: the read surface IS the + // store; write roles widen it in P3 + + package storage + type GraphCapable interface { + BeadGraph() (graphops.Store, error) // error = operational failure, + } // never "unsupported" + ``` + + (`graphops` owns `Store`, `GraphReadSource`, `ReadSnapshot`, and + `Scope`; the UOW adapter satisfies them by constructing a + `ReadSnapshot` over the transaction a direct `NewUOW` owns, answering + `graphops.Scope` queries from that one transaction.) + + `*dolt.DoltStore` implements it concretely. Exposure policy, settled: + **in-tree-only for v0** — out-of-tree implementation arrives only when + the contract is deliberately opened (claim 6), not by accident of an + exported interface. "Unsupported" and "broken" stay distinct all the + way up: resolution returns `(GraphReadSource, error)` with a sentinel + `ErrGraphUnsupported`; any other error is an operational failure and + must not be collapsed into absence. + +2. **Decorators do not forward it.** Forwarding through every wrapper is + the failure mode the tree already documents. Instead, resolution does + what `bd serve` already does — targeted peels, telemetry retained: + + ```go + package graphsource // internal/storage/graphsource — see placement below + + func ResolveGraphReadSource(s storage.Storage) (graphops.GraphReadSource, error) + // Peels the known hook layer, then — because telemetry's wrapper + // embeds the statically typed DoltStorage, so an inner BeadGraph + // method is NOT promoted through it — inspects THROUGH telemetry, + // asserts GraphCapable on the inner store, and explicitly re-wraps + // the returned graph source in the telemetry layer it peeled. Never + // storage.UnwrapStore. The result names every peeled/rewrapped + // layer; ErrGraphUnsupported means absence, anything else is failure. + func ResolveGraphReadSourceFromUOW(p uow.UnitOfWorkProvider) (graphops.GraphReadSource, error) + // The UOW access path CANNOT ride RunTxRead — it closes its unit of + // work before returning. OpenSnapshot instead takes ownership of a + // direct NewUOW; ReadSnapshot.Close performs the rollback/close. + ``` + + Graph reads carry the same telemetry issue reads carry — by explicit + re-wrap, not by promotion. + +3. **The one genuinely new storage primitive: the snapshot lease.** + Existing read helpers are per-call — `withReadTx` opens and closes a + transaction inside each role call, which is exactly why they cannot + serve BDP snapshot semantics. `GraphReadSource` therefore exposes: + + ```go + package graphops // owns Store, GraphReadSource, ReadSnapshot, Scope + + type GraphReadSource interface { + OpenSnapshot(ctx context.Context) (ReadSnapshot, error) + } + type ReadSnapshot interface { + Scope // unqualified: same package; all reads + Close(ctx context.Context) error // answer from ONE transaction + } + ``` + + The RESOLVERS live in a neutral assembly package, + `internal/storage/graphsource` — a SEPARATE package (not package + `storage`): it imports `storage`, `uow`, and `graphops`, and nothing + imports it back except composition roots (`bd serve`, tests). This is + forced, not stylistic: `uow` already imports `storage`, so placing the + provider-arm resolver in package `storage` itself would create a + `storage → uow → storage` cycle. `GraphCapable` stays in `storage` + (returning `graphops.Store`; `storage → graphops` is a leafward + import); the resolvers qualify every foreign type. + + A snapshot is request-scoped, and **`ScopeResolver` is its one owner**: + it selects workspace, authorization view, and opens the snapshot; the + handler receives and uses it; the resolver closes it when the response + is written. This is a new *lifetime* discipline, not a new engine + feature — the same Dolt/SQL transaction machinery `withReadTx` uses, + held open for the request instead of per call. Two P1 design items + with tests: pool interaction (a leaked snapshot must not pin a + connection indefinitely), and **detached, bounded close** — rollback + must run on a fresh bounded context, never the request context, which + may already be cancelled (the tree documents that rolling back on a + cancelled context burns the pinned connection). + +4. **Schema machinery: normal series, no special cases.** Graph tables + (beads, links, type descriptors, allocation/tombstone ledger) are + ordinary migrations in the existing series, subject to the existing + version gate (older binary refuses newer DB — §1's contract). No + changes to the migration framework itself; the ruling-13 fence triggers + are DDL in the same files, shipped through the unchanged runner (probed: + one multi-statement `Exec` creates `BEGIN … END` trigger bodies over the + tree's `multiStatements=true` DSN). + +5. **`bd serve` gets a separate OPTIONAL graph field, not a role-table + entry.** The existing role binding table is deliberately mandatory — + it aborts on any binding error, and the HTTP layer rejects partial + role sets — so BDP cannot join it as one more ordinary binding. + Instead: an optional graph source on the server config, populated at + assembly by the source-appropriate resolver (store arm or UOW provider + arm), with a conditional route-registration seam. `ErrGraphUnsupported` leaves BDP routes + unregistered (existing serve behavior exactly as before); an + operational error still aborts; and capability-present-but-no-Scope- + yet is a THIRD state with its own explicit representation — per + ruling 12 as amended by A2, `bd --graph-mode link serve` mints the Scope + on first serve under a configured URL and serves it honestly empty; plain + `bd serve` never mints and mounts only an already-minted held Scope; without a configured URL there + are no BDP routes — never conflated with capability absence. The optional field is populated via the source-appropriate + resolver (`ResolveGraphReadSource` for the store arm, + `ResolveGraphReadSourceFromUOW` for the provider arm — `serve.go` + assembles from both). + +6. **`backend/` (all providers): public from P1, precise about the + existing machinery.** Today `RunAll` never exercises the optional + capability families — `RunUnsupportedContract` proves their typed + refusals instead. The graph contract arrives as its own suite beside + them (the P1 graph-storage conformance suite) with a refusal contract + for non-capable stores; `GraphCapable` is a completeness-guard ROOT and + `graphops` types carry public aliases from P1, because providers other + than Dolt are first-class targets (ruling 9), not a later opening. + +7. **`issueops`, the journal, sync, and every legacy role: untouched.** + The graph store is a sibling under the same DoltStore, not a layer + over the issue roles — with the projection withdrawn, nothing in the + graph path calls them at all. + +### Lifecycle commands (ruling 12) + +> **Spelling as ruled 2026-09-07 (A2/A3/A6):** `bd bdp-serve` (now `bd --graph-mode link serve`) → +> `bd --graph-mode link serve` (the strict, minting command over the same +> `httpapi` server; `bd serve` mounts the BDP rows only when it holds an +> already-minted Scope); graph behavior is selected by the root flag +> `--graph-mode link|dependency`, never by a verb prefix; `bdp.scope_url` +> lives in tracked `config.yaml`, the per-workspace `link-graph.route` and +> `bdp.server` in untracked `config.local.yaml` (nothing in `metadata.json`). Detail: +> `BDP_GRAPH_CLI_AND_STORAGE_SPEC.md` Part A. + +Three commands, three responsibilities — the store, the Scope, and the +client: + +1. **`bd init` initializes the graph store** alongside everything it + initializes today: graph tables, the allocation/tombstone ledger, and the + Type Descriptor bootstrap, all against the normalized storage interfaces + (any provider). No separate `bd graph init`. A workspace therefore always + has a graph store; it does not yet have a *Scope*. +2. **`bd --graph-mode link serve` creates the BDP Scope on top of the store; `bd serve` + serves an already-minted Scope it holds** (as ruled 2026-09-07, + A2/A7/A9): on its first serve under a configured `bdp.scope_url` (ruling + 7a) `bd --graph-mode link serve` mints the Scope row, the `mint` ledger event, and the + built-in Type catalog in one **multi-phase, fenced** transaction (a shared + database: the dolt-ignored authority lease with its fence cell; a + configured remote — *deferred under A9*: fetch → ancestor check → scoped + commit → push), finalizes this workspace's + authority witness, and serves the Scope — honestly empty at birth, with + `beads/`, `links/`, and `types/` all present. Because the Scope URL is a + tracked project fact, **among serving commands, only `bd --graph-mode link serve` mints**: a plain `bd serve` on + an unminted store keeps the legacy surface up with a notice. BDP routes + are a conditional second table inside `internal/httpapi` behind the same + middleware, in v0 served only from SQL-server workspaces — the + unit-of-work leg (`bd serve` refuses embedded Dolt permanently; a + registered backend's store arm has no fence to offer, so its rows are + absent until it declares one). The mint runs as the spec's one staged startup sequence (shared read + → release → exclusive only when there is no Scope row → release → + shared serve). `bd serve` with no configured URL is + byte-identical to today; on a workspace that does not hold the authority + it keeps the legacy surface up with the BDP rows absent and a notice — + never a startup refusal on account of the graph. `bd --graph-mode link serve` refuses + (exit 2) in those cases. No development-mode URL derivation exists in + bd. (W2 decides whether `bd --graph-mode link serve` survives as the alias — default + yes; it is the serving minting path.) +3. **Client wiring — `bd init --bdp-server ` and `bd --graph-mode link client`** + (as ruled 2026-09-07, A6): one more `bd init` target, beside + `--server`, `--shared-server`, `--proxied-server`, `--team-server`, and + `--backend`, distinguished by rerouting ABOVE the normalized storage + abstraction (at the CLI): the link-mode read verbs become a BDP client of + the designated server. The per-workspace keys live in the untracked + `config.local.yaml`; the project fact lives in tracked `config.yaml`: + + ```yaml + # config.yaml (tracked) + bdp: + scope_url: https://beads.example/acme/ # what the authority mints/serves (7a) + # config.local.yaml (untracked, machine-specific; merged over config.yaml) + bdp: + # (link-graph.route: local | server, default local — the client route) + server: https://beads.example/acme/ # graph-verb target when client: server + ``` + + `bd init --bdp-server ` and `bd --graph-mode link client server --server ` + write `config.local.yaml`; generic `bd config set` refuses the + per-workspace keys with that guidance. Env: `BDP_SCOPE_URL` (7a) and + `BD_BDP_SCOPE_URL`; `BD_BDP_SERVER`; **`link-graph.route` is blocked from env** + like `backend`. The bearer token comes from a file only — + `BEADS_BDP_TOKEN_FILE` or a credentials-file section keyed by origin and + Scope path — never from an environment variable and never from a config + key. Precedence: env (where permitted) > `config.local.yaml` > + `config.yaml`; `metadata.json` carries nothing for the graph. `client` + is an explicit mode, never inferred from the presence of a URL. Issue + verbs are untouched. v0 routes graph verbs only. + +### Replication participation matrix (review High 4, corrected round 2) + +Each row is policy decided in P-1, not discovered in CI. "Byte-identical +legacy behavior" scopes to **legacy-only data and operations**; rows are +split by topology where the tree differs: + +| Surface | Legacy behavior (verified) | Graph-store policy (ruled; §9) | +| --- | --- | --- | +| Dolt push/pull (server + embedded) | rows travel; embedded pushes directly | graph rows travel identically | +| Merge settlement | `versioncontrolops/mergesettle.go` already settles metadata, dependencies, migrations, config, issues, labels, comments, and events, with seven-table FK-cascade repair — conflict dispatch is a hard-coded switch, separate from an always-considered FK-repair pass; NOTE `MergeWithStrategy` returns early on clean merges and plain `Merge` bypasses settlement entirely | graph settlement must be **centralized so every merge entry point runs it** (clean-merge early-returns and plain `Merge` included — enumerate or funnel the routes): identity/endpoint integrity, dangling-Link detection, owned-Link invariant validation. A pass can reject or quarantine invalid imported state; it CANNOT serialize two independently accepted `max`-violating writes after the fact — hence decision 9: BDP writes flow through one serving authority per Scope, and foreign-clone merges of graph tables are out-of-contract (quarantined on detection); **ruling 14 (2026-09-07) settles this row:** every SQL pull route fetches, inspects the eight graph tables against the tracking ref, and refuses a foreign or unexplained delta before merging; routes that cannot inspect first fall to the validator's revert; no graph-table conflict is auto-resolved and `--strategy` never touches one | +| Federation type-filtering | **server-topology-specific**; deletes `issues` rows by type | v0: graph tables ride federation **unfiltered, by decision** (rulings 9/14); a per-topology filter hook is post-v0, and filtering one endpoint must also drop/deny the Link (never emit a dangling edge) | +| Journal (frozen v0 vocabulary) | Issue/Dependency/Comment payloads only | **graph events are excluded**; a separate graph changefeed carries them; the frozen vocabulary is not extended | +| Export/JSONL (contract class) | contractual shapes | graph gets its own export lane; legacy shapes untouched | +| Backup / restore | whole-database state (a different contract class from export); a Dolt backup restore carries the working set, dolt-ignored tables included (probed) | ruling 11 as amended by A5 (ruled 2026-09-07): the installation-keyed authority witness (`.beads/graph-authority.local.json`) records the hash-chained ledger head; a restore keeps the file but the store no longer contains that head → refused until `bd --graph-mode link restore`, which shows continuity from a `bd --graph-mode link ledger snapshot` (recovery predicate) or rotates the Scope URL and epoch; providers DECLARE `LedgerDurability`; `bd backup restore` also marks the witness unverified | +| Wisps | private/transient; excluded from export/federation by default | **ruling 6:** not served in v0 (C-lane note) | + +## 5. Thrust 3 — Issues/Dependencies beside the graph + +### The seam decision (HISTORICAL — C-lane record; superseded for v0 by +the withdrawal below) + +What follows is preserved as design input for the C lane, not v0 scope. +Option A (projection port + union composite) over B (peer interfaces on the +structs), C (storage unification now), D (call-site switches) — with the +review's correction adopted: the union is the *representation* seam only, +subordinate to the outer authority seam, snapshot-scoped, and: + +- **Duplicate full Resource ID across legs is an integrity error, never + precedence.** The v1 "native first, then legacy" shadowing is withdrawn. +- **Namespace AND ledger — they answer different laws (round-2 + correction):** a reserved graph-store namespace prevents *collisions*; it does + nothing for *lifetime identity non-reuse* (a deleted projected Issue ID + must never be reassigned — BDP's no-URL-reassignment law survives + deletion and epoch changes). So: namespace disjointness for allocation, + PLUS a durable allocation/tombstone guarantee behind every exposed URL, + graph-store and projected — covering legacy import's same-ID UPSERT and + Dependency delete/recreate reuse. And an **eligibility policy for legacy + IDs** (P-1): an issue ID that is not a canonical BDP path segment is + omitted, mapped to a stable surrogate, or fails Scope projection — ruled, + not improvised (current validation checks prefix shape, not BDP grammar). +- **Cross-realization Links** (C-lane decision when projection returns): + if a graph Link may target a projected Issue, every legacy deletion + needs a graph coordinator hook (else dangling edges); if forbidden, the + Type constraints must say so. Moot in v0 — nothing legacy is served. +- Multi-repo routing stays where it is — `ScopeResolver` wraps the existing + owning-store resolution; the union never spans stores. + +### The substrate decision (SETTLED for v0: S1) + +S1 (new tables) is the v0 substrate — with the projection withdrawn there +is nothing for a chassis substrate to buy: S2's free-rider argument was +chassis sync for *legacy interop*, and v0 has none. The historical +scorecard stands as C-lane input: S2 fails conformance on three laws +(`depid` admits one edge per endpoint pair — no type, no multiplicity; +Dependencies carry no revision; dependency edits don't version the +source); S2-lite was the fallback only while a projection existed. + +**Current-source qualification (2026-09-09):** the dependency-writer statement +above describes that historical substrate. Jim's Phase 2 now versions the +referencing Issue when an outgoing dependency changes and captures its complete +outgoing dependency set. Its current limits and the BDP translation boundary +are recorded in §0a above; this progress does not turn Dependencies into +first-class BDP Links or reverse the ruled v0 projection withdrawal. + +### The Issue projection is withdrawn from v0 (round-5 conclusion) + +The conflict inventory in §2b is the full map; rounds 3–5 tested every +read-side fidelity mechanism against it, and each fell to tree +counterexamples: + +- **State tuples** (r3): label add→remove recreates the tuple; direct text + restoration moves only second-granularity `updated_at`. +- **Read-time witness ledgers** (r4): witness reads, not transitions — + legacy A→B→A between reads serves the old revision. +- **Complete-representation state hashes** (r5): `updated_at` is + second-precision `DATETIME` and the tree documents same-second ties, so + A→B→A within one second reuses the hash; `bd import --allow-stale` + deliberately restores old rows including `updated_at`; `bd sql` permits + arbitrary direct writes no witness can enumerate; merge resolution and + backup restore reinstate historical rows. +- **Birth-identity URLs** (r5): same-second recreation collides; import + accepts caller-supplied historical `created_at`; import-over-existing + does not converge `created_at` across replicas; rename A→B→A reactivates + the original URL; database restore resurrects old tuples. BDP's + never-reassign law cannot be met. +- **Type immutability** (r5): legacy `issue_type` is ordinarily mutable; + BDP declared Types are immutable. + +The historical round-5 assessment was: mutation-time witnessing — the only +remaining mechanism — would require instrumenting every legacy write path +including `bd sql`, which is +arbitrary SQL and cannot be completely instrumented even in principle. +The conclusion is structural, not incremental: **a store that permits +timestamp ties, stale restores, arbitrary SQL, and identity resurrection +cannot be projected into BDP's revision and identity laws by any read-side +mechanism.** Current-source qualification (2026-09-09, §0a): Jim's writer +now versions 21 of 34 listed live paths, including outgoing dependency edits; +this is mutation witnessing, distinct from the old `row_lock` survey. Unchanged +re-import currently mints, UOW can mint per repository write, and raw SQL, +restore and merge-settle remain outside that witness contract. This progress +does not prove complete BDP translation or change the historical conclusion +about read-side reconstruction. So v0 withholds the projection: + +- The v0 BDP Scope serves **graph beads and links only**. +- Issues keep their existing surfaces (CLI, REST v0, JSONL) untouched. +- Issues join the graph when storage unification (Option C) moves them + into the graph store — where operation-local revisions and durable + identity are properties of the write path, not reconstructions. The + union composite and this section's counterexample record are the design + input for that future lane. +- The `unionscope`/`issueproj` machinery drops out of v0 scope; the + authority seam (`ScopeResolver`: workspace, view, one ReadSnapshot) and + `GraphReadSource` remain — they serve the graph store. + +### The C lane: paths to Issues/Dependencies on the graph (informative) + +Operator direction (2026-09-02): the withdrawal stands for v0, and the C +lane should be sketched now. The round-3–5 counterexamples fix the shape of +the solution space: **uniform versioning requires that every mutation +either funnels through one write path or is completely observed at the +storage layer.** Read-side reconstruction is proven impossible. That yields +three paths: + +- **C1 — Funnel with a legacy compat shim** (the operator's sketch): Issues + and Dependencies become graph beads/links; the legacy surfaces (CLI + verbs, REST v0, JSONL, journal, sync) are reimplemented as a compat + adapter OVER the graph store, reproducing legacy behavior byte-for-byte. + Versioning is uniform because every mutation goes through the graph store's + write path. The crux is what "keep the current code path" means at the + storage layer: if legacy code keeps writing legacy TABLES, the bypasses + persist and uniformity fails; so C1 means legacy *behavior* preserved + over graph *storage* — and the hard cases are exactly the round-5 + killers re-specified deliberately: `bd sql` (verification task: whether + Dolt supports legacy-compatible updatable views that can route DML + through graph revision/tombstone semantics — else direct SQL is + re-scoped), import `--allow-stale` (becomes a versioned operation), + backup/restore (restores history, not just state; decision 11). The + wisp precedent (plane routing at storage, surfaces unchanged) is the + house style for this move. +- **C2 — Observe: a complete mutation feed at the storage layer**: legacy + tables remain the record for legacy surfaces; a storage-level observer — + DB triggers on the legacy tables feeding a transition log in the same + transaction — would give the graph per-operation revisions and + tombstones without touching legacy code paths, and would be the only + observation variant that survives round 5 IF the following verification + tasks all pass (the original C2 survey did not establish them): (a) Dolt + trigger availability and transactional semantics; (b) whether direct `bd sql` DML actually + fires them (noting `bd sql` is unavailable in embedded mode and runs via + direct SQL-server or proxied-server paths — and UOW is an access path, + not a third storage engine); (c) trigger-row behavior under replication, + merge, and restore; (d) Scope URL/epoch handling after restore + (decision 11). Current-source qualification (2026-09-09, §0a): the graph + fence probes and Jim's application-level version writer are later evidence + with their own scopes; neither proves this complete legacy observer. Build + on the current writer/inventory rather than repeating a claim of no mutation + witnessing; raw SQL, restore and merge-settle coverage still needs proof. +- **C3 — Cutover**: one-time migration, graph store becomes the only + store, legacy tables dropped or frozen read-only. Maximum uniformity, + no dual bookkeeping, maximum one-shot risk; `bd sql` compat ends or + becomes views. Realistic only after C1's compat adapter exists and has + soaked — C3 is C1 minus the legacy tables, not an alternative to it. + +Sequencing implication: C1 and C3 share the compat-adapter investment; C2 +is the only path that leaves legacy storage untouched. A future C-lane +ruling chooses funnel (C1→C3) vs observe (C2) — and none of it blocks or +changes v0. + +## 6. Addressing + +One workspace = one Scope. Scope URL scheme is a P-1 decision (config key +vs derived). Graph-bead IDs mint under BDP creation-time rules (supplied +multi-segment or generated flat, reject-don't-trim) against the graph-store +allocation/tombstone ledger. No legacy IDs are served in v0. + +## 7. Phasing (re-sequenced per review; each phase exits green) + +> **Names in this section are superseded** (`GraphCapable`, +> `GraphReadSource`, `graphsource`, `bd bdp-serve` (now `bd --graph-mode link serve`), `bd bead`/`bd link` +> verbs): read them through `BDP_GRAPH_ARCHITECTURE.md` §2. Phase +> *boundaries* stand: P0 contracts + pinned wire, P1 storage (roles, +> bodies, migrations, conformance; the replication/merge ADR is a P1 +> gate), P2 serving (BDP rows inside `httpapi`; collection routes after the +> cursor ADR), P3 writes. **P0 is open (A1–A9 and rulings 13–14 ruled 2026-09-07).** + +- **P-1 — Decisions and pins (no code):** charter ADR; ratify the + projection withdrawal (v0 Scope = graph store only); Scope URL/identity; + graph-store allocation/tombstone design; serving authority; replication + matrix rows; auth-view mapping for bearer-token reality; + listener/authority-semantics choice. (The BDP pin is already written in + §0.) *Exit: every row ruled by Donna, recorded in this doc.* +- **P0 — Contracts:** wire DTOs held to the pinned schema by tests (hand-written, Part D.3); immutable + domain values (`Properties`, `Ref` sum, records); pure validators; typed + error vocabulary; the three ruling-13 verification rows — **answered + 2026-09-07: PASS / PASS-WITH-RULE / PASS-WITH-RULE** + (`engdocs/BDP_P0_VERIFICATION_ROWS.md` on the P0 branch; the fence + ships, with the rules spec B3/B4 now record). *Exit: model laws 100% + table-tested; DTO round-trip against pinned schema fixtures; the three + rows answered.* **Met against the historical §0 pin on 2026-09-07** on `janet-beadgraph-p0` (council 11: + three reviewers, all findings folded; graphops 100% statement coverage; + bdpwire 94%). This is historical completion only; §0a and the owner gates + below govern current-wire completion and later serving claims. Contracts-only + P0 promotion must name that scope and its remaining gates; it is not a graph + capability/readiness or upstream merge grant. +- **P1 — Graph read storage (S1):** the replication/merge ADR first + (ruling 14: `engdocs/BDP_GRAPH_REPLICATION_ADR.md`, council-reviewed; no + graph migration merges before it); record the A10 solo mint trigger and + workspace-gate ↔ lease-predicate mapping (architecture §2b) before wiring + the embedded leg; then tables + migrations (descriptor + store and the ruling-13 fence triggers included); typed snapshot-source resolution (`GraphReadSource`) + with single-request snapshot consistency and the zero-legacy-writes + regression (defer-wake); the resolver pair across the storage legs — + `ResolveGraphReadSource` for server/embedded Dolt (embedded as + storage-contract leg), `ResolveGraphReadSourceFromUOW` for the UOW + access path — with decorator regression tests; an internal, non-BDP + bootstrap/fixture write API (the only writer until P3) enforcing the + allocation/tombstone ledger; replication-matrix gates. *Exit: a NEW + graph-storage conformance suite — defined in this phase under + `backend/conformance`, enumerating the storage contract (snapshot + isolation, ordering, ledger enforcement, descriptor persistence) — + green on all legs (descriptor persistence AND inventory serving + included); cross-request cursor stability is explicitly NOT a P1 + claim.* +- **P2 — Protocol Read over the graph store:** snapshot-bound cursors — + including the **cross-request continuation mechanism** BDP requires + (later requests continue the same selected set, projection, and + revisions): a durable snapshot registry, materialized result sets, or + Dolt `AS OF` identity surviving through cursor expiry — chosen by ADR in + this phase; BDP handler through the existing middleware path + (auth/project/deadline semantics preserved); run the external BDP Read + matrix **deliberately re-pinned under §0** as a target. *Exit: that + successor matrix green, the applicable owner gates below complete, with its + own provenance split honored — packaged rows proven at the packaged + public boundary, self-certified in-process rows via the in-process lane + and labeled as such (the pinned artifact is explicit that they are not + black-box conformance) — plus a beads-owned public-boundary + cursor-stability test across requests.* +- **P3 — Writes and CLI, gated on its own ADR AND on upstream spec + artifacts:** the pinned write-profile envelope (an owned-Link mutation's + result must also report the source Bead's resulting revision), the + owned-Link Event delta, AND the sequence/idempotency envelope schemas, + problem rows at the reviewed write-profile pin recorded in §0 before P3. + At the historical §0a draft pins, #19 already has + [`packages/conformance/catalog/read-update-v1.json`](https://github.com/gastownhall/bdp/blob/06ebabdb391d8ea730295f4e01ed00bc1206fe38/packages/conformance/catalog/read-update-v1.json) + and illustrative [`fixtures/read-update/`](https://github.com/gastownhall/bdp/tree/06ebabdb391d8ea730295f4e01ed00bc1206fe38/fixtures/read-update); + #20 has [`packages/conformance/catalog/transactional-v1.json`](https://github.com/gastownhall/bdp/blob/5c3f3b10a2edbb77d914b7260cdf035008fc34c7/packages/conformance/catalog/transactional-v1.json) + and illustrative [`fixtures/transactional/`](https://github.com/gastownhall/bdp/tree/5c3f3b10a2edbb77d914b7260cdf035008fc34c7/fixtures/transactional). + These are catalog metadata and illustrations, not executable write matrices + or observed runtime evidence; those remain pending at these pins. The + shared HTTP ACKs are materialized in merged #20; this phase must adopt + their reviewed result and supply its own runtime evidence. + Profiles are **Scope-wide** + (uniformity law), and the Event-delta gate binds exactly the profile + that has Events: a Scope containing owning Types cannot advertise the + **Transactional** profile until the owned-Link Event delta exists — + Read+Update has no Events and is not blocked by it — and this is a + Scope-level gate, not a per-Type advertisement. Write tests require: create/property-update + mint fresh Link AND source revisions; **deletion mints nothing for the + deleted Link** — its result reports the deleted identity plus the + source's fresh revision; the deleted identity carries the Link's final + live revision, agreeing with `DeletedData` and changefeed tombstones + ([#20 Mutation results](https://github.com/gastownhall/bdp/blob/5c3f3b10a2edbb77d914b7260cdf035008fc34c7/docs/specs/bdp.md#L3328-L3347)); target revision + unchanged throughout; both surviving revisions preserved on semantic + no-op. Then tombstones, + endpoint constraints, replication of writes; only then + `bd bead`/`bd link` verbs. *Exit: the pinned write-profile conformance + artifacts green when they exist upstream, plus beads-owned transaction, + identity/non-reuse, deletion-result, installed-Type-contract + validation, and replication tests at the public boundary.* + +### Current-wire and profile adoption gates (2026-09-09) + +Owners below are phase responsibilities within this plan (janet's graph work); +BDP owns the upstream source/evidence products. A row is an exit condition, +not evidence that work has run unless a dated satisfaction record is stated. +The first three exits are satisfied at the §0 `19923f5b` adoption; they remain +prerequisites for a later repin. Preserve the historical P0 result above. + +| Work / owner | Phase and prerequisite | Required exit before the corresponding claim | +| --- | --- | --- | +| Read successor pin — P0 wire owner | P0 current-wire completion; reviewed upstream Read cohort | Satisfied at the §0 `19923f5b` adoption. On subsequent repins: record the selected spec/bundle/projection and matrix pins in §0, honoring #24's named projection and actual successor provenance. Never relabel old observations or import the whole TX bundle as Read. | +| Wire parity — P0 wire owner | Same P0 successor adoption | Satisfied at the §0 `19923f5b` adoption. On subsequent repins: update vendored provenance, bundle, examples, fixtures, matrix references and DTO parity together; replace the obsolete wildcard-rejection tripwire with the successor's applicable wildcard contract checks. | +| Erased-problem boundary — P0 wire owner | Same P0 successor adoption | Satisfied at the §0 `19923f5b` adoption. On subsequent repins: port #27's narrow `resource-erased` pointer prohibition with focused Go boundary checks, preserving harmless RFC 9457 extensions. | +| Response negotiation — P0 wire / P2 serving owners | Reviewed materialization of the shared HTTP ACK; P0 captures the contract, P2 serves it | Body-less 406 for unsupported response media and its normal failure/auth non-disclosure precedence are represented and tested at the Go HTTP boundary before current serving claims. | +| Applicable conditionals — P0 wire / P2 serving owners | Same reviewed HTTP materialization; apply only to the endpoints/profiles that use it | Preserve the selected native body-less 304/412 behavior, validation precedence and normal response metadata; do not substitute a BDP revision conflict. Prove the Read endpoint behavior at the public boundary; receipt/feed validator policy belongs to its P3 profile. | +| Read execution — P2 serving owner | Above applicable P0 contracts and the re-pinned Read matrix | Fresh applicable Go public-boundary observations, provenance-labelled in-process rows and the beads-owned cross-request cursor check; old P0 probes are not successor observations. | +| Selected write profile — P3 owner | Reviewed §0 write pin and P3 delta ADR | Adopt applicable admission, results and recovery contracts and approved HTTP successors; prove the selected profile's executable conformance and beads-owned exits. RU does not wait for TX-only receipts, Events or erasure-feed implementation. | + +A contracts-only P0 may land with the adopted §0 wire pin after its hosted +review and landing gates. The later completion owners remain explicit: +current-serving contract claims wait for the applicable remaining P0 rows; +Read serving claims also wait for P2. Neither requires all TX runtime or Jim's +remaining phases. A future Issue/History integration still needs its §0a +translation proofs; no new interface, table, capability or upstream merge +permission is selected by assigning these gates. + +## 8. Related workstreams (operator direction 2026-09-02) + +This plan covers the graph store and its Read serving. Sibling workstreams, +each owning its own writeup: + +- **W-arch** — `BDP_GRAPH_ARCHITECTURE.md` and + `BDP_GRAPH_CLI_AND_STORAGE_SPEC.md` (v17, 2026-09-12; v16: 2026-09-10; v15: 2026-09-09; + v14: 2026-09-02), eight council rounds with live Dolt probes; A1–A9 and + decisions 13–14 ruled 2026-09-07, with A10 ruled 2026-09-08 and recorded + in §9. + Preceded P0 code; P0 is open. +- **W1** — flesh out the **Update and Transactional profiles** of BDP and + the reference implementations (the protocol is Read-heavy today); this is + the upstream gate for P3 writes. +- **W2** — `bd --graph-mode link serve` / `bd serve` integration (as ruled 2026-09-07, + A2: one server, a conditional BDP route table): decide whether the + strict alias survives, whether BDP rows contribute a capability token, + and whether the current HTTP surface moves; nothing to fold in. +- **W3** — **inventory of bead types and generation of Bead/Link Types** — + in the beads repo, not bdp; feeds the descriptor store's bootstrap + catalog (§4). + +## 8a. Process + +All work on `feat/bead-graph`; slices land by PR with adversarial +convergence; the feature branch merges to main only at phase exits behind a +differential gate proving same-version legacy behavior unchanged. Spec +changes go to gastownhall/bdp first — this plan's §0 pin is the enforcement +of that. + +## 9. Decisions requested from Donna (the P-1 list) + +1. **Charter — RULED (2026-09-02): core.** The charter amendment FOLLOWS + working bits (the maintainers' own precedent: the charter file changes + when implementation lands). Its scope: *the bead graph expands to + include non-work-tracking information* (wisps being the existing + example) — a generalization of what beads already is, not a second + product surface. +2. **Substrate — RULED: S1** (graph tables: beads, links, Type + Descriptors, allocation/tombstone ledger, authority marker). +3. **Allocation/tombstone ledger — RULED:** append-only allocation record + per committed canonical ID (URL, birth authority id, epoch, + tombstoned-at), consulted before every create and by restore; + condition accepted as a contract obligation — the ID test is a keyed + point lookup, O(1)/O(log n), never a scan. (Namespace-vs-issue-grammar + and legacy-ID eligibility move to the C lane with the projection.) +4. *(Moved to the C lane — cross-realization Links cannot arise in v0; + see §5's historical record.)* +5. **Projection withdrawal — RULED: ratified.** The v0 Scope serves graph + beads and links only; Issues, Dependencies, and wisps keep their + existing surfaces and join via the C lane (wisps inherit every Issue + counterexample — they are plane-routed Issues). +6. **Wisps — RULED:** moot for v0 serving; recorded as a C-lane + *visibility* decision (wisps are private/transient by default today, so + their eventual graph entry needs a visibility ruling, not just plane + routing). +7a. **Scope URL scheme — RULED:** mirror BDP's pinned startup contract. + An explicit `bdp.scope_url` (`BDP_SCOPE_URL`) is required to serve a + real Scope; a `local-test` URL derived from the listener is permitted + only under an explicit development mode and is never persisted as + identity; the URL is persisted in the graph store beside the authority + marker; never derived from a git remote or workspace path; one Scope + per workspace, path-distinguished under one host. +7b. **Listener — RULED (amended 2026-09-07, A2):** same listener, same + table-driven middleware path; BDP routes are a conditional second route + table inside `internal/httpapi` behind the same `route()` wrapper, so + bearer-auth and project-identity semantics are preserved by construction; + among serving commands, only `bd --graph-mode link serve` mints, and `bd serve` never refuses on + account of the graph. v0 authorization-view mapping: one view per bearer + token = the whole Scope (no hidden Resources) — honest and conformant + until real views exist; federation/multi-view later changes the + mapping, not the listener. +8. **Journal/changefeed — RULED:** frozen v0 journal untouched; the graph + store gets its own changefeed as a contract capability arriving with + P3 writes (providers with a native event log realize it over that). +9. **Serving authority — RULED (corrected model):** the authority is the + graph store *as reached through the normalized storage abstraction*, + whichever provider realizes it — not `bd serve`, and not Dolt. The + authority marker (Scope URL + authority id, minted on first serve by + `bd --graph-mode link serve` under a configured URL — ruling 12 as + amended by A2; A10 separately permits local solo minting), + single-serialized history, non-authority refusal (of graph writes AND + BDP serving for that URL), and **single-transaction operations under a + store-asserted authority witness** (A1, ruled 2026-09-07; the snapshot + lease is withdrawn as a mechanism — cross-request continuation is P2's + cursor ADR) are graph-CONTRACT obligations proven by the graph + conformance suite; the CLI graph verbs + and the BDP handler are both clients of that abstraction, so they are + one authority on any provider. Dolt is the in-tree reference + realization. Promotion is explicit and epoch-rotating; **in v0 a Scope's + authority is a shared database that minted it**, except A10's embedded + solo topology (A9 ruled 2026-09-07, amended by A10 on 2026-09-08): + replication, restore, and copy confer nothing; promotion in place is a + self-regrant or an operator's explicit steal; a new database takes a new + Scope URL; the shared-database fence is the lease of A7. Consequence: the + graph is single-authority while Issues stay multi-clone-mergeable — + graph writes on a non-authority instance refuse with a typed error. + Replica *reads* from a non-authority instance are deferred until BDP + defines replica labeling (candidate note for gastownhall/beads#6051). +10. *(Absorbed into decision 5 — the round-5 review closed this fork: + withholding is the only conformant option.)* +11. **Restore vs identity — RULED: both, layered.** The ledger is + append-only and restorable independently of state (older state + + current ledger preserves non-reuse); providers declare whether their + ledger survives restore; when preservation cannot be guaranteed, + `bd --graph-mode link restore` (spelling per A3) rotates the Scope URL and + epoch and refuses the old URL. An epoch change alone is never + sufficient. +12. **Store, Scope, client — RULED (replaces "empty-at-birth"):** three + commands, three responsibilities (§4 "Lifecycle commands"). `bd init` + initializes the graph store with everything else, against the + interfaces — no separate graph init. `bd --graph-mode link serve` + creates the Scope on first serve under a configured URL (A2), and + serves it honestly empty; `bd serve` only mounts an already-minted + held Scope and never mints. No URL → no BDP routes. A10 separately + permits local solo minting and verbs, with no embedded HTTP serving. A + client-wiring is `bd init --bdp-server ` — one more `bd init` + target, distinguished by rerouting ABOVE the storage abstraction (at + the CLI) rather than below it (§4 "Lifecycle commands"); after it, the + CLI's graph verbs speak BDP to the designated server. Tests prove Issues never leak into graph inventories; + a provider implementing the six accessor stubs without the capability + keeps existing `bd serve` behavior — routes absent, never a startup + failure (A8, ruled 2026-09-07). + +13. **Out-of-role DML enforcement boundary — RULED (2026-09-07): "A+B".** + Out-of-role DML — `bd sql` in both modes, raw SQL clients, force-push, + and merges — is out of contract. The state-change validator refuses + invalid or foreign-authority graph state on every observed + state-version change; for the ledger-covered tables (descriptors, + allocations, the ledger itself) the delta must be explained by ledger + events since the recorded head, and bead and link bodies are checked + by row provenance (`last_authority_id`/`last_epoch`). The eight + replicated graph tables carry `BEFORE INSERT/UPDATE/DELETE` triggers, + installed by the graph migrations, that refuse a row unless the session + set the role variable `@bd_graph_role`; every graphops mutation sets it + inside its transaction and clears it before `COMMIT` or `ROLLBACK`. + The fence stops accidents, not holders of database credentials; a + DB-privilege boundary (two SQL users) is a C-lane task. Merges belong + to ruling 14. Probed on Dolt 2.1.8: the trigger shape parses (in + `BEGIN … END` form) and fires (errno 1644); a session variable gates + it; a transaction that commits without clearing leaves the pooled + connection unfenced, one that clears does not; the triggers replicate + through `dolt_schemas` by push, clone, and pull; they are silent on + `DOLT_MERGE` and `DOLT_PULL`; one multi-statement `Exec` of a migration + file creates them over the tree's DSN; privileges live in + `.doltcfg/privileges.db` per installation and never replicate. Three + P0 verification rows gate the fence (§7); if one fails, v0 ships the + validator alone and this ruling records it. **Answered 2026-09-07:** + (i) PASS — the embedded leg creates and fires the triggers; (ii) + PASS-WITH-RULE — a transaction cancelled between statements is pooled + with the variable set on both server legs, so the deferred clear runs + on `context.WithoutCancel` and poisons the connection when it cannot be + confirmed; (iii) PASS-WITH-RULE — the CLI migration bundle needs a + `DELIMITER` rendition, check D and `doltIgnorePatterns` must learn the + lease table, and a dirty `dolt_schemas` is refused late. The fence + ships. **Ruled 2026-09-08 (Part D.7 = A):** the validator and ruling 14's + inspection set carry a fence census over `dolt_schemas` — each of the + eight replicated tables must carry its three triggers; a missing one is + repaired with the migration's idempotent `DROP TRIGGER IF EXISTS` + + `CREATE TRIGGER` pair before a delta is judged, and the census never + changes the graph-state version. No new `bd sql` flag: the + deliberate override is a proxied-mode batch that sets the variable + first, or a raw client session. Option A alone (validator only), C + (two SQL users in v0), and D (a `bd sql` statement guard) were the + alternatives; C stays a C-lane task, D is redundant under B. + +14. **Replication/merge ADR — RULED (2026-09-07): option B, the gate plus + a four-law charter.** The ADR gates the graph migrations (P1) and is + council-reviewed before they merge; it writes mechanism and conformance + rows under these laws. (1) **Fetch, inspect, merge.** Every SQL pull + route fetches, inspects the eight replicated tables between HEAD and + the remote-tracking ref (`dolt_diff('HEAD', 'remotes//', + '')`), and refuses before merging when the delta is + foreign-authority or unexplained by ledger events; routes that cannot + inspect first — the CLI-subprocess pull, a merge that already landed, + restore, force-push — fall to the state-change validator, which reverts + the eight tables to their state at the recorded HEAD in a new commit + when that HEAD is an ancestor (the hazard-R undo shape: table-scoped, + later commits preserved) and marks the witness `unverified` otherwise. + (2) **No graph-table conflict is ever auto-resolved**, `--strategy + ours|theirs` never touches a graph table, and the pull is refused + naming the table; the remedies are the link-mode verbs (rotate, steal, + restore), not conflict resolution. (3) **A foreign graph delta is + refused whole**; graph tables are never merged cell by cell; the later + of two mints under one URL adopts the earlier by an explicit verb the + ADR names (the A9 interim "earlier mint wins" becomes that verb). + (4) **A workspace without a witness takes the remote's graph state + wholesale** — its graph tables are a replica — and refuses to mint + until rotated or stolen (A9). Federation carries the graph tables + unfiltered in v0. The entry points the ADR must cover are every + `DOLT_PULL`/`DOLT_MERGE` route: the SQL pull route + (`pullWithAutoResolveUnchecked`), the CLI-subprocess pull, federation + peer pulls on both routes, the UOW leg's `Pull`, `bd vc merge` + (`MergeWithStrategy`), the remote-migrate gate's `--ff-only` adopt, and + `ForcePush`. Probed on Dolt 2.1.8: `DOLT_PULL` inside a transaction + commits the merge immediately — fast-forward and no-conflict three-way + alike — and `ROLLBACK` does not undo it (only a conflicted merge stays + in the working set, which is what the tree's rollback-on-conflict + relies on); after `DOLT_FETCH`, `dolt_diff` against the tracking ref + enumerates the incoming rows before any merge. Tree facts the ADR + inherits: `TryAutoResolveMergeConflicts` resolves only `metadata`, + audit-only `dependencies`, `issues` (field-level three-way), `labels`, + `comments`, and `events` — a conflict on any other table already fails + the pull; the SQL pull route merges into the default branch (be-5ybd), + where the graph tables and the lease live. Options A (gate only, + content open), C (post-hoc validator only), and D (gate at P2/P3) + rejected. The ADR is P1's first deliverable: + `engdocs/BDP_GRAPH_REPLICATION_ADR.md`. + +### Amendments ruled (A1–A9: 2026-09-07; A10: 2026-09-08) — the interview record + +Raised by eight three-reviewer councils on the W-arch docs and ruled one +decision at a time on 2026-09-07. The normative text above (rulings 7b, 9, +11, 12; §3; §4 lifecycle) now reads as amended; this block is the record. + +- **A1 (ruling 9).** "Single-transaction operations under a store-asserted + authority witness" replaces "the snapshot lease": the accessor loads this + workspace's witness (a clone-local file) and the body asserts it inside + its transaction — Scope row identity, hash-chained ledger head, the lease + (a read requires an unexpired lease and never writes it; a mutation must + UPDATE it and see one affected row), and the graph-state version. No + request type carries authority fields. The cursor is opaque from P1; + cross-request continuation is P2's cursor ADR; no collection routes ship + before it. +- **A2 (rulings 7b, 12).** BDP routes are a conditional second table inside + `internal/httpapi` behind the same middleware, served from the + unit-of-work leg. Only `bd --graph-mode link serve` mints, through the + staged startup; it inherits serve's whole-surface `--readonly` refusal + and refuses without a held Scope. `bd serve` mounts the rows when it + holds an already-minted Scope, converts every graph failure into "rows + absent + notice", and never refuses on account of the graph. Intra-Scope + references are stored Scope-relative and rendered against the live Scope + row; serving under a different base URL is a rotation, never a remount. +- **A3 (ruling 12 / §4 lifecycle).** Graph behavior is selected by the root + flag `--graph-mode link` (default `dependency`; `BD_GRAPH_MODE`; config + `graph-mode`), never by a verb prefix. The mode names the graph by its + edge kind; every verb creates, reads, or serves the selected graph or + refuses; `bd link` creates the selected graph's edge; without the flag + every verb is byte-identical to today. The root store policy keys on mode + and command path and is authoritative at every leaf-name call site. +- **A4 (§3 layering).** Values, laws, and roles live in public `graphops`; + accessors are named `BeadGraph*`; no `backend/` aliases. +- **A5 (ruling 11).** The clone-local half is `.beads/graph-authority.local.json`, + bound to an installation key, written under a bounded exclusive lock with + multi-phase transitions recovered by evidence; the ledger is an + append-only, hash-chained event table with a nonced sequence counter; the + witness records the head; no event exists before mint; the ledger lane + restores anti-reuse history only; providers declare `LedgerDurability`; + restore rotates unless continuity is shown. Residuals stated. The + retained-versions shape Memory needs is the History lane's (bdp#1). The + History lane's first laws are now ruled there (2026-09-08): a + version-addressed read is complete or a typed refusal — Unretained is a + refusal naming the missing fields, never a member inside a record — and + ownership over an open vocabulary is the `"*"` entry in `ownsOutgoing`; the + graph plane's own history reads, when they come, follow both. +- **A6 (§4 lifecycle, 7a env).** `bdp.scope_url` is a project fact in + tracked `config.yaml` (`BDP_SCOPE_URL` first), refused by `config set` + once a witness is held; `link-graph.route`, `bdp.server`, and + `bdp.insecure_http` live in untracked `config.local.yaml`, written by + `bd init --bdp-server` and the link-mode `client` verb; tokens from files + only; nothing in `metadata.json`; precedence env, then local, then + tracked, with the route blocked from env. +- **A7 (ruling 9, promotion) — the shared-database half.** A dolt-ignored + lease row bound to Scope and authority whose every write rewrites a + random fence cell and predicates on the value it read (probe-confirmed + on Dolt 2.1.8, which merges transactions cell by cell); reads never write + it and require an unexpired lease; an expired lease naming this workspace + self-regrants; a foreign holder is replaced only by an explicit + `--steal`; fenced transactions beside a live server carry a deadline + below a third of the TTL; `promote` and `rotate` run beside the server, + `types install`, `restore`, and `ledger apply` take the exclusive gate. + The remote half (publication primitive, remote-read freshness, + publication recovery) is deferred to the write-profile ADR under A9. +- **A9 (ruling 9).** v0 authority requires a shared database. The topology + matrix: a shared database that minted locally is authoritative regardless + of any configured remote; one that received the Scope row by replication, + restore, or copy refuses until rotated or explicitly stolen; embedded and + registered-backend workspaces refuse local authority operations and exist + as client hosts; a remote neither grants nor removes authority; two + shared databases minting under one tracked URL are settled by the + replication ADR (interim: the earlier mint wins). **Amended 2026-09-08 + (solo topology, ruled B — A10 below):** an embedded workspace with no + configured remote and no server is its own authority. + +- **A8 (§1 constraint #1; ruling 12) — option A.** Constraint #1 is + scoped to *behavior*: every in-tree topology and existing workspace is + byte-identical in gate output; out-of-tree `backend/` implementers take + the source break the storage interface already declares (six one-line + `ErrUnsupported` stubs, CHANGELOG call-out with the stub migration). The + compiler catches direct implementers; a required method promotes silently + through every wrapper that embeds the interface, so the three reflection + censuses stay mandatory. Option B (an optional capability interface with + explicit wrapper implementations, a capability census, and resolvers) + rejected. + +- **A10 (ruling 9; amends A9) — solo topology, RULED 2026-09-08: B.** An + embedded workspace with no configured remote and no server mints a local + Scope, holds a witness and a lease satisfied by the workspace gate (the + fence has nothing to fence: one process holds an embedded store), serves + nothing (`bd serve` still refuses embedded Dolt), and answers every + link-mode verb locally. It becomes a client host the moment a shared + database or remote appears, under the rotation and steal rules; a solo + store later pushed to a remote is "minted locally" for the replication + ADR — authoritative until a foreign delta appears. The embedded leg wires + the full read contract for the solo topology and the refusal contract for + client hosts. Raised by Steph's adoption harness (sjarmak/mem), which runs + bd embedded with one isolated store per trial; without this row the + post-P3 memory projection would have no local graph on any laptop. + Options A (defer to the P3 packet) and C (require a local server) + rejected. Epoch spelling confirmed the same day (`authority_epoch`, + `last_authority_epoch`, `birth_authority_epoch` at P1). diff --git a/engdocs/BDP_GRAPH_ARCHITECTURE.md b/engdocs/BDP_GRAPH_ARCHITECTURE.md new file mode 100644 index 000000000..9a6f71a7d --- /dev/null +++ b/engdocs/BDP_GRAPH_ARCHITECTURE.md @@ -0,0 +1,422 @@ +# BDP graph store — architecture and design + +**Status:** Draft v17 (W-arch) — A1–A9 and decisions D1–D2 (plan rulings 13–14) ruled 2026-09-07; A10 ruled 2026-09-08; P0 current-wire completion open — feat/bead-graph +**Date:** 2026-09-12 (v16: 2026-09-10; v15: 2026-09-09; v14: 2026-09-02) +**Companion:** `BDP_BEAD_GRAPH_PLAN.md` (the plan and its rulings, 1–14) and +`BDP_GRAPH_CLI_AND_STORAGE_SPEC.md` (the detailed CLI and storage-interface +changes). This document is the *shape*: what the pieces are, where they live, +how a request flows, and where this design corrects the plan after the +tree's own conventions were read closely. Eight three-reviewer councils +(Claude, Codex, Gemini) reviewed v1–v9; §2 records what changed and which +changes amend a ruling rather than a mechanism. Rounds 3–5 converged on one +area — the authority mechanism — and every round since v3 has replaced an +invented primitive with one the tree already has. v6 added the +operator's **simplification ruling (A9)**; v9 states its arbiter honestly: +physical database copies are an operator-managed hazard, not a fenced one. + +Revision v15: 2026-09-09 current-source alignment and council corrections; +phase/owner gates and pinned-source clarity added, historical rulings preserved. +Revision v16: 2026-09-10 formal-review correction carries the already-ruled A10 +into §2b and refreshes current dependency status. It does not clear the +reviewer/owner merge gate. + +Revision v17: 2026-09-12 records the P0 Read adoption and merged BDP +Transactional/History dependencies consistently with the owning plan; no new +contract pin, migration slot or runtime capability is selected. + + + +## Current dependency alignment (2026-09-09, refreshed 2026-09-12) + +[Plan §0a](BDP_BEAD_GRAPH_PLAN.md#0a-current-bdp-and-versioned-beads-alignment-2026-09-09) +contains the historical source records and the 2026-09-12 current refresh: +BDP #19/#20 and History #30 wire/spec are merged; Jim's Phase 1 is merged +and Phase 0/2 remain open. History realization and provider mapping remain +separate from the completed upstream normative materialization. The role split remains: graphops is the +graph domain, Jim's writer owns Issue history, and BDP wire DTOs own protocol +representations. No Issue projection or C-lane substrate change is selected. + +The graph authority lease is not TX's receipt execution/creator-attempt fence; +the graph anti-reuse ledger is not the projected erasure ledger; an Issue +ordinal is neither a graph revision nor a durable History address. P3 must +compose its durable admission/effects/outcomes under the upstream profile +contract. A future History provider must translate context, numeric values, +retained identity and erasure provenance explicitly. These obligations do +not add Writer or History methods to the existing P0 interface sketch. +The P3 ADR audits storage/interface deltas and their migration, state-version, +fence, replication-inspection and census implications under plan §0a. The +initial eight-table P1 scope does not prescribe future tables or another +accessor widening; any necessary addition honors frozen migrations and A8's +source-break policy. P1 need not await the full P3 design. + +P0 adopted the Read foundation at `19923f5bb6cc3f4ee4c508e36df3bd4c5c52344b`; +plan §0 records its exact pins and dated contract checks, including the narrow +erased-pointer port. The original pin and tests remain historical. Later +wire adoption and applicable successor checks remain explicit gates. [Plan §7's owner gates](BDP_BEAD_GRAPH_PLAN.md#current-wire-and-profile-adoption-gates-2026-09-09) +assign P0 contract/parity work and P2 serving proof, including shared response +negotiation and applicable conditionals. P3 separately records its reviewed +write-profile pin and evidence exit; RU need not await TX-only runtime. +This alignment does not claim that all upstream drafts have +merged or that graph/P0 implements their runtime behavior. + +## 1. The one-paragraph version + +The graph store is a new **plane** beside issues and memories: a public leaf +contract package (`graphops`) declaring the value types, the laws, and six +role interfaces, reached through **role accessors on `storage.Storage`** +(`BeadGraph*`, to keep clear of the issue-graph `GraphCounter()`) exactly as +`issueops` and `memoryops` are — declared explicitly by every decorator +(promotion is the failure mode the censuses catch), wrapped by telemetry, +recursed unwrapped by the hook layer — with one shared transaction-level +body under `internal/storage` taking a `DBTX`-shaped runner so that both +Dolt stores *and* the unit-of-work leg call the same code, proven by +`backend/conformance` role contracts wired on all three legs and guarded by +the existing coverage gates. BDP is served by the existing +`internal/httpapi` server as a **conditional second route table** behind the +same `route()` middleware — in v0 **only from SQL-server workspaces** (the +unit-of-work leg; `bd serve` refuses embedded Dolt permanently, and a +registered backend's store arm has no fence to offer until it declares +one). `bd --graph-mode link serve` is the strict command over that server: it mints and +it requires a Scope this workspace holds; `bd serve` mounts the same rows +when it holds an already-minted Scope and never refuses on account of the +graph. Every operation is **one role call, one transaction**, asserting a +**store-owned authority witness** — loaded by the accessor from a +clone-local file bound to this installation, checked against a hash-chained +ledger head and, on the shared-database leg, a lease row the mutation itself +must update. The store refuses a clone without local authority, a restore whose +head is absent from the witness, and a promotion elsewhere; no caller can +supply the witness. Copies carrying coherent local state are an operator-managed +hazard, including a solo store copy; the store cannot infer their provenance. +A shared database is fenced by that +lease. Under A9, a configured remote neither grants nor removes authority; +hazard R's publication mechanism is deferred to the write-profile ADR. A +shared database that minted locally remains authoritative with a remote. +The A10 exception is an embedded workspace with no remote and no server: it has local authority and +local link-mode verbs, but serves no HTTP. Its workspace gate satisfies the +solo lease; appearance of a shared database or remote makes it a client host +under the existing rotation and steal rules. A10 also preserves the replication +case: a solo store later pushed to a remote counts as minted locally and remains +authoritative until a foreign delta appears. The full A10 row governs both cases. + +## 2. Corrections to the plan and ruled amendments (read this first) + +Two kinds of change are recorded here and must not be confused. A +**mechanism correction** replaces something the plan's §4 *proposed* with +the house idiom that already solves the problem; the ruling it serves is +unchanged. A **ruling amendment** changes text the operator ratified in §9; +the amendments below are recorded outcomes, with their ruling dates. They +are no longer proposals; an implementation gate is not a pending ruling. + +### 2a. Mechanism corrections (no ruling changes) + +| Plan §4 mechanism | Replaced by | Why | +| --- | --- | --- | +| `GraphCapable` as a *separate optional interface*, resolved by targeted decorator peels (`graphsource` package) | **Role accessors on `storage.Storage`** — the house rule — under ruled A8 option A; option B was rejected | Every accessor lives on `Storage` (28 today); `DoltStorage` embeds it; both decorators embed the `DoltStorage` *interface*. A method added to `Storage` is therefore **promoted through the embedded interface**: every wrapper compiles unchanged — which is exactly why the reflection census in `role_accessor_decorator_test.go` (and its telemetry twin) exists: wrappers must **declare** each accessor, and the census catches the ones that silently promote. | +| A `ResolveGraphReadSource` policy that "re-applies telemetry" after peeling | Nothing — **the accessors carry the layers** | This is what accessors are *for* in this tree. | +| `backend/types.go` aliases for every `graphops` type | **No aliases.** `graphops` is a public root package, like `issueops` | The completeness guard demands aliases only for types under `internal/`. | +| `internal/graphapi` as a separate meaning-function package | **The laws live in `graphops`** | Import rule and cycle. | +| A `ReadSnapshot` handed from a resolver to a handler; a caller-supplied expectation (v2/v3) | **One role call, one transaction, asserting a store-owned witness** (A1) | A witness the *caller* supplies is forgeable from the replicated rows. | +| `SELECT … FOR UPDATE` on the Scope row to serialize the ledger (v4); a bare `next = next + 1` counter (v5–v6) | **A single-row counter whose every allocation writes a fresh random cell** (`next_seq = next_seq + 1, alloc_nonce = `) — the journal's `bd_events_seq` shape, corrected | Dolt has no row locks (`FOR UPDATE` is a parse-only no-op) **and merges concurrent transactions cell by cell**: two sessions each doing `next = next + 1` from the same value both commit and the counter reads one increment (probed on 2.1.8). Only a same-cell-*different-value* write is a serialization failure (`1213`) that `withRetryTx`/`RunTxResult` replay; the random cell makes every allocation one. The events PK is the second guard, and it too converges silently on byte-identical rows — the nonce makes rows differ. The journal's own prose carries the misconception; its PK plus duplicate-key heal is what actually guards it. `next` is reserved in Dolt's parser. | +| `DOLT_RESET --hard` to undo a refused publication (v4–v5) | **`DOLT_RESET --soft `, then per graph table `DOLT_RESET('
')` (unstage) and `DOLT_CHECKOUT('
')`** when HEAD is still the operation commit; **`DOLT_REVERT `** when HEAD has moved; the ignored lease restored on either path under the same-holder guard | A hard reset discards unrelated dirty work on a shared server; a bare checkout after a soft reset restores from the *staged* root and reverts nothing (probed), the unstage step makes it revert only the graph tables; a revert preserves later commits from other actors. | + +### 2b. Ruling amendments A1–A10 and decisions D1–D2 (ruled 2026-09-07 and 2026-09-08) + +| # | Ruling | Earlier drafts said | Ruled outcome (A1–A9: 2026-09-07; A10: 2026-09-08) | Evidence | +| --- | --- | --- | --- | --- | +| A1 | **9** ("the snapshot lease" in the obligation list) | dropped silently (v1); caller-supplied expectation (v2–v3) | **RULED.** **The per-call transaction is the v0 lease and asserts a store-owned authority witness:** the accessor loads the witness from the clone-local file and the body checks it *inside the same transaction* — Scope row identity, the hash-chained ledger head (exact-prefix identity), the lease row (a protected read `SELECT`s it inside the read transaction and checks holder, epoch, **and `expires_at > NOW(6)`** — a holder/epoch match alone proves only that no takeover was visible in the snapshot, not that the lease is live; **reads never write the lease**: on the serving leg the watcher renews and a near-expiry read fails closed as `lost`; a CLI read whose lease names this workspace but has expired regrants **once, ephemerally, before opening a fresh read transaction** and retries; the read's context deadline is derived from the remaining lease interval and is below it; a mutation `UPDATE`s it and requires one affected row, with the holder's installation key, epoch, **and the `fence` cell value read in this transaction** in the predicate, and **sets `fence` to a fresh random value and `expires_at = NOW(6) + ttl`** — every lease write does, so any two concurrent lease writers are a same-cell-different-value conflict Dolt reports as `1213` (probed on both the versioned and the ephemeral commit paths); the loser is replayed with a fresh random fence and **re-evaluates its preconditions**: a still-authorized writer then succeeds serially, a superseded or stolen one matches zero rows and refuses. An expired lease that still names this workspace is **self-regranted** by the same write — promotion is needed only when the holder or the epoch differ), and the graph-state version (the ordered per-table hashes of the eight replicated graph tables). Public request types carry **no** authority fields. The cursor type is opaque from P1. | Rounds 1, 3, 4, 5. | +| A2 | **7b + 12** (listener; "`bd serve` creates the Scope on first serve") | a sibling server (v1); `bd serve` mints (v2–v4) | **RULED.** **BDP rows mount inside `internal/httpapi`** as a conditional second route table behind the same `route()`. **Of the serving commands, only `bd --graph-mode link serve` mints** (A10 separately permits local solo minting), through the **one staged startup sequence** in the spec's Part A (shared gate → temporary source reads the Scope row → close → release → only when there is no Scope row: exclusive gate → reopen, re-check, mint → close → release → shared gate → serving source → re-evaluate the identity table under it → serve; the tree forbids a shared→exclusive upgrade, and the conformance case asserts the shared gate is released before the exclusive acquisition). `bd --graph-mode link serve` inherits `errServeReadonly` and refuses without a held Scope; **`bd serve` converts every graph failure into "rows absent + notice"** and is byte-identical without a URL. **v0 serves BDP only from SQL-server workspaces** (the unit-of-work leg): embedded Dolt never serves, and a **registered backend's store arm** — which may itself be embedded — has no fence, so its rows are absent in v0; an out-of-tree backend cannot import an `internal/` capability, so the seam it would declare is the deferred ADR's to define (a public interface or an in-tree adapter), not `graphcap`'s. **Intra-Scope references are stored Scope-relative and rendered against the live Scope row, never as absolute URLs, so a remount rewrites nothing; a server started under a base URL that differs from the persisted Scope URL refuses — serving under a new base is a rotation, never a remount** (operator, 2026-09-07). | Rounds 2–5. | +| A3 | **12** / §4 lifecycle | verbs "reserved now"; then a link mode prefix | **RULED.** Graph behavior is selected by the root flag **`--graph-mode link`** (default `dependency`; `BD_GRAPH_MODE`; config `graph-mode`), never by a verb prefix. The mode names the graph by its edge kind: every verb creates, reads, or serves the selected graph or refuses; `bd link` creates the selected graph's edge; without the flag every verb is byte-identical to today. The root store policy keys on mode and command path and is authoritative at every leaf-name call site (paired Cobra-walk and source-scan tests). | `bd link`, `bd graph`, `bd restore`, `bd promote` exist; a verb prefix named the protocol, not the graph (operator). | +| A4 | §3 layering | values moved silently | **RULED.** **Record it:** values, laws, and roles in public `graphops`; accessors named `BeadGraph*`. | Package layout is public API. | +| A5 | **11** (ledger "restorable independently … its own migration") | dolt-ignored table (v2); project-id file (v3); hostname key (v4) | **RULED.** **(i) The clone-local half is `.beads/graph-authority.local.json`**, bound to an **installation key**: a random id created once, `O_EXCL`, mode 0600, re-read after creation, directory fsynced, in the user config directory the tree's `UserConfigYamlPath` resolver already chooses (`~/.config/bd`, native fallback) — plus the canonical `.beads` path; never the hostname. Written only by the witness manager under a bounded exclusive lock; **transitions are multi-phase** (`begun → local_committed → published → config_written → finalized`, recording a **durable operation id** — a hash-covered, indexed `op_id` column on every ledger event, and the commit message — the pre-operation HEAD and ledger head, the operation commit, the expected graph roots, the remote pre-head, the pre-operation lease row, and the config intent), recovered on the next load by **evidence, not by phase alone**: the ledger is checked for the operation id (a crash between the commit and the phase write leaves `begun` with the operation committed), then the remote is classified as {still at the pre-head, contains this operation, contains foreign work}, and recovery resumes publication, finalizes, or undoes accordingly; on a shared database with no remote a locally committed transition counts as published, **executes any outstanding `config_intent`**, records `config_written`, and only then finalizes. An **undo is itself phased** (`undo_started → versioned_undone → lease_restored`) and resumes from its recorded phase regardless of whether the operation still appears in the ledger; in-process renewal and graph mutation pause for its duration; the lease is restored **only on the reset path and only if it still names this workspace**. `Advance` is a **descendant-aware compare-and-advance** that holds the file lock while a **provider-supplied verifier** (ledger-prefix and commit-ancestry checks, run in the store) decides: a candidate already contained in the current witness is a successful no-op, newer fields are never replaced by older ones, and a fork is rejected — commits may complete in one order and advance in another; opaque hashes alone cannot decide this, so the manager never tries to. The manager ensures the ignore entries and refuses a git-tracked path; a tracked witness is an **error-class** doctor finding (`sensitiveFileNames`). **(ii) The ledger is an append-only, hash-chained event table** (`mint`, `install`, `update`, `promote`, `rotate`, `allocate`, `tombstone`, `refuse_url`) with a single-row counter; the witness records the head `{seq, hash}`. **No event exists before mint.** The ledger lane (`bd --graph-mode link ledger snapshot|apply`) restores **anti-reuse history, not graph content**: an applied `allocate` whose row is absent becomes a `reserved` allocation (never reusable; reads answer gone), the Scope lineage is replayed, and the counter is set to `last_seq + 1`; full recovery is a database restore *plus* the lane. **(iii)** providers declare `LedgerDurability`; `bd --graph-mode link restore` rotates unless continuity is shown. **Two epochs, distinct:** History's `store_epoch` singleton (versioned-beads Phase 1, migration 0067) fences restore and replacement on the issue plane; the graph's authority epoch fences promotion on the graph plane; a restore must be reasoned about for both. **Stated residuals:** a whole-directory or whole-installation copy carries the witness and is undetectable without an arbiter — so outside A10, an *authority-preserving* deployment must have one (a shared database under A9). **A10 amends that topology restriction:** an embedded workspace with no remote and no server has local authority under its workspace gate; the solo/client-host boundary and rotation/steal rules are stated in A10 below. The solo leg is single-copy by operator responsibility; a copied or restored solo store that cannot establish continuity requires a new Scope, rather than a claim that the gate detects a coherent copy. Physical copies remain the stated operator-managed hazard. | Rounds 2–5. | +| A6 | §4 lifecycle (metadata.json; `BD_BDP_TOKEN`; `BDP_SCOPE_URL`) | both files; env token | **RULED.** **`bdp.scope_url` is a project fact in tracked `config.yaml`** (yaml-only; `BDP_SCOPE_URL` read first, then `BD_BDP_SCOPE_URL`). A mint with `--scope-url` writes it as the transition's `config_written` phase. **Once this workspace holds a witness, `bd config set`/`set-many`/`unset` refuse the key** (one guard in the shared `rejectProtectedConfigKey` path; a DB-free file check) — the URL then changes only through `bd --graph-mode link promote --rotate-url` / `bd --graph-mode link restore`, which are refused while an overriding `BDP_SCOPE_URL` is exported. **`bdp.client`, `bdp.server`, `bdp.insecure_http` live in `config.local.yaml`** via `bd init --bdp-server` and `bd --graph-mode link client`. The three new `.beads/` files join the gitignore template, `requiredPatterns`, and `trackedRuntimePatterns`; only the witness joins `sensitiveFileNames` (error class). No env-carried token; no token key in config; `bdp.client` blocked from env. | Rounds 2–5. | +| A7 | **9** (promotion "explicit and epoch-rotating") — *new* | v5 partitioned by hazard but fenced a subset | **RULED.** **Fences compose by hazard; every replicated graph mutation is fenced inside its transaction and, on hazard R, published by one primitive.** *Hazard S — a shared database* (every SQL-server topology): the dolt-ignored **`graph_authority_lease`** row (the `leases`/`RunTxEphemeral` precedent) with the **fence cell** predicate in A1 — the holder is the **workspace (installation key)**, so the serving process and the workspace's own CLI verbs share it (`promote` and `rotate` take the *shared* gate and rely on the lease; `types install`, `restore`, and `ledger apply` take the exclusive gate and require the server stopped); renewal is ephemeral, rewrites the fence, and extends `expires_at`; an expired lease naming this workspace is self-regranted by the next write **regardless of expiry**; a lease naming another holder is taken **only with `--steal`** — its expiry alone never grants a takeover — and the epoch is CASed. **A lease row is not proof of "minted here"**: `dolt clone` omits the dolt-ignored table, but `DOLT_BACKUP` restore and a directory copy carry the working set with it, and Dolt's `@@server_uuid` is per machine (`~/.dolt/config_global.json`; probed identical for a same-machine copy), so no in-band identity distinguishes a copied database served by a second `sql-server`. The lease row is therefore bound to `scope_url` and `authority_id`, and in-place promotion has exactly two paths: **self-regrant** when the row names this workspace, and **`--steal`**, an operator assertion of "same database" in the class of force-push and `bd sql`; a foreign holder's *expiry alone* never grants a takeover. `Promote --rotate-url` is the bootstrap that creates a new lease row under a new URL (refusing the old one forever) — the path for a clone, a restore that cannot show continuity, and a copy. Residual, stated: a `--steal` on a copied database creates a second authority; a restored copy is caught first by the witness's ledger head (`ErrStateRewound`). Throughput model, stated: concurrent graph mutations in one workspace serialize pairwise on the fence cell, and a fenced transaction that spans a renewal loses whenever the renewal commits first, so **every fenced transaction that runs beside a possible renewer (the shared-gate context) carries a deadline below a third of the TTL** (cancelled and retried past it — the replay budget must allow more than one attempt), in-process renewal is serialized against the process's own mutations with jittered cadence, and **`types install` runs under the exclusive gate**, where the sole writer sets `expires_at` itself and runs unbounded. **The file lock is held continuously from `Begin` through `Finalize`/`Abandon`**, and recovery acquires it first, so a live transition is never mistaken for crash residue. *Hazard R — a configured remote* **[deferred under A9, ruled: input to the write-profile ADR, not normative for v0]**: **every** replicated graph mutation (`Mint`, `Promote`, `Rotate`, `Install`, `LedgerApply`, the P1 seeds, P3 writes) runs through **`PublishGraphMutation`** on the provider: `DOLT_FETCH`; require the remote-tracking HEAD to be an **ancestor** of local HEAD (`DOLT_MERGE_BASE`); record the remote's graph roots and ledger head; the fenced transaction; a **scoped** commit (`DOLT_ADD` of the graph tables, `DOLT_COMMIT -m` — never `-Am`; a new `RunTxScopedResult` on the UOW leg, whose `Commit` hardcodes `-Am` today); `DOLT_PUSH` classified by a **typed** lift of the tree's untyped `pushRacePattern` (it already matches all three race routes) — on a race, refetch and compare **both** the remote-tracking ref's **ledger head** (`SELECT seq, hash FROM graph_ledger_events AS OF '' ORDER BY seq DESC LIMIT 1` — `MAX(seq), hash` errors under `ONLY_FULL_GROUP_BY`, probed) **and the eight graph tables' diff** between the recorded remote pre-head and the new remote head (`DOLT_DIFF_STAT`/`dolt_diff` restricted to those tables; `DOLT_HASHOF_TABLE` reads only the working set) against what was recorded before the transaction: any graph delta or ledger movement → fail closed and undo — **never the `(authority_id, epoch)` tuple alone**, which a same-witness twin (a VM image or shared home) or a same-authority fork shares; neither changed (issue-plane divergence only) → keep the commit, `ErrSyncRequired`; any other failure → keep the commit, mark `unpublished`, retry later. The classifier lifts the **whole** of `isPushRaceErr` — its diverged-history and ancestor-PK-mismatch exclusions included — behind a typed lower-layer error. The remote-tracking ref is `remotes//`, built by one provider API from the configured sync remote and the active branch (the `verifyPullLanded` spelling); a missing ref is vacuously an ancestor (the push creates it); an empty remote ledger reads as no head. Undo = `DOLT_RESET --soft `, then per graph table `DOLT_RESET('
')` (unstage) and `DOLT_CHECKOUT('
')` — a bare checkout after a soft reset restores from the *staged* root and reverts nothing (probed) — when HEAD is still the operation commit, `DOLT_REVERT ` otherwise; then, **on either path**, a compensating ephemeral write restores the pre-operation **lease** row — predicated on the lease still naming this workspace at the operation's epoch and on the current fence, and writing a fresh fence (a revert restores the Scope epoch while the ignored lease keeps the new one, which would lock the workspace out of its own lease — probed); if another holder now legitimately holds the lease, it is left alone; the undo runs before any other graph mutation. **Reads on hazard R** require a remote observation no older than `bdp.authority_heartbeat` (a serving process fetches on a timer; a CLI read fetches when stale), **comparing the remote ledger head against the workspace's witness — reloaded on every check — not against a process-local expectation**, and recognizing a **pending local operation** (a publication that landed before the witness advanced, or a `local_committed` record) as this workspace's own, so a publication by the workspace's CLI is a re-arm, not a loss; they fail closed after the grace. Recovery on hazard R reuses the same ledger-plus-eight-table delta classifier as the push race: issue-plane-only movement is `ErrSyncRequired`, never an undo. The fence watcher is a state machine `held → renewing → lost`: on loss the BDP rows are disabled atomically (legacy surface untouched), `bd --graph-mode link serve` exits 3, and the watcher joins before provider shutdown. *Both hazards → both fences.* A clone that received the Scope row by `dolt clone` has no lease row and bootstraps only with `bd --graph-mode link promote --rotate-url`; a copy or restore that carries the row is the operator hazard stated above. Services on an ephemeral home pin `BEADS_INSTALLATION_ID_FILE` to persistent storage, or every restart is a `--steal`. A `promote --rotate-url` beside a live server changes the served URL and the host allowlist, which are fixed at startup, so the server exits 3 and is restarted. Force-push routes bypass the fence as operator acts. | Round 5 (Codex C2–C4, H5, H7, H10, H11; Gemini). | +| A8 | plan §1 constraint #1 and ruling 12 — *new* | v5's method-set reasoning was inverted | **RULED: option A.** **A:** constraint #1 scoped to *behavior* (byte-identical gate output). Adding six required methods to `Storage` breaks **direct implementers** (the compiler catches them; six `ErrUnsupported` stubs; the joint `ReadyClaimer`/`BatchCloser` CHANGELOG entry is the precedent) and is **silently promoted through every wrapper that embeds the interface** — which is why the censuses are mandatory, not optional. **B:** an optional `BeadGraphCapable` interface on the concrete store is **not** promoted through an interface-embedding wrapper at all, so every wrapper must implement it explicitly *and* every consumer needs a resolver/unwrap — the v1-plan `graphsource` shape. | Round 5 (Codex M14, Gemini). | +| A9 | **9** — simplification, **as amended by A10** | — | **RULED 2026-09-07; solo exception ruled 2026-09-08.** **Outside A10's solo topology, v0 authority requires a shared database.** Hazard R's publication primitive, remote-read freshness, and multi-phase publication recovery are **deferred to the write-profile ADR**; a remote-backed workspace is a **non-authority** for any Scope it did not mint on its own shared database (its `bd serve` shows rows absent; its CLI reads refuse); cross-database promotion is **`--rotate-url` only** (a new Scope, continuity via the ledger lane). The graph tables still replicate through push/pull like any other table; the validator refuses foreign deltas. What remains of A7 is hazard S alone — one arbiter, one lease, one counter. **Topology matrix, as amended by A10:** a shared database that **minted locally** is authoritative regardless of any configured remote; a shared database that received the Scope row by replication, restore, or copy without a valid local authority refuses (`ErrNotAuthority`; `--rotate-url` or `--steal` as above); outside A10's embedded solo exception, the embedded and registered-store client-host arms refuse authority-establishing and authority-dependent local operations (`Mint`/`Promote`/`Rotate`/`Install` and local graph reads answer `ErrNotAuthority: authority requires a shared database`; the embedded client-host leg uses `bdp.client: server`, while the solo leg supplies the full local read contract under A10; client-mode reads stay allowed everywhere); a configured remote neither grants nor removes authority, and **transition recovery takes the local-operation path on every shared database** (the remote classification exists only when hazard R is in force); two shared databases that both mint under one tracked `bdp.scope_url` are settled by the replication/merge ADR — until it lands, the earlier `mint` event (lineage) wins and the loser rotates; every hazard-R passage (publication primitive, remote-read freshness, publication recovery, `Remote` fixture cases) is excluded — but the default-branch rule for the ignored lease table (Part D.5) stays, because it is a property of dolt-ignored tables, not of hazard R; A5's "single-copy by operator responsibility" sentence is withdrawn under A9; A10 subsequently adds the solo exception, whose single-copy safety is again an operator responsibility. Physical database copies remain the stated operator-managed hazard. **Selected for v0**: the only serving topology already is the SQL-server workspace, and this removes the largest block of new mechanism from P1/P2. | Round 5 (Codex C1: "require an externally observable fence or weaken the guarantee"). | +| A10 | **9**, amends A9 | embedded authority refused under A9 | **RULED 2026-09-08: B — solo topology.** An embedded workspace with no configured remote and no server mints a local Scope, holds a witness and a lease satisfied by the workspace gate (one process holds the embedded store), and answers every link-mode verb locally. It serves nothing: `bd serve` still refuses embedded Dolt. It becomes a client host the moment a shared database or remote appears, under the rotation and steal rules. A solo store later pushed to a remote is "minted locally" for the replication ADR — authoritative until a foreign delta appears. The embedded leg wires the full read contract for solo topology and the refusal contract for client hosts. Options A (defer to P3) and C (require a local server) were rejected. | Plan §9 A10; operator ruling 2026-09-08, raised by Steph's adoption harness (sjarmak/mem). | + +A10 mechanism work for P1: assign the local solo mint trigger without adding a +serving path, and map its exclusive workspace gate to the shared-leg lease +predicates and fence census. The witness, Scope identity, ledger-head and graph- +state checks still apply; the gate satisfies the solo lease, rather than +requiring an invented shared database. The exact lease-row representation and +expiry/self-regrant mapping must be recorded before implementing that leg. This +is implementation work under ruled A10, not a new CLI-name ruling. + +Two decisions recorded here and ruled 2026-09-07 as plan rulings 13–14: + +- **Enforcement boundary for out-of-role writes — RULED 2026-09-07 (plan + ruling 13, "A+B").** `bd sql`, the proxied `RawSQLUseCase`, force-push, + and a merge can change graph tables without allocation, authority, + revision, or owned-Link coupling checks. Out of contract; the + **state-change validator** rejects invalid or foreign-authority graph + state (a delta on the ledger-covered tables must be explained by ledger + events since the recorded head; bead and link bodies by row provenance); + and the eight replicated tables carry session-gated `BEFORE + INSERT/UPDATE/DELETE` triggers that refuse a row unless `@bd_graph_role` + is set — every graphops mutation sets it inside its transaction and + clears it before `COMMIT`/`ROLLBACK` (the clear is load-bearing: a + pooled connection keeps the variable otherwise — probed). Probed on Dolt + 2.1.8: the triggers fire (errno 1644), replicate through `dolt_schemas`, + are created by one multi-statement `Exec` of a migration file, and are + silent on `DOLT_MERGE`/`DOLT_PULL` (the validator's and ruling 14's + territory). A fence against accidents, not credentials; the two-SQL-user + boundary is a C-lane task. Three P0 verification rows gate the fence + (spec B4). +- **Replication/merge ADR as a P1 gate — RULED 2026-09-07 (plan ruling 14, option B: the gate plus a four-law charter).** The merge entry points are not + four Go functions: `mergesettle.go` exports seven, `fastforward.go` and + `automerge.go` more; `CALL DOLT_PULL` merges inside Dolt on every pull + route; the UOW leg's `doltVersionControlSQLRepository` calls + `DOLT_MERGE`/`DOLT_PULL`/`DOLT_PUSH` directly; embedded federation sync + fetches and merges; the remote-migrate gate does a fast-forward + `DOLT_MERGE`. The validator runs **on every observed graph-state-version + change**: the witness + records the graph-state version — `DOLT_HASHOF_TABLE('')` for each + of the eight replicated graph tables in a fixed order, hashed together + (the function exists in Dolt 2.1.8 and takes one table argument; the + lease is ephemeral and excluded) and the HEAD commit; a body that sees a + different version returns `ErrStateChanged` *without* validating inside + the held transaction; the accessor validates under **one singleflight + coordinator per provider instance** in its own transaction (ancestry + `DOLT_MERGE_BASE(recorded HEAD, HEAD)`; row provenance for foreign + updates), advances the witness, and retries once. Descriptor caches are + keyed by the descriptors table's hash. **The charter:** (1) every SQL + pull route fetches, inspects the eight tables between HEAD and the + remote-tracking ref, and refuses a foreign-authority or unexplained + delta *before* merging — `DOLT_PULL` commits a clean merge immediately + and `ROLLBACK` does not undo it (probed), so inspection is the only + pre-merge refusal point; routes that cannot inspect first (the + CLI-subprocess pull, a merge already landed, restore, force-push) fall to + the validator, which reverts the eight tables to their state at the + recorded HEAD in a new commit when that HEAD is an ancestor (the hazard-R + undo shape; later commits preserved) and marks the witness `unverified` + otherwise; (2) no graph-table conflict is auto-resolved and `--strategy` + never touches a graph table — the pull is refused naming the table, the + remedies are the link-mode verbs; (3) a foreign graph delta is refused + whole, never merged cell by cell, and the later of two mints under one + URL adopts the earlier by an explicit verb the ADR names; (4) a + workspace without a witness takes the remote's graph state wholesale and + refuses to mint until rotated or stolen. Federation unfiltered in v0. + The ADR (`engdocs/BDP_GRAPH_REPLICATION_ADR.md`) is P1's first + deliverable, council-reviewed; no graph migration merges before it. + +What none of this changes: ruling 9's level — the authority is the graph +store as reached through the normalized storage abstraction, on any +provider; Dolt is the reference realization; the CLI verbs and the BDP +handler are both clients of that abstraction. + +## 3. Packages and their imports + +```text +graphops/ PUBLIC LEAF (sibling of issueops/, memoryops/) + ├─ types.go Bead, Link, Ref, Properties, Revision, Attribution, + │ TypeDescriptor, OwnedLinkDecl, OwnedLinkGroup, ScopeIdentity, + │ LedgerEvent, LedgerManifest, Cursor (opaque) + ├─ laws.go canonical-ID grammar, code-unit ordering, JSON canonicalization, + │ RFC 6902 §4.6 equality, Scope-URL validation, ledger hashing + ├─ reader.go Reader: Bead, Link, Beads, Links, IncidentLinks + ├─ types_role.go DescriptorReader: Descriptors, Descriptor + │ TypeInstaller: Install (post-mint; published on hazard R) + ├─ identity.go IdentityReader: Read, LedgerDurability + │ ScopeBootstrapper: Mint (once; installs the built-in catalog) + │ Admin: Promote, Rotate, LedgerSnapshot, LedgerApply, + │ MarkUnverified, ClearUnverified + (transaction-bound provider capabilities — StateVersioner, GraphPublication, LeaseClaim — + live in internal/storage/graphcap, not here: the public leaf carries no runner type) + ├─ writer.go (P3) Writer + └─ errors.go ErrNotFound, ErrValidation, GoneError{Path, State}, + ErrNoScope, ErrScopeExists, ErrNotAuthority, ErrStateRewound, + ErrStateChanged, ErrSyncRequired, ErrUnpublished, ErrURLReused, + ErrRepresentationTooLarge, ErrNotServedYet + NO authority fields on any request type — the witness is the store's. + imports: stdlib + beadserrors ONLY + +internal/storage/authority/ THE WITNESS MANAGER (clone-local half; no SQL) + Witness{InstallationKey, ScopeURL, AuthorityID, Epoch, LedgerSeq, LedgerHash, + StateVersion, StateCommit, Unverified, GrantedAt, Pending *Transition} + Transition{Kind, OpID, Phase (begun|local_committed|published|config_written| + undo_started|versioned_undone|lease_restored), PreHead, PreLedgerHead, PreLease, + OpCommit, ExpectedRoots, RemotePreHead, ConfigIntent} + Advance takes a provider-supplied Verifier (ledger-prefix + ancestry; under hazard S the + ledger seq is a total order, so seq decides) and runs it under the file lock; the lock is + held from Begin through Finalize/Abandon; LeaseClaim lives in internal/storage/graphcap + installation id: the directory user_config_path.go's UserConfigYamlPath chooses + (~/.config/bd preferred; native fallback), file installation-id, or BEADS_INSTALLATION_ID_FILE; + created O_EXCL 0600, re-read, directory fsynced; per OS user (a service user and an + operator compute different keys — cross-user shared roots are unsupported, as the + workspace gate already declares); an ephemeral home regenerates it (promote again) + Load: plain read; a Pending record → recovery by evidence (the ledger carries the op id? + the remote: pre-head / contains this op / foreign?) → resume, finalize, or undo — BEFORE + any assertion; run by admin verbs and bd --graph-mode link serve only; bd serve and CLI reads treat + Pending as rows-absent / ErrNotAuthority with a notice + Advance: bounded exclusive flock on .beads/graph-authority.lock (internal/lockfile; + poll with timeout, the workspacegate precedent; both ErrLocked and ErrLockBusy honored) + → descendant-aware compare-and-advance (older contained candidate = no-op; fork = reject) + → atomicfile → fsync dir + Begin / SetPhase / Finalize / Abandon; preflight ENSURES the .beads/.gitignore entries and + refuses a git-tracked path + +internal/storage/graphops/ TX-LEVEL SHARED BODY — all three legs call it + type DBTX interface { ExecContext; QueryContext; QueryRowContext } + assertAuthorityInTx(ctx, tx, w, claim, mutating): Scope row == w; ledger head; lease row — + read: SELECT holder/epoch/expires_at/fence and require expires_at > NOW(6) (reads never + write the lease; a CLI read regrants once, ephemerally, before a fresh read tx when its own + lease has expired); mutation: UPDATE … SET heartbeat_at = ?, + expires_at = NOW(6) + ttl, fence = WHERE id = 1 + AND holder_installation_key = ? AND epoch = ? AND fence = with exactly + one affected row (same-cell-different-value → 1213 → replay re-evaluates: still + authorized → succeeds serially; superseded → 0 rows → refuse); the 1213 surfaces from + CALL DOLT_COMMIT on the scoped path, so that call stays inside the retried closure; + graph-state version == w.StateVersion else ErrStateChanged + nextLedgerSeqInTx: UPDATE graph_ledger_seq SET next_seq = next_seq + 1, alloc_nonce = + WHERE id = 0 (the random cell is what makes two allocators conflict) + ReadBeadInTx / … / MintScopeInTx / PromoteInTx / RotateInTx / LedgerSnapshotInTx / + LedgerApplyInTx (anti-reuse history; reserved allocations; counter set) / + ValidateStateInTx / graphStateVersionInTx: eight calls DOLT_HASHOF_TABLE('') + in the fixed order; StateVersion = sha256 of the concatenated hashes + SeedBeadInTx / SeedLinkInTx — fixture writer; _test.go call sites only + +internal/storage/dolt/beadgraph_*.go, internal/storage/embeddeddolt/beadgraph_*.go + CLI legs (embedded never serves): witness + claim loaded per call; withReadTx / + withRetryTx; scoped commit (DOLT_ADD graph tables + DOLT_COMMIT -m — the + doltAddAndCommit precedent); PublishGraphMutation for hazard R + +internal/storage/domain/db/beadgraph.go + doltVersionControlSQLRepository additions + BeadGraphUseCase over db.Runner; the repository gains Fetch/Push (exist), MergeBase, + ResetSoft, CheckoutTables, Revert, HashOfTables +internal/storage/uow/beadgraph_*.go THE SERVING LEG + uow.UnitOfWork gains BeadGraphUseCase(); doltSQLProvider gains beadsDir (received by + cmd/bd/uow_factory.go's newSQLServerUOWProvider today, dropped) and timedProvider gains a + getter for it (it builds roles over the wrapper today); NEW + RunTxScopedResult(tables, msg) — doltServerTx.Commit hardcodes DOLT_COMMIT('-Am') today; + RunTxEphemeral for lease renewal; PublishGraphMutation on the provider + +internal/storage/storage.go + six BeadGraph* accessors +internal/storage/hook_beadgraph_*.go, internal/telemetry/beadgraph_*.go, backend/conformance/… +internal/httpapi/bdp_routes.go bdpRouteTable — conditional rows behind route() (P2); + FenceSource state machine (held → renewing → lost) +internal/httpapi/bdpwire/ hand-written DTOs held to the vendored, pinned schema by tests (Part D.3, recorded 2026-09-07) — P0 +internal/bdpclient/ graphops.Reader/DescriptorReader over the wire +cmd/bd/bdp*.go link mode root; bdpRootPolicy keyed by CommandPath(); + bdp_serve.go staged startup (exclusive mint, then shared serve) +cmd/bd/backup_restore.go runBackupRestore → Admin.MarkUnverified (no-op without a witness) +``` + +Dependency direction, enforced: `cmd/bd → graphops, storage accessors, +bdpclient`; `internal/httpapi → graphops, bdpwire`; `internal/storage/* → +graphops, authority`; `graphops → beadserrors, stdlib`. A new depguard rule +denies `internal/storage/graphops` to everything but the three legs and +`domain/db`. + +## 4. Roles — how many, and why + +The house test: a role is a **different question**, born whole with the +methods that are shapes of one question; and *can one caller be entitled +to the read and not the write?* — if yes, two roles. Six, each behind its +own `BeadGraph*` accessor. **Authority is never a parameter.** Transitions +produce the witness and carry their own preconditions instead of the head +check — named per method. + +- **`graphops.Reader`** — one record by path (grouped, bounded + `ownedLinks`), keyset pages under an opaque cursor, incident Links. + Protected. +- **`graphops.DescriptorReader`** — the ordered catalog and a keyed lookup. + Protected. Bounded. +- **`graphops.TypeInstaller`** — post-mint install/converge with `install` + events; a fenced mutation, **published through the same primitive as + every other replicated mutation** on hazard R. P1. Before mint there is + no install: the built-in catalog is installed by `Mint`. +- **`graphops.IdentityReader`** — the Scope row, the witness's claim, and + `LedgerDurability`. **Exempt** (it reports state). +- **`graphops.ScopeBootstrapper`** — `Mint`, once, under the exclusive gate + through a temporary source (the spec's one staged-startup sequence: shared + read → release → exclusive only when there is no Scope row → release → + shared serve), fenced per hazard, multi-phase: precondition *no Scope row*; INSERT the singleton Scope row, seed + the counter, append `mint`, install the built-in catalog with its + `install` events — one transaction, one scoped commit, published on + hazard R, `config.yaml` written when `--scope-url` supplied it; then the + witness is finalized. +- **`graphops.Admin`** — `Promote` (precondition: Scope row CAS + the + fence; produces the witness), `Rotate` (precondition: Scope-row lineage + and the lease; `refuse_url(old)` + `rotate(new)` in one + transaction; `config.yaml` in the `config_written` phase; refused while + `BDP_SCOPE_URL` overrides), `LedgerSnapshot`, `LedgerApply` (recovery + predicate; anti-reuse history only; regrants), `MarkUnverified`/ + `ClearUnverified`. Authorized by being the local administrative + composition root — `Promote` and `Rotate` under the **shared** gate (they + rely on the lease and run beside a live server), `Install`, `LedgerApply`, + and `bd --graph-mode link restore` under the **exclusive** gate; `httpapi.GraphConfig` + has no field for it. +- **`graphops.Writer`** (P3, not now). + +## 5. A read, end to end + +```text +client ──GET /acme/beads/x──▶ internal/httpapi (bd serve | bd --graph-mode link serve; UOW leg) + │ route(): deadline → bearer → Bd-Project-Id stamp (absent = pass) → database slot + ▼ +bdp handler: path grammar (graphops laws) → ONE role call + ▼ +graphops.Reader.Bead(ctx, BeadRequest{Path}) ← no authority fields + ▼ +BeadGraphReader (manager-backed role): w := authority.Load(beadsDir); claim := process claim + │ hazard R: require a remote observation ≤ bdp.authority_heartbeat old (fetch if stale; + │ fail closed past the grace) [absent under A9] + ▼ RunTxRead ─▶ storage/graphops.ReadBeadInTx(ctx, runner, w, claim, req) + │ stmt 1 Scope row: (scope_url, authority_id, epoch) == w + │ stmt 2 ledger head: event at w.LedgerSeq has hash w.LedgerHash; MAX(seq) >= w.LedgerSeq + │ stmt 3 lease row: holder key/epoch == claim AND expires_at > NOW(6) (SELECT — a read never + │ writes the lease; a mutation UPDATEs it, rewriting the fence cell and extending + │ expires_at, self-regranting if expired; a CLI read on its own expired lease regrants + │ once ephemerally before a fresh read tx) + │ stmt 4 graph-state version: DOLT_HASHOF_TABLE('') × 8 in fixed order, sha256 of + │ the concatenation == w.StateVersion → else ErrStateChanged (returned WITHOUT validating here; + │ the accessor validates under the provider's singleflight coordinator, advances the + │ witness, retries once) + │ stmt 5 bead row + │ stmt 6 descriptors for the Bead's Type (cache keyed by the descriptors table's hash, + │ which stmt 4 already read) + │ stmt 7 ONE batched owned-links query, LIMIT (bound − rows so far) + 1 + ▼ +graphops.BeadRecord {Bead, OwnedLinks []OwnedLinkGroup} + ▼ +bdp handler: bdpwire DTO ← record; typed error → BDP Problem; JSON out +``` + +Statement budgets are per role method (spec B2). A write (P3): the body +asserts **mutatingly** (the lease `UPDATE` with one affected row), runs the +no-op gate, records attribution, versions the source on owned-Link +mutation, takes the next `seq`, appends the event, stamps provenance; the +accessor commits **scoped**, **publishes on hazard R**, and only then +advances the witness — DB first, file second. + +## 6. Where the rulings land + +| Ruling | Lands in | +| --- | --- | +| 1 charter | `engdocs/PROJECT_CHARTER.md` edit rides the first merged slice | +| 2 substrate S1 | replicated migrations (scope, history, descriptors, beads, links, ledger events + counter, allocations) + the lease's three parts (`doltIgnorePatterns`, main-series creation, ignored-series twin) + `ignoredSource.sentinelTables` gains the lease | +| 3 allocation ledger | `graph_allocations` (derived; `reserved` state after a ledger-lane apply); `graph_ledger_events`; `graph_ledger_seq` | +| 5 withdrawal | nothing projects Issues; structural | +| 7a Scope URL | `bdp.scope_url` in tracked `config.yaml` (`BDP_SCOPE_URL` first); singleton Scope row; no dev-mode derivation | +| 7b listener | BDP rows behind `httpapi.route()` (A2) | +| 8 changefeed | P3 | +| 9 authority | store-owned witness in every transaction (A1); fences by hazard (A7), hazard S under A9, and the solo workspace gate under A10; contract cases incl. clone, restore, copied witness, expired-lease mutation, nonce mismatch, graph delta under an unchanged tuple, revert when HEAD moved, each phase's recovery | +| 11 restore vs identity | hash-chained head in the witness; multi-phase transitions; ledger lane = anti-reuse history; `LedgerDurability`; rotation (A5) | +| 12 store/Scope/client | `bd init` migrations only; among serving commands only `bd --graph-mode link serve` mints (staged); A10 solo mint trigger is a P1 mechanism; `bd --graph-mode link client` (A6); A8 options; registered backends absent in v0 | +| 13 out-of-role DML | session-gated triggers in the five table files (spec B4); the validator's ledger accounting (B3); three P0 verification rows; the two-SQL-user boundary is C-lane | +| 14 replication/merge | `engdocs/BDP_GRAPH_REPLICATION_ADR.md` first in P1; fetch-inspect-merge on the SQL pull routes; validator revert on the rest; graph tables excluded from auto-resolve and `--strategy`; clones take remote state wholesale | +| 6 wisps | not served | + +## 7. What is deliberately not designed here + +- Cross-request cursor continuation (P2 ADR); no collection routes before it. +- The write profiles' wire (W1), `graphops.Writer`, per-token authorization + classes, the push-on-commit latency budget, and the + acknowledged-but-unwitnessed-write window (P3). +- The replication/merge ADR's mechanism (§2b; the charter is plan ruling 14) — P1's first deliverable, `engdocs/BDP_GRAPH_REPLICATION_ADR.md`; precedes the migrations. +- A DB-privilege (two-SQL-user) boundary for the graph tables (C-lane, ruling 13). +- The `GraphPublication` capability a registered backend would declare to + serve BDP (deferred; v0 serves from SQL-server workspaces only). +- Whether `bd --graph-mode link serve` remains after W2 (default: yes — the serving minting path). +- Type generation from the bead-type inventory (W3) — it feeds the built-in + catalog `Mint` installs. diff --git a/engdocs/BDP_GRAPH_CLI_AND_STORAGE_SPEC.md b/engdocs/BDP_GRAPH_CLI_AND_STORAGE_SPEC.md new file mode 100644 index 000000000..5b7efc1fb --- /dev/null +++ b/engdocs/BDP_GRAPH_CLI_AND_STORAGE_SPEC.md @@ -0,0 +1,1262 @@ +# BDP graph store — CLI and storage-interface changes, in detail + +**Status:** Draft v17 (W-arch) — A1–A9 and plan rulings 13–14 ruled 2026-09-07; A10 ruled 2026-09-08; P0 current-wire completion open — feat/bead-graph +**Date:** 2026-09-12 (v16: 2026-09-10; v15: 2026-09-09; v14: 2026-09-02) +**Companions:** `BDP_BEAD_GRAPH_PLAN.md` (rulings), `BDP_GRAPH_ARCHITECTURE.md` +(shape; its §2b lists A1–A9 and plan rulings 13–14, **ruled 2026-09-07**, +and the A10 solo-topology amendment **ruled 2026-09-08**; every +hazard-R paragraph is marked *[deferred under A9]*). This document is the +*diff*: every command, flag, config key, interface member, package, +migration, and gate the graph work adds or touches — and what it does not +touch (Part C) and what it changes that an earlier draft claimed it did not +(Part C2). Phase markers follow the plan's §7: **P0** contracts and wire, +**P1** storage, **P2** serving, **P3** writes. + +Revision v15: 2026-09-09 current-source alignment and council corrections; +phase/owner gates and pinned-source clarity added, historical rulings preserved. +Revision v16: 2026-09-10 formal-review correction aligns all embedded-leg +summaries with A10 and qualifies the registry claim; plan §0a carries the +current dependency refresh and outstanding reviewer/owner gate. + +Revision v17: 2026-09-12 records the P0 Read adoption and merged BDP +Transactional/History dependencies consistently with the owning plan; no new +contract pin, migration slot or runtime capability is selected. + + + +## Alignment addendum (2026-09-09, refreshed 2026-09-12) + +[Plan §0a](BDP_BEAD_GRAPH_PLAN.md#0a-current-bdp-and-versioned-beads-alignment-2026-09-09) +records the historical pins and the 2026-09-12 refresh: BDP #19/#20 and +History #30 wire/spec are merged; Jim #6304 is merged and #6147/#6358 remain +open. History realization and completion gates remain separate. The original +P0 pin and the adopted Read foundation at `19923f5b` remain explicit; +neither is a current-write or History capability claim. Three storage/adapter +boundaries follow from that reconciliation: + +1. P3 delete results carry the shared `deletedIdentity` schema in the + `deleted` result member, including the removed Resource's final live + revision. Owned-Link results also report `source` (the source Bead's + absolute canonical URL) and `sourceRevision` (that Bead's resulting + revision), on creation, update and deletion alike. Deletion never mints a + deleted Resource version. +2. The allocation/authority ledger below is neither Jim's retained + `issue_versions` store nor the TX projected erasure ledger. Preserve the + separate epochs and recovery duties. A future History store needs complete + retained records and applicable copy cleanup; adding History names to this + allocation ledger does not implement either requirement. The P3 ADR + inventories selected-profile storage/interface deltas and affected migration, + state-version, fence, inspection and census gates under plan §0a. The eight + replicated tables below are the initial P1 scope; no new table or interface + widening is prescribed, and P1 need not wait for the full P3 design. Any + necessary later addition preserves frozen migrations and A8 source-break + disclosure. +3. The approved History context envelope is distinct from carried attribution + and properties. Its commit-time, operation fan-out, legacy absence, + postimage/Event/row placement and erasure constraints are materialized in + merged #30 (`1fe8cf32`, recorded in the dated plan §0a dependency table); + their local adoption needs an explicit provider mapping. Jim's existing + columns, empty-actor status and local ordinal do not supply that mapping. + +Plan §0 records P0's adoption of the Read foundation and narrow erased-pointer +rejection, preserving other RFC 9457 extensions. Subsequent wire adoption +remains deliberate; those dated checks do not establish current serving. P1 rechecks merged main and the migration advisory before claiming +actual slots; 0067 is now merged and 0068 is reserved by Jim's still-open +Phase 2. [Plan §7's owner gates](BDP_BEAD_GRAPH_PLAN.md#current-wire-and-profile-adoption-gates-2026-09-09) +assign these exits, shared negotiation/conditional contracts and their P2 +public-boundary proof. Before P3, record the reviewed selected write-profile +pin under plan §0. Field spellings above quote the §0a upstream pins and are +re-verified at that write pin; this addendum introduces no new local wire +field, migration or implementation. + +## Part A — CLI + +Graph behavior is selected by the **root flag `--graph-mode link`** +(default `dependency`; `BD_GRAPH_MODE`; config key `graph-mode`), never +by a verb prefix (amendment A3, ruled 2026-09-07). The mode names the +graph by the kind of edge it carries: the dependency graph is issues joined +by dependencies, the link graph is graph beads joined by typed Links. +**Every verb creates, reads, or serves the selected graph or refuses**; +`bd link a b` creates a dependency, `bd --graph-mode link link a b --type +` creates a Link; verbs with no link-graph meaning (`dep`, `ready`, +`prime`, …) refuse under the flag rather than silently running on the +dependency graph. Without the flag every verb is byte-identical to today; +the differential gate gains one row per legacy verb form (Part B7). A +workspace may default to link mode through the config key, and the key's +help says what that does to `bd link`. + +**Root store policy is keyed by mode and command path, and it is +authoritative.** The root command classifies commands by *leaf name* at +several sites — `effectiveRootStorePolicy(cmd.Name(), …)`, +`runsPostCommandMaintenance(cmd.Name(), …)`, `isReadOnlyCommand` +(`readOnlyCommands`, which `context_cmd.go` mutates at init), +`shouldAutoPruneEventsJournal`, the `cmd.Name() != "import" && != "setup"` +branches, `workspace_gate.go`, `main_errors.go`. One +`commandPolicy(mode, *cobra.Command)` keyed by the mode and `CommandPath()` +is consulted first at each site (a new seam — the only `CommandPath()`-keyed +map today is `help_supplements.go`), with an exhaustive Cobra-tree test +**paired with a source scan** that fails on any `cmd.Name()` consumer not +routed through the policy. The flag is a root persistent flag consulted +before any store opens, like `--readonly`. + +| Verb under `--graph-mode link` | Local store | Gate | Maintenance | +| --- | --- | --- | --- | +| `show `, `list`, `types [get]`, `status` | read-only when `link-graph.route: local`; **skipped entirely** when `link-graph.route: server` | shared | no | +| `serve` | serve's classification (A3); **staged** — the one normative sequence: bypass the generic pre-run store gate (the skip-store seam); acquire shared; open a temporary source, read the Scope row, close it; **release shared**; if there is no Scope row: acquire exclusive, reopen, re-check, mint, close, release exclusive; acquire shared; open the serving source; re-evaluate the identity table under it; serve | shared → release → (exclusive → release, only for a mint) → shared; never an upgrade | no | +| `client` | none (writes `config.local.yaml`) | none | no | +| `ledger snapshot` | read-only, local | shared | no | +| `promote` | writable, always local | **shared** — it relies on the lease (the workspace is the holder), so it runs beside a live `bd serve` | no | +| `types install`, `restore`, `ledger apply` | writable, always local | **exclusive** (`internal/workspacegate`, the `bd backup restore` precedent) — the server must be stopped; `commandNeedsExclusiveGate` learns them | no | +| (P3) `create`, `update`, `delete`, `link` | writable | shared | no | + +### A1. `bd init` — graph store initialization (ruling 12) + +1. Runs the graph migrations (Part B4): the replicated series, and the + dolt-ignored `graph_authority_lease` through the tree's three-part + mechanism — its name in `doltIgnorePatterns` (seeded by `MigrateUp` + before either series), a main-series migration that creates it for + existing workspaces, the ignored-series twin for fresh clones (the 0055 / + `ignored/0012` shape; hygiene check D) — and the lease joins + `ignoredSource.sentinelTables` so an at-latest but partially + materialized clone repairs it. +2. **Installs no descriptors.** There is no ledger before mint; the + built-in catalog is installed by `Mint` (A3/A4). `bd init` on any clone + keeps working and installs nothing. A provider answering + `*storage.ErrUnsupported` from the capability probe is skipped silently + at the default verbosity (debug-level only), so gate output is + byte-identical. +3. Writes **no Scope identity**, no witness, nothing to `metadata.json`. +4. Ensures `.beads/.gitignore` carries `config.local.yaml`, + `graph-authority.local.json`, `graph-authority.lock` through + `EnsureGitignoreForBeadsDir`; the template, `requiredPatterns`, and + `trackedRuntimePatterns` gain them, and the witness joins + **`sensitiveFileNames`** so a tracked copy is an **error**, not a + warning. Init paths that bypass that call (`--init-if-missing`, an + external `BEADS_DIR` that differs from the local dolt dir — the gate is + `useLocalBeads`) are not relied on: + the witness manager ensures the entries before its first write (B3). + +**Registered backends:** `bd init` refuses to provision them today; their +own path owes the same obligations. In v0 they do **not serve BDP** (A3). + +### A2. Client wiring — `bd init --bdp-server ` and `bd --graph-mode link client` (ruling 12; amendment A6, ruled 2026-09-07) + +One more `bd init` target, rerouting *above* the storage abstraction: the +link-mode read verbs become a BDP client of the designated server. + +**Two files, by what the key is.** `config.yaml` is git-tracked by default; +per-workspace keys go to **`config.local.yaml`** (merged by viper over +`config.yaml` for machine-specific settings; merged as the sibling of +the project-level `config.yaml` (never a user-level one); the `.beads`/basename requirement is +`yaml_config.go`'s `projectConfigPathFromLoadedState`, so the writer ensures +a project `config.yaml` exists and gets its own path plumbing). + +| Key | File | Values | Notes | +| --- | --- | --- | --- | +| `bdp.scope_url` | `config.yaml` (tracked; yaml-only) | absolute URL | a **project** fact (ruling 7a). Settable while this workspace holds **no witness**; once it does, `bd config set` / `set-many` / `unset` refuse it (one guard in the shared `rejectProtectedConfigKey` path, which `set` and `set-many` call today and `unset` gains an explicit call to — a DB-free file check; a hand edit of the tracked file bypasses it, and the A3 "configured ≠ persisted" row is the real guard) and the URL changes only through `bd --graph-mode link promote --rotate-url` / `bd --graph-mode link restore`, which write it in their `config_written` phase and are refused while `BDP_SCOPE_URL` overrides it | +| `bdp.authority_heartbeat` | `config.yaml` | duration (default `30s`) | hazard R *[deferred under A9]* | +| `bdp.authority_heartbeat_grace` | `config.yaml` | count (default `3`) | hazard R *[deferred under A9]* | +| `bdp.lease_ttl` | `config.yaml` | duration (default `30s`, renewed every third) | hazard S | +| `link-graph.route` | **`config.local.yaml`** | `local` (default) \| `server` | per-workspace; **not settable from env** (`blockedEnvVars`) | +| `bdp.server` | `config.local.yaml` | absolute URL | `https` required unless loopback or `bdp.insecure_http: true` | +| `bdp.insecure_http` | `config.local.yaml` | bool | the named waiver | + +**Writers.** `bd init --bdp-server ` and **`bd --graph-mode link client server +--server [--insecure-http]`** / **`bd --graph-mode link client local`** write the +per-workspace keys through one shared writer. Generic `bd config set` +accepts the `config.yaml` keys (yaml-only routing) and refuses the +per-workspace keys with "use `bd --graph-mode link client`". No token key in config +(`IsSecretKey` + the tracked-config guard; other trackers accept yaml-only +tokens — BDP chooses a file). Mechanics: `bdp.` joins the inline prefix +slice in `IsYamlOnlyKey` and `recognizedConfigPrefixes`; a `localOnlyKeys` class names the +three per-workspace keys; `validateYamlConfigValue` gains the entries. + +**Environment.** `BD_` via viper for the config keys; `BD_BDP_CLIENT` +blocked. `BDP_SCOPE_URL` is **read first, explicitly** (viper consults +`AutomaticEnv` before a `BindEnv` list — the GH#4645 `BD_ACTOR` precedent; +the `BEADS_ACTOR` shape), then `BD_BDP_SCOPE_URL`. The client token file is +**`BEADS_BDP_TOKEN_FILE`**; no `BD_BDP_TOKEN` (child-process inheritance). + +**Credential lookup** (client): `BEADS_BDP_TOKEN_FILE` > credentials file +section `[bdp ]` with `token=`. No redirects followed; +`Authorization` only to the configured origin. + +**Precedence, per command** (a table test pins it): `bd init --bdp-server` +— flag > env > existing `config.local.yaml`, writes `config.local.yaml`; +`bd --graph-mode link client` — writes `config.local.yaml`; `bd config set bdp.scope_url` +— no witness: writes `config.yaml`; witness held: refused; every link-mode +verb — env (where permitted) > `config.local.yaml` > `config.yaml`; +`bd --graph-mode link status` — prints route, target, token source (never the token), +`insecure_http`, and the identity state row. + +**In `link-graph.route: server` mode** the verbs' `openBeadGraph*()` accessors return +a BDP-client realization of the same `graphops` roles (A5); `bd --graph-mode link serve` +there refuses unless `--serve-local-store`. Issue verbs are unaffected. + +### A3. `bd --graph-mode link serve` — serving a Scope (rulings 7b, 9, 12; amendments A1, A2, A7, A9 — ruled 2026-09-07; A10 — ruled 2026-09-08) + +**v0 serves BDP only from SQL-server workspaces.** `bd serve` refuses +embedded Dolt permanently; every Dolt-server topology serves from the +unit-of-work provider — the serving leg, where every fence lives. A +**registered backend** is served from its store arm (`serveDatabaseSource` +routes it there; the backend may itself be embedded) and has no fence to +offer, so its BDP rows are **absent in v0** (`bd --graph-mode link serve` exit 2, typed); +the seam it would declare later is the deferred ADR's to define (an +out-of-tree module cannot import `internal/storage/graphcap`). Embedded +workspaces under A9 as amended by A10 are solo authorities when they have +no remote and no server, with local graph reads and verbs. Embedded client +hosts retain the local graph `ErrNotAuthority` refusal contract. Neither +embedded topology serves BDP over HTTP in v0. + +`bd --graph-mode link serve` is a **thin command over the existing `internal/httpapi` +server**; two policies differ from `bd serve`: it **requires a Scope this +workspace holds** (exit 2 otherwise) and **it is the only serving command that +mints**, through a **staged startup** — the gate rules forbid a +shared→exclusive upgrade, so the sequence in Part A's table is the only +one: shared gate → temporary source reads the Scope row → close → +**release** → (no Scope row: exclusive gate → reopen and re-check → mint +(A4) → close → release) → shared gate → serving source → serve. `bd serve` mounts the rows only when +it holds an already-minted Scope, **converts every graph failure into "rows +absent + notice"**, and is byte-identical with no URL. Both inherit +`errServeReadonly` wholesale. + +```text +bd --graph-mode link serve [--addr IP:PORT] [--allow-non-loopback] [--auth-token-file PATH] + [--insecure-no-auth] [--allowed-host NAME]... (serve's own flags/variables) + [--scope-url URL] first serve: mints under it and writes config.yaml + (config_written phase); later: must equal the + persisted Scope URL or refuse + [--serve-local-store] permit serving in a client: server workspace +``` + +No `--dev-local-test`. Behavior, in order: + +1. **Classification:** `serveDatabaseSource`, verbatim; registered backend → + rows absent (v0); embedded → refused; otherwise the UOW provider, which + gains a `beadsDir` field (`cmd/bd/uow_factory.go`'s + `newSQLServerUOWProvider` receives it today and forwards it to the + journal and root resolution, but the provider struct itself keeps none; + `timedProvider` gains a getter). +2. **Roles from the same source** (provider arm: the provider beneath + `uow.UnwrapProvider`; `checkDatabaseSource`'s exactly-one-source rule + extends to them). +3. **Capability probe, all-or-nothing:** `bd --graph-mode link serve` exit 2 on + `ErrUnsupported`, abort on any other error; `bd serve` → rows absent + + notice in both cases. +4. **Identity** — split by command; `bd serve` **never refuses and never + mints**: + + | Persisted Scope | Configured URL | Witness | `bd --graph-mode link serve` | `bd serve` | + | --- | --- | --- | --- | --- | + | none | none | — | exit 2 | no BDP rows, silent | + | none | set | — | **staged mint** (A4) then serve honestly empty | no BDP rows; notice "unminted; run `bd --graph-mode link serve`" | + | present | none / **different** | any | exit 2 / refuse | no BDP rows; notice | + | present, matches | matches | **absent** (clone; pull into a fresh dir; copy elsewhere — installation key mismatch) | refuse `ErrNotAuthority`; guidance: `bd --graph-mode link promote --steal` if this is the same database (a moved or re-keyed workspace — the lease names the old key), otherwise `bd --graph-mode link promote --rotate-url` | no BDP rows; notice | + | present, matches | matches | **pending transition** | recovery first (B3, by evidence), then re-evaluate | no BDP rows; notice (plain `bd serve` never runs recovery — it never mints, fetches, or publishes; CLI reads answer `ErrNotAuthority` with the same notice) | + | present, matches | matches | `(authority_id, epoch)` stale, or the lease held by **another** holder | refuse; guidance `bd --graph-mode link promote --steal` (an operator assertion of "same database"; a foreign holder's expiry alone never grants a takeover) or `--rotate-url` | no BDP rows; notice | + | present, matches | matches | consistent but the lease **expired while still naming this workspace** (the server was down longer than the TTL) | **self-regrant** on the next lease write (same fence-cell predicate; no epoch change); serve | serve BDP rows | + | present, matches | matches | ledger head not in the store (restore or different history) | refuse `ErrStateRewound`; guidance `bd --graph-mode link restore` | no BDP rows; notice | + | present, matches | matches | `unverified` set | refuse until `bd --graph-mode link restore` | no BDP rows; notice | + | present, matches | matches | consistent | take/renew the lease; serve | serve BDP rows | + +5. **Host policy:** the Scope URL's host joins the allowlist; plaintext + behind TLS termination. +6. **Fencing while serving — the watcher state machine** (`FenceSource`): + `held → renewing → lost`. Hazard S: the lease is renewed every third of + `bdp.lease_ttl` through `RunTxEphemeral` — the renewal rewrites `fence` + **and extends `expires_at = NOW(6) + ttl`** — and asserted inside every + transaction with the full predicate (B3); the watcher **rebuilds its claim + from the witness on every renewal** (an in-workspace `promote --rotate-url` + moves the epoch; a consistent witness makes that a re-arm, not a loss) with + jittered cadence, serialized in-process against the process's own + mutations; every fenced transaction in the shared-gate context carries a + deadline below a third of the TTL and is cancelled and retried past it; a + failed renewal past `expires_at` is `lost`, and so is a protected read + whose remaining lease interval is shorter than its deadline — the serving + leg never regrants on the read path. Hazard R *[deferred under A9]*: the tracking ref + `remotes//` is fetched every `bdp.authority_heartbeat` and + its **ledger head** is read (`SELECT seq, hash FROM graph_ledger_events AS + OF '' ORDER BY seq DESC LIMIT 1`); a head not contained in the + **workspace's witness (reloaded on every check)**, or + `bdp.authority_heartbeat_grace` missed fetches, is `lost` — the tuple + alone cannot distinguish a same-witness twin, and a process-local + expectation would mistake the workspace's own CLI publication for a loss. + On `lost`: the BDP rows are **disabled atomically** (the legacy surface + and its capability list untouched), `bd --graph-mode link serve` exits 3 after + draining, `bd serve` logs and continues; the watcher **joins before the + provider shuts down**. Both hazards → both watchers. +7. **Mounting:** `serveListen(opts, httpapi.Config{…, Graph: …})`. +8. **Lifecycle:** excluded from the post-command maintenance net by + `commandPolicy`, not by the leaf name. + +### A4. `bd --graph-mode link promote` / `restore` / `ledger` / `types install` (rulings 9, 11; amendments A5, A7, A9 — ruled 2026-09-07) + +The only reachers of `BeadGraphAdmin()` and `BeadGraphTypeInstaller()`. +`promote` and `rotate` run under the **shared** gate and rely on the lease +(the workspace is the holder, so they run beside a live server); +`types install`, `restore`, and `ledger apply` run under the **exclusive** +gate with the server stopped. Every replicated graph mutation +(mint, promote, rotate, install, ledger apply, the P1 seeds, P3 writes) +runs through **one primitive on the provider, `PublishGraphMutation`**, and +transitions (mint, promote, rotate, apply) are **multi-phase** (B3). + +**The primitive, per hazard.** *Hazard S:* the fenced transaction (lease +`UPDATE` rewriting the fence cell and extending `expires_at` with one +affected row — self-regranting an expired lease that still names this +workspace — the counter with its allocation nonce, rows, events, each +transition event carrying the transition's **operation id**), scoped commit +(`DOLT_ADD` graph tables + `DOLT_COMMIT -m` via the new `RunTxScopedResult`; +`doltServerTx.Commit` hardcodes `-Am` today), done. *Hazard R [deferred +under A9]:* record local HEAD; `DOLT_FETCH`; require the remote-tracking +HEAD to be an **ancestor** of local HEAD (`DOLT_MERGE_BASE`; unpushed +issue-plane commits do not block); record the remote's graph roots and +ledger head; the fenced transaction; scoped commit (phase +`local_committed`, op commit recorded); `DOLT_PUSH`, classified by a +**typed lift of the whole of `isPushRaceErr`** (`cmd/bd/sync.go`: its +`pushRacePattern` matches all three race routes — the SQL "behind its +remote counterpart", the CLI `! [rejected] … (non-fast-forward)`, and the +`git+*` `(stale info)`/`(fetch first)` forms — **and** its diverged-history +and ancestor-PK-mismatch exclusions, which must travel with it): **race** → +refetch and compare **both** the remote-tracking ref's **ledger head** +(`SELECT seq, hash FROM graph_ledger_events AS OF '' ORDER BY seq DESC +LIMIT 1` — `MAX(seq), hash` errors under Dolt's default +`ONLY_FULL_GROUP_BY`, probed) **and the eight graph tables' diff** between +the recorded remote pre-head and the new remote head (`DOLT_DIFF_STAT` +restricted to those tables) against what was recorded before the +transaction — any graph delta or ledger movement → **fail closed and +undo** (never the `(authority_id, epoch)` tuple alone: a VM-image twin or a +same-authority fork shares it); neither changed (issue-plane divergence +only) → keep the commit, `ErrSyncRequired`, retryable after `bd dolt pull`; **any other failure** → +keep the commit, phase stays `local_committed` with `unpublished` set, +retry on the next attempt. **Undo:** if HEAD is still the op commit, +`DOLT_RESET --soft `, then per graph table `DOLT_RESET('
')` +(unstage — a bare checkout after a soft reset restores from the *staged* +root and reverts nothing, probed) and `DOLT_CHECKOUT('
')` (or +`DOLT_CHECKOUT('HEAD', '--', '
')`), leaving unrelated dirty tables +untouched; if HEAD has moved, `DOLT_REVERT ` (later commits from +other actors are preserved). The versioned undo does not touch the +dolt-ignored lease, so **on either path, and only if the lease still +names this workspace at the operation's epoch**, a compensating +`RunTxEphemeral` write restores the pre-operation lease row — predicated +on the current fence and writing a fresh one (a `DOLT_REVERT` restores the +Scope epoch while the ignored lease keeps the operation's, which would lock +the workspace out of its own lease — probed); when another holder now +legitimately holds the lease, it is left alone. The undo is phased (`undo_started → +versioned_undone → lease_restored`), resumes from its recorded phase on the +next load whether or not the operation still appears in the ledger, and +pauses in-process renewal and graph mutation while it runs. Then `Abandon`. +`doltVersionControlSQLRepository` gains `MergeBase`, `ResetSoft`, +`UnstageTables`, `CheckoutTables`, `Revert`, `HashOfTables`; the remote +pre-head hash is read with `SELECT commit_hash FROM dolt_log AS OF +'' LIMIT 1` (`DOLT_HASHOF` rejects the `remotes/` spelling). Dolt's +staging area is shared, so a scoped `DOLT_COMMIT -m` still sweeps whatever +another session staged in the same tables — a stated limitation, in the +`bd sql` class. A missing remote-tracking ref is +vacuously an ancestor (the push creates it; an empty remote ledger reads as +no head); the ref is `remotes//`, built by one provider API +from the configured sync remote and the active branch — the tree's +`verifyPullLanded` spelling, and the one `DOLT_MERGE_BASE` already receives. Table-scoped staging still sweeps rows +other sessions left uncommitted in the *same* graph tables — consistent +with `bd sql` being out of contract, and stated. *Both hazards → both.* +**A lease row is not proof of "minted here"** — `dolt clone` omits the +dolt-ignored table, but `DOLT_BACKUP` restore and a directory copy carry +the working set with it, and Dolt's `@@server_uuid` is per machine +(`~/.dolt/config_global.json`, identical for a same-machine copy — probed), +so nothing in-band distinguishes a copied database served by a second +`sql-server`. In-place promotion therefore has exactly two paths: +**self-regrant** when the lease row (bound to `scope_url` and +`authority_id`) names this workspace, and **`--steal`**, an operator +assertion of "same database" in the class of force-push and `bd sql`; a +foreign holder's expiry alone never grants a takeover. **`Promote +--rotate-url` is the bootstrap** that creates a new lease row under a new +URL and refuses the old one forever — the path for a clone, a copy, and a +restore that cannot show continuity. On the shared-database leg under A9 this is the whole arbiter; +without A9 hazard R adds the remote fence. Stated residual: a `--steal` on +a copied database creates a second authority. + +- **`Mint`** (serving path: `bd --graph-mode link serve`'s staged startup; + A10 local solo trigger and gate mapping are P1 mechanisms, architecture §2b): precondition *no Scope + row*; INSERT the singleton row, seed `graph_ledger_seq`, `mint` event, + install the built-in catalog with `install` events; hazard S: take the + lease; publish; `config_written` when `--scope-url` supplied the URL; + finalize. +- **`bd --graph-mode link promote`**: precondition a consistent Scope row; three cases, + no fourth. (1) The lease names this workspace → self-regrant regardless + of expiry (no epoch change; the verb reports "already the authority"). + (2) It names another holder → only `--steal` (operator-confirmed) takes + it: CAS the epoch (a lost race is a serialization loser → typed refusal) + with a `promote` event carrying the `op_id`; publish; finalize. (3) No + lease row → **refuse** unless `--rotate-url`, which creates the lease row + under the new URL with `refuse_url(old)` + `rotate(new)`; publish; + finalize. `--rotate-url` beside a live server makes the server exit 3 + (its served URL and host allowlist are fixed at startup). `--rotate-url ` rotates in the same + transition (refused while `BDP_SCOPE_URL` is exported). +- **`bd --graph-mode link restore`**: runs after a database restore (`bd backup restore` + — also reached by `bd bootstrap`'s restore action — calls + `Admin.MarkUnverified` after `RestoreDatabase`, before its commit; a + no-op without a witness). Exempt from the head check; precondition + lineage match under the exclusive gate; branches on `LedgerDurability`: + `in-state` (Dolt, v0) → requires a ledger snapshot reaching the witness's + `{seq, hash}` (`--ledger `, applied through `LedgerApply`) to show + continuity, otherwise **rotates** (`refuse_url` + `rotate`, `config.yaml`, + regrant); `independent` → re-validates (ancestry) and regrants; `none` → + always rotates. Never silent. +- **`bd --graph-mode link ledger snapshot|apply`**: the hash-chained events as JSONL + under a manifest `{scope_url, authority lineage, first_seq, last_seq, + prev_hash of first, head_hash}`. `LedgerApply`'s recovery predicate: + exclusive gate; lineage matches; the store's head equals the manifest's + predecessor; every `hash` verifies. It restores **anti-reuse history, + not graph content**: an applied `allocate` whose row is absent becomes a + **`reserved`** allocation (never reusable; reads answer the gone family), + the Scope lineage is replayed, `graph_scope_history` re-derived, and the + counter set to `last_seq + 1`; then regrant. Full recovery is a database + restore *plus* the lane. +- **`bd --graph-mode link types install `**: post-mint catalog change (P1; W3 + emits the file): a fenced, published mutation with `install` events. + +### A5. Graph verbs (v0 reads; P3 writes) + +```text +bd --graph-mode link show # a Bead or a Link, by path +bd --graph-mode link list [--kind bead|link] [--type URL] [--source PATH] [--target REF] [--after CURSOR] [--limit N] +bd --graph-mode link types [get ] | types install +bd --graph-mode link status +bd --graph-mode link client local | server --server URL [--insecure-http] +bd --graph-mode link serve | promote [--rotate-url URL] [--steal] | restore [--ledger FILE] | ledger snapshot|apply +(P3) bd --graph-mode link create|update|delete … ; bd --graph-mode link link --type URL +``` + +Each verb reaches its role through an accessor (the `cmd/bd/label.go` +pattern plus the client route), with a route-fork test in the shape of the +`*_proxied_integration_test.go` / `*_embedded_test.go` pairs. CLI reads on +the authority workspace read its own state; on any other workspace they +refuse (`ErrNotAuthority`) — there is no replica read in v0. Under A9 as +amended by A10, an embedded workspace with no remote and no server is a solo +authority with local reads and verbs; embedded client hosts and registered- +backend client hosts retain the refusal contract. Solo authority serves no HTTP. +`internal/bdpclient` maps Problems back to the typed errors (round-trip +test). No collection routes before the cursor ADR (`ErrNotServedYet` on +the client route; `list` works on the local route from P1). + +## Part B — Storage interfaces + +### B1. Accessors on `storage.Storage` (amendments A4, A8 — option A wording) + +Named **`BeadGraph*`** (`GraphCounter()` counts the *issue* graph). Six +accessors — `BeadGraphReader`, `BeadGraphTypes`, `BeadGraphTypeInstaller`, +`BeadGraphIdentityReader`, `BeadGraphBootstrapper`, `BeadGraphAdmin` — +with the doc comments of v5 (manager-backed roles; every call reloads the +witness; no request carries authority; the admin role is never held by a +server). Added to **`storage.Storage`**. A required method is **promoted +through every wrapper that embeds the `DoltStorage` interface** — the +wrappers compile unchanged — so every decorator and provider wrapper +**declares** each accessor explicitly and the three censuses (B5) catch the +ones that do not; **direct implementers** (a custom store, mock, proxy) fail +to compile until they add the six stubs — the source break `storage.go` +declares, called out in CHANGELOG as the joint `ReadyClaimer`/`BatchCloser` +entry was. Under option B, an optional `BeadGraphCapable` interface on the +concrete store is **not** promoted through an interface-embedding wrapper, +so every wrapper implements it explicitly and every consumer resolves it. + +### B2. The `graphops` leaf (public, repo root; amendment A4) + +```go +package graphops // imports: stdlib, beadserrors — nothing else + +// ---- requests and results: NO authority fields anywhere (the witness is the store's) +type Cursor string // OPAQUE: store-produced; binds Scope URL, epoch, selection hash, last path; + // P2 adds snapshot identity inside it — no public interface change +type BeadRequest struct{ Path string } +type LinkRequest struct{ Path string } +type BeadSelectRequest struct{ TypeURL string; After Cursor; Limit int } +type LinkSelectRequest struct{ TypeURL string; Source *Ref; Target *Ref; After Cursor; Limit int } // endpoints symmetric (P0 council 2026-09-07) +type IncidentRequest struct{ Path string; Direction Direction /* In | Out | Both */; After Cursor; Limit int } +type DescriptorRequest struct{ URL string } +type InstallRequest struct{ Descriptors []TypeDescriptor } + +type OwnedLinkGroup struct{ TypeURL string; Links []Link } // the pinned schema keys ownedLinks by Link Type URL +type BeadRecord struct{ Bead Bead; OwnedLinks []OwnedLinkGroup } // groups in code-unit order of TypeURL; Links in code-unit + // order of path; an owned Type with no Links is an EMPTY group +type BeadPage struct{ Items []BeadRecord; Next Cursor } +type LinkPage struct{ Items []Link; Next Cursor } + +type Reader interface { + Bead(ctx, BeadRequest) (BeadRecord, error) + Link(ctx, LinkRequest) (Link, error) + Beads(ctx, BeadSelectRequest) (BeadPage, error) // WHERE path > last ORDER BY path LIMIT n, binary-collated column + Links(ctx, LinkSelectRequest) (LinkPage, error) + IncidentLinks(ctx, IncidentRequest) (LinkPage, error) // one UNION over (source, target) indexes, ordered, limited +} +type DescriptorReader interface { + Descriptors(ctx) ([]TypeDescriptor, error) // ordered by URL; bounded by MaxCatalog + Descriptor(ctx, DescriptorRequest) (TypeDescriptor, error) +} +type TypeInstaller interface { + Install(ctx, InstallRequest) (InstallResult, error) // post-mint; fenced; published on hazard R; idempotent by fingerprint +} +type IdentityReader interface { + Read(ctx) (ScopeIdentity, error) // Scope row + witness claim (Held, Epoch, LedgerSeq, Unverified, Pending) + LedgerDurability(ctx) (LedgerDurability, error) // in-state | independent | none (ruling 11) +} +type ScopeBootstrapper interface { + Mint(ctx, MintRequest) (ScopeIdentity, error) // multi-phase; fenced per hazard; catalog installed inside +} +type Admin interface { + Promote(ctx, PromoteRequest) (ScopeIdentity, error) // multi-phase; fenced per hazard; RotateURL optional + Rotate(ctx, RotateRequest) (ScopeIdentity, error) // refuse_url(old) + rotate(new), one transaction; config.yaml in config_written + LedgerSnapshot(ctx, LedgerRange) (LedgerManifest, []LedgerEvent, error) + LedgerApply(ctx, LedgerManifest, []LedgerEvent) (LedgerApplyResult, error) // recovery predicate; anti-reuse history; regrants + MarkUnverified(ctx) error // no-op without a witness + ClearUnverified(ctx) error +} + +type AllocationState = string // live | reserved | pruned | erased ("reserved": ledger-applied, row absent) + +// NOT here: transaction-bound provider capabilities live in internal/storage/graphcap — +// StateVersioner { GraphStateVersion(ctx, tx DBTX) (StateVersion, error) } // DOLT_HASHOF_TABLE('') × 8, sha256 +// GraphPublication (a registered backend's own hazard-R fence; deferred) +// LeaseClaim{InstallationKey, Epoch} +// — the public leaf carries no runner type, so the capability that takes one cannot be public. +``` + +**Values** (`Bead`, `Link`, `Ref`, `Properties`, `Revision`, `Attribution`, +`TypeDescriptor`, `OwnedLinkDecl`, `ScopeIdentity`, `LedgerEvent`, +`LedgerManifest`) have unexported fields and constructors that enforce the +laws in `laws.go`. `Properties` is the immutable raw-JSON object value from +the plan; its canonical bytes are what B4 stores. `Ref` is a sum: in-Scope +(`Path`) or external (`URL`). `Revision` is 128 bits from `crypto/rand`, +lower-hex. A `LedgerEvent` carries `{seq, kind, op_id, path|scope_url, +revision?, fingerprint?, authority_id, epoch, at, prev_hash, hash}` with +`hash = sha256(canonical(event without hash))`. + +**Bounds:** `MaxExpandedRows` with `LIMIT (MaxExpandedRows − materialized) + 1`; +`Max` required on owning Types. **Statement budgets, per role method** +(pinned by the contract; a validation run has its own budget outside the +read's transaction; the lease `UPDATE` of a mutation counts as one; a CLI +read's one-time ephemeral regrant on its own expired lease is a separate +transaction outside the budget): + +| Method | Statements | Composition | +| --- | --- | --- | +| `Bead` / `Beads` page | ≤ 7 (6 on a descriptor-cache hit) | Scope row; ledger head; lease; state version; row/page; descriptors; batched owned links | +| `Link`, `IncidentLinks`, `Links` page | ≤ 5 | Scope row; ledger head; lease; state version; the query (one `UNION` for incident) | +| `Descriptors`, `Descriptor` | ≤ 5 | Scope row; ledger head; lease; state version; catalog | +| `IdentityReader.Read` | 3 | Scope row; ledger head; lease | + +**The row-level fence (ruling 13).** Every mutating body issues `SET +@bd_graph_role = 1` as its first statement inside the transaction and +`SET @bd_graph_role = NULL` as its last statement before `COMMIT` or +`ROLLBACK`, on every exit path (deferred); reads never set it. The clear +is load-bearing: probed over the MySQL protocol with a one-connection +pool, a transaction that commits without clearing leaves the next plain +statement on that connection unfenced, and one that clears does not. Verification row (ii) corrected the cancellation claim (2026-09-07): a +transaction cancelled *between* statements is rolled back and its +connection **pooled with the variable still set** on both server legs +(the UOW leg's `closeAttempt` rolls back on `context.WithoutCancel` and +releases the connection; the `*sql.Tx` shape keeps it because the driver +implements `SessionResetter` and `Validator`); only a mid-statement +cancellation closes the socket. The rule: the deferred clear runs on +`context.WithoutCancel(ctx)` with its own short timeout — proved to fence +the pooled session — and a clear that cannot be confirmed poisons the +connection (closed, never pooled); the CLI leg's wrapper begins its +transaction on `context.WithoutCancel` or pins `db.Conn`. The embedded leg +has no pool hazard: its driver's `ResetSession` returns `ErrBadConn`, so +every checkout is a fresh session. Mutating budgets carry two +statements more than their SQL alone. A body that omits the variable +cannot write — the triggers refuse its own statements — so the +conformance suite catches the omission by construction. + +**Errors:** `ErrNoScope`, `ErrScopeExists`, `ErrNotAuthority`, +`ErrStateRewound`, `ErrStateChanged`, `ErrSyncRequired`, `ErrUnpublished`, +`ErrURLReused`, `ErrRepresentationTooLarge`, `ErrNotServedYet`, +`GoneError{Path, State}`. Home (P0, recorded 2026-09-07): the plane-neutral +sentinels are declared in `beadserrors` and aliased here; `ErrNoScope`, +`ErrScopeExists`, `ErrURLReused`, and `GoneError` are `graphops`'s own, +because `beadserrors`' charter keeps domain-naming refusals in the leaf. +`GoneError` matches `ErrNotFound` under `errors.Is` (the spec's same-404 +default); a handler opts into the 410 by `errors.As`. + +**P0 implementation notes (recorded 2026-09-07 after council 11's fold; the +code on `janet-beadgraph-p0` is the reference).** Scope-URL laws split in two: +`ValidateScopeURL` is the client-side law (a client may reference a bdptest +dev server's `…/local-test/` Scope) and `ValidatePersistedScopeURL` the +persisted-identity law used by `Mint`, `Rotate`, ledger events carrying +`scope_url`, and manifests (`local-test` refused there). `NormalizeScopeURL` +normalizes the **whole origin** under one WHATWG model — scheme and host case, +percent-encoded host characters, the ends-in-a-number rule (all-digit or `0x` +last label ⇒ IPv4, rendered dotted-decimal), IPv6 compression (`[::ffff:102:304]`), +ports with leading zeros and default ports — and the same model classifies a +reference as in-Scope or external; a noncanonical in-Scope spelling is refused, +an external reference is preserved byte-for-byte; a trailing-dot registered name +is canonical and a distinct host; no IDNA (configure IDN hosts as A-labels). +`LinkSelectRequest` takes `Source *Ref` and `Target *Ref` (endpoints symmetric; +the one-in-Scope-endpoint law). Ledger: `MaxLedgerSeq = MaxUint64-1`, seq ∈ +[1, MaxLedgerSeq]; the counter is exhausted at `MaxUint64` and the chain +refuses wraparound. Descriptor canonical form: `description:""` ≡ absent, +`propertiesSchema:""` refused, a zero endpoint constraint is the empty set, +`conformsTo` sorted by code unit. Every string entering a JSON-backed value must +be valid UTF-8. **Ruled on bdp#1 (2026-09-08):** `ownsOutgoing` admits the +wildcard entry `"*": { max }` — every outgoing Link Type not listed explicitly +is owned, `max` bounds the whole owned set, explicit entries take precedence +for the types they name; `OwnedLinkDecl` gains that variant and `Owns` resolves +explicit-then-wildcard; the record's owned groups exist for types actually +present plus empty groups only for explicitly declared types; no group is +ever keyed `"*"`, and `Owns("*")` is false (it is a key, not a Type). Landed +on the P0 branch (1cbb5e6e3): `OwnedLinkDecl` is a sum — +`NewWildcardOwnedLinkDecl(max)`, `Wildcard()`, `WildcardOwnedLinkKey` — and +`ValidateTypeURL("*")` is refused by name everywhere a Type URL is expected. +**Historical wire description, superseded by the §0 `19923f5b` adoption:** +the original pinned bundle's `propertyNames: +absoluteHttpUrl` on `ownsOutgoing` and `ownedLinks` refuses `"*"` (bdpwire's +decoder holds member shape, not key grammar; the test-only tripwire +`TestWildcardOwnedLinkKeyIsNotInThePinnedBundle` was retired by that adoption). + +### B3. Bodies, the witness manager, and legs + +Bodies take **`DBTX`**, the witness, and the process-local claim: + +```go +func ReadBeadInTx(ctx, tx DBTX, w authority.Witness, claim graphcap.LeaseClaim, req graphops.BeadRequest) (graphops.BeadRecord, error) +``` + +**`internal/storage/authority` — the witness manager** (no SQL): + +- **Installation key.** A random id created once in the directory the + tree's `UserConfigYamlPath` resolver (`internal/config/user_config_path.go`) + chooses — the documented `~/.config/bd` when possible, the native + `os.UserConfigDir` location otherwise — file `installation-id`, or the + path in `BEADS_INSTALLATION_ID_FILE`: `O_EXCL`, mode 0600, re-read after + creation (the winner of a race is what every process uses), directory + fsynced; an unresolvable directory fails closed. `InstallationKey = + sha256(id ":" realpath(.beads))`. Never the hostname. Stated residuals: the + id is **per OS user** (a service user's `bd serve` and an operator's + `bd --graph-mode link promote` compute different keys — cross-user shared roots are + unsupported, as the workspace gate already declares); an **ephemeral home** + regenerates it on every start (`ErrNotAuthority` until `bd --graph-mode link promote`); + a moved workspace needs a `bd --graph-mode link promote` (guidance: "moved or copied"). +- **`Load`** is a plain read; a pending transition triggers **recovery** + before any assertion (below). +- **`Advance`** takes the exclusive lock with a bounded poll (`internal/lockfile` + has no timeout API; the `workspacegate` poll is the precedent; both + `ErrLocked` and `ErrLockBusy` honored) and, **while holding it, asks the + evidence provider** to decide a **descendant-aware compare-and-advance**: + a candidate whose ledger head is an exact prefix of, and whose commit is + an ancestor of, the current witness's is a successful no-op; newer fields + are never replaced by older ones; a forked candidate is rejected — two + writers can commit in one order and advance in the other, and opaque + hashes alone cannot decide this; then `internal/atomicfile` (file fsync) + and a directory fsync. +- **Transitions are multi-phase, recovered by evidence.** `Begin` + (preflight: ensure the three ignore entries, refuse a git-tracked witness, + take the lock — **held continuously through `Finalize`/`Abandon`**, and + recovery acquires it first, so a live transition is never mistaken for + crash residue) writes `{kind, op_id, phase: begun, pre_head, + pre_ledger_head, pre_lease, remote_pre_head, expected_roots, + config_intent}`; every ledger event carries an indexed, hash-covered + `op_id` column and the commit message repeats it; the SQL-free manager + asks the store through an **evidence provider** ("is `op_id` in the + ledger?", "does the current commit descend from this one?", "is this + head an exact prefix?"); after the scoped commit `SetPhase(local_committed, op_commit)`; + after the push `published`; after `config.yaml` `config_written`; then + `Finalize` writes the new witness and clears the record. **Recovery** on + `Load` never trusts the phase alone: it first asks the ledger whether + `op_id` is present (a crash between the commit and the phase write leaves + `begun` with the operation committed — then it is `local_committed`); with + no local operation → `Abandon`; with a local operation on a shared + database when hazard R is not in force (no remote, **or any remote under + A9**) → publication is satisfied: **execute any outstanding + `config_intent`, record `config_written`, then `Finalize`**; with hazard + R in force → classify the remote with the same ledger-plus-eight-table + delta classifier as the push race, in this precedence: {contains this + operation → `published`; still at `remote_pre_head` → resume the push; + issue-plane-only movement → `ErrSyncRequired`, keep the commit; graph + delta from foreign work → undo and `Abandon`}; `published` → write config + if intended; `config_written` → `Finalize`. `LedgerApply`'s evidence is + kind-specific — the manifest's head, range, and expected roots — because + imported events keep their original `op_id`s (rewriting them would break + their hashes). Retrying a transition never mints a second epoch. Ordinary + published mutations (`Install`, P3 writes) carry an `op_id` in their event + and an `unpublished` marker until pushed, recovered the same way. +- **Order of an ordinary mutation:** DB commit (and publish) before the + witness advances; a crash between leaves the witness behind, which the + next assertion tolerates. Residual (P3): an acknowledged write never + witnessed before a restore. + +| Leg | Files | Body | +| --- | --- | --- | +| server Dolt (CLI) | `internal/storage/dolt/beadgraph_*.go` | witness + claim per call; `withReadTx` / `withRetryTx`; scoped commit; `PublishGraphMutation` | +| embedded Dolt (CLI only, A9 as amended by A10) | `internal/storage/embeddeddolt/beadgraph_*.go` | same body, `withConn`; solo topology wires the full local read contract with its witness and workspace-gate lease; client hosts wire `ErrNotAuthority` refusal. No embedded HTTP serving. | +| unit of work (**the serving leg**) | `internal/storage/domain/beadgraph.go`, `internal/storage/domain/db/beadgraph.go` (+ the version-control repository's new `MergeBase`/`ResetSoft`/`CheckoutTables`/`Revert`/`HashOfTables`), `internal/storage/uow/beadgraph_*.go` (`BeadGraphUseCase()`; `RunTxRead`; **`RunTxScopedResult(tables, msg)`** — new, since `doltServerTx.Commit` hardcodes `DOLT_COMMIT('-Am')`; `RunTxEphemeral` for renewal; `PublishGraphMutation` on the provider) | **same body** | + +Every protected body begins with `assertAuthorityInTx(ctx, tx, w, claim, +mutating)`: Scope row identity; ledger head present (exact prefix) and +`MAX(seq) >= w.LedgerSeq`; on hazard S the lease row — a protected read `SELECT`s it inside the +read transaction and checks holder key, epoch, **and `expires_at > +NOW(6)`** (a holder/epoch match alone proves only that no takeover was +visible in the snapshot); **reads never write the lease**: on the serving +leg the watcher renews and a read whose remaining interval is shorter than +its deadline fails closed as `lost`; a CLI read whose own lease has expired +regrants **once, ephemerally, before opening a fresh read transaction** +(a read transaction opened before the regrant keeps its expired snapshot — +probed) and retries; the read's context deadline is derived from the +remaining lease interval (the shared `route()` deadline of sixty seconds +exceeds the default TTL, so BDP rows carry their own per-row deadline below +a third of the TTL); a mutation reads the `fence` cell and a +mutation `UPDATE graph_authority_lease SET heartbeat_at = ?, expires_at = +NOW(6) + ttl, fence = WHERE id = 1 +AND holder_installation_key = ? AND epoch = ? AND fence = ` and requires **exactly one affected row** — which also **self-regrants +an expired lease that still names this workspace** (a server restart longer +than the TTL needs no promotion); a lease held by *another* holder is taken +**only with `--steal`** — its expiry alone never grants a takeover. **Dolt merges concurrent +transactions cell by cell** (probed on 2.1.8): a takeover that rewrites +`holder`/`epoch` while a mutation rewrites `heartbeat_at` lets *both* +commit; only a same-cell-different-value write is a `1213` serialization +failure. Every lease write — grant, steal, expiry reclaim, renewal, and the +per-mutation fence — therefore rewrites `fence` with a fresh random value, +so any two of them conflict (probed on Dolt 2.1.8 for the versioned path, +the ephemeral plain-`COMMIT` path, read-then-mutate, and disjoint-column +takeovers; the tree's `TestRowLockForcesConflictOnDisjointCellWrites` is the +same trick for `row_lock`). `withRetryTx`/`RunTxResult`/`RunTxEphemeral` +replay the loser, which **re-evaluates its preconditions** with a new random +fence: a still-authorized writer (two mutations, or a renewal and a +mutation) succeeds serially; a superseded, stolen, or expired-and-retaken +claim matches zero rows → refusal. On the scoped-commit path the `1213` +surfaces from `CALL DOLT_COMMIT` (the trailing `COMMIT` then succeeds with +nothing persisted), so `RunTxScopedResult` keeps that call inside the +retried closure. Bound, stated: a fenced transaction that spans a renewal loses +whenever the renewal commits first, so every fenced transaction **in the +shared-gate context** carries a deadline below a third of the TTL +(cancelled and retried past it; the replay budget allows more than one +attempt), in-process renewal is serialized against the process's own +mutations with jittered cadence, and `types install` is exclusive (the +server stopped; the sole writer sets `expires_at` itself and runs +unbounded). The `leases` precedent's +`INSERT … ON DUPLICATE KEY UPDATE … IF(...)` is a statement-time guard and +does not fence at commit; this design does not rely on it. The ledger +counter is the same shape: `UPDATE graph_ledger_seq SET next_seq = next_seq ++ 1, alloc_nonce = WHERE id = 0` — a bare `+ 1` from the same +value **converges** (both allocators commit, one increment lands; probed), +the random cell makes it a conflict, and the events PK is the second guard +(it too converges on byte-identical rows, which the nonce prevents); the **graph-state version** from the provider's `StateVersioner` +(Dolt: `DOLT_HASHOF_TABLE('')` for each of the eight +replicated graph tables in the fixed B4 order, the eight hashes hashed +together with sha256 — the function exists in 2.1.8 and takes exactly one +argument; `DOLT_HASHOF_DB()` is not used because every ephemeral write, +including this lease's own renewal, moves it) equal to +`w.StateVersion`, else `ErrStateChanged` **without validating in the held +transaction**; the accessor then validates under **one singleflight +coordinator per provider instance** (per-request `timedProvider` roles +share it) in its own transaction — ancestry `DOLT_MERGE_BASE(w.StateCommit, +HEAD)`; for the ledger-covered tables — descriptors, allocations, the +ledger — the delta must be explained by ledger events since the recorded +head, and bead and link bodies are checked by row provenance (ruling 13) — +advances the witness, and retries once. A refused delta is **undone** +when the recorded HEAD is an ancestor of HEAD: the eight tables are +reverted to their state at `w.StateCommit` in a new commit (the hazard-R +undo shape — table-scoped, later commits preserved) and the caller sees one +`ErrStateChanged`; otherwise the witness is marked `unverified` (ruling 14). The validation +also runs the **fence census** (Part D.7 = A): each replicated table carries +its three ruling-13 triggers; a missing one is repaired with the migration's +idempotent pair before the delta is judged. Descriptor caches are keyed by the descriptors table's hash. +Providers without `StateVersioner` fail closed. Exempt from the head check, +with their own preconditions: `Mint`, `Promote`, `Rotate`, `LedgerApply`, +`IdentityReader`, the witness-file operations. + +### B4. Schema (migrations; frozen once merged) + +Rules the tree enforces: migrations are **frozen once merged** — hygiene +check C forbids editing a shipped file (a git-diff check), and the runtime +`content_skew.go` compares `schema_migrations.content_hash` across clones; +**no `NOW()`/`UUID()`/`RAND()`** in migration SQL (check B) — timestamps and +ids come from Go; real-Dolt tests for anything a `sqlmock` echo cannot +exercise; DDL is not transactional across statements, so each `CREATE` is +guarded and resumable. **Initial P1 scope: eight replicated tables in five files**, with unresolved +`NNNN` migration slots: slot +0067 is occupied by the merged versioned-beads Phase 1 migration (`issue_versions`, +the `store_epoch` singleton, `issues.current_revision`); slot 0068 is reserved +by its still-open Phase 2 (`0068_add_attribution_status`, +`issue_versions.attribution_status` and byte-preserving `durable_state` LONGBLOB +storage; the `version_id` and participation +steps remain deferred at the §0a pin), +and the historical graph claim is on the still-open #6149 branch, not on +main (row added 2026-09-07 at c53ef8810 as "0069 and later"). Its current +rows propose Phase 3 at 0069–0070 and graph at 0071 if Donna agrees, while +the graph row still says 0069+ (exact source in plan §0a). The overlap is +unresolved and this document selects no slot; P1 must recheck after its ADR +and owner coordination — +`NNNN_beadgraph_scope.up.sql` (scope, history), `NNNN_beadgraph_types.up.sql`, +`NNNN_beadgraph_beads.up.sql`, `NNNN_beadgraph_links.up.sql`, +`NNNN_beadgraph_ledger.up.sql` (events, counter, allocations) — plus the +lease's three parts: its name in `doltIgnorePatterns`, a main-series +`NNNN_beadgraph_authority_lease.up.sql` that creates it for existing +workspaces (the 0055 `__temp__` + conditional `RENAME` shape), and +`ignored/NNNN_beadgraph_authority_lease.up.sql` for fresh clones (check D); +the lease joins `ignoredSource.sentinelTables`. It is reached exactly as +`issueops/lease.go` reaches `leases`: on the default branch's working set +(branch-qualified sessions do not see it — which is why publication stays +on the default branch, Part D.5). + +**The row-level fence (ruling 13).** Each of the five table files also +carries, for every replicated table it creates, three triggers — +`
_bi`, `
_bu`, `
_bd` (`BEFORE INSERT/UPDATE/DELETE … +FOR EACH ROW`), body `BEGIN IF @bd_graph_role IS NULL THEN SIGNAL SQLSTATE +'45000' SET MESSAGE_TEXT = '
: out-of-role write refused'; END IF; +END` — twenty-four in all, each a `DROP TRIGGER IF EXISTS` + `CREATE +TRIGGER` pair (Dolt 2.1.8 has no `CREATE TRIGGER IF NOT EXISTS`; the pair +is resumable), no `NOW()`/`RAND()`. The lease table carries none +(dolt-ignored, fenced by its own law). Probed on Dolt 2.1.8: the body +parses only in `BEGIN … END` form; it fires with errno 1644; a session +variable gates it; the triggers replicate through the versioned +`dolt_schemas` table by push, clone, and pull; they are silent on +`DOLT_MERGE` and `DOLT_PULL` (ruling 14's territory); and one +multi-statement `Exec` of such a file over the tree's +`multiStatements=true` DSN (`doltutil/dsn.go`) creates them — the files +ship through `execMigrationBody` unchanged (the `dolt sql` CLI splits on the body's +inner `;`, so the `AllMigrationsSQL()` bundle the CLI-parity test loads with +`dolt sql -f` needs a `DELIMITER`-wrapped `cliCompatibleMigrationSQL` +rendition — which the protocol path in turn refuses — and the parity +oracle, which excludes `dolt_` tables, gains a trigger count). Three **P0 +verification rows** gate the fence — a failure ships v0 with the +validator alone and ruling 13 records it: **answered 2026-09-07** +(`engdocs/BDP_P0_VERIFICATION_ROWS.md`, spikes on the P0 branch): (i) +**PASS** — `embeddeddolt.OpenSQL` with one pinned connection and one +`ExecContext` of the migration text creates the triggers, they fire, the +variable gates them, and `dolt_schemas` stages and commits; the +skip-by-rule branch is not needed; (ii) **PASS-WITH-RULE** — B3's clear on +`WithoutCancel` and poison on failure; (iii) **PASS-WITH-RULE** — hygiene +checks A–E pass on a trigger-carrying file and the real runner commits +`dolt_schemas` with the table and cursor; three P1 rules follow: the +CLI-bundle rendition above; check D's clone-local list and +`doltIgnorePatterns` must learn `graph_authority_lease` before the B4 twin +is enforced; `migrationSQLTouchesTable` cannot see trigger DDL, so a +pre-existing dirty `dolt_schemas` is refused by the post-pass signature +check rather than up front. **Ruled (Part D.7 = A, 2026-09-08):** +`dolt_schemas` is outside the eight hashed and inspected tables, so an +out-of-band `DROP TRIGGER` replicates silently and `content_skew.go` +cannot see it (equal hashes) — proposed: the validator and ruling 14's +inspection set gain a **fence census** over `dolt_schemas` (trigger +presence per graph table). +Clones receive the triggers with the schema and refuse raw DML too — +harmless: clones are not authorities, and their in-role paths set the +variable. `bd sql` gains no flag; the deliberate override is a +proxied-mode batch whose first statement sets the variable, or a raw +client session. + +**Collation.** Dolt's default collation is already binary +(`utf8mb4_0900_bin` — probed), and no migration in the tree declares one. +Every identifier column below still carries **`CHARACTER SET utf8mb4 +COLLATE utf8mb4_bin`** (written `BIN`) as the defense for providers whose +default is case-insensitive, with a contract case. + +**Two epochs, two spellings (recorded 2026-09-07).** Every `epoch` in the +graph tables — `graph_scope.epoch`, the lease's `epoch`, `last_epoch`, +`birth_epoch` — is the **authority epoch** of ruling 9/A5, rotated by +promote, rotate, and restore-without-continuity. It is not the History +lane's `store_epoch` (versioned beads, migration 0067: bumped only by +restore, destructive reinit, or a token-scheme change, and voiding only +addresses of versions no longer served). To keep SQL unambiguous, P1 spells +the graph columns `authority_epoch`, `last_authority_epoch`, and +`birth_authority_epoch`; the docs keep the short names as the concept's name. + +**Identity is Scope-relative.** Rows store the canonical Scope-relative +`path`; the absolute URL is `scope_url + path`, computed at the boundary, +so a URL rotation rewrites no rows. + +**JSON is bytes.** `properties` and `descriptor` are canonical JSON bytes in +`LONGBLOB`, never the engine `JSON` type (the tree measured `1.0`→`1`, +integers past 2^53 rounded, `1e300` expanded in `internal/storage/issueops/metadata_cas.go` and the public +`issueops/metadatacas.go`; `-0.0`→`0` per the role guide). The canonical +form (P0 decision 3, recorded 2026-09-07) is RFC 8785 serialization applied +to each number literal's **exact decimal value**, never its nearest binary64: +`1.0`→`1`, `-0.0`→`0`, `1e300`→`1e+300`, and integers past 2^53 survive +intact; the exponent bound applies to the normalized value so that +canonicalization is a fixed point. Every string entering a canonicalized or +hashed value must be **valid UTF-8** (P0 council: invalid bytes collapse to +U+FFFD in JSON, so distinct values would hash identically). The frozen +ledger hash layout is `graphops`' golden: JCS of the event's members with +absent members omitted, `at` as RFC 3339 UTC with six fractional digits, +sha256 hex, genesis = 64 zeros. The value limit is a P1 number (Part D.1). +Admission law (bdp#21, ruled 2026-09-08): a number literal whose exact +decimal value does not round-trip through IEEE-754 binary64 (nearest double, +serialized shortest, equal to the literal's value) is refused at admission +with the offending JSON pointer, so on every stored `properties`/`descriptor` +value the exact-decimal form and a JCS peer's binary64 serialization agree +byte-for-byte; the ledger framing is exempt (its `seq`/`epoch` are Go integers +hashed exactly over the full uint64 range) and its frozen layout is unchanged +(P0 commit 944b1fc9f). Descriptor canonical form sorts `conformsTo` (and endpoint +`conformsTo`) by code unit — they are sets — so reordered parents fingerprint +identically. Canonicalization is the only thing the store does to the +content of `properties`: a URI or pinned reference inside it is neither +validated, resolved, canonicalized as a URL, nor traversed, and it is not an +edge — `graph_links` holds every edge there is, and a reference that needs +graph semantics is a Link, owned under an explicit entry or the wildcard +(bdp#1 item 5 as amended, ruled 2026-09-08). + +**Provenance on every mutable row.** `last_authority_id` / `last_epoch` are +stamped by every mutation on descriptors, beads, links, and allocations. + +**The graph-state version** is `DOLT_HASHOF_TABLE('')` for each of +the eight replicated tables below, in this order, the eight hashes hashed +together with sha256; the lease is ephemeral and excluded. The descriptors +table's hash within it keys the descriptor cache. + +| Table | Columns (type; nullability) | Keys / constraints | +| --- | --- | --- | +| `graph_scope` | `id TINYINT NOT NULL` (always 1), `scope_url VARCHAR(2048) BIN NOT NULL`, `authority_id CHAR(32) NOT NULL`, `epoch BIGINT UNSIGNED NOT NULL`, `minted_at DATETIME(6) NOT NULL` | `PRIMARY KEY (id)`, `CHECK (id = 1)` — singleton. **Distinct from History's `store_epoch`** (migration 0067), which fences restore and replacement on the issue plane; this epoch fences promotion on the graph plane; a restore reasons about both | +| `graph_scope_history` | `scope_url VARCHAR(2048) BIN NOT NULL`, `refused_seq BIGINT UNSIGNED NOT NULL`, `refused_at DATETIME(6) NOT NULL`, `reason VARCHAR(64) NOT NULL` | `PRIMARY KEY (scope_url)`; derived from `refuse_url` events | +| `graph_type_descriptors` | `url VARCHAR(2048) BIN NOT NULL`, `descriptor LONGBLOB NOT NULL`, `fingerprint CHAR(64) NOT NULL`, `installed_seq BIGINT UNSIGNED NOT NULL`, `installed_at DATETIME(6) NOT NULL`, `last_authority_id CHAR(32) NOT NULL`, `last_epoch BIGINT UNSIGNED NOT NULL` | `PRIMARY KEY (url)`; `UNIQUE (fingerprint)` | +| `graph_beads` | `path VARCHAR(1024) BIN NOT NULL`, `type_url VARCHAR(2048) BIN NOT NULL`, `revision CHAR(32) NOT NULL`, `attribution_principal VARCHAR(512) NULL`, `attribution_status ENUM('claimed','unknown') NULL`, `properties LONGBLOB NOT NULL`, `last_authority_id CHAR(32) NOT NULL`, `last_epoch BIGINT UNSIGNED NOT NULL`, `created_at DATETIME(6) NOT NULL`, `updated_at DATETIME(6) NOT NULL` | `PRIMARY KEY (path)`; `INDEX (type_url, path)`; `FOREIGN KEY (type_url) REFERENCES graph_type_descriptors(url)`; attribution columns both NULL or both set | +| `graph_links` | `path VARCHAR(1024) BIN NOT NULL`, `type_url … BIN NOT NULL`, `revision CHAR(32) NOT NULL`, `source_kind ENUM('in','ext') NOT NULL`, `source_path VARCHAR(1024) BIN NULL`, `source_url VARCHAR(2048) BIN NULL`, `source_pin VARCHAR(512) BIN NULL`, `target_kind ENUM('in','ext') NOT NULL`, `target_path VARCHAR(1024) BIN NULL`, `target_url VARCHAR(2048) BIN NULL`, `target_pin VARCHAR(512) BIN NULL` (endpoints symmetric and pins variable-width — **changed 2026-09-07, P0 council:** the pinned fixtures carry external-source Links such as `urn:external:pin-witness → beads/demo-f`, and a pin is an opaque string echoed byte-identically, so `CHAR(32)` cannot hold it), `attribution_*`, `properties LONGBLOB NOT NULL`, `last_authority_id`, `last_epoch`, timestamps | `PRIMARY KEY (path)`; `INDEX (source_path, type_url, path)`, `INDEX (target_path, type_url, path)` (a typed incoming read is a keyed scan — accepted from sjarmak's review); `FOREIGN KEY (source_path) REFERENCES graph_beads(path)` (a NULL `source_path` — external source — skips the check); `CHECK` exactly one of `source_path`/`source_url` per `source_kind` and exactly one of `target_path`/`target_url` per `target_kind`, and at least one endpoint `in` (the pinned spec's endpoint law); **no** uniqueness on (type, source, target) | +| `graph_ledger_seq` | `id TINYINT NOT NULL` (always 0), `next_seq BIGINT UNSIGNED NOT NULL` (`next` is reserved in Dolt's parser), `alloc_nonce CHAR(32) NOT NULL` | `PRIMARY KEY (id)` — **the single-row sequence counter**: `UPDATE … SET next_seq = next_seq + 1, alloc_nonce = WHERE id = 0` inside the mutation's transaction; the random cell is what makes two allocators a `1213` conflict (a bare increment converges under Dolt's cell-wise merge — probed); a rolled-back transaction burns no seq; seeded by `Mint`; set by `LedgerApply` | +| `graph_ledger_events` | `seq BIGINT UNSIGNED NOT NULL`, `op_id CHAR(32) NOT NULL` (indexed; covered by the hash), `kind ENUM('mint','install','update','promote','rotate','allocate','tombstone','refuse_url') NOT NULL`, `path VARCHAR(1024) BIN NULL`, `scope_url VARCHAR(2048) BIN NULL`, `resource_kind ENUM('bead','link') NULL`, `revision CHAR(32) NULL`, `state ENUM('pruned','erased') NULL`, `fingerprint CHAR(64) NULL`, `authority_id CHAR(32) NOT NULL`, `epoch BIGINT UNSIGNED NOT NULL`, `at DATETIME(6) NOT NULL`, `prev_hash CHAR(64) NOT NULL`, `hash CHAR(64) NOT NULL` | `PRIMARY KEY (seq)` — **append-only, hash-chained**; `UNIQUE (hash)`; `INDEX (path, seq)`; `INDEX (op_id)` (non-unique: one operation may append several events); `CHECK` per kind. Every mutation is an event | +| `graph_allocations` | `path VARCHAR(1024) BIN NOT NULL`, `resource_kind ENUM('bead','link') NOT NULL`, `birth_seq BIGINT UNSIGNED NOT NULL`, `birth_authority_id CHAR(32) NOT NULL`, `birth_epoch BIGINT UNSIGNED NOT NULL`, `state ENUM('live','reserved','pruned','erased') NOT NULL`, `tombstone_seq BIGINT UNSIGNED NULL`, `last_authority_id CHAR(32) NOT NULL`, `last_epoch BIGINT UNSIGNED NOT NULL` | `PRIMARY KEY (path)` — the O(1)/O(log n) ID test (ruling 3); **derived state**; `reserved` = ledger-applied with no row (A4) | +| `graph_authority_lease` (**dolt-ignored**, never replicates) | `id TINYINT NOT NULL`, `scope_url VARCHAR(2048) BIN NOT NULL`, `authority_id CHAR(32) NOT NULL` (bound to the Scope row), `holder_installation_key CHAR(64) NOT NULL` (the workspace), `renewer CHAR(32) NOT NULL` (informational: the process that last renewed), `epoch BIGINT UNSIGNED NOT NULL`, `granted_at DATETIME(6) NOT NULL`, `expires_at DATETIME(6) NOT NULL`, `heartbeat_at DATETIME(6) NOT NULL`, **`fence CHAR(32) NOT NULL`** | `PRIMARY KEY (id)`, `CHECK (id = 1)`; the hazard-S fence (A7): **every write rewrites `fence`** with a fresh random value and predicates on the value it read — the one cell all lease writers collide on; renewals through the ephemeral commit form | + +`updated_at` is protocol-irrelevant bookkeeping. Bead `type_url` and Link +`source_path`/`target_*` are immutable after insert. + +**The witness file: `.beads/graph-authority.local.json`.** +`{installation_key, scope_url, authority_id, epoch, ledger_seq, +ledger_hash, state_version, state_commit, unverified, granted_at, +pending?}`. Written only by the manager (B3). What each operation does to +it: `git clone` / `dolt clone` — absent; pull — untouched; `bd backup +restore` / `DOLT_BACKUP` restore to an **older** state — present, and the +ledger head it names is no longer in the store → `ErrStateRewound` (a +restore to the matching head is not a rewind; `bd backup restore`'s +`MarkUnverified` is the belt for that case and is tested separately); directory copy to another path +— installation key mismatch → `ErrNotAuthority`; a copy to the same path on +another machine — a different installation id → `ErrNotAuthority`; a +**whole-installation copy** (id and path both preserved) — the A5 +residual, undetectable without an arbiter. + +**Cross-repo coupling (bts).** `DoltTeamServer` workspaces refuse to open +when `current < latest` with **no `BD_IGNORE_SCHEMA_SKEW` hatch** — a +**numeric-version** comparison only. The coupling is a cross-repository +**release-parity gate**: bts must ship byte-identical copies of the six +main-series files and the ignored-series twin (the +`schema_migrations.content_hash` values `migration_content_hashes.go` +reads are what a bts-side parity test compares). The migration PR is +sequenced with bts; the remote-migrate gate (#4259) forces +migrate-vs-adopt on every remote-backed workspace at upgrade. + +**P1 must ship what P0 settled (recorded 2026-09-07).** `source_path` is +nullable with the `CHECK` that at least one endpoint is `in` (the symmetric +columns above); the ledger counter's exhaustion rule; the descriptor canonical +form and UTF-8 rule stated under "JSON is bytes"; `migrationSQLTouchesTable` +learns `CREATE TRIGGER … ON
` and `DROP TRIGGER [IF EXISTS] ` +separately (a DROP names no table; metadata lookup); the Dolt lane runs the +ruling-13 spikes (they gate on `testutil.RequireDoltBinary` alone). The +installer's `Max` law covers the wildcard declaration (bdp#1, 2026-09-08): +an owning declaration — explicit or `"*"` — without `max` is refused; the +wildcard's `max` bounds the Bead's **whole owned set** — every owned Link +across every owned type, explicit entries included — and an explicit entry's +`max` MUST NOT exceed the wildcard's (refused at descriptor validation); +ruled OW1 = A on 2026-09-08, the literal reading (P0's narrower first reading +is being flipped). The P1 batched owned-Links read for a wildcard owner +selects all owned Links grouped by type under `LIMIT wildcard.max + 1`, +inside the ≤ 7-statement budget row; that single statement covers only the +whole-set bound, so an explicit group over its own `max` is caught after +grouping in the body or refused at acceptance — `graphops.CheckBeadRecord` +enforces both bounds at acceptance (P0 commit ec692e146). + +### B5. Decorators, censuses, and every embedding surface + +- `internal/storage/hook_beadgraph_*.go` (six files): declared, recurse + **unwrapped**; `storage.RoleFiresHooks` is a type switch over hook + wrappers, so an unwrapped role needs no entry; a test asserts each graph + role answers `false`. Added to `role_accessor_decorator_test.go`'s table. +- `internal/telemetry/beadgraph_*.go`: every method spanned; the + **telemetry census** gains the classification. +- **Three censuses**, each must learn `graphops`: the storage reflection + census, the telemetry census, and the conformance package's + **source-parsed** `facadePackages` map (`role_coverage_scan_test.go`) — + without the third, `TestRoleFacadeCensusAgreesWithReflection` + (`role_coverage_gate_test.go`) fails. +- `internal/storage/uow/notifying.go` (explicit accessors, parity test); + `internal/httpapi/claim.go`'s `timedProvider` (which builds roles over the wrapper today and gains a `beadsDir` getter); + `cmd/bd/serve.go`'s `serveRoleSource` and its stubs; + every surface that embeds the store or a provider, enumerated by + `grep -l 'func (.*) Memories()'` at implementation. Because a required + method is promoted silently through every interface-embedding wrapper, + the censuses are what catch an undeclared one; the compiler catches direct + implementers — `internal/jira/tracker_test.go`'s `configStore` is one (a + flat implementer, not an embedder) and fails to compile until it gains the + stubs. + +### B6. `backend/` public surface and depguard + +- **No aliases** (amendment A4): `graphops` is public and imported + directly, like `issueops`. `TestPublicSurfaceComplete` stays green + *because* no `internal/` type is reachable from the new accessors — a + test asserts that. +- `backend/backend.go`'s doc-comment sketch of a minimal external backend + gains the six accessors as `ErrUnsupported` stubs (option A; there is no + example package under `backend/` — the stub contract is + `conformance.RunUnsupportedContract`). The **CHANGELOG entry** follows the + joint `ReadyClaimer`/`BatchCloser` entry's wording ("must add both methods + to compile"). +- `.golangci.yml` gains a **new, stricter** rule (cmd/bd imports the + `issueops` tx-body package directly today, so this is not the existing + convention): `internal/storage/graphops` is importable only by + `internal/storage/{dolt,embeddeddolt,domain/db,uow,graphcap}` and its own + tests. A + mutation test **deletes the deny entry and asserts that a fixture + violating it then passes lint** — which proves the entry is what fails + the violation. + +### B7. Conformance + +- Families: `beadgraph_reader_contract.go`, `beadgraph_types_contract.go` + (reader + installer), `beadgraph_identity_contract.go` (reader, + bootstrapper, admin), each citing the leaf doc by line. +- `RoleContractBundle` gains six factory fields **and** their rows in + `role_bundle_cases.go`; `BeadGraphFixture` carries the seed hook, a + `Witness` hook (a temp workspace directory and installation id standing + in for `.beads/` and the user config dir), and a `Remote` hook (a temp + Dolt remote for hazard-R cases *[deferred under A9]*). +- Wirings on all three legs (under A9 as amended by A10 the embedded leg wires the full + read contract for the solo topology and the refusal contract for client hosts); the leg registry + (`internal/storage/contract_leg_registry_test.go`) and + `TestEveryLegWiresEveryRoleContract` see them; both coverage gates apply. +- Non-capable stores answer `*storage.ErrUnsupported{Op: ""}` — the six strings pinned — proven per accessor. +- Cases the councils asked for by name: a clone produced by push/pull + refuses; a **`DOLT_BACKUP` restore of an authority** refuses + (`ErrStateRewound`); a **copied witness** in another directory refuses; + an **expired claim held by another holder** cannot mutate and is not taken over by expiry alone; an expired claim naming this workspace self-regrants; a **stale fence value** cannot mutate; a protected read on an expired, un-regranted lease refuses; + a **lease takeover between a mutation's SELECT and its commit** refuses + **even when the takeover rewrites disjoint columns** (the fence cell); + two allocators with **byte-identical event payloads** conflict on the + counter's nonce; + two clones minting before either pulls (hazard R: the second push is a + race and is undone); concurrent mint on one database (one wins); a + promotion race (one CAS wins; the loser's push races, is undone by soft + reset + checkout, unrelated dirty tables untouched); a **graph delta + under an unchanged `(authority_id, epoch)`** fails closed on a race; + **issue-plane-only divergence** keeps the commit and answers + `ErrSyncRequired`; a **network failure on push** keeps the commit as + unpublished and retries; **undo when HEAD moved** reverts and preserves + later commits; **each transition phase** recovers on the next load + (resume and undo, both outcomes); an `Install` is published on hazard R; + a hazard-R CLI read with a stale observation fetches and fails closed + past the grace; heartbeat detects a changed `(authority_id, epoch)`; + rotation refuses the old URL and updates `config.yaml`; `bd config set + bdp.scope_url` is refused with a witness present, and via + `set-many`/`unset`; `bd --graph-mode link serve`'s staged startup releases the + exclusive gates before serving; a registered backend serves no rows; the + watcher disables rows atomically and joins before shutdown; a heartbeat + does **not** change the graph-state version; case-differing paths + distinct and code-unit ordered; ownedLinks completeness incl. **empty + groups** — empty groups only for explicit declarations, wildcard-owned + groups only when a Link is present, none keyed `"*"` — and the bound under + `LIMIT remaining+1`; keyset continuation + inside one transaction; gone-family incl. `reserved`; a promote in + another process is honored by the next read; descriptor read on a + non-authority clone refuses; `bd init` re-run on any clone succeeds and + installs nothing; `Mint` installs the built-in catalog with `install` + events; ledger snapshot/apply round trip, gap refusal, foreign-lineage + refusal, recovery-predicate regrant, counter set; the installer refuses + an owning declaration without `Max`; statement budgets per method; + `ErrStateChanged` triggers one validation under concurrent reads and the + reads retry once. +- **Ruling 13 rows:** a raw `INSERT`, `UPDATE`, and `DELETE` on each of + the eight replicated tables without the variable is refused (errno + 1644, the table named); the same statement with `@bd_graph_role = 1` + in the session succeeds; a three-way `DOLT_MERGE` and a `DOLT_PULL` + carrying graph rows land without the variable (the validator, not the + trigger, decides them); a mutation followed by a raw statement on the + same one-connection pool is refused (no leak); a body that omits the + variable cannot write; a clone carries the triggers; the validator + refuses a descriptors/allocations/ledger delta unexplained by ledger + events and marks the witness `unverified`. +- **Ruling 14 rows (per route):** an SQL pull whose fetched delta touches + a graph table with foreign provenance or ledger events of a foreign + lineage is refused before merging, naming the table, and HEAD does not + move; the same delta arriving by the CLI-subprocess route lands, and the + next in-role transaction reverts the eight tables to the recorded HEAD + in a new commit with later issue-plane commits preserved; `--strategy + theirs` on a pull with a graph-table conflict leaves the graph table + untouched and the pull failed; a clone without a witness takes the + remote's graph state wholesale; a federation peer pull carries graph + tables unfiltered and is refused on a foreign delta like any pull; the + remote-migrate gate's fast-forward onto a remote that carries graph rows + succeeds and the workspace refuses to mint (A9); a mirror round-trip + produces no graph delta and no refusal; `bd dolt pull` with no graph + delta is byte-identical. +- **Fence census (Part D.7):** a clone that received a foreign `DROP TRIGGER` + through replication is repaired at its next validation, and the census never + changes the graph-state version. +- **Solo topology (A10):** an embedded workspace with no remote and no server + mints, holds a gate-satisfied lease, answers every link-mode read locally, + serves nothing, and becomes a client host when a remote or shared database + appears. +- **Properties are opaque (bdp#1 item 5 as amended, 2026-09-08):** a URI or + pinned reference inside `properties` is data, never an edge; the store + validates nothing inside `properties`, and `graph_links` holds every edge + there is. +- **Rotation is never a remount:** a server started under a base URL that + differs from the persisted Scope URL refuses, and no stored intra-Scope + reference changes when the Scope URL rotates (paths are Scope-relative). +- Differential-gate rows: every legacy verb without `--graph-mode` is + byte-identical, including `bd link`, `bd graph`, `bd graph check`, + `bd restore`, `bd promote`; + `bd init` gate output on a non-capable backend is byte-identical; + `bd serve` without a Scope URL is byte-identical. + +### B8. `httpapi` integration and the pinned wire (amendments A2, A7) + +- **`httpapi.Config.Graph *GraphConfig`** — `{Reader graphops.Reader; Types + graphops.DescriptorReader; ScopeURL string; Fence FenceSource}` on the + store arm; on the provider arm `Reader`/`Types` are nil and the provider's + own accessors answer per request through `timedProvider`. `Fence` carries + the `held → renewing → lost` state machine of A3.6 and its shutdown join. + No admin or installer field (a test asserts it); `checkDatabaseSource`'s + exactly-one-source rule extends to the graph fields. Registered backends + and embedded workspaces never reach `Graph != nil` in v0. +- **`bdpRouteTable`** (`internal/httpapi/bdp_routes.go`) — **P2**: rows in + the same `route` shape, registered by `Server.handler()` **only when + `cfg.Graph != nil`** — `handler()` reads no `Config` today, so this is a + first, and `TestSpecRouteParity`'s `(&Server{}).handler()` keeps excluding + the rows — each wrapped by the same `s.route(rt)`. First rows: discovery, + `types/`, one Bead, one Link; **collection rows wait for the cursor ADR**. + No capability token in v0; a sibling parity test compares `bdpRouteTable` + against the pinned schema's path grammar. +- **Posture parity test:** one refusal matrix drives a legacy row and a BDP + row and asserts identical status and log shape. +- **Handler = serializer**; typed graph errors → BDP Problem records + (`bdp_problem.go`), here and only here. +- **Wire — P0 (vendored 2026-09-07 on the P0 branch):** + `internal/httpapi/bdpwire/schema/bdp-v0.schema.json` is vendored verbatim + with a `PROVENANCE` file (upstream repo, the plan's §0 commit, and per + file the sha256 and git blob sha1) covering the bundle, the + reference-domain and Read fixtures, the Read catalog and matrix, and the + spec's JSON example fences; a test recomputes every digest and fails on + drift. **Generator decision (Part D.3):** hand-written DTOs held to the + bundle by parity, round-trip, and matrix tests — the recorded fallback; + both generator routes were run on the pinned bundle and rejected + (`oapi-codegen` cannot consume the bundle by external `$ref` and + `openapi.v0.yaml` is frozen; `go-jsonschema` collapses the reference sum, + the consts, and nullable `next` to `interface{}`), see + `internal/httpapi/bdpwire/GENERATOR.md`. There is no `make bdp-gen`; + `bdp-check` is the package's tests, which already run inside + `make api-check`'s `go test ./internal/httpapi/...` step, so + `scripts/ci/pr-policy.sh` gains no target. Decoding posture (council 11 fold): + `bdpwire.Unmarshal`/`Decode` read member by member — exact case-sensitive + names, required ⇔ no `omitempty` (welded to the bundle by the parity test), + null refused except a collection's nullable `next`, each member held to its + JSON type, integers decoded exactly from any RFC 8259 spelling within the + documented Go `int` (64-bit) range; `ReadDiscovery.Validate()` enforces the + two consts. + +## Part C — What does not change + +`storage.Storage`'s existing 28 accessors and every `issueops` role; the +journal's frozen vocabulary; `openapi.v0.yaml` and `TestSpecRouteParity`; +`bd serve` on a workspace with **no** `bdp.scope_url` (byte-identical) and +on any workspace that does not hold the authority (legacy surface up, rows +absent); every legacy CLI verb (differential gate rows); JSONL export +shapes; `metadata.json`'s schema; `bd init` gate output on non-capable +backends; a registered backend's serving behavior (rows absent). + +## Part C2 — What changes that an earlier draft claimed did not + +- **Merge, pull, and sync.** Every `DOLT_PULL`/`DOLT_MERGE` route (the + `versioncontrolops` exports — seven in `mergesettle.go`, plus + `fastforward.go` and `automerge.go`; `doltCLIPull`, `Pull`, `PullRemote`, + `pullTransport`/`pullWithAutoResolve` in `internal/storage/dolt/store.go`; + the UOW leg's `doltVersionControlSQLRepository`; embedded federation sync; + the remote-migrate gate's fast-forward `DOLT_MERGE`) can change graph + state outside the roles — the ruling-13 triggers are silent on merge and + pull (probed) — so, under ruling 14, every SQL pull route **fetches, + inspects the eight tables against the tracking ref, and refuses a + foreign or unexplained delta before merging** (`DOLT_PULL` commits a + clean merge immediately and `ROLLBACK` does not undo it — probed — so + inspection is the only pre-merge refusal point); routes that cannot + inspect first fall to the **state-change validator** (B3), which reverts + the eight tables to the recorded HEAD in a new commit or marks the + witness `unverified`; no graph-table conflict is auto-resolved and + `--strategy` never touches one; a workspace without a witness takes the + remote's graph state wholesale. The replication/merge ADR + (`engdocs/BDP_GRAPH_REPLICATION_ADR.md`) writes the mechanism under that + charter before the migrations land. +- **Federation.** Graph tables ride filtered pushes **unfiltered, by + decision, in v0**; the lease table never replicates. +- **`bd sql`, raw SQL, and force-push.** Out of contract for graph tables + (ruling 13): raw DML on the eight replicated tables is refused by the + row-level fence unless the session set `@bd_graph_role`; force-push and + merges are the validator's and ruling 14's. `bd sql` itself is unchanged — + no flag; a legacy statement never names a graph table. +- **`bd dolt pull`, `bd federation sync`, `bd vc merge`, `bd conflicts + resolve`** gain the fetch-inspect step (one `DOLT_FETCH`, eight `dolt_diff` + reads against the tracking ref) before merging and the graph-table + exclusion for `--strategy` (ruling 14); gate output is byte-identical + unless a graph delta is refused. +- **`bd backup restore`** calls `Admin.MarkUnverified` after + `RestoreDatabase`, before its commit (no-op without a witness). +- **Root store policy** gains `commandPolicy` (Part A), and + `commandNeedsExclusiveGate` in `cmd/bd/workspace_gate.go` — today true only + for `backup restore` — learns `bd --graph-mode link types install`, `restore`, and + `ledger apply`. +- **`bd init`** gains the three `.beads/.gitignore` entries and installs no + descriptors (the catalog moves to `Mint`). +- **`bd config set`/`set-many`/`unset`** refuse `bdp.scope_url` once a + witness is held. +- **The UOW leg** gains `RunTxScopedResult` and `PublishGraphMutation`; the + version-control repository gains `MergeBase`, `ResetSoft`, + `CheckoutTables`, `Revert`, `HashOfTables`. +- **The doctor** gains an error-class finding for a tracked witness; the + `domain/fs` `WriteBeadsGitignore` writer shares the template and gains the + entries too (hygiene check D already warns and skips without a base ref — + no change there). + +## Part D — Open implementation questions (not rulings) + +1. Proposed numbers (`MaxExpandedRows`, `MaxCatalog`, page bounds, value + limit, lease TTL, heartbeat, grace) fixed at P1 with rationale. +2. Whether the P1 fixture writer becomes the internal half of `Writer`. +3. Generator choice for `bdpwire` — recorded at P0 (2026-09-07): hand-written + DTOs held to the vendored bundle by tests (B8; `GENERATOR.md`). +4. Whether `bd --graph-mode link serve` remains after W2 (default: yes). +5. Whether hazard-R publication should use an isolated branch instead of + soft-reset/checkout/revert. The constraint that decides it survives A9: + the ephemeral lease table lives in the default branch's working set and + branch-qualified sessions do not see it, so every fenced transaction runs + on the default branch. +6. The adoption verb for the later of two mints under one URL (ruling 14, + law 3) — name and shape fixed in the replication/merge ADR. +7. **Ruled 2026-09-08 (A):** the state-change validator and ruling 14's + fetch-inspect set carry a fence census over `dolt_schemas` (three triggers + per replicated table; repaired with the migration's idempotent pair; never + part of the graph-state version). + +## Part E — Ruled amendments (A1–A9 and 13–14: 2026-09-07; A10: 2026-09-08) + +Ruled: A1 store-owned witness asserted in every transaction is the v0 lease +(ruling 9); A2 BDP rows inside `httpapi`, `bd --graph-mode link serve` the +only minting path among serving commands (A10 separately permits local solo +minting), `bd serve` never refusing on account of the graph, +intra-Scope references Scope-relative and a new base URL a rotation +(rulings 7b/12); A3 the `--graph-mode link|dependency` root flag with a +mode-and-path-keyed policy; A4 public `graphops`, `BeadGraph*` accessors, no +`backend/` aliases; A5 installation-keyed witness with multi-phase +transitions, hash-chained ledger, ledger lane restoring anti-reuse history, +provider `LedgerDurability`; A6 tracked `bdp.scope_url`, per-workspace keys in +`config.local.yaml`, tokens from files only; A7's shared-database half (the +fence cell); A9 v0 authority requires a shared database outside A10's +embedded solo exception; the remote half of A7 is deferred to the write-profile +ADR; A8 option A — constraint #1 scoped to +behavior, out-of-tree implementers take the declared source break with six +stubs and a CHANGELOG call-out. Ruling 13 (out-of-role DML, "A+B"): out of +contract, the state-change validator with ledger accounting, and +session-gated triggers on the eight replicated tables (B3, B4, B7, C2). +Ruling 14 (replication/merge ADR, option B): the gate plus the four-law +charter — fetch-inspect-merge on the SQL pull routes, validator revert +elsewhere, no auto-resolve or `--strategy` on graph tables, foreign deltas +refused whole, clones take remote state wholesale (B3, B7, C2). +A10 (solo topology, B), Part D.7 (fence census, A), the +`authority_epoch` spelling, and the properties-are-opaque amendment (bdp#1 +item 5) ruled 2026-09-08. **These rulings are settled.** Full A10 text is in +architecture §2b; current BDP #19/#20, History #30 and Jim dependencies are in the plan +§0a refresh of 2026-09-12. Local solo verbs do not authorize embedded HTTP +serving. diff --git a/engdocs/DOC_INVENTORY.md b/engdocs/DOC_INVENTORY.md index 76d821f3e..a92b667db 100644 --- a/engdocs/DOC_INVENTORY.md +++ b/engdocs/DOC_INVENTORY.md @@ -1,5 +1,6 @@ # Documentation Disposition Inventory +Graph-plane design records added: 2026-09-10. Reviewed: 2026-07-07 (paths updated 2026-07-10 for the Mintlify port: user docs now live in the docs/ site tree; this ledger and other internal docs live in engdocs/) CI cleanup entry added: 2026-05-28 @@ -57,6 +58,9 @@ Follow-up automation should replace marker-only checks with generated or | `ANTIVIRUS.md` | Keep | User-facing operational note; review vendor/version claims when touched. | | `ARCHITECTURE.md` | Keep | Primary architecture overview; evidence is current package layout and Dolt-only storage path. | | `ATTRIBUTION.md` | Keep | Attribution record for removed merge engine. | +| `BDP_BEAD_GRAPH_PLAN.md` | Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. | +| `BDP_GRAPH_ARCHITECTURE.md` | Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. | +| `BDP_GRAPH_CLI_AND_STORAGE_SPEC.md` | Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. | | `CLAUDE_INTEGRATION.md` | Keep | Design/user guide for Claude setup; paired with `SETUP.md`. | | `CLAUDE.md` | Revise | Kept as architecture orientation only; command/workflow duplication was reduced in favour of root `AGENTS.md` and `AGENT_INSTRUCTIONS.md`. | | `CLI_REFERENCE.md` | Keep/generated | Generated command reference from live help output. |