* BDP bead-graph plan: seven-round converged design (v7, SOUND)
The plan for implementing BDP natively in this repo, driven through seven
adversarial review rounds at max effort. Headlines:
- Pinned to BDP aee075f5 (the owned-Links rulings); spec-first enforced.
- v0 Scope serves NATIVE beads/links only. The Issue/Dependency projection
was withdrawn on proven counterexamples (rounds 3-5): no read-side
mechanism can satisfy BDP's revision and identity laws over a store
permitting timestamp ties, stale imports, arbitrary SQL, and identity
resurrection. The counterexample record and §2b conflict inventory are
preserved as the C-lane requirements list.
- §2b: fifteen-row inventory of where BDP and the current stack disagree.
- C lane sketched: funnel (C1 compat-shim-over-graph-storage → C3 cutover)
vs observe (C2 storage-level trigger feed), all claims as verification
tasks.
- Native design: graph model + graphops trait, GraphReadSource resolution
honoring the tree's decorator/telemetry discipline, persisted Type
Descriptor store with installation lifecycle, allocation/tombstone
ledger, replication participation matrix, provable P-1..P3 exits.
- Twelve P-1 decisions enumerated for operator ruling.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan: the storage interfaces, concretely (operator request)
Member-by-member attachment: Storage unchanged (GraphCapable as separate
optional interface on DoltStore); no decorator forwarding (targeted-peel
resolution, telemetry re-wrapped); the snapshot lease as the one new
storage primitive (request-scoped transaction lifetime vs per-call
withReadTx, pool/timeout design named); normal migration series; serve
role-source entry with non-capable fallback; backend/ additive+gated;
issueops/journal/sync untouched.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan: storage-interfaces round-8 fixes
UOW lease cannot ride RunTxRead (it closes its unit of work on return) —
OpenSnapshot owns a direct NewUOW, Close rolls back; telemetry wrapper
does not promote inner methods — resolver inspects through it and
explicitly re-wraps; capability contract closed (graphops.Store = read
surface for v0, ErrGraphUnsupported vs operational failure, in-tree-only
exposure); bd serve gets an optional graph field + conditional route
seam, not a mandatory role-table entry, with absent/broken/uninitialized
kept distinct; ScopeResolver named the one snapshot owner with detached
bounded close (cancelled-context rollback burns the connection);
conformance description corrected (RunUnsupportedContract proves
refusals; GraphCapable becomes a completeness-guard root if opened).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan v8: round-9 reconciliation
Resolver signatures unified on the error contract everywhere;
graphops.Store defined (v0 alias of GraphReadSource, package ownership
stated, UOW-to-Scope adaptation named); decision 12 kept open with the
uninitialized state explicitly represented under either branch; serve
assembly names both source-appropriate resolvers; header reflects the
nine-round record.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan v8: round-10 reconciliation — resolver pair named everywhere; package ownership cycle-free
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan v8: resolvers to neutral graphsource package — the actual cycle-free layout
uow already imports storage, so the provider-arm resolver cannot live in
package storage. Both resolvers move to internal/storage/graphsource, a
separate assembly package importing storage+uow+graphops, consumed only
by composition roots; GraphCapable stays in storage (leafward import of
graphops). Signatures fully qualified.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan v8: align the remaining resolver sketch (package clause + qualified types)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan v9: ruling tranche 1 — terminology, charter, withdrawal, S1, Scope URL, authority model
- Terminology block: 'graph beads / graph links / the graph store' replace
'native' (which reads as the existing implementation inside this repo);
'the bead graph' names ruling 1's union concept. Swept throughout.
- Ruling 1 (charter): core; amendment follows working bits; scope = the
bead graph expands to non-work-tracking information (wisps the example).
- Ruling 5: projection withdrawal ratified (wisps included).
- Ruling 2: substrate S1.
- Ruling 7a: Scope URL mirrors BDP's pinned startup contract.
- Ruling 9 (corrected model): the authority is the graph store as reached
through the NORMALIZED STORAGE ABSTRACTION, whichever provider realizes
it — not bd serve, not Dolt. Marker, serialized history, non-authority
refusal, and the snapshot lease are contract obligations proven by the
graph conformance suite; CLI verbs and the BDP handler are both clients.
Consequence: the graph capability is part of the PUBLIC backend/
contract from P1 (flips the in-tree-only hedge); §4 reframed with Dolt
as reference realization.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan v10: ruling tranche 2 — restore, lifecycle commands, ledger, journal, wisps, listener
All twelve P-1 decisions are now ruled (one spelling open):
- 11 restore vs identity: layered — restorable append-only ledger with
provider-declared survival; Scope-URL + epoch rotation when preservation
cannot be guaranteed (spec: identity-losing restore = different Scope).
- 12 (replaces empty-at-birth): store/Scope/client — bd init initializes
the graph store against the interfaces; bd serve mints the Scope on
first serve under a configured URL and serves it honestly empty; a
client-wiring command (spelling TBD) makes the CLI a BDP client of a
designated server. New §4 'Lifecycle commands'.
- 3 ledger: append-only allocation record; ID test is a keyed O(1)/O(log n)
lookup as a contract obligation.
- 8 journal/changefeed, 6 wisps (C-lane visibility), 7b listener (same
middleware path; v0 view = whole Scope per bearer token): ratified.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan v11: close P-1 — client wiring is a bd init target that reroutes above the storage abstraction
bd init --bdp-server <url> joins --server/--shared-server/--proxied-server/
--team-server/--backend as an init target; unlike those (which select the
provider/topology BELOW the normalized storage interfaces) it reroutes
ABOVE them, at the CLI: graph verbs become a BDP client of the designated
server. Config bdp.client store|server (explicit mode) + bdp.server;
env/credentials/precedence mirror dolt.mode. All twelve P-1 decisions
are now ruled.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Plan v12: bd bdp-serve as the isolated bootstrap path; related workstreams (W-arch, W1, W2, W3)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* W-arch: graph architecture/design + detailed CLI and storage-interface spec
Two companion writeups to the plan (operator request):
- BDP_GRAPH_ARCHITECTURE.md: the shape — packages, imports, roles, a read
end to end, where each ruling lands — and three corrections to the
plan's §4 after reading the tree's role machinery: accessors on
storage.Storage (house rule; promoted through decorators by interface
embedding; breaking-change-with-changelog as Memories() was) replace
GraphCapable + the graphsource resolver; one-role-call-one-transaction
replaces the snapshot lease for P1 (cross-request continuation stays
P2's ADR); accessors carry the layers, so no peel-and-rewrap policy.
- BDP_GRAPH_CLI_AND_STORAGE_SPEC.md: the diff — bd init graph bootstrap,
bd init --bdp-server (config/metadata/env/precedence), bd bdp-serve
flags and behavior, bd graph restore/promote, reserved verbs and the
three-route accessor fork; Storage accessors, the graphops public leaf,
bodies per leg, migrations, decorators, backend/ aliases, conformance
contracts and gates, bdpapi + DTO generation; what does not change; open
implementation questions.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* W-arch v2: answer the three-reviewer council; six ruling amendments proposed (pending)
Architecture v2: mechanism corrections separated from ruling amendments;
six roles (Reader, DescriptorReader, TypeInstaller, IdentityReader,
ScopeBootstrapper, AuthorityRotator); DBTX-shaped shared bodies so the UOW
leg (bd serve's primary path) shares one body; replicated Scope row +
clone-local dolt-ignored authority half asserted inside every read
transaction; BDP rows mounted inside internal/httpapi behind route();
bd bdp serve as a thin strict command; bd bdp namespace; laws in graphops;
no backend/ aliases.
CLI/storage spec v2: config.yaml single source for bdp.*; BEADS_BDP_TOKEN_FILE
(no env token); credentials keyed by origin+scope path; identity state table;
promote CAS + fencing by expectation; bd bdp restore branching on
LedgerDurability; ledger export/import lane; full DDL with utf8mb4_bin
collation, Scope-relative paths, LONGBLOB canonical JSON; three censuses and
every embedding surface; conformance cases the council named; bts migration
coupling; Part C2 (merge funnel, federation, bd sql) replaces v1's
'does not change' claims.
Plan v13: superseded-mechanism banner on §4, amended lifecycle spellings,
and a PENDING 'Amendments proposed by W-arch v2' block under §9 (A1–A6 plus
the DML enforcement boundary and the replication/merge ADR).
* W-arch v3: answer council round 2; plan v14 reopens P-1 for amendments A1-A8
Round 2 (Gemini/Codex/Claude on v2) disproved v2's A5 premise with a live
Dolt probe: DOLT_BACKUP restore carries the working set, so a dolt-ignored
authority table survives restore. v3: the clone-local authority half is a
gitignored .beads/graph-authority.local.json carrying a ledger high-water
mark, asserted in every transaction (clone/pull arrive without it; a
restore keeps it but rewinds the ledger -> ErrStateRewound). Append-only
graph_ledger_events with one global sequence; graph_allocations derived;
bd bdp ledger snapshot|apply continuity lane. A7: promotion fenced at the
remote (CAS + push, non-fast-forward fails) with bdp.authority_heartbeat.
A8: constraint #1 scoped to behavior; out-of-tree backends stub six
accessors. Also: BeadGraph* accessor names (GraphCounter clash); Admin
role; OwnedLinks grouped by Type URL (the pinned schema's shape); opaque
Cursor from P1; expectation on descriptor reads/installs; bd bdp serve
inherits errServeReadonly; CommandPath-keyed root policy; --dev-local-test
removed; BDP_SCOPE_URL honored via BindEnv; no token key in config;
bd backup restore marks unverified; merge entry-point inventory corrected;
bts coupling stated as a release-parity gate; provenance columns; LIMIT
bound+1; statement counts pinned; wire artifact in future tense.
Plan v14: status reopens P-1; section 9 block A1-A8 + two decisions;
section 7 superseded-names note; section 8 W-arch bullet.
* W-arch v4: answer council round 3 — store-owned witness, per-topology fencing, hash-chained ledger; plan v15
Round 3 converged on the authority mechanism. v4: the authority witness is
STORE-OWNED (the accessor loads it from .beads/graph-authority.local.json
under an advisory lock; no request type carries authority fields — a
caller-supplied expectation was forgeable from replicated rows); the file is
bound to a workspace key (hostname + real path, not the shared project id),
written under an exclusive lock with monotone read-modify-write and
directory fsync, and only once .beads/.gitignore carries the entry (all
three doctor lists). The ledger is hash-chained (prev_hash/hash) with
mint/install/promote/rotate/allocate/tombstone/refuse_url events; the
witness records the head {seq, hash} so a restore or a different history is
refused by exact-prefix identity. A7 fencing per topology: shared SQL server
-> dolt-ignored graph_authority_lease (the leases/bd-lrgn1 precedent,
ephemeral heartbeats); remote-backed embedded -> Mint/Promote are fetch ->
compare -> CAS -> DOLT_COMMIT -> push with non-fast-forward reset, heartbeat
compares (authority_id, epoch) and fails closed after a grace, P3 writes
push-on-commit; no remote -> CAS alone. A8 presented as two options, not
pre-empted. A6: bdp.scope_url in tracked config.yaml; bdp.client/server/
insecure_http in untracked config.local.yaml via bd bdp client (config.yaml
is git-tracked by default). bd serve never refuses on account of the graph
(legacy up, rows absent on non-authority clones); bd init bootstraps only on
an unminted store or the authority workspace and is silent otherwise;
CommandPath-keyed policy authoritative at every leaf-name call site (list
may coincide); five statements per read with LIMIT remaining+1; validator
singleflight; tree corrections (14 files, ReadyClaimer CHANGELOG precedent,
-0.0 attribution, facade census file, provider-arm assembly).
Plan v15: operative lifecycle items 2-3 rewritten as amended (pending),
backup/restore matrix row, W2 bullet, section 9 block refreshed to v4.
* W-arch v5: answer council round 4 — fences by hazard on the serving leg, sequence counter, two-phase transitions; plan v16
Round 4 (Gemini/Codex/Claude on v4) converged on the authority mechanism.
v5 on the tree's precedents: a single-row graph_ledger_seq counter (the
journal's bd_events_seq shape; Dolt's FOR UPDATE is a no-op); fences
composed by hazard rather than storage mode — a shared database gets the
dolt-ignored lease that every mutation must UPDATE with one affected row
(a takeover is a serialization loser), a configured remote gets DOLT_FETCH
-> ancestor check (DOLT_MERGE_BASE) -> scoped commit (DOLT_ADD graph tables,
never -Am) -> DOLT_PUSH with a typed non-fast-forward classifier and reset
to the recorded pre-op HEAD; both when both; embedded no-remote not
promotable in place. Every serving workspace is a SQL-server workspace, so
the serving leg is the UOW provider and the fences live there (doltSQLProvider
gains beadsDir). Only bd bdp serve mints (tracked Scope URL); bd serve
converts every graph failure into rows-absent + notice. No ledger event
before mint: the built-in catalog is installed inside the Mint transaction;
bd init installs nothing. Two-phase transitions (pending record, recovery on
load) for mint/promote/rotate/ledger-apply; LedgerApply and restore carry
their own recovery predicate. Installation key (per-installation id under
the user config dir + canonical path) replaces the hostname. Graph-state
version = per-table DOLT_HASHOF_TABLE hashes (DOLT_HASHOF_DB moves on every
heartbeat); ErrStateChanged returned without validating in the held tx,
validated under singleflight by the accessor. config.local.yaml/witness/lock
in all three doctor lists; bd config set bdp.scope_url refused once minted;
BDP_SCOPE_URL read first. Lease table via doltIgnorePatterns + main-series
+ ignored-series (0055/ignored 0012 shape). update event kind; provenance on
allocations; per-method statement budgets; tree corrections from round 4.
Plan v16: witness wording in the section 4 banner, config split in the
lifecycle banner, mint trigger in lifecycle item 2, ruling 11 spelling,
section 9 block refreshed to v5.
* W-arch v6: answer council round 5 (Codex, Gemini); propose A9 simplification; plan v17
Lease predicate now carries the holder installation key, a per-process
nonce, the epoch, and an unexpired expires_at by database time; an expired
claim is never renewed. Every replicated graph mutation (mint, promote,
rotate, install, ledger apply, seeds, P3 writes) runs through one provider
primitive on hazard R: fetch -> ancestor check -> record remote graph roots
-> fenced transaction -> scoped commit (new RunTxScopedResult; the UOW commit
hardcodes -Am today) -> push classified by a typed lift of sync.go's
pushRacePattern; on a race every remote graph root is compared (any graph
delta fails closed; issue-plane-only divergence keeps the commit as
ErrSyncRequired; other failures keep it unpublished). Undo is soft reset +
per-table DOLT_CHECKOUT when HEAD is still the op commit (verified against
Dolt 2.1.8), DOLT_REVERT otherwise — never a hard reset. Transitions are
multi-phase (begun/local_committed/published/config_written) with resume-or-
undo recovery. Installation id created O_EXCL 0600 in the directory
UserConfigYamlPath chooses. v0 serves BDP only from SQL-server workspaces
(registered backends' store arm has no fence; deferred behind a
GraphPublication capability). bd bdp serve mints via a staged startup
(exclusive gates through a temporary source, then shared). config set/
set-many/unset refuse bdp.scope_url once a witness is held (file check);
rotate refused under an overriding BDP_SCOPE_URL. LedgerApply restores
anti-reuse history only (reserved allocations; counter set). Graph-state
version = ordered per-table hashes of the eight replicated tables
(DOLT_HASHOF_TABLE verified to exist); one singleflight coordinator per
provider; descriptor cache keyed by the descriptors table hash. A8's
method-set reasoning corrected (required methods promote through
interface-embedding wrappers; optional interfaces do not). A9 proposed:
v0 authority requires a shared database; hazard R deferred.
Plan v17: A7/A8 refreshed, A9 added, lifecycle item 2 notes registered
backends and the staged mint.
* W-arch v7: fold the Claude reviewer's probe-backed round 5 — fence cell, counter nonce, ledger-head comparisons; plan v18
Probed on Dolt 2.1.8: concurrent transactions merge cell by cell, so a lease
UPDATE fences a takeover only when both rewrite the same cell with different
values, and two 'next = next + 1' increments from the same value both commit
with one increment landing. v7: every lease write (grant, steal, expiry
reclaim, renewal, per-mutation fence) rewrites a random 'fence' cell and
predicates on the value it read; the ledger counter writes a random
allocation nonce ('next' is reserved; column is next_seq); the events PK is
the second guard (it converges on byte-identical rows, which the nonce
prevents). Push-race classification and the heartbeat compare the remote
ledger head via AS OF 'origin/main', never the (authority_id, epoch) tuple
(a VM-image twin shares it). No configured remote => not promotable in
place on every topology (a copied data directory under a second sql-server
is a different, unobservable database). Lease holder is the workspace
(installation key); admin verbs other than restore/ledger apply take the
shared gate and rely on the lease so they run beside a live server; plain
bd serve never runs transition recovery. Installation id: user_config_path.go
resolver, BEADS_INSTALLATION_ID_FILE, per-OS-user and ephemeral-home
residuals. Fresh-remote and ref-spelling rules; timedProvider getter;
domain/fs gitignore writer; check D warns without a base ref.
* W-arch v8: fold council round 6 — self-regrant, A9 arbiter, gate model, undo unstage step, ref spelling; plan v19
Round 6 (Gemini/Codex/Claude on v7): the Claude reviewer's live Dolt 2.1.8
probes CONFIRM the fence cell (1213 on the versioned and ephemeral paths,
read-then-mutate, and disjoint-column takeovers) and the counter nonce
(byte-identical events conflict). v8 closes the residuals: an expired lease
still naming this workspace self-regrants (renewal and mutation extend
expires_at; reads carry no expiry term; promotion only when holder or epoch
differ); the lease row Mint creates is the sole proof of 'minted here' and
in-place Promote requires it (A9's arbiter; clones promote only with
--rotate-url); promote/rotate/install take the shared gate, restore/ledger
apply the exclusive gate, stated identically everywhere; staged bd bdp
serve bypasses the generic pre-run gate and takes exclusive only when there
is no Scope row; transition recovery is by evidence (durable op id in the
ledger event; begun-with-committed-op detected; local-committed on a shared
DB finalizes; remote classified pre-head / contains op / foreign); Advance
is a descendant-aware compare-and-advance; the undo unstages before the
per-table checkout (a bare checkout after a soft reset reverts nothing,
probed) and restores the ignored lease row; push races compare the remote
ledger head (ORDER BY seq DESC LIMIT 1 — MAX(seq),hash errors under
ONLY_FULL_GROUP_BY) AND the graph tables' diff, against the workspace's
witness; the ref is remotes/<remote>/<branch>; the classifier lifts all of
isPushRaceErr; DOLT_HASHOF_TABLE('<name>') x 8 with a stated encoding;
renewal-interval bound on fenced transactions; A9 cut sheet; doctor-list
membership per list; tree corrections (uow_factory forwards beadsDir; no
example backend package; jira stub is a flat implementer; config unset
gains an explicit guard call; config.local.yaml merge wording).
* W-arch v9: fold council round 7 — honest A9 arbiter, read-path expiry, op_id column, phased undo, one staged sequence; plan v20
Round 7 (Gemini, Codex; Claude probes pending): a dolt-ignored lease row is
NOT proof of 'minted here' — DOLT_BACKUP restore and a directory copy carry
the working set, and Dolt's @@server_uuid is per machine (probed: identical
for a same-machine copy). v9: in-place promotion is self-regrant (the lease
names this workspace) or an operator --steal (an assertion of 'same
database', in the class of force-push); a foreign holder's expiry alone never
grants a takeover; promote --rotate-url is the bootstrap that creates the
lease row for clones, copies, and restores; physical database copies are the
stated operator-managed hazard; the lease row is bound to scope_url and
authority_id. Protected reads self-regrant ephemerally first and require an
unexpired lease inside the read; request deadline below the remaining lease
interval. op_id becomes an indexed, hash-covered ledger column; the SQL-free
manager asks an evidence provider; no-remote recovery executes config_intent
before finalizing; undo is phased (undo_started/versioned_undone/
lease_restored), pauses renewal, and restores the lease only on the reset
path and only if it still names this workspace; Advance runs a
provider-supplied prefix/ancestry verifier under the file lock; one
normative staged-startup sequence with an explicit shared release before
exclusive; every fenced transaction carries a deadline below TTL/3 with
jittered, serialized renewal; types install is uniformly exclusive;
hazard-R recovery reuses the delta classifier and the watcher recognizes a
pending local op; A9 topology matrix keeps the default-branch rule;
transaction-bound capabilities (StateVersioner, GraphPublication,
LeaseClaim) move to internal/storage/graphcap. Plan v20 mirrors A1/A7/A9.
* W-arch v9: op_id on the public LedgerEvent sketch
* W-arch v10: fold council round 8 — one lease predicate, read path never writes the lease, A9 propagated, transition lock held; plan v21; held for rulings
Round 8 (Gemini/Codex/Claude on v9): the residuals were text-level. v10:
one lease predicate everywhere (a self-held lease CASes regardless of
expiry; a foreign holder is replaced only by --steal; no row -> --rotate-url;
every 'expired or --steal' and 'lease Mint created here' formulation
removed, including the plan's unexpired-expires_at term); protected reads
SELECT first and require an unexpired lease inside the transaction, never
write it (the serving leg's watcher renews; a near-expiry read fails closed;
a CLI read on its own expired lease regrants once, ephemerally, before a
fresh read tx — probe-backed ordering); BDP rows carry their own per-row
deadline below TTL/3 (the shared route() deadline of 60s exceeds the TTL);
types install exclusive in every section and the TTL/3 deadline scoped to
the shared-gate context; the file lock is held from Begin through
Finalize/Abandon and recovery acquires it first; LedgerApply's crash
evidence is the manifest (imported op_ids are never rewritten); recovery
keyed on 'hazard R in force' (any remote under A9 takes the local path)
with the delta-classifier precedence incl. issue-plane-only; the undo
restores the lease on either path under the same-holder guard with a fresh
fence (a revert restores the Scope epoch and would orphan the lease —
probed); one staged-startup sequence everywhere; A9 propagated to A5's
bracket, the embedded leg, and 'CLI-only'; concurrent mint under one
tracked URL settled by the ADR (interim: earlier mint wins); ephemeral-home
services pin BEADS_INSTALLATION_ID_FILE; rotate beside a live server exits
3; graphcap references; INDEX (op_id); ledger snapshot shared;
commandNeedsExclusiveGate learns the new verbs; depguard allowlist gains
uow/graphcap; UnstageTables; dolt_log AS OF for the remote pre-head; shared
staging sweep stated; matching-head restore is not a rewind; metadata.
* Materialize rulings A1–A7 and A9 (2026-09-07); re-pin BDP to bdp#18 merge 0b7d86e7; plan v22, W-arch v11
Operator rulings taken one decision at a time on 2026-09-07:
A1 store-asserted witness replaces the snapshot lease (ruling 9); A2 BDP
rows inside httpapi, only the strict serve mints, bd serve never refuses,
intra-Scope references Scope-relative and a new base URL is a rotation
(7b/12); A3 the root flag --graph-mode link|dependency replaces the bd bdp
prefix (the mode names the graph by its edge kind; bd link creates the
selected graph's edge; policy keyed on mode + command path);
link-graph.route replaces bdp.client; A4 public graphops + BeadGraph*
accessors; A5 witness file + hash-chained ledger + ledger lane +
LedgerDurability (retained versions to the History lane); A6 config
placement (tracked scope_url, local per-workspace keys, file tokens); A7
the shared-database fence (fence cell); A9 v0 authority requires a shared
database, remote half of A7 deferred to the write-profile ADR.
Also folded: bdp#18 (attribution, two statuses) merged and re-pinned in §0,
attribution row restored in §2b; sjarmak's accepted inputs (typed incident
index; the two §2 plane statements); migration slots start at 0068 (0067 is
versioned-beads Phase 1) with a CLAIMED.md registration at P0; History's
store_epoch vs the graph authority epoch stated as distinct. A8 and the two
decisions remain pending.
* A2: record the remount-is-rotation statement in the architecture row
* Materialize A8 (option A, 2026-09-07): constraint #1 scoped to behavior; out-of-tree backends take the declared source break; plan v23, W-arch v12
* Materialize ruling 13 (D1, A+B, 2026-09-07): out-of-role DML out of contract; validator with ledger accounting; session-gated triggers on the eight replicated tables; plan v24, W-arch v13
* Materialize ruling 14 (D2, option B, 2026-09-07): replication/merge ADR gates P1 with a four-law charter; P0 open; plan v25, W-arch v14
* Docs: clear four stale proposed/pending markers left after rulings 13–14 (arch §2b heading; plan matrix header, wisps row, §8 W-arch bullet, ruling 11 spelling note)
* Docs: record the P0 results — 40 pinned scenarios, generator decision (Part D.3), verification rows (i)-(iii) answered with their rules; fence census over dolt_schemas queued for ruling (Part D.7)
* Docs (P0 council 2026-09-07): Link endpoints symmetric (external-source Links are in the pinned fixtures), pins variable-width, error home recorded, canonical-form and UTF-8 hashing rules stated
* Docs (P0 council): P0 wire wording, JCS interop caveat, conformsTo sorted in the descriptor canonical form
* Docs: migration slots 0069 and later (0068 claimed by versioned-beads Phase 2 attribution_status; CLAIMED.md row c53ef8810)
* Docs: P0 implementation notes from council 11's fold (Scope-URL law split, WHATWG origin model, symmetric endpoints, ledger bounds, descriptor canonical form, strict wire decoding); P0 exit met
* Docs: name the graph plane's epoch columns authority_epoch at P1 to keep them distinct from the History lane's store_epoch
* Docs: record the bdp#1 rulings of 2026-09-08 — wildcard ownership entry (B2/B4) and complete-or-refuse historical reads (History lane)
* Docs: wildcard ownership as implemented at P0 — reserved-key sum, max reading, present-only groups, pinned-wire tripwire
* Docs: OW1 ruled A — the wildcard max bounds the whole owned set; explicit max never exceeds it
* Docs: bdp#21 admission law in B4 — round-trip rule refuses at admission; ledger framing exempt
* Docs: B4 — CheckBeadRecord enforces both owned-set bounds at acceptance; P1's LIMIT covers the whole-set bound only
* Docs: A10 solo topology (ruled B), Part D.7 fence census (ruled A), authority_epoch confirmed — 2026-09-08
* engdocs: properties are opaque — references inside properties are data, never edges (bdp#1 item 5 as amended, ruled 2026-09-08)
* docs: align graph design with current BDP and versioned beads (#6154)
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box
* docs: wire graph alignment exits and clarify pinned sources (#6154)
Preserve historical P0 results, assign current-wire and serving gates, and clarify selected-profile pins and future storage delta review. Fold adjudicated source and History precision corrections without changing the ruled graph plane or adding runtime claims.
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box
* Align graph architecture with ruled solo topology (#6154)
Carry A10 into the architecture and embedded-leg summaries, reconcile minting and registry references, and record merged Read/RU dependencies alongside the published TX draft and Jim's dated checks. Preserve the formal change-request hold and phase-specific implementation/evidence gates.
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box
* Reconcile solo authority mechanisms and remaining graph review references
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box
* docs: complete A10 solo authority consistency sweep
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box
* docs: close approved graph review follow-up nits
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box
* docs: reconcile graph adoption and remaining phase gates (#6154)
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Donna Box
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
104 KiB
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
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
defines that order; the cohort generator
binds the digest and the evidence gate
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.
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.
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
ownedLinksmember: 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
deletedIdentityschema, carried as the result'sdeletedmember ({ 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-prunedandresource-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. 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 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 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
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
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
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
records dependency changes and final outgoing dependency state. The current
inventory
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
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
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
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 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=versionsenumeration; 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 authorizedlatest-versionmay 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-unrepresentableis 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-unsafeis 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 at1fe8cf32in the dated §0a dependency table; adoption and runtime proof remain separate. Historical resolution never makes an old token a current write guard: the existingexpectedRevisionequality/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:
- 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-lineErrUnsupportedstubs for theBeadGraph*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. - BDP fidelity at the pin, provable by the pinned matrix under its packaged/public-boundary and self-certified/in-process provenance split.
- 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 seegraphopsinterfaces; composites are the only switches.
2. What exists (survey — corrected after adversarial verification)
- Storage contract:
internal/storage/storage.godefinesStorageas 28 role accessors (IssueLifecycle, IssueReader, IssueClaimer, ReadyClaimer, BatchCloser, BatchCreator, DependencyEditor, Commenter, Counter, Memories, …), each returning a role interface. Implementations:*dolt.DoltStoreunder decorator chains (hook_*.go, telemetry) plus a distinct UOW/provider chain. Documented policy: adding a requiredStoragemethod 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
UnwrapStorepeeling 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 serveassembles 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/conformanceexists butRunAllopenly 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; evenOpenForReadOnlyCommandreturns a writable store. - Data model:
Issue(internal/types/types.go:17–190) is very wide (well over 40 exported fields),Metadata json.RawMessageas extension point,RowVersion int64equality-only with documented partial coverage.Dependency: surrogateIDpopulated only by some read paths, endpoints,Type,Metadataas 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
Issuestruct routed to a second table by storage-class flags; detail assembly carriesisWispexplicitly 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:
IssueTypeis an open vocabulary (decision, message, molecule, gate, event, plustypes.custom);issue_type NOT INfilters exist. Non-task semantics on the Issue chassis is proven practice. - Memories:
memoryopsis 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. NoteMemories()remains wired inbd servetoday; retiring it is future work outside this plan. - Charter tension, named honestly:
engdocs/PROJECT_CHARTER.mdframes 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/domainis UOW-specific machinery overtypes.Issueand.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 legacybd remember/bd recall/bd memories/bd forgetsurfaces survive as projections overgraphopsafter 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:
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.
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
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 —
GraphCapableas a separate optional interface, thegraphsourceresolvers, theReadSnapshotlease,backend/aliases, and thebd serveoptional graph field — are replaced by the house idiom inBDP_GRAPH_ARCHITECTURE.md§2a (role accessors onstorage.Storage,DBTX-shaped shared bodies, per-call transactions asserting a store-owned authority witness, BDP rows mounted insidehttpapi). 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:
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):
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):
-
storage.Storagedoes not change. No new required method — the documented breaking-change policy holds. The graph capability is a separate, optional interface: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"(
graphopsownsStore,GraphReadSource,ReadSnapshot, andScope; the UOW adapter satisfies them by constructing aReadSnapshotover the transaction a directNewUOWowns, answeringgraphops.Scopequeries from that one transaction.)*dolt.DoltStoreimplements 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 sentinelErrGraphUnsupported; any other error is an operational failure and must not be collapsed into absence. -
Decorators do not forward it. Forwarding through every wrapper is the failure mode the tree already documents. Instead, resolution does what
bd servealready does — targeted peels, telemetry retained: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.
-
The one genuinely new storage primitive: the snapshot lease. Existing read helpers are per-call —
withReadTxopens and closes a transaction inside each role call, which is exactly why they cannot serve BDP snapshot semantics.GraphReadSourcetherefore exposes: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 packagestorage): it importsstorage,uow, andgraphops, and nothing imports it back except composition roots (bd serve, tests). This is forced, not stylistic:uowalready importsstorage, so placing the provider-arm resolver in packagestorageitself would create astorage → uow → storagecycle.GraphCapablestays instorage(returninggraphops.Store;storage → graphopsis a leafward import); the resolvers qualify every foreign type.A snapshot is request-scoped, and
ScopeResolveris 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 machinerywithReadTxuses, 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). -
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
ExeccreatesBEGIN … ENDtrigger bodies over the tree'smultiStatements=trueDSN). -
bd servegets 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.ErrGraphUnsupportedleaves 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 servemints the Scope on first serve under a configured URL and serves it honestly empty; plainbd servenever 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 (ResolveGraphReadSourcefor the store arm,ResolveGraphReadSourceFromUOWfor the provider arm —serve.goassembles from both). -
backend/(all providers): public from P1, precise about the existing machinery. TodayRunAllnever exercises the optional capability families —RunUnsupportedContractproves 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;GraphCapableis a completeness-guard ROOT andgraphopstypes carry public aliases from P1, because providers other than Dolt are first-class targets (ruling 9), not a later opening. -
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(nowbd --graph-mode link serve) →bd --graph-mode link serve(the strict, minting command over the samehttpapiserver;bd servemounts 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_urllives in trackedconfig.yaml, the per-workspacelink-graph.routeandbdp.serverin untrackedconfig.local.yaml(nothing inmetadata.json). Detail:BDP_GRAPH_CLI_AND_STORAGE_SPEC.mdPart A.
Three commands, three responsibilities — the store, the Scope, and the client:
-
bd initinitializes 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 separatebd graph init. A workspace therefore always has a graph store; it does not yet have a Scope. -
bd --graph-mode link servecreates the BDP Scope on top of the store;bd serveserves an already-minted Scope it holds (as ruled 2026-09-07, A2/A7/A9): on its first serve under a configuredbdp.scope_url(ruling 7a)bd --graph-mode link servemints the Scope row, themintledger 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, withbeads/,links/, andtypes/all present. Because the Scope URL is a tracked project fact, among serving commands, onlybd --graph-mode link servemints: a plainbd serveon an unminted store keeps the legacy surface up with a notice. BDP routes are a conditional second table insideinternal/httpapibehind the same middleware, in v0 served only from SQL-server workspaces — the unit-of-work leg (bd serverefuses 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 servewith 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 serverefuses (exit 2) in those cases. No development-mode URL derivation exists in bd. (W2 decides whetherbd --graph-mode link servesurvives as the alias — default yes; it is the serving minting path.) -
Client wiring —
bd init --bdp-server <url>andbd --graph-mode link client(as ruled 2026-09-07, A6): one morebd inittarget, 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 untrackedconfig.local.yaml; the project fact lives in trackedconfig.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: serverbd init --bdp-server <url>andbd --graph-mode link client server --server <url>writeconfig.local.yaml; genericbd config setrefuses the per-workspace keys with that guidance. Env:BDP_SCOPE_URL(7a) andBD_BDP_SCOPE_URL;BD_BDP_SERVER;link-graph.routeis blocked from env likebackend. The bearer token comes from a file only —BEADS_BDP_TOKEN_FILEor 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.jsoncarries nothing for the graph.clientis 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 —
ScopeResolverwraps 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_atis second-precisionDATETIMEand the tree documents same-second ties, so A→B→A within one second reuses the hash;bd import --allow-staledeliberately restores old rows includingupdated_at;bd sqlpermits 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 convergecreated_atacross 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_typeis 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/issueprojmachinery drops out of v0 scope; the authority seam (ScopeResolver: workspace, view, one ReadSnapshot) andGraphReadSourceremain — 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 sqlDML actually fires them (notingbd sqlis 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 sqlcompat 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(nowbd --graph-mode link serve),bd bead/bd linkverbs): read them throughBDP_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 insidehttpapi; 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,Refsum, 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.mdon 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 onjanet-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 —ResolveGraphReadSourcefor server/embedded Dolt (embedded as storage-contract leg),ResolveGraphReadSourceFromUOWfor 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 underbackend/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 OFidentity 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.jsonand illustrativefixtures/read-update/; #20 haspackages/conformance/catalog/transactional-v1.jsonand illustrativefixtures/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 withDeletedDataand changefeed tombstones (#20 Mutation results); target revision unchanged throughout; both surviving revisions preserved on semantic no-op. Then tombstones, endpoint constraints, replication of writes; only thenbd bead/bd linkverbs. 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.mdandBDP_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 serveintegration (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)
-
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.
-
Substrate — RULED: S1 (graph tables: beads, links, Type Descriptors, allocation/tombstone ledger, authority marker).
-
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.)
-
(Moved to the C lane — cross-realization Links cannot arise in v0; see §5's historical record.)
-
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).
-
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; alocal-testURL 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 insideinternal/httpapibehind the sameroute()wrapper, so bearer-auth and project-identity semantics are preserved by construction; among serving commands, onlybd --graph-mode link servemints, andbd servenever 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. -
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).
-
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 bybd --graph-mode link serveunder 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). -
(Absorbed into decision 5 — the round-5 review closed this fork: withholding is the only conformant option.)
-
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. -
Store, Scope, client — RULED (replaces "empty-at-birth"): three commands, three responsibilities (§4 "Lifecycle commands").
bd initinitializes the graph store with everything else, against the interfaces — no separate graph init.bd --graph-mode link servecreates the Scope on first serve under a configured URL (A2), and serves it honestly empty;bd serveonly 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 isbd init --bdp-server <url>— one morebd inittarget, 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 existingbd servebehavior — routes absent, never a startup failure (A8, ruled 2026-09-07). -
Out-of-role DML enforcement boundary — RULED (2026-09-07): "A+B". Out-of-role DML —
bd sqlin 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 carryBEFORE INSERT/UPDATE/DELETEtriggers, 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 beforeCOMMITorROLLBACK. 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 (inBEGIN … ENDform) 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 throughdolt_schemasby push, clone, and pull; they are silent onDOLT_MERGEandDOLT_PULL; one multi-statementExecof a migration file creates them over the tree's DSN; privileges live in.doltcfg/privileges.dbper 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 oncontext.WithoutCanceland poisons the connection when it cannot be confirmed; (iii) PASS-WITH-RULE — the CLI migration bundle needs aDELIMITERrendition, check D anddoltIgnorePatternsmust learn the lease table, and a dirtydolt_schemasis 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 overdolt_schemas— each of the eight replicated tables must carry its three triggers; a missing one is repaired with the migration's idempotentDROP TRIGGER IF EXISTS+CREATE TRIGGERpair before a delta is judged, and the census never changes the graph-state version. No newbd sqlflag: 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 (abd sqlstatement guard) were the alternatives; C stays a C-lane task, D is redundant under B. -
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/<remote>/<branch>', '<table>')), 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 witnessunverifiedotherwise. (2) No graph-table conflict is ever auto-resolved,--strategy ours|theirsnever 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 everyDOLT_PULL/DOLT_MERGEroute: the SQL pull route (pullWithAutoResolveUnchecked), the CLI-subprocess pull, federation peer pulls on both routes, the UOW leg'sPull,bd vc merge(MergeWithStrategy), the remote-migrate gate's--ff-onlyadopt, andForcePush. Probed on Dolt 2.1.8:DOLT_PULLinside a transaction commits the merge immediately — fast-forward and no-conflict three-way alike — andROLLBACKdoes not undo it (only a conflicted merge stays in the working set, which is what the tree's rollback-on-conflict relies on); afterDOLT_FETCH,dolt_diffagainst the tracking ref enumerates the incoming rows before any merge. Tree facts the ADR inherits:TryAutoResolveMergeConflictsresolves onlymetadata, audit-onlydependencies,issues(field-level three-way),labels,comments, andevents— 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/httpapibehind the same middleware, served from the unit-of-work leg. Onlybd --graph-mode link servemints, through the staged startup; it inherits serve's whole-surface--readonlyrefusal and refuses without a held Scope.bd servemounts 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(defaultdependency;BD_GRAPH_MODE; configgraph-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 linkcreates 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 namedBeadGraph*; nobackend/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 declareLedgerDurability; 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 inownsOutgoing; the graph plane's own history reads, when they come, follow both. -
A6 (§4 lifecycle, 7a env).
bdp.scope_urlis a project fact in trackedconfig.yaml(BDP_SCOPE_URLfirst), refused byconfig setonce a witness is held;link-graph.route,bdp.server, andbdp.insecure_httplive in untrackedconfig.local.yaml, written bybd init --bdp-serverand the link-modeclientverb; tokens from files only; nothing inmetadata.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;promoteandrotaterun beside the server,types install,restore, andledger applytake 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-lineErrUnsupportedstubs, 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 servestill 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_epochat P1).