beads/backend/conformance
Julian Knutsen 4e7cc88180
feat(journalops): the mutation journal becomes the third facade namespace (#5552)
* feat(journalops): the mutation journal becomes the third facade namespace

The durable mutation journal's read side is now a role. `journalops` is a
leaf package beside `issueops` and `memoryops` holding Row, Page,
TruncatedError/TruncatedCode and `Journal`, whose doc comment is the
specification: since-exclusive, seq-ascending, limit 0 uncapped with the
wire's cap named as the handler's, a head that comes with its rows and never
decreases, a caught-up checkpoint, and a typed truncation naming a resumable
window.

NOTHING CHANGES BEHAVIOR. The four names in `internal/storage` become
ALIASES of the leaf — `type EventsJournalCursor = journalops.Journal` and its
three siblings — so every implementation, every errors.As site and every
caller compiles unchanged. The alias direction is what avoids the import
cycle: the leaf imports context and fmt and cannot name internal/storage, so
the canon goes down and the alias goes up. Outside storage.go and the
conformance tier, the only non-test edits in this change are COMMENTS.

The role brings the apparatus a role owes:

- backend/conformance/journal_contract.go, six cases over a fixture carrying
  the role, the activation switch, a prune, and a mutation kit that is
  exhaustive against the engine's closed op vocabulary.
- Wirings on all three legs (dolt, embeddeddolt, uow), so #5499's
  entrypoint-scoped lock passes with every leg running every case.
- journalops added to the conformance census's facadePackages. That is the
  #5459 demand side, and the role that needed it: `Journal` is handed out by
  NO accessor — a front door type-asserts for it — so only a source parse can
  see it. issueops.Importer is the precedent.

EventsJournalAccessor and EventsJournalConfigurer stay in internal/storage.
Retention and activation are operator surface, and a server documented to
publish the journal and never retain it must not hold a delete.

Net deletion on the bespoke side: TestEventsJournalPageReportsTheHead is
subsumed by the contract and is gone. TestEventsJournalRestartAndRetentionBoundary
stays, because it observes ReadEventsInTx — the accessor's second read body,
deliberately not on the role — and a mutation of one is invisible to the other.

Mutation-measured, per case, on the embedded leg: an inclusive checkpoint, a
head derived from the page, an untyped truncation, a head taken from MAX(seq)
of surviving rows, and a dropped engine-only op each redden exactly the arm
named for them, and a fixture whose activation hook is a no-op reddens all
six. Reading the head BEFORE the rows leaves all six green — that promise is
declared unpinnable in the contract header rather than faked.

Refs ga-fvya1, ga-2yaqp.4.

* docs(journalops): fix three comment-precision findings from review

All comments, plus one test-only compile-time pin block.

1. journal_facade_test.go told a misassembled causal story: it used the
   CURSOR de-aliasing as its example and then attributed the breakage to
   errors.As. Those are two different failures. Measured, both:
   de-aliasing the interface builds the WHOLE TREE clean and breaks nothing
   behavioral — what it costs is the claim that one role has one name — while
   the error's dangerous shape is not the bare defined type (which loses
   Error() and fails to build) but the COPY-PASTE TWIN, which compiles in
   silence and stops crossing errors.As for everything holding the leaf's
   spelling. Rewritten to say that straight.

2. The seq commit-order unpinnable declaration cited "the dolt package's own
   journal tests" for the server-mode half. Those are single-threaded. The
   actual pin is internal/storage/domain/db/journal_seq_test.go —
   TestEventsJournal_CommitOrderedGaplessSeq drives two OVERLAPPING
   transactions on independent connections, and
   TestEventsJournal_ConcurrentWritersGaplessNoDup a racing batch. Cited
   correctly, and the single-threaded ones named as NOT the pin.

3. EveryMutationKindLandsARow's runs-last ordering is load-bearing but held
   by convention: a reorder compiles, passes, and silently gives up the only
   coverage that a journal keeps recording after a full prune. It was stated
   in the dispatch table and the three leg wirings; it is now stated at the
   case itself, where somebody editing a leg file is actually looking.

And the compile-time half of the alias pin, which fires before any test runs:
a pointer conversion per name. The pointer form is not decoration — for the
three structs a plain assignment would do, but for the INTERFACE it would be
blind, since interface-to-interface assignment goes by method set and a
de-aliased cursor still accepts a journalops.Journal. Watched fail: the
de-aliased interface, which nothing else in the tree catches.

---------

Co-authored-by: Review Sim <ci@beads.test>
2026-08-10 10:58:05 -07:00
..
audit.go feat(storage): public backend contract + conformance suite for out-of-tree backends (bd-h3dib.2) (#5321) 2026-08-03 16:03:11 -07:00
audit_config_metadata_slots_repomtime.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
audit_dependencies_readiness.go refactor: delete the dead orphan-handling capability (bd-gwryr) (#5497) 2026-08-09 12:03:18 -07:00
audit_issue-lifecycle.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
audit_labels-comments-events.go feat(storage): public backend contract + conformance suite for out-of-tree backends (bd-h3dib.2) (#5321) 2026-08-03 16:03:11 -07:00
audit_molecule_wisp_batch_iter.go refactor: delete the dead orphan-handling capability (bd-gwryr) (#5497) 2026-08-09 12:03:18 -07:00
audit_search-counts-stats.go refactor: delete the dead orphan-handling capability (bd-gwryr) (#5497) 2026-08-09 12:03:18 -07:00
batch_apply_contract.go Add issueops.BatchApplier: one plan, one transaction (#5480) 2026-08-09 06:59:34 -07:00
batch_closer_contract.go Make the conformance obligation true: rewire the dolt_log probes, fix the doc that lied (#5449) 2026-08-08 19:55:20 -07:00
batch_creator_contract.go Migrate the batch and comment audit cases, and give Importer the contract its report justifies (#5469) 2026-08-09 02:34:17 -07:00
blocked_state.go Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436) 2026-08-08 11:23:34 -07:00
blocking_annotator_contract.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
bootstrapper_contract.go Assert exactly-one history for a comment, and state the bootstrap split per leg (#5455) 2026-08-08 22:43:13 -07:00
claim.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
claimer_contract.go fix(bd): canonicalize remaining actor==assignee comparisons in claim/heartbeat CAS (ga-v2k49) (#5479) 2026-08-09 17:19:00 -07:00
commenter_contract.go chore: retire a zombie test, drop a dead field, true up two leaf docs (#5492) 2026-08-09 10:42:34 -07:00
conformance.go test(conformance): de-stage the hard Lifecycle contracts onto the role seam (#5474) 2026-08-09 04:44:29 -07:00
counter_contract.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
cycle_detector_contract.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
deleter_contract.go Add DeleteRequest.ExpectedVersion: a compare-and-delete on the named row (#5481) 2026-08-09 07:17:54 -07:00
dependency_editor_contract.go Migrate the vocabulary and dependency audit cases, including the edge that bricks bd list (#5468) 2026-08-09 01:43:54 -07:00
edge_reader_contract.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
graph_counter_contract.go Add issueops.GraphCounter: how many edges, in one named direction (ga-itny5) (#5485) 2026-08-09 11:29:32 -07:00
history_matching.go Make the conformance obligation true: rewire the dolt_log probes, fix the doc that lied (#5449) 2026-08-08 19:55:20 -07:00
importer_contract.go Migrate the batch and comment audit cases, and give Importer the contract its report justifies (#5469) 2026-08-09 02:34:17 -07:00
issue_operations_contract.go test(conformance): de-stage the hard Lifecycle contracts onto the role seam (#5474) 2026-08-09 04:44:29 -07:00
issue_operations_staging.go test(conformance): de-stage the hard Lifecycle contracts onto the role seam (#5474) 2026-08-09 04:44:29 -07:00
journal_contract.go feat(journalops): the mutation journal becomes the third facade namespace (#5552) 2026-08-10 10:58:05 -07:00
lifecycle_close_reopen_contract.go Migrate the lifecycle and issue-operations audit cases onto fixtures that can see the difference (#5472) 2026-08-09 02:13:44 -07:00
lifecycle_create_contract.go test(conformance): de-stage the hard Lifecycle contracts onto the role seam (#5474) 2026-08-09 04:44:29 -07:00
lifecycle_update_contract.go fix(bd): canonicalize actor==assignee comparisons in unclaim.go and AuthorizeAssigneeTransferWithPools (#5439) 2026-08-09 11:35:01 -07:00
memories_contract.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
metadata_cas_contract.go Add issueops.MetadataCAS: compare-and-set over one metadata key (#5473) 2026-08-09 04:15:34 -07:00
portable.go test(conformance): pin the missing-parent child-counter skip on a real backend (bd-k4bcj) (#5505) 2026-08-09 13:44:54 -07:00
querier_contract.go Migrate the query-family audit cases into role contracts, with fixtures that can see what the old ones could not (#5448) 2026-08-08 19:13:22 -07:00
reader_contract.go feat(workapi,storage): opt-in Brief projection for the list and ready pages (#5554) 2026-08-10 10:45:23 -07:00
ready_claimer_contract.go feat(workapi,storage): opt-in Brief projection for the list and ready pages (#5554) 2026-08-10 10:45:23 -07:00
ready_counter_contract.go Migrate the claim-family audit cases into role contracts, including a lease nobody pinned (#5447) 2026-08-08 19:12:48 -07:00
reclaim_scope.go Make the conformance obligation true: rewire the dolt_log probes, fix the doc that lied (#5449) 2026-08-08 19:55:20 -07:00
relations_contract.go feat(issueops): put every issue capability behind one library surface 2026-08-04 12:27:56 -07:00
releaser_contract.go fix: a re-close that runs on_close, a silent cycle-gate walker, and a leaf that contradicts the wire (#5537) 2026-08-10 02:37:34 -07:00
role_bundle.go feat(journalops): the mutation journal becomes the third facade namespace (#5552) 2026-08-10 10:58:05 -07:00
role_bundle_cases.go feat(journalops): the mutation journal becomes the third facade namespace (#5552) 2026-08-10 10:58:05 -07:00
role_bundle_test.go RunRoleContracts: make the semantic conformance tier callable (#5456) 2026-08-08 23:47:30 -07:00
role_coverage_gate_test.go Migrate the batch and comment audit cases, and give Importer the contract its report justifies (#5469) 2026-08-09 02:34:17 -07:00
role_coverage_scan_test.go feat(journalops): the mutation journal becomes the third facade namespace (#5552) 2026-08-10 10:58:05 -07:00
search_paging.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
stats_reporter_contract.go Migrate the query-family audit cases into role contracts, with fixtures that can see what the old ones could not (#5448) 2026-08-08 19:13:22 -07:00
sweeper_contract.go Version embedded role deletes and sweeps, and replace the range that hid it (#5458) 2026-08-08 23:53:57 -07:00
tree_walker_contract.go Prune each half of a both walk before merging them 2026-08-06 21:46:53 +00:00
version_reconciler_contract.go feat(issueops): put the startup version reconciler behind the VersionReconciler role (bd-gkmft) 2026-08-05 16:35:01 +00:00
workspaceconfig_contract.go docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545) 2026-08-10 08:05:07 -07:00