* 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>
51 KiB
BDP graph store — architecture and design
Status: Draft v17 (W-arch) — A1–A9 and decisions D1–D2 (plan rulings 13–14) ruled 2026-09-07; A10 ruled 2026-09-08; P0 current-wire completion open — feat/bead-graph
Date: 2026-09-12 (v16: 2026-09-10; v15: 2026-09-09; v14: 2026-09-02)
Companion: BDP_BEAD_GRAPH_PLAN.md (the plan and its rulings, 1–14) and
BDP_GRAPH_CLI_AND_STORAGE_SPEC.md (the detailed CLI and storage-interface
changes). This document is the shape: what the pieces are, where they live,
how a request flows, and where this design corrects the plan after the
tree's own conventions were read closely. Eight three-reviewer councils
(Claude, Codex, Gemini) reviewed v1–v9; §2 records what changed and which
changes amend a ruling rather than a mechanism. Rounds 3–5 converged on one
area — the authority mechanism — and every round since v3 has replaced an
invented primitive with one the tree already has. v6 added the
operator's simplification ruling (A9); v9 states its arbiter honestly:
physical database copies are an operator-managed hazard, not a fenced one.
Revision v15: 2026-09-09 current-source alignment and council corrections; phase/owner gates and pinned-source clarity added, historical rulings preserved. Revision v16: 2026-09-10 formal-review correction carries the already-ruled A10 into §2b and refreshes current dependency status. It does not clear the reviewer/owner merge gate.
Revision v17: 2026-09-12 records the P0 Read adoption and merged BDP Transactional/History dependencies consistently with the owning plan; no new contract pin, migration slot or runtime capability is selected.
Current dependency alignment (2026-09-09, refreshed 2026-09-12)
Plan §0a contains the historical source records and the 2026-09-12 current refresh: BDP #19/#20 and History #30 wire/spec are merged; Jim's Phase 1 is merged and Phase 0/2 remain open. History realization and provider mapping remain separate from the completed upstream normative materialization. The role split remains: graphops is the graph domain, Jim's writer owns Issue history, and BDP wire DTOs own protocol representations. No Issue projection or C-lane substrate change is selected.
The graph authority lease is not TX's receipt execution/creator-attempt fence; the graph anti-reuse ledger is not the projected erasure ledger; an Issue ordinal is neither a graph revision nor a durable History address. P3 must compose its durable admission/effects/outcomes under the upstream profile contract. A future History provider must translate context, numeric values, retained identity and erasure provenance explicitly. These obligations do not add Writer or History methods to the existing P0 interface sketch. The P3 ADR audits storage/interface deltas and their migration, state-version, fence, replication-inspection and census implications under plan §0a. The initial eight-table P1 scope does not prescribe future tables or another accessor widening; any necessary addition honors frozen migrations and A8's source-break policy. P1 need not await the full P3 design.
P0 adopted the Read foundation at 19923f5bb6cc3f4ee4c508e36df3bd4c5c52344b;
plan §0 records its exact pins and dated contract checks, including the narrow
erased-pointer port. The original pin and tests remain historical. Later
wire adoption and applicable successor checks remain explicit gates. Plan §7's owner gates
assign P0 contract/parity work and P2 serving proof, including shared response
negotiation and applicable conditionals. P3 separately records its reviewed
write-profile pin and evidence exit; RU need not await TX-only runtime.
This alignment does not claim that all upstream drafts have
merged or that graph/P0 implements their runtime behavior.
1. The one-paragraph version
The graph store is a new plane beside issues and memories: a public leaf
contract package (graphops) declaring the value types, the laws, and six
role interfaces, reached through role accessors on storage.Storage
(BeadGraph*, to keep clear of the issue-graph GraphCounter()) exactly as
issueops and memoryops are — declared explicitly by every decorator
(promotion is the failure mode the censuses catch), wrapped by telemetry,
recursed unwrapped by the hook layer — with one shared transaction-level
body under internal/storage taking a DBTX-shaped runner so that both
Dolt stores and the unit-of-work leg call the same code, proven by
backend/conformance role contracts wired on all three legs and guarded by
the existing coverage gates. BDP is served by the existing
internal/httpapi server as a conditional second route table behind the
same route() middleware — in v0 only from SQL-server workspaces (the
unit-of-work leg; bd serve refuses embedded Dolt permanently, and a
registered backend's store arm has no fence to offer until it declares
one). bd --graph-mode link serve is the strict command over that server: it mints and
it requires a Scope this workspace holds; bd serve mounts the same rows
when it holds an already-minted Scope and never refuses on account of the
graph. Every operation is one role call, one transaction, asserting a
store-owned authority witness — loaded by the accessor from a
clone-local file bound to this installation, checked against a hash-chained
ledger head and, on the shared-database leg, a lease row the mutation itself
must update. The store refuses a clone without local authority, a restore whose
head is absent from the witness, and a promotion elsewhere; no caller can
supply the witness. Copies carrying coherent local state are an operator-managed
hazard, including a solo store copy; the store cannot infer their provenance.
A shared database is fenced by that
lease. Under A9, a configured remote neither grants nor removes authority;
hazard R's publication mechanism is deferred to the write-profile ADR. A
shared database that minted locally remains authoritative with a remote.
The A10 exception is an embedded workspace with no remote and no server: it has local authority and
local link-mode verbs, but serves no HTTP. Its workspace gate satisfies the
solo lease; appearance of a shared database or remote makes it a client host
under the existing rotation and steal rules. A10 also preserves the replication
case: a solo store later pushed to a remote counts as minted locally and remains
authoritative until a foreign delta appears. The full A10 row governs both cases.
2. Corrections to the plan and ruled amendments (read this first)
Two kinds of change are recorded here and must not be confused. A mechanism correction replaces something the plan's §4 proposed with the house idiom that already solves the problem; the ruling it serves is unchanged. A ruling amendment changes text the operator ratified in §9; the amendments below are recorded outcomes, with their ruling dates. They are no longer proposals; an implementation gate is not a pending ruling.
2a. Mechanism corrections (no ruling changes)
| Plan §4 mechanism | Replaced by | Why |
|---|---|---|
GraphCapable as a separate optional interface, resolved by targeted decorator peels (graphsource package) |
Role accessors on storage.Storage — the house rule — under ruled A8 option A; option B was rejected |
Every accessor lives on Storage (28 today); DoltStorage embeds it; both decorators embed the DoltStorage interface. A method added to Storage is therefore promoted through the embedded interface: every wrapper compiles unchanged — which is exactly why the reflection census in role_accessor_decorator_test.go (and its telemetry twin) exists: wrappers must declare each accessor, and the census catches the ones that silently promote. |
A ResolveGraphReadSource policy that "re-applies telemetry" after peeling |
Nothing — the accessors carry the layers | This is what accessors are for in this tree. |
backend/types.go aliases for every graphops type |
No aliases. graphops is a public root package, like issueops |
The completeness guard demands aliases only for types under internal/. |
internal/graphapi as a separate meaning-function package |
The laws live in graphops |
Import rule and cycle. |
A ReadSnapshot handed from a resolver to a handler; a caller-supplied expectation (v2/v3) |
One role call, one transaction, asserting a store-owned witness (A1) | A witness the caller supplies is forgeable from the replicated rows. |
SELECT … FOR UPDATE on the Scope row to serialize the ledger (v4); a bare next = next + 1 counter (v5–v6) |
A single-row counter whose every allocation writes a fresh random cell (next_seq = next_seq + 1, alloc_nonce = <random>) — the journal's bd_events_seq shape, corrected |
Dolt has no row locks (FOR UPDATE is a parse-only no-op) and merges concurrent transactions cell by cell: two sessions each doing next = next + 1 from the same value both commit and the counter reads one increment (probed on 2.1.8). Only a same-cell-different-value write is a serialization failure (1213) that withRetryTx/RunTxResult replay; the random cell makes every allocation one. The events PK is the second guard, and it too converges silently on byte-identical rows — the nonce makes rows differ. The journal's own prose carries the misconception; its PK plus duplicate-key heal is what actually guards it. next is reserved in Dolt's parser. |
DOLT_RESET --hard to undo a refused publication (v4–v5) |
DOLT_RESET --soft <pre-op commit>, then per graph table DOLT_RESET('<table>') (unstage) and DOLT_CHECKOUT('<table>') when HEAD is still the operation commit; DOLT_REVERT <op commit> when HEAD has moved; the ignored lease restored on either path under the same-holder guard |
A hard reset discards unrelated dirty work on a shared server; a bare checkout after a soft reset restores from the staged root and reverts nothing (probed), the unstage step makes it revert only the graph tables; a revert preserves later commits from other actors. |
2b. Ruling amendments A1–A10 and decisions D1–D2 (ruled 2026-09-07 and 2026-09-08)
| # | Ruling | Earlier drafts said | Ruled outcome (A1–A9: 2026-09-07; A10: 2026-09-08) | Evidence |
|---|---|---|---|---|
| A1 | 9 ("the snapshot lease" in the obligation list) | dropped silently (v1); caller-supplied expectation (v2–v3) | RULED. The per-call transaction is the v0 lease and asserts a store-owned authority witness: the accessor loads the witness from the clone-local file and the body checks it inside the same transaction — Scope row identity, the hash-chained ledger head (exact-prefix identity), the lease row (a protected read SELECTs it inside the read transaction and checks holder, epoch, and expires_at > NOW(6) — a holder/epoch match alone proves only that no takeover was visible in the snapshot, not that the lease is live; reads never write the lease: on the serving leg the watcher renews and a near-expiry read fails closed as lost; a CLI read whose lease names this workspace but has expired regrants once, ephemerally, before opening a fresh read transaction and retries; the read's context deadline is derived from the remaining lease interval and is below it; a mutation UPDATEs it and requires one affected row, with the holder's installation key, epoch, and the fence cell value read in this transaction in the predicate, and sets fence to a fresh random value and expires_at = NOW(6) + ttl — every lease write does, so any two concurrent lease writers are a same-cell-different-value conflict Dolt reports as 1213 (probed on both the versioned and the ephemeral commit paths); the loser is replayed with a fresh random fence and re-evaluates its preconditions: a still-authorized writer then succeeds serially, a superseded or stolen one matches zero rows and refuses. An expired lease that still names this workspace is self-regranted by the same write — promotion is needed only when the holder or the epoch differ), and the graph-state version (the ordered per-table hashes of the eight replicated graph tables). Public request types carry no authority fields. The cursor type is opaque from P1. |
Rounds 1, 3, 4, 5. |
| A2 | 7b + 12 (listener; "bd serve creates the Scope on first serve") |
a sibling server (v1); bd serve mints (v2–v4) |
RULED. BDP rows mount inside internal/httpapi as a conditional second route table behind the same route(). Of the serving commands, only bd --graph-mode link serve mints (A10 separately permits local solo minting), through the one staged startup sequence in the spec's Part A (shared gate → temporary source reads the Scope row → close → release → only when there is no Scope row: exclusive gate → reopen, re-check, mint → close → release → shared gate → serving source → re-evaluate the identity table under it → serve; the tree forbids a shared→exclusive upgrade, and the conformance case asserts the shared gate is released before the exclusive acquisition). bd --graph-mode link serve inherits errServeReadonly and refuses without a held Scope; bd serve converts every graph failure into "rows absent + notice" and is byte-identical without a URL. v0 serves BDP only from SQL-server workspaces (the unit-of-work leg): embedded Dolt never serves, and a registered backend's store arm — which may itself be embedded — has no fence, so its rows are absent in v0; an out-of-tree backend cannot import an internal/ capability, so the seam it would declare is the deferred ADR's to define (a public interface or an in-tree adapter), not graphcap's. Intra-Scope references are stored Scope-relative and rendered against the live Scope row, never as absolute URLs, so a remount rewrites nothing; a server started under a base URL that differs from the persisted Scope URL refuses — serving under a new base is a rotation, never a remount (operator, 2026-09-07). |
Rounds 2–5. |
| A3 | 12 / §4 lifecycle | verbs "reserved now"; then a link mode prefix | RULED. Graph behavior is selected by the root flag --graph-mode link (default dependency; BD_GRAPH_MODE; config graph-mode), never by a verb prefix. The mode names the graph by its edge kind: every verb creates, reads, or serves the selected graph or refuses; bd link creates the selected graph's edge; without the flag every verb is byte-identical to today. The root store policy keys on mode and command path and is authoritative at every leaf-name call site (paired Cobra-walk and source-scan tests). |
bd link, bd graph, bd restore, bd promote exist; a verb prefix named the protocol, not the graph (operator). |
| A4 | §3 layering | values moved silently | RULED. Record it: values, laws, and roles in public graphops; accessors named BeadGraph*. |
Package layout is public API. |
| A5 | 11 (ledger "restorable independently … its own migration") | dolt-ignored table (v2); project-id file (v3); hostname key (v4) | RULED. (i) The clone-local half is .beads/graph-authority.local.json, bound to an installation key: a random id created once, O_EXCL, mode 0600, re-read after creation, directory fsynced, in the user config directory the tree's UserConfigYamlPath resolver already chooses (~/.config/bd, native fallback) — plus the canonical .beads path; never the hostname. Written only by the witness manager under a bounded exclusive lock; transitions are multi-phase (begun → local_committed → published → config_written → finalized, recording a durable operation id — a hash-covered, indexed op_id column on every ledger event, and the commit message — the pre-operation HEAD and ledger head, the operation commit, the expected graph roots, the remote pre-head, the pre-operation lease row, and the config intent), recovered on the next load by evidence, not by phase alone: the ledger is checked for the operation id (a crash between the commit and the phase write leaves begun with the operation committed), then the remote is classified as {still at the pre-head, contains this operation, contains foreign work}, and recovery resumes publication, finalizes, or undoes accordingly; on a shared database with no remote a locally committed transition counts as published, executes any outstanding config_intent, records config_written, and only then finalizes. An undo is itself phased (undo_started → versioned_undone → lease_restored) and resumes from its recorded phase regardless of whether the operation still appears in the ledger; in-process renewal and graph mutation pause for its duration; the lease is restored only on the reset path and only if it still names this workspace. Advance is a descendant-aware compare-and-advance that holds the file lock while a provider-supplied verifier (ledger-prefix and commit-ancestry checks, run in the store) decides: a candidate already contained in the current witness is a successful no-op, newer fields are never replaced by older ones, and a fork is rejected — commits may complete in one order and advance in another; opaque hashes alone cannot decide this, so the manager never tries to. The manager ensures the ignore entries and refuses a git-tracked path; a tracked witness is an error-class doctor finding (sensitiveFileNames). (ii) The ledger is an append-only, hash-chained event table (mint, install, update, promote, rotate, allocate, tombstone, refuse_url) with a single-row counter; the witness records the head {seq, hash}. No event exists before mint. The ledger lane (`bd --graph-mode link ledger snapshot |
apply) restores **anti-reuse history, not graph content**: an applied allocatewhose row is absent becomes areservedallocation (never reusable; reads answer gone), the Scope lineage is replayed, and the counter is set tolast_seq + 1; full recovery is a database restore *plus* the lane. **(iii)** providers declare LedgerDurability; bd --graph-mode link restorerotates unless continuity is shown. **Two epochs, distinct:** History'sstore_epoch` singleton (versioned-beads Phase 1, migration 0067) fences restore and replacement on the issue plane; the graph's authority epoch fences promotion on the graph plane; a restore must be reasoned about for both. Stated residuals: a whole-directory or whole-installation copy carries the witness and is undetectable without an arbiter — so outside A10, an authority-preserving deployment must have one (a shared database under A9). A10 amends that topology restriction: an embedded workspace with no remote and no server has local authority under its workspace gate; the solo/client-host boundary and rotation/steal rules are stated in A10 below. The solo leg is single-copy by operator responsibility; a copied or restored solo store that cannot establish continuity requires a new Scope, rather than a claim that the gate detects a coherent copy. Physical copies remain the stated operator-managed hazard. |
| A6 | §4 lifecycle (metadata.json; BD_BDP_TOKEN; BDP_SCOPE_URL) |
both files; env token | RULED. bdp.scope_url is a project fact in tracked config.yaml (yaml-only; BDP_SCOPE_URL read first, then BD_BDP_SCOPE_URL). A mint with --scope-url writes it as the transition's config_written phase. Once this workspace holds a witness, bd config set/set-many/unset refuse the key (one guard in the shared rejectProtectedConfigKey path; a DB-free file check) — the URL then changes only through bd --graph-mode link promote --rotate-url / bd --graph-mode link restore, which are refused while an overriding BDP_SCOPE_URL is exported. bdp.client, bdp.server, bdp.insecure_http live in config.local.yaml via bd init --bdp-server and bd --graph-mode link client. The three new .beads/ files join the gitignore template, requiredPatterns, and trackedRuntimePatterns; only the witness joins sensitiveFileNames (error class). No env-carried token; no token key in config; bdp.client blocked from env. |
Rounds 2–5. |
| A7 | 9 (promotion "explicit and epoch-rotating") — new | v5 partitioned by hazard but fenced a subset | RULED. Fences compose by hazard; every replicated graph mutation is fenced inside its transaction and, on hazard R, published by one primitive. Hazard S — a shared database (every SQL-server topology): the dolt-ignored graph_authority_lease row (the leases/RunTxEphemeral precedent) with the fence cell predicate in A1 — the holder is the workspace (installation key), so the serving process and the workspace's own CLI verbs share it (promote and rotate take the shared gate and rely on the lease; types install, restore, and ledger apply take the exclusive gate and require the server stopped); renewal is ephemeral, rewrites the fence, and extends expires_at; an expired lease naming this workspace is self-regranted by the next write regardless of expiry; a lease naming another holder is taken only with --steal — its expiry alone never grants a takeover — and the epoch is CASed. A lease row is not proof of "minted here": dolt clone omits the dolt-ignored table, but DOLT_BACKUP restore and a directory copy carry the working set with it, and Dolt's @@server_uuid is per machine (~/.dolt/config_global.json; probed identical for a same-machine copy), so no in-band identity distinguishes a copied database served by a second sql-server. The lease row is therefore bound to scope_url and authority_id, and in-place promotion has exactly two paths: self-regrant when the row names this workspace, and --steal, an operator assertion of "same database" in the class of force-push and bd sql; a foreign holder's expiry alone never grants a takeover. Promote --rotate-url is the bootstrap that creates a new lease row under a new URL (refusing the old one forever) — the path for a clone, a restore that cannot show continuity, and a copy. Residual, stated: a --steal on a copied database creates a second authority; a restored copy is caught first by the witness's ledger head (ErrStateRewound). Throughput model, stated: concurrent graph mutations in one workspace serialize pairwise on the fence cell, and a fenced transaction that spans a renewal loses whenever the renewal commits first, so every fenced transaction that runs beside a possible renewer (the shared-gate context) carries a deadline below a third of the TTL (cancelled and retried past it — the replay budget must allow more than one attempt), in-process renewal is serialized against the process's own mutations with jittered cadence, and types install runs under the exclusive gate, where the sole writer sets expires_at itself and runs unbounded. The file lock is held continuously from Begin through Finalize/Abandon, and recovery acquires it first, so a live transition is never mistaken for crash residue. Hazard R — a configured remote [deferred under A9, ruled: input to the write-profile ADR, not normative for v0]: every replicated graph mutation (Mint, Promote, Rotate, Install, LedgerApply, the P1 seeds, P3 writes) runs through PublishGraphMutation on the provider: DOLT_FETCH; require the remote-tracking HEAD to be an ancestor of local HEAD (DOLT_MERGE_BASE); record the remote's graph roots and ledger head; the fenced transaction; a scoped commit (DOLT_ADD of the graph tables, DOLT_COMMIT -m — never -Am; a new RunTxScopedResult on the UOW leg, whose Commit hardcodes -Am today); DOLT_PUSH classified by a typed lift of the tree's untyped pushRacePattern (it already matches all three race routes) — on a race, refetch and compare both the remote-tracking ref's ledger head (SELECT seq, hash FROM graph_ledger_events AS OF '<ref>' ORDER BY seq DESC LIMIT 1 — MAX(seq), hash errors under ONLY_FULL_GROUP_BY, probed) and the eight graph tables' diff between the recorded remote pre-head and the new remote head (DOLT_DIFF_STAT/dolt_diff restricted to those tables; DOLT_HASHOF_TABLE reads only the working set) against what was recorded before the transaction: any graph delta or ledger movement → fail closed and undo — never the (authority_id, epoch) tuple alone, which a same-witness twin (a VM image or shared home) or a same-authority fork shares; neither changed (issue-plane divergence only) → keep the commit, ErrSyncRequired; any other failure → keep the commit, mark unpublished, retry later. The classifier lifts the whole of isPushRaceErr — its diverged-history and ancestor-PK-mismatch exclusions included — behind a typed lower-layer error. The remote-tracking ref is remotes/<remote>/<branch>, built by one provider API from the configured sync remote and the active branch (the verifyPullLanded spelling); a missing ref is vacuously an ancestor (the push creates it); an empty remote ledger reads as no head. Undo = DOLT_RESET --soft <pre-op>, then per graph table DOLT_RESET('<table>') (unstage) and DOLT_CHECKOUT('<table>') — a bare checkout after a soft reset restores from the staged root and reverts nothing (probed) — when HEAD is still the operation commit, DOLT_REVERT <op commit> otherwise; then, on either path, a compensating ephemeral write restores the pre-operation lease row — predicated on the lease still naming this workspace at the operation's epoch and on the current fence, and writing a fresh fence (a revert restores the Scope epoch while the ignored lease keeps the new one, which would lock the workspace out of its own lease — probed); if another holder now legitimately holds the lease, it is left alone; the undo runs before any other graph mutation. Reads on hazard R require a remote observation no older than bdp.authority_heartbeat (a serving process fetches on a timer; a CLI read fetches when stale), comparing the remote ledger head against the workspace's witness — reloaded on every check — not against a process-local expectation, and recognizing a pending local operation (a publication that landed before the witness advanced, or a local_committed record) as this workspace's own, so a publication by the workspace's CLI is a re-arm, not a loss; they fail closed after the grace. Recovery on hazard R reuses the same ledger-plus-eight-table delta classifier as the push race: issue-plane-only movement is ErrSyncRequired, never an undo. The fence watcher is a state machine held → renewing → lost: on loss the BDP rows are disabled atomically (legacy surface untouched), bd --graph-mode link serve exits 3, and the watcher joins before provider shutdown. Both hazards → both fences. A clone that received the Scope row by dolt clone has no lease row and bootstraps only with bd --graph-mode link promote --rotate-url; a copy or restore that carries the row is the operator hazard stated above. Services on an ephemeral home pin BEADS_INSTALLATION_ID_FILE to persistent storage, or every restart is a --steal. A promote --rotate-url beside a live server changes the served URL and the host allowlist, which are fixed at startup, so the server exits 3 and is restarted. Force-push routes bypass the fence as operator acts. |
Round 5 (Codex C2–C4, H5, H7, H10, H11; Gemini). |
| A8 | plan §1 constraint #1 and ruling 12 — new | v5's method-set reasoning was inverted | RULED: option A. A: constraint #1 scoped to behavior (byte-identical gate output). Adding six required methods to Storage breaks direct implementers (the compiler catches them; six ErrUnsupported stubs; the joint ReadyClaimer/BatchCloser CHANGELOG entry is the precedent) and is silently promoted through every wrapper that embeds the interface — which is why the censuses are mandatory, not optional. B: an optional BeadGraphCapable interface on the concrete store is not promoted through an interface-embedding wrapper at all, so every wrapper must implement it explicitly and every consumer needs a resolver/unwrap — the v1-plan graphsource shape. |
Round 5 (Codex M14, Gemini). |
| A9 | 9 — simplification, as amended by A10 | — | RULED 2026-09-07; solo exception ruled 2026-09-08. Outside A10's solo topology, v0 authority requires a shared database. Hazard R's publication primitive, remote-read freshness, and multi-phase publication recovery are deferred to the write-profile ADR; a remote-backed workspace is a non-authority for any Scope it did not mint on its own shared database (its bd serve shows rows absent; its CLI reads refuse); cross-database promotion is --rotate-url only (a new Scope, continuity via the ledger lane). The graph tables still replicate through push/pull like any other table; the validator refuses foreign deltas. What remains of A7 is hazard S alone — one arbiter, one lease, one counter. Topology matrix, as amended by A10: a shared database that minted locally is authoritative regardless of any configured remote; a shared database that received the Scope row by replication, restore, or copy without a valid local authority refuses (ErrNotAuthority; --rotate-url or --steal as above); outside A10's embedded solo exception, the embedded and registered-store client-host arms refuse authority-establishing and authority-dependent local operations (Mint/Promote/Rotate/Install and local graph reads answer ErrNotAuthority: authority requires a shared database; the embedded client-host leg uses bdp.client: server, while the solo leg supplies the full local read contract under A10; client-mode reads stay allowed everywhere); a configured remote neither grants nor removes authority, and transition recovery takes the local-operation path on every shared database (the remote classification exists only when hazard R is in force); two shared databases that both mint under one tracked bdp.scope_url are settled by the replication/merge ADR — until it lands, the earlier mint event (lineage) wins and the loser rotates; every hazard-R passage (publication primitive, remote-read freshness, publication recovery, Remote fixture cases) is excluded — but the default-branch rule for the ignored lease table (Part D.5) stays, because it is a property of dolt-ignored tables, not of hazard R; A5's "single-copy by operator responsibility" sentence is withdrawn under A9; A10 subsequently adds the solo exception, whose single-copy safety is again an operator responsibility. Physical database copies remain the stated operator-managed hazard. Selected for v0: the only serving topology already is the SQL-server workspace, and this removes the largest block of new mechanism from P1/P2. |
Round 5 (Codex C1: "require an externally observable fence or weaken the guarantee"). |
| A10 | 9, amends A9 | embedded authority refused under A9 | RULED 2026-09-08: B — solo topology. An embedded workspace with no configured remote and no server mints a local Scope, holds a witness and a lease satisfied by the workspace gate (one process holds the embedded store), and answers every link-mode verb locally. It serves nothing: bd serve still refuses embedded Dolt. It becomes a client host the moment a shared database or remote appears, under the rotation and steal rules. A solo store later pushed to a remote is "minted locally" for the replication ADR — authoritative until a foreign delta appears. The embedded leg wires the full read contract for solo topology and the refusal contract for client hosts. Options A (defer to P3) and C (require a local server) were rejected. |
Plan §9 A10; operator ruling 2026-09-08, raised by Steph's adoption harness (sjarmak/mem). |
A10 mechanism work for P1: assign the local solo mint trigger without adding a serving path, and map its exclusive workspace gate to the shared-leg lease predicates and fence census. The witness, Scope identity, ledger-head and graph- state checks still apply; the gate satisfies the solo lease, rather than requiring an invented shared database. The exact lease-row representation and expiry/self-regrant mapping must be recorded before implementing that leg. This is implementation work under ruled A10, not a new CLI-name ruling.
Two decisions recorded here and ruled 2026-09-07 as plan rulings 13–14:
- Enforcement boundary for out-of-role writes — RULED 2026-09-07 (plan
ruling 13, "A+B").
bd sql, the proxiedRawSQLUseCase, force-push, and a merge can change graph tables without allocation, authority, revision, or owned-Link coupling checks. Out of contract; the state-change validator rejects invalid or foreign-authority graph state (a delta on the ledger-covered tables must be explained by ledger events since the recorded head; bead and link bodies by row provenance); and the eight replicated tables carry session-gatedBEFORE INSERT/UPDATE/DELETEtriggers that refuse a row unless@bd_graph_roleis set — every graphops mutation sets it inside its transaction and clears it beforeCOMMIT/ROLLBACK(the clear is load-bearing: a pooled connection keeps the variable otherwise — probed). Probed on Dolt 2.1.8: the triggers fire (errno 1644), replicate throughdolt_schemas, are created by one multi-statementExecof a migration file, and are silent onDOLT_MERGE/DOLT_PULL(the validator's and ruling 14's territory). A fence against accidents, not credentials; the two-SQL-user boundary is a C-lane task. Three P0 verification rows gate the fence (spec B4). - Replication/merge ADR as a P1 gate — RULED 2026-09-07 (plan ruling 14, option B: the gate plus a four-law charter). The merge entry points are not
four Go functions:
mergesettle.goexports seven,fastforward.goandautomerge.gomore;CALL DOLT_PULLmerges inside Dolt on every pull route; the UOW leg'sdoltVersionControlSQLRepositorycallsDOLT_MERGE/DOLT_PULL/DOLT_PUSHdirectly; embedded federation sync fetches and merges; the remote-migrate gate does a fast-forwardDOLT_MERGE. The validator runs on every observed graph-state-version change: the witness records the graph-state version —DOLT_HASHOF_TABLE('<name>')for each of the eight replicated graph tables in a fixed order, hashed together (the function exists in Dolt 2.1.8 and takes one table argument; the lease is ephemeral and excluded) and the HEAD commit; a body that sees a different version returnsErrStateChangedwithout validating inside the held transaction; the accessor validates under one singleflight coordinator per provider instance in its own transaction (ancestryDOLT_MERGE_BASE(recorded HEAD, HEAD); row provenance for foreign updates), advances the witness, and retries once. Descriptor caches are keyed by the descriptors table's hash. The charter: (1) every SQL pull route fetches, inspects the eight tables between HEAD and the remote-tracking ref, and refuses a foreign-authority or unexplained delta before merging —DOLT_PULLcommits a clean merge immediately andROLLBACKdoes not undo it (probed), so inspection is the only pre-merge refusal point; routes that cannot inspect first (the CLI-subprocess pull, a merge already landed, restore, force-push) fall to the validator, which reverts the eight tables to their state at the recorded HEAD in a new commit when that HEAD is an ancestor (the hazard-R undo shape; later commits preserved) and marks the witnessunverifiedotherwise; (2) no graph-table conflict is auto-resolved and--strategynever touches a graph table — the pull is refused naming the table, the remedies are the link-mode verbs; (3) a foreign graph delta is refused whole, never merged cell by cell, and the later of two mints under one URL adopts the earlier by an explicit verb the ADR names; (4) a workspace without a witness takes the remote's graph state wholesale and refuses to mint until rotated or stolen. Federation unfiltered in v0. The ADR (engdocs/BDP_GRAPH_REPLICATION_ADR.md) is P1's first deliverable, council-reviewed; no graph migration merges before it.
What none of this changes: ruling 9's level — the authority is the graph store as reached through the normalized storage abstraction, on any provider; Dolt is the reference realization; the CLI verbs and the BDP handler are both clients of that abstraction.
3. Packages and their imports
graphops/ PUBLIC LEAF (sibling of issueops/, memoryops/)
├─ types.go Bead, Link, Ref, Properties, Revision, Attribution,
│ TypeDescriptor, OwnedLinkDecl, OwnedLinkGroup, ScopeIdentity,
│ LedgerEvent, LedgerManifest, Cursor (opaque)
├─ laws.go canonical-ID grammar, code-unit ordering, JSON canonicalization,
│ RFC 6902 §4.6 equality, Scope-URL validation, ledger hashing
├─ reader.go Reader: Bead, Link, Beads, Links, IncidentLinks
├─ types_role.go DescriptorReader: Descriptors, Descriptor
│ TypeInstaller: Install (post-mint; published on hazard R)
├─ identity.go IdentityReader: Read, LedgerDurability
│ ScopeBootstrapper: Mint (once; installs the built-in catalog)
│ Admin: Promote, Rotate, LedgerSnapshot, LedgerApply,
│ MarkUnverified, ClearUnverified
(transaction-bound provider capabilities — StateVersioner, GraphPublication, LeaseClaim —
live in internal/storage/graphcap, not here: the public leaf carries no runner type)
├─ writer.go (P3) Writer
└─ errors.go ErrNotFound, ErrValidation, GoneError{Path, State},
ErrNoScope, ErrScopeExists, ErrNotAuthority, ErrStateRewound,
ErrStateChanged, ErrSyncRequired, ErrUnpublished, ErrURLReused,
ErrRepresentationTooLarge, ErrNotServedYet
NO authority fields on any request type — the witness is the store's.
imports: stdlib + beadserrors ONLY
internal/storage/authority/ THE WITNESS MANAGER (clone-local half; no SQL)
Witness{InstallationKey, ScopeURL, AuthorityID, Epoch, LedgerSeq, LedgerHash,
StateVersion, StateCommit, Unverified, GrantedAt, Pending *Transition}
Transition{Kind, OpID, Phase (begun|local_committed|published|config_written|
undo_started|versioned_undone|lease_restored), PreHead, PreLedgerHead, PreLease,
OpCommit, ExpectedRoots, RemotePreHead, ConfigIntent}
Advance takes a provider-supplied Verifier (ledger-prefix + ancestry; under hazard S the
ledger seq is a total order, so seq decides) and runs it under the file lock; the lock is
held from Begin through Finalize/Abandon; LeaseClaim lives in internal/storage/graphcap
installation id: the directory user_config_path.go's UserConfigYamlPath chooses
(~/.config/bd preferred; native fallback), file installation-id, or BEADS_INSTALLATION_ID_FILE;
created O_EXCL 0600, re-read, directory fsynced; per OS user (a service user and an
operator compute different keys — cross-user shared roots are unsupported, as the
workspace gate already declares); an ephemeral home regenerates it (promote again)
Load: plain read; a Pending record → recovery by evidence (the ledger carries the op id?
the remote: pre-head / contains this op / foreign?) → resume, finalize, or undo — BEFORE
any assertion; run by admin verbs and bd --graph-mode link serve only; bd serve and CLI reads treat
Pending as rows-absent / ErrNotAuthority with a notice
Advance: bounded exclusive flock on .beads/graph-authority.lock (internal/lockfile;
poll with timeout, the workspacegate precedent; both ErrLocked and ErrLockBusy honored)
→ descendant-aware compare-and-advance (older contained candidate = no-op; fork = reject)
→ atomicfile → fsync dir
Begin / SetPhase / Finalize / Abandon; preflight ENSURES the .beads/.gitignore entries and
refuses a git-tracked path
internal/storage/graphops/ TX-LEVEL SHARED BODY — all three legs call it
type DBTX interface { ExecContext; QueryContext; QueryRowContext }
assertAuthorityInTx(ctx, tx, w, claim, mutating): Scope row == w; ledger head; lease row —
read: SELECT holder/epoch/expires_at/fence and require expires_at > NOW(6) (reads never
write the lease; a CLI read regrants once, ephemerally, before a fresh read tx when its own
lease has expired); mutation: UPDATE … SET heartbeat_at = ?,
expires_at = NOW(6) + ttl, fence = <fresh random, regenerated per retry> WHERE id = 1
AND holder_installation_key = ? AND epoch = ? AND fence = <value just read> with exactly
one affected row (same-cell-different-value → 1213 → replay re-evaluates: still
authorized → succeeds serially; superseded → 0 rows → refuse); the 1213 surfaces from
CALL DOLT_COMMIT on the scoped path, so that call stays inside the retried closure;
graph-state version == w.StateVersion else ErrStateChanged
nextLedgerSeqInTx: UPDATE graph_ledger_seq SET next_seq = next_seq + 1, alloc_nonce = <random>
WHERE id = 0 (the random cell is what makes two allocators conflict)
ReadBeadInTx / … / MintScopeInTx / PromoteInTx / RotateInTx / LedgerSnapshotInTx /
LedgerApplyInTx (anti-reuse history; reserved allocations; counter set) /
ValidateStateInTx / graphStateVersionInTx: eight calls DOLT_HASHOF_TABLE('<validated name>')
in the fixed order; StateVersion = sha256 of the concatenated hashes
SeedBeadInTx / SeedLinkInTx — fixture writer; _test.go call sites only
internal/storage/dolt/beadgraph_*.go, internal/storage/embeddeddolt/beadgraph_*.go
CLI legs (embedded never serves): witness + claim loaded per call; withReadTx /
withRetryTx; scoped commit (DOLT_ADD graph tables + DOLT_COMMIT -m — the
doltAddAndCommit precedent); PublishGraphMutation for hazard R
internal/storage/domain/db/beadgraph.go + doltVersionControlSQLRepository additions
BeadGraphUseCase over db.Runner; the repository gains Fetch/Push (exist), MergeBase,
ResetSoft, CheckoutTables, Revert, HashOfTables
internal/storage/uow/beadgraph_*.go THE SERVING LEG
uow.UnitOfWork gains BeadGraphUseCase(); doltSQLProvider gains beadsDir (received by
cmd/bd/uow_factory.go's newSQLServerUOWProvider today, dropped) and timedProvider gains a
getter for it (it builds roles over the wrapper today); NEW
RunTxScopedResult(tables, msg) — doltServerTx.Commit hardcodes DOLT_COMMIT('-Am') today;
RunTxEphemeral for lease renewal; PublishGraphMutation on the provider
internal/storage/storage.go + six BeadGraph* accessors
internal/storage/hook_beadgraph_*.go, internal/telemetry/beadgraph_*.go, backend/conformance/…
internal/httpapi/bdp_routes.go bdpRouteTable — conditional rows behind route() (P2);
FenceSource state machine (held → renewing → lost)
internal/httpapi/bdpwire/ hand-written DTOs held to the vendored, pinned schema by tests (Part D.3, recorded 2026-09-07) — P0
internal/bdpclient/ graphops.Reader/DescriptorReader over the wire
cmd/bd/bdp*.go link mode root; bdpRootPolicy keyed by CommandPath();
bdp_serve.go staged startup (exclusive mint, then shared serve)
cmd/bd/backup_restore.go runBackupRestore → Admin.MarkUnverified (no-op without a witness)
Dependency direction, enforced: cmd/bd → graphops, storage accessors, bdpclient; internal/httpapi → graphops, bdpwire; internal/storage/* → graphops, authority; graphops → beadserrors, stdlib. A new depguard rule
denies internal/storage/graphops to everything but the three legs and
domain/db.
4. Roles — how many, and why
The house test: a role is a different question, born whole with the
methods that are shapes of one question; and can one caller be entitled
to the read and not the write? — if yes, two roles. Six, each behind its
own BeadGraph* accessor. Authority is never a parameter. Transitions
produce the witness and carry their own preconditions instead of the head
check — named per method.
graphops.Reader— one record by path (grouped, boundedownedLinks), keyset pages under an opaque cursor, incident Links. Protected.graphops.DescriptorReader— the ordered catalog and a keyed lookup. Protected. Bounded.graphops.TypeInstaller— post-mint install/converge withinstallevents; a fenced mutation, published through the same primitive as every other replicated mutation on hazard R. P1. Before mint there is no install: the built-in catalog is installed byMint.graphops.IdentityReader— the Scope row, the witness's claim, andLedgerDurability. Exempt (it reports state).graphops.ScopeBootstrapper—Mint, once, under the exclusive gate through a temporary source (the spec's one staged-startup sequence: shared read → release → exclusive only when there is no Scope row → release → shared serve), fenced per hazard, multi-phase: precondition no Scope row; INSERT the singleton Scope row, seed the counter, appendmint, install the built-in catalog with itsinstallevents — one transaction, one scoped commit, published on hazard R,config.yamlwritten when--scope-urlsupplied it; then the witness is finalized.graphops.Admin—Promote(precondition: Scope row CAS + the fence; produces the witness),Rotate(precondition: Scope-row lineage and the lease;refuse_url(old)+rotate(new)in one transaction;config.yamlin theconfig_writtenphase; refused whileBDP_SCOPE_URLoverrides),LedgerSnapshot,LedgerApply(recovery predicate; anti-reuse history only; regrants),MarkUnverified/ClearUnverified. Authorized by being the local administrative composition root —PromoteandRotateunder the shared gate (they rely on the lease and run beside a live server),Install,LedgerApply, andbd --graph-mode link restoreunder the exclusive gate;httpapi.GraphConfighas no field for it.graphops.Writer(P3, not now).
5. A read, end to end
client ──GET /acme/beads/x──▶ internal/httpapi (bd serve | bd --graph-mode link serve; UOW leg)
│ route(): deadline → bearer → Bd-Project-Id stamp (absent = pass) → database slot
▼
bdp handler: path grammar (graphops laws) → ONE role call
▼
graphops.Reader.Bead(ctx, BeadRequest{Path}) ← no authority fields
▼
BeadGraphReader (manager-backed role): w := authority.Load(beadsDir); claim := process claim
│ hazard R: require a remote observation ≤ bdp.authority_heartbeat old (fetch if stale;
│ fail closed past the grace) [absent under A9]
▼ RunTxRead ─▶ storage/graphops.ReadBeadInTx(ctx, runner, w, claim, req)
│ stmt 1 Scope row: (scope_url, authority_id, epoch) == w
│ stmt 2 ledger head: event at w.LedgerSeq has hash w.LedgerHash; MAX(seq) >= w.LedgerSeq
│ stmt 3 lease row: holder key/epoch == claim AND expires_at > NOW(6) (SELECT — a read never
│ writes the lease; a mutation UPDATEs it, rewriting the fence cell and extending
│ expires_at, self-regranting if expired; a CLI read on its own expired lease regrants
│ once ephemerally before a fresh read tx)
│ stmt 4 graph-state version: DOLT_HASHOF_TABLE('<name>') × 8 in fixed order, sha256 of
│ the concatenation == w.StateVersion → else ErrStateChanged (returned WITHOUT validating here;
│ the accessor validates under the provider's singleflight coordinator, advances the
│ witness, retries once)
│ stmt 5 bead row
│ stmt 6 descriptors for the Bead's Type (cache keyed by the descriptors table's hash,
│ which stmt 4 already read)
│ stmt 7 ONE batched owned-links query, LIMIT (bound − rows so far) + 1
▼
graphops.BeadRecord {Bead, OwnedLinks []OwnedLinkGroup}
▼
bdp handler: bdpwire DTO ← record; typed error → BDP Problem; JSON out
Statement budgets are per role method (spec B2). A write (P3): the body
asserts mutatingly (the lease UPDATE with one affected row), runs the
no-op gate, records attribution, versions the source on owned-Link
mutation, takes the next seq, appends the event, stamps provenance; the
accessor commits scoped, publishes on hazard R, and only then
advances the witness — DB first, file second.
6. Where the rulings land
| Ruling | Lands in |
|---|---|
| 1 charter | engdocs/PROJECT_CHARTER.md edit rides the first merged slice |
| 2 substrate S1 | replicated migrations (scope, history, descriptors, beads, links, ledger events + counter, allocations) + the lease's three parts (doltIgnorePatterns, main-series creation, ignored-series twin) + ignoredSource.sentinelTables gains the lease |
| 3 allocation ledger | graph_allocations (derived; reserved state after a ledger-lane apply); graph_ledger_events; graph_ledger_seq |
| 5 withdrawal | nothing projects Issues; structural |
| 7a Scope URL | bdp.scope_url in tracked config.yaml (BDP_SCOPE_URL first); singleton Scope row; no dev-mode derivation |
| 7b listener | BDP rows behind httpapi.route() (A2) |
| 8 changefeed | P3 |
| 9 authority | store-owned witness in every transaction (A1); fences by hazard (A7), hazard S under A9, and the solo workspace gate under A10; contract cases incl. clone, restore, copied witness, expired-lease mutation, nonce mismatch, graph delta under an unchanged tuple, revert when HEAD moved, each phase's recovery |
| 11 restore vs identity | hash-chained head in the witness; multi-phase transitions; ledger lane = anti-reuse history; LedgerDurability; rotation (A5) |
| 12 store/Scope/client | bd init migrations only; among serving commands only bd --graph-mode link serve mints (staged); A10 solo mint trigger is a P1 mechanism; bd --graph-mode link client (A6); A8 options; registered backends absent in v0 |
| 13 out-of-role DML | session-gated triggers in the five table files (spec B4); the validator's ledger accounting (B3); three P0 verification rows; the two-SQL-user boundary is C-lane |
| 14 replication/merge | engdocs/BDP_GRAPH_REPLICATION_ADR.md first in P1; fetch-inspect-merge on the SQL pull routes; validator revert on the rest; graph tables excluded from auto-resolve and --strategy; clones take remote state wholesale |
| 6 wisps | not served |
7. What is deliberately not designed here
- Cross-request cursor continuation (P2 ADR); no collection routes before it.
- The write profiles' wire (W1),
graphops.Writer, per-token authorization classes, the push-on-commit latency budget, and the acknowledged-but-unwitnessed-write window (P3). - The replication/merge ADR's mechanism (§2b; the charter is plan ruling 14) — P1's first deliverable,
engdocs/BDP_GRAPH_REPLICATION_ADR.md; precedes the migrations. - A DB-privilege (two-SQL-user) boundary for the graph tables (C-lane, ruling 13).
- The
GraphPublicationcapability a registered backend would declare to serve BDP (deferred; v0 serves from SQL-server workspaces only). - Whether
bd --graph-mode link serveremains after W2 (default: yes — the serving minting path). - Type generation from the bead-type inventory (W3) — it feeds the built-in
catalog
Mintinstalls.