Add a durable, replayable local journal of committed issue mutations for
external tooling — a database feature in the spirit of a binlog/WAL — and,
along the way, fix script hooks so they fire on both of bd's write plumbings.
Storage: a journal TABLE, written in the SAME transaction as the mutation.
bd has two write plumbings — the DoltStorage decorator chain and the
unit-of-work path — and both bottom out in the internal/storage/issueops
*InTx functions. A row is inserted into bd_mutations_journal at that shared
seam inside the mutation's own transaction, so the journal can never lag the
data, record a phantom, or collide on a sequence number: seq is an
engine-assigned AUTO_INCREMENT PK serialized across every connection.
Columns: seq (PK), ts, op (create|update|close|delete|dep_add|dep_remove),
issue_id, issue_json (full post-mutation issue; NULL on delete), dep_json
(edge for dependency ops). Coverage is structural — every op through the seam
is journaled: ordinary issues and wisps, claim / ready-claim, lease reclaim,
rename / rename-prefix, cascade and by-source-repo bulk deletes (each affected
row in-tx), and creation-time dependency edges. The unit-of-work repositories
reimplement several mutators instead of routing through issueops, so those
emit at their own seam too; two completeness guards (source-scanning call-graph
tests) fail the build if any current or future mutator stops journaling.
dolt_ignore: the table is node-local working-set state, never versioned. It is
registered in dolt_ignore at creation, so bd's batch auto-commit never stages
it and it produces no Dolt history. Tests prove tx atomicity across the
tracked+ignored tables (commit/rollback together), that rows survive commit
cycles, and — critically — that they survive `dolt reset --hard` (an ignored,
working-set table is not reset). On a hypothetical sqlite backend it is a
plain table; the current tree is Dolt-only (sqlite/mysql/postgres backends are
removed and rejected at startup).
Reading and retention (bd mutations):
- tail --since <seq> JSONL to stdout; --follow polls the local table (cheap)
- export the whole journal from seq 1
- prune --before <seq> honoring retain floors that can only ever keep more:
mutations-journal-retain-days / -rows
seq never resets across prune or restart. The CLI read/prune path goes through
a new storage.MutationsJournalAccessor capability implemented by both the
embedded store (via its per-operation withConn transaction) and the
server-mode store (via withReadTx/withRetryTx); the query bodies live once at
the issueops seam (ReadMutationsInTx / PruneMutationsInTx). This is required
because the default local workspace is the embedded store, which owns its
connections and exposes no stable *sql.DB — the RawDBAccessor path that only
server mode provides would (and did) fail there.
Feature is OFF by default (zero overhead, no table writes): enable per workspace
with `bd config set mutations-journal true` or BD_MUTATIONS_JOURNAL=1.
Hooks fix: the unit-of-work plumbing previously fired no script hooks after a
commit, so integrations wired to .beads/hooks/ silently missed every mutation
that went through it. A NotifyingProvider now runs the same fire-and-forget
hooks on that plumbing too, buffered and drained strictly post-commit. Hook
semantics are unchanged; the journal is the durable, ordered record.
Consumer contract: a committed golden (cmd/bd/testdata) marshals real
types.Issue and dependency values through the tail record shape, pinning bd's
field marshaling (issue_type, omitempty, dependency fields, null-on-delete)
against silent wire drift. The record contract and the prune/watermark/dolt-gc
guidance are documented in the command help. Consumers track their own
watermark; pruned history is unrecoverable from the workspace, so pair a Dolt
prune with `dolt gc`.
Tests drive real entry points on BOTH plumbings — create/update/claim (incl.
ready --claim), close, reopen, delete (incl. cascade and by-source-repo),
dep add/remove and creation-time deps, wisp create/update/close, rename, lease
reclaim; rollback journals nothing; seq is one shared monotonic sequence across
independent handles; prune floors + seq continuity; replay-from-0 reconstructs
the exact live set; the dolt_ignore guards above; and the read/prune capability
on both the embedded and server stores.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>