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. |