* 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>
13 KiB
Documentation Disposition Inventory
Graph-plane design records added: 2026-09-10. Reviewed: 2026-07-07 (paths updated 2026-07-10 for the Mintlify port: user docs now live in the docs/ site tree; this ledger and other internal docs live in engdocs/)
CI cleanup entry added: 2026-05-28
Scope: every Markdown file under docs/, including adr/, design/,
design/otel/, and the staged-for-removal bin.
Evidence bar: retained factual claims must be backed by current CLI behaviour,
current tests, or code that is used by the product. Reference-shaped docs either
need generated/checkable maintenance, or an explicit Last reviewed: marker and
freshness source.
Canonical Seams
| Seam | Canonical docs | Rule |
|---|---|---|
| Architecture | ARCHITECTURE.md, INTERNALS.md, DOLT.md, adr/, design/ |
Durable structure, package boundaries, storage model, and invariants live here. |
| Behaviour/reference | CLI_REFERENCE.md, CONFIG.md, SETUP.md, JSON_SCHEMA.md, RECOVERY.md, ERROR_HANDLING.md, TROUBLESHOOTING.md |
CLI/config/runtime contracts live here and need generation or freshness review. |
| User-facing workflow | INSTALLING.md, QUICKSTART.md, FAQ.md, SYNC_SETUP.md, integration guides, WORKTREES.md, UNINSTALLING.md |
Task-oriented user docs live here; avoid duplicating implementation tables unless linked to reference docs. |
| Maintainer/operator | root RELEASING.md, RELEASE-STABILITY-GATE.md, LINTING.md, SECURITY-DEPENDENCY-EXCEPTIONS.md, PERFORMANCE_TESTING.md, CI_TEST_SURFACE_AUDIT.md, CI_CLEANUP_PLAN.md, SERVE_RUNBOOK.md |
Maintainer process docs stay active only when tied to current scripts/checks. |
| Historical/staged | staged-for-removal/ |
Resolved audits, stale duplicates, and unsupported snapshots are preserved here until deleted or rescued. |
Reference Freshness
| Doc | Freshness path |
|---|---|
CLI_REFERENCE.md |
Generated from bd help --all. |
plugins/beads/skills/beads/resources/CLI_REFERENCE.md |
Pointer-only doc: must link to live CLI help and canonical generated docs/CLI_REFERENCE.md; do not duplicate generated command tables. |
reference/configuration.md |
Last reviewed: marker tied to cmd/bd/main.go, cmd/bd/config.go, and internal/configfile/. (Mintlify port: absorbed CONFIG.md.) |
getting-started/ide-setup.md |
Last reviewed: marker tied to cmd/bd/setup*.go and internal/recipes/. (Mintlify port: absorbed SETUP.md.) |
integrations/azure-devops.md |
Last reviewed: marker tied to cmd/bd/ado*.go and internal/ado/. (Mintlify port: was ADO_CONFIG.md.) |
reference/json-schema.md |
Last reviewed: marker tied to cmd/bd/output.go, cmd/bd/errors.go, and protocol tests. (Mintlify port: was JSON_SCHEMA.md.) |
recovery/init-safety.md |
Last reviewed: marker tied to cmd/bd/init*.go safety code and tests. (Mintlify port: was RECOVERY.md.) |
ERROR_HANDLING.md |
Last reviewed: marker tied to current command error exits and JSON error helpers. |
LINTING.md |
Last reviewed: marker tied to .golangci.yml, scripts/ci/pr-lint.sh, the Makefile wrapper, and CI workflow wiring. |
SERVE_RUNBOOK.md |
Last reviewed: marker tied to the operating-envelope constants in internal/httpapi/server.go and the log fields in its event/request emitters. |
CI_CLEANUP_PLAN.md |
Last reviewed: marker tied to the CI audit, workflow files, wrapper scripts, Makefile, package manifests, and maintainer decision review. |
design/otel/otel-data-model.md |
Last reviewed: marker tied to telemetry, Dolt storage, hooks, and AI call sites. |
Follow-up automation should replace marker-only checks with generated or
--check blocks where a clean code source exists.
Active Docs
| File | Disposition | Rationale and evidence |
|---|---|---|
ADAPTIVE_IDS.md |
Keep | Behaviour doc for hash ID scaling; verify against ID generation code before changing numeric claims. |
ADO_CONFIG.md |
Keep with freshness | ADO reference; marker points at ADO command/client code. |
AGENT_SIGNING.md |
Keep | Maintainer/operator convention for agent comment and commit signatures. |
adr/0001-multi-remote-approach.md |
Keep | ADR; historical decision record, not a live reference table. |
adr/0002-init-safety-invariants.md |
Keep | ADR backing RECOVERY.md and init safety code. |
adr/0003-provenance-event-log.md |
Keep | ADR; historical decision record for the provenance_events table and bd provenance command group. Status: Proposed pending a maintainer post on issue 4460. |
ADVANCED.md |
Keep/revise as needed | User-facing advanced workflows; mixed command examples should defer to generated CLI reference when expanded. |
AIDER_INTEGRATION.md |
Keep | User-facing integration guide; evidence is setup/integration behaviour. |
ANTIVIRUS.md |
Keep | User-facing operational note; review vendor/version claims when touched. |
ARCHITECTURE.md |
Keep | Primary architecture overview; evidence is current package layout and Dolt-only storage path. |
ATTRIBUTION.md |
Keep | Attribution record for removed merge engine. |
BDP_BEAD_GRAPH_PLAN.md |
Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. |
BDP_GRAPH_ARCHITECTURE.md |
Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. |
BDP_GRAPH_CLI_AND_STORAGE_SPEC.md |
Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. |
CLAUDE_INTEGRATION.md |
Keep | Design/user guide for Claude setup; paired with SETUP.md. |
CLAUDE.md |
Revise | Kept as architecture orientation only; command/workflow duplication was reduced in favour of root AGENTS.md and AGENT_INSTRUCTIONS.md. |
CLI_REFERENCE.md |
Keep/generated | Generated command reference from live help output. |
CI_CLEANUP_PLAN.md |
Keep as maintainer context | Dated CI policy, measurements, and implementation roadmap; current commands live in workflows and the Makefile. |
CI_REQUIRED_CHECK_TOPOLOGY.md |
Keep as maintainer context | Implemented workflow design record for aggregate-gate policy; branch-protection and ruleset adoption remain pending. Live job membership and display names come from .github/workflows/*.yml and their structural tests; copied wiring and rollout steps are historical snapshots. |
CI_TEST_SURFACE_AUDIT.md |
Keep as historical snapshot | Dated test-surface inventory; current commands live in workflows and the Makefile. |
plugins/beads/skills/beads/resources/CLI_REFERENCE.md |
Keep pointer | Plugin skill resource intentionally points at live CLI sources to avoid duplicate generated command snapshots. |
CODEX_INTEGRATION.md |
Keep | User-facing Codex integration guide. |
COLLISION_MATH.md |
Keep | Mathematical background; low product drift. |
COMMUNITY_TOOLS.md |
Keep | Curated external tools list; external links need periodic review. |
CONFIG.md |
Keep with freshness | Reference doc; reviewed against config and env-var code. |
CONTRIBUTOR_NAMESPACE_ISOLATION.md |
Keep | Design/user guide for contributor routing and BEADS_DIR behaviour. |
COPILOT_CLI_INTEGRATION.md |
Keep | Design doc for GitHub Copilot CLI integration; paired with COPILOT_INTEGRATION.md (VS Code + MCP). |
COPILOT_INTEGRATION.md |
Keep | User-facing integration guide. |
DEPENDENCIES.md |
Keep | Behaviour doc for graph semantics. |
design/bd-serve-v0.md |
Keep | bd serve v0 contract and the decisions behind it; defers to internal/httpapi/spec/openapi.v0.yaml, internal/httpapi/doc.go and issueops/reader.go as sources of truth. |
design/dolt-concurrency.md |
Keep | Design note for Dolt concurrency. |
design/kv-store.md |
Keep | Draft design note; retain as design seam, not user reference. |
design/otel/otel-architecture.md |
Keep | Architecture/design doc for telemetry; reference tables should defer to data model. |
design/otel/otel-data-model.md |
Keep with freshness | Reference schema; reviewed against telemetry and emission code. |
DOC_INVENTORY.md |
Keep | This disposition and seam inventory. |
DOLT-BACKEND.md |
Consolidated pointer | Old duplicate staged; stable path points to canonical DOLT.md. |
DOLT.md |
Keep/canonical | Canonical Dolt backend guide. |
ERROR_HANDLING.md |
Keep with freshness | Pattern guide with code-linked examples; marker added. |
EXCLUSIVE_LOCK.md |
Keep | Behaviour/design doc for lock protocol. |
FAQ.md |
Revise | Opening wording now describes beads as Dolt-powered; stale pre-1.0 status removed. |
FEDERATION.md |
Keep/canonical | Canonical federation (peer-to-peer sync) guide; moved from root FEDERATION-SETUP.md, which is now a stable pointer. Absorbed the duplicate federation section previously in DOLT.md. |
GIT_INTEGRATION.md |
Keep | User-facing git/worktree/hook behaviour. |
graph-links.md |
Keep | Behaviour/design doc for graph links. |
ICU-POLICY.md |
Revise | Link updated to canonical Dolt doc. |
INSTALLING.md |
Keep | User-facing installation guide; install matrix needs periodic link/version review. |
INTEGRATION_CHARTER.md |
Keep | Scope-boundary policy. |
INTERNALS.md |
Keep | Internal architecture/runtime deep dive. |
JSON_SCHEMA.md |
Keep with freshness | JSON contract; marker tied to schema constant and tests. |
LABELS.md |
Keep | User-facing label philosophy plus examples; generated CLI handles command reference. |
LINTING.md |
Revise with freshness | Zero-issue wrapper contract and CI pin reviewed; marker tied to lint configuration, wrapper, and workflow wiring. |
messaging.md |
Keep | Design doc for messaging issue types. |
METADATA.md |
Keep | Behaviour doc for metadata field semantics. |
MOLECULES.md |
Keep | User-facing workflow concept doc. |
MULTI_REPO_AGENTS.md |
Keep | Agent workflow guide. |
MULTI_REPO_MIGRATION.md |
Keep | Human migration guide. |
OBSERVABILITY.md |
Keep | User-facing OTel guide; data-model reference owns schema tables. |
PERFORMANCE_TESTING.md |
Keep | Maintainer testing guide. |
PLUGIN.md |
Keep | User-facing plugin guide. |
PROJECT_CHARTER.md |
Keep | Canonical product scope and boundary policy. |
PROTECTED_BRANCHES.md |
Keep | User-facing protected-branch workflow. |
QUICKSTART.md |
Keep pointer | Short pointer to website quickstart; low drift. |
README_TESTING.md |
Compatibility pointer | Points to the sole canonical testing guide, TESTING.md. |
RECOVERY.md |
Keep with freshness | Runtime recovery playbooks; marker tied to init safety constants/tests. |
RELATED_PROJECTS.md |
Keep | Curated list of adjacent, non-integration projects; companion to COMMUNITY_TOOLS.md. |
RELEASE-STABILITY-GATE.md |
Keep | Maintainer release gate policy. |
RELEASING.md |
Consolidated pointer | Old duplicate staged; canonical process is root RELEASING.md. |
REPO_CONTEXT.md |
Keep | Architecture/behaviour doc for repo context. |
ROUTING.md |
Keep | Multi-repo auto-routing design. |
RULES_AUDIT_DESIGN.md |
Keep | Design doc for rules audit. |
SECURITY-DEPENDENCY-EXCEPTIONS.md |
Keep with freshness | Existing freshness-marker exemplar. |
SERVE_RUNBOOK.md |
Keep with freshness | Operator runbook for bd serve; the operating envelope it tabulates is constants in internal/httpapi/server.go and must be re-checked when they move. |
SETUP.md |
Keep with freshness | Setup reference; marker tied to setup commands and recipes. |
staged-for-removal/MANIFEST.md |
Keep | Staged removal process and per-file rationale. |
superpowers/plans/2026-05-03-unclaim-command.md |
Removed | PR-passenger planning artifact from a contributor's personal multi-agent rig, same class as the artifacts removed in commit 187ba85f3 (#4632); no readers in this repo, content stays in git history. |
superpowers/specs/2026-05-03-unclaim-command-design.md |
Removed | PR-passenger design-spec artifact paired with the plans file above; same removal rationale, content stays in git history. |
SYNC_CONCEPTS.md |
Keep/canonical | Sanctioned website-mirror source for the sync conceptual model (Dolt source of truth, wire format, JSONL export, anti-patterns); listed in deploy-docs.yml and linked from AGENTS.md, README.md, ARCHITECTURE.md, DOLT.md, GIT_INTEGRATION.md, and FAQ.md. |
SYNC_SETUP.md |
Revise | Links now point at canonical DOLT.md. |
TESTING.md |
Keep/canonical | Sole authority for test commands, test design, and PR-readiness guidance. |
TESTING_PHILOSOPHY.md |
Compatibility pointer | Points to the sole canonical testing guide, TESTING.md. |
TODO.md |
Keep | Behaviour/user guide for bd todo. |
TROUBLESHOOTING.md |
Keep | User-facing recovery guide; debug/env tables need freshness review when edited. |
UI_PHILOSOPHY.md |
Keep | Design philosophy. |
UNINSTALLING.md |
Keep | User-facing uninstall guide. |
WORKTREES.md |
Keep | User-facing worktree guide. |
Staged Docs
Every staged file is recorded in
staged-for-removal/MANIFEST.md with original
path, reason, missing evidence, and rescue criteria.