`bd events tail|export|prune` is how a consumer actually reaches the journal.
tail emits JSONL from a --since checkpoint and --follow keeps printing new
records as they commit; export is tail from zero; prune deletes below --before,
honoring the retention floors. All three work identically against the embedded
store, a server-mode store, and proxied-server mode, which reads and prunes
through its unit-of-work journal capability rather than a raw connection. The
proxied prune commits with the SQL-only form: the journal table is dolt_ignored,
so its delete must persist into the working set without minting a Dolt commit.
A pruned-past checkpoint surfaces as {"code":"events_journal_truncated","since",
"floor","head"} with a non-zero exit. Both read call sites report it, because
wiring only one still lets `export` present a pruned journal as a complete
history — and the two are framed differently on purpose. The one-shot read
prints the object the way every other --json failure does. The --follow poll
prints it as ONE line on the JSONL stream it interrupts: the consumer there is
a line reader, and a pretty-printed multi-line object dropped into its input is
unparseable, so it would see the stream stop with garbage after the last good
record. Same fields, same code, same exit; only the framing follows the stream.
A negative --since is refused outright rather than serving `seq > -5` as if it
were a resume.
Activation is applied by the FACTORIES that build a store or a unit-of-work
provider, not by the commands that use one. It did not start there, and the
failures that got it here are the argument for the guard that now holds it:
first a process-global switch; then two root pre-run call sites, which covered
the CLI's own store and its proxied provider and missed `bd serve` (which
builds its own provider for a server-mode workspace), routed creates and
remote-cache hydration (which open a SECOND store for another workspace), the
pluggable backend registry arm, and the personal-migration planning store; then
a blanket exemption for bd doctor whose stated reason — "workspace repairs, not
bead mutations" — was FALSE for three of its repair handlers. Each ran with the
journal off while every command reported success, and an empty journal is
indistinguishable from a quiet one.
Those three now journal. StaleClosedIssues and PatrolPollution DELETE issues
and the two fresh-clone import paths CREATE them, so they open through an
activating factory of their own; a repair is the last place a silent divergence
is acceptable, because it runs unattended on a workspace someone is already
worried about. The policy moved to internal/eventsjournal for it: bd doctor's
fix package cannot import package main, and two copies of an activation rule is
how the rule stops being one rule. What remains exempt in doctor is named
handler by handler with a reason that can be checked against the code, rather
than inherited from a directory.
So TestEveryStoreConstructionActivatesTheEventsJournal enumerates every
construction of a store or provider across cmd/bd, bd doctor, its fix package
and the standalone embedded utility, and fails unless the constructing function
activates in its OWN body or carries a written exemption. Deliberately no
call-graph fixpoint: "the caller does it" is exactly the assumption that kept
being wrong. The factories use a deferred rewrite of their named results so the
open and its activation are one syntactic unit, which is what makes the check
local. Sites are keyed by file, so the CGO and non-CGO twins of a factory are
checked separately rather than one silently shadowing the other, and
constructors are matched through each file's IMPORT TABLE rather than by
package identifier — an aliased import would otherwise produce no site at all,
which is the worst thing a guard can do, because it reports success while
checking nothing. Its remaining honest limits (a constructor reached through a
method value, a package nobody added to the scan) are written down in the
guard rather than claimed away.
A cross-workspace open reads the TARGET workspace's own config.yaml, not the
launching one's: the journal records that workspace's mutations, so that
workspace decides whether they are recorded. An explicitly set
BD_EVENTS_JOURNAL outranks both — environment beats file here as everywhere
else in bd, and a routed write into several workspaces is exactly where an
operator reaches for it; a file that could veto it would make the variable a
suggestion, discovered later as an empty journal.
The three config keys join YamlOnlyKeys, which is the whole of review blocker 6.
They are read through viper during pre-run, before the store is open, so a
DB-backed write is silently unread — the GH#536 class that map exists to
prevent. TestEventsPruneHonorsRetainRowsFloorFromConfig enables the journal
through `bd config set` and then asserts records actually appear, so the
blocker cannot regress into a green suite.
The committed golden pins the record envelope external consumers parse,
including the comment op, and is built by marshaling real types.Issue /
EventDep / EventComment values through the same buildRecord path tail uses.
Four properties are guarded rather than assumed. No record may carry an inline
"dependencies" array. Every comment record's source must be one an emit site
can actually produce, and both must appear — the golden shipped for one
revision pinning "comment", a value invented for the fixture, which is worse
than no fixture because a golden's job is to be the thing consumers trust. And
the file must be reproducible: an issue snapshot carries wall-clock ride-alongs,
notably lease_expires_at / heartbeat_at, which a claim stamps from time.Now().
A fixture that reached for the clock would pass on the run that regenerated it
and fail on every run after, reading as flake rather than as the fixture bug it
is. Rather than normalize those fields away, the claimed fixture carries FIXED
lease values — so the golden pins the shape a consumer of a claimed bead really
sees — and a second test renders twice and requires byte equality.
The help text carries the contract a consumer has to know before it trusts a
cursor, because none of it is inferable from the records: the journal is
per-branch working-set state and per REPLICA, so `bd dolt pull` and the changes
a merge settles in are NOT journaled and a mirror must re-baseline after a sync;
each replica counts its own seq space, so a checkpoint taken against one is
meaningless against another; raw DML through `bd sql` bypasses the mutation seam;
store-open-time migrations and version reconciliation are unjournaled by design;
retention floors are not a consumer watermark; prune is manual and pairs with
`dolt gc`, since ordinary Dolt commits never collect dolt_ignored state. And the
two dependency asymmetries a naive consumer gets wrong: a dep_add is emitted for
an idempotent same-type re-add that only refreshes metadata (the audit table
dedupes that case, the journal does not — it is an upsert, not proof the edge is
new), and dep.metadata is the value being written on add but the raw stored
column read back on remove, so the two can differ byte for byte while meaning
the same thing.
Four end-to-end tests hold the activation paths, and each was verified by
removing the activation it covers: a proxied mutation reports "journaled 0
records"; `bd serve` against a server-mode workspace journals nothing for an
HTTP mutation; a routed create into a journal-enabled target records nothing;
and a bead-mutating `bd doctor --fix` deletes issues while journaling none of
them. The routed tests also pin the direction and the precedence — the
launching workspace, which enabled nothing, stays empty, and a target that
explicitly set the key to false is still overridden by the environment.
Ports cmd/bd/events.go + events_journal.go from 3bfed2431/0a3fe0f9b and the
golden from 3666e5026. Deviations: the reference's validateEventsJournalBackend
named a backend allowlist including a SQL family OSS main does not have, so the
capability check itself fails closed instead; its proxied prune used a
uow.RunInTx helper that does not exist here, replaced by RunTxEphemeral, which
states the dolt_ignored intent rather than relying on the commit path to demote
an empty DOLT_COMMIT; activation is factory-scoped rather than applied at the
reference's root pre-run call sites; and the golden's comment source is taken
from the engine's constants rather than restated.
Co-authored-by: CI Bot <ci@beads.test>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen