Commit graph

8 commits

Author SHA1 Message Date
Julian Knutsen
d90823480a
ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414)
* ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files

//scripts:scripts_test declared //:repo_files (the whole checkout), so every
PR re-ran it, and it took ~181s on rbe-west. Most of that (60-79s) was
TestBazelGatedLanesNeverRetryFlakyTests line-regexping the --run_under
wrapper's pinned dolt binary (tools/bazel/hermetic_bin/dolt, in every
test's runfiles); it now skips binary files, as git grep -I does.

tools/bazel/go_srcs.py's per-package repo_files block now partitions each
package's files into repo_go_srcs, repo_go_test_srcs, repo_doc_files and
repo_other_files, aggregated at the root; //:repo_files is their union
(same 4679 files). The //scripts tests are split into go_test targets by
what they read (traced per test with strace over a runfiles-shaped tree):

  scripts_test          CI/Bazel policy: //:repo_other_files (+1 Go file)
  shell_scripts_test    script fixtures: //scripts files, a few root files
  go_test_sources_test  _test.go scans: //:repo_go_test_srcs + shard files
  go_sources_test       check-testing-short.sh: every .go file
  tracked_files_test    every tracked file: //:repo_files

Shared helpers move to helpers-only files; TestScriptsTestTargetsPartition-
TheTests fails on a test file in no target or in two. //test/docsync and
the //scripts/repochecks slices declare partitions or single files instead
of //:repo_files where they can.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* ci(bazel): skip only the non-checkout hermetic_bin dir in the flaky-retry walk

Skipping every binary file also stopped scanning tracked binaries (images,
.binpb fixtures). Skip just tools/bazel/hermetic_bin, the --run_under
wrapper's runfiles directory, which is not in the checkout, so the walk's
coverage of tracked files is unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-09 05:13:07 +00:00
Julian Knutsen
0500fc6f40
ci(bazel): run the scripts and source-walking tests remotely; retire their go test legs (#7320)
//scripts:scripts_test and //scripts/check-versions:check-versions_test
drop their host-tools/no-remote-exec/no-remote-cache tags and run on the
rbe-west workers like every other target (the worker image ships bash, git,
python3, jq, yq, curl, openssl, unzip and coreutils; a missing tool fails the
test under Bazel rather than skipping it). Go comes in hermetically as the
registered SDK; check-versions.sh's `go build` is stood in for by the
Bazel-built checker.

The tests that walked the source checkout now get it as data:
tools/bazel/go_srcs.py keeps a managed `repo_files` filegroup in every
package and aggregates them into //:repo_files (exactly the tracked files
Bazel can see; make bazel-sync-check fails on a package without one).
scripts_test and docsync_test take it instead of hand-listed filegroups,
and every TEST_SRCDIR/IsBazel skip and go-test-only block in them is gone.
The release formula under .bazelignore'd .beads/ comes in through a
@beads_formulas local repository; npm-package/ and .claude/ are visible to
Bazel again (only their node_modules/worktrees stay ignored), so the npm
manifest release check and the AGENTS.md skill links run under Bazel too.
TestZZStdioNotLeaked falls back to TestMain's pre-run streams instead of
skipping in a shard without its baseline.

tools/bazel/equivalence_allowlist.txt shrinks from 20 skip entries to the
two cmd/bd tests of plain go test's own bd build fallback, which Bazel never
takes; pr-preflight-platforms now runs them on Linux, macOS and Windows. The
scripts-go-checks scripts-test and allowlisted legs, their scripts
(scripts-go-test.sh, allowlisted-go-tests.sh, run_allowlisted_go_tests.py)
and main.yml's --compile-only warm for them are removed. The vet leg stays
(ga-96smfk.18).

Refs: ga-96smfk.16

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-06 22:20:16 +00:00
Julian Knutsen
f66375459f
test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828)
* test(bazel): add internal/testutil/bazeltest runfiles helpers

Repository-path resolution for tests that works identically under plain
go test (package cwd, full checkout), bazel test locally, and remote
execution (declared runfiles only):

- IsBazel, RepoRoot (BEADS_TEST_REPO_ROOT, then the runfiles workspace
  root, then a go.mod walk), OverrideRoot (drop-in condition for existing
  helpers; empty under plain go test), CallerDir
- Runfile for $(rlocationpath) values, GOROOT for type-checking tests
- ShardFreeEnv for helpers that re-exec a test binary

Every helper reduces to the pre-Bazel behavior under go test.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): declare source/data reads for 14 scan-guard targets

Source-scanning and repo-file tests read files their Bazel targets never
declared, so they failed under `bazel test` (and could not run on remote
workers at all). Declare narrow inputs as `data` and resolve paths through
bazeltest where the test located the tree via runtime.Caller:

- tools/bazel/go_srcs.py (run by `make bazel-sync` after gazelle) keeps a
  managed `go_srcs` filegroup in the packages whose Go source tests scan,
  plus `//internal/storage:tree_go_srcs` for the storage-tree walk. Bazel
  globs stop at package boundaries, so the aggregate needs one filegroup
  per package; the script keeps it in sync and gazelle-stable.
- Hand-written narrow inputs: //internal/storage/schema:migrations,
  //:docsync_files, //plugins/beads:plugin_files, and exports of
  .gitattributes, .claude-plugin/marketplace.json, cmd/bd list.go and
  ready.go, testutil/testdoltcommon.go, scripts README.md and the release
  catalog, each visible only to its consumer.
- runtime.Caller-based roots in backend, backend/conformance,
  internal/storage, internal/formula and test/docsync now go through
  bazeltest.CallerDir / OverrideRoot; relative-path tests need data only.
- integrations/ leaves .bazelignore (it is still gazelle-excluded) so the
  docsync link check can declare integrations/beads-mcp/PYPI.md.

Under --config=prcore every target reports the same PASS/SKIP/FAIL test
set as `go test -race -short` for its package, locally and remotely.
Plain `go test` behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): guard generated go_srcs and harden bazeltest root override

- tools/bazel/go_srcs.py: add --check (print diff, exit 1 on stale blocks);
  new `make bazel-sync-check` target runs it.
- scripts/bazel_policy_test.go: under go test, assert every tree_go_srcs
  (//internal/storage) lists exactly the BUILD.bazel packages below its
  root, run go_srcs.py --check, and forbid BUILD files under docs/ and
  engdocs/ (they would cut subtrees out of //:docsync_files).
- bazeltest: honor BEADS_TEST_REPO_ROOT only when it holds go.mod
  (RepoRoot fails loudly otherwise); drop the unused GOROOT() helper,
  whose compiled-in branch could never fire under rules_go.
- scripts/ci/lib/test-env.sh: unset BEADS_TEST_REPO_ROOT.
- Document the hand-listed out-of-tree link targets in //:docsync_files.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* build(bazel): re-sync BUILD files with main

Regenerated with make bazel-sync after commits that landed while the
scaffold PR was in CI (new internal/execenv, gitenv, gitignore packages
and new sources/deps).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): declare init_safety_help.go for docsync

TestInitSafetyCLIHelpCoversReCloneGotchas (#6431) reads
cmd/bd/init_safety_help.go; export it to //test/docsync only.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 08:24:08 -07:00
Julian Knutsen
57ef364501
build(bazel): side-by-side Bazel scaffold + policy tests (#6798)
* build(bazel): add side-by-side Bazel scaffold (module + gazelle)

Add a Bzlmod Bazel build alongside the Go toolchain. `go build` and
`go test` are unchanged; nothing in CI invokes Bazel yet.

- MODULE.bazel: rules_go 0.63.0, gazelle 0.53.0, Go SDK 1.26.7 (matches
  the go.mod toolchain directive), go_deps from go.mod.
- ICU policy (engdocs/ICU-POLICY.md): a go-mysql-server gazelle_override
  selects the pure-Go regex backend and excludes regex_cgo.go, and
  .bazelrc builds with --@rules_go//go/config:tags=gms_pure_go, so no
  target depends on go-icu-regex or links libicu.
- third_party/patches: three module_override patches for dolt deps that
  ship WORKSPACE-era BUILD files, adapted from the gascity project.
- .bazelrc: prcore/ci test configs (inert for now; they match pr-core's
  test selection, not yet its environment isolation) and a generic
  remote-exec config with a bounded remote timeout. Executor endpoints and
  TLS credentials come only from a gitignored .bazelrc.local/user.bazelrc
  or a CI rc outside the workspace.
- .bazelversion pins Bazel 9.2.0; .bazelignore skips separate modules,
  non-Go trees, nested agent worktrees (.claude, .worktrees) and local
  data/output dirs (.beads, .dolt, dist, .runtime, tmp), so a primary
  checkout neither builds nor gazelle-rewrites nested worktree copies.
- Gazelle-generated BUILD.bazel files for every Go package.
- Makefile: `make bazel-sync` (gazelle + bazel mod tidy).
- .gitignore: bazel-* output symlinks and machine-local rc files.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): policy tests for the Bazel configuration

Add scripts/bazel_policy_test.go, plain Go tests that run under both
`go test ./scripts` and `bazel test //scripts:scripts_test`:

- MODULE.bazel go_sdk.download version equals the go.mod toolchain.
- ICU policy: .bazelrc sets gms_pure_go for build, the go-mysql-server
  gazelle_override excludes regex_cgo.go, and the root BUILD.bazel
  carries `# gazelle:build_tags gms_pure_go`.
- .bazelversion pins an exact Bazel release.
- .bazelrc.local and user.bazelrc are gitignored (parsed from .gitignore
  and cross-checked with git check-ignore when in a checkout).
- No remote-execution endpoints or credentials in committed bazelrc-like
  files, Markdown docs or .github/**: remote/BES/TLS flags
  (--remote_executor, --remote_cache, --bes_backend, --remote_header,
  --tls_client_certificate, ...) with a literal value, with or without a
  URL scheme, and non-loopback gRPC URLs in rc/.github files. Placeholders,
  $VARIABLES, and loopback are allowed; Markdown gRPC URLs (OTel exporter
  docs) are not flagged. Skipped outside a git checkout, e.g. in the Bazel
  sandbox.

Each check is a pure function also exercised against fixtures that break
the invariant. The files the tests read are declared as data via
//:bazel_policy_files so they resolve from runfiles under Bazel.

scripts/check-build-tags.sh now treats Bazel invocations as governed by
.bazelrc: the shell command segment that invokes Bazel (split on &&, ||,
;, |, $( and backticks) is exempt from the per-line `go` tag check, while
a bare `go` in another segment of the same line is still flagged. When
any scanned file invokes Bazel (or .bazelrc exists) .bazelrc must set
--@rules_go//go/config:tags=gms_pure_go for build.
scripts/check_build_tags_test.go covers both in a temp repository.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(scripts): split bazel lines in pure bash so check-build-tags works with BSD sed

BSD sed (macOS) does not expand \n in s/// replacements, so the segment
split never happened and the Bazel-exemption tests failed on macos-latest.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(scripts): skip check-build-tags tests when bash lacks mapfile

macOS runners use /bin/bash 3.2, which has no mapfile; check-build-tags.sh
has always required bash >= 4, so the new tests are skipped there.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 03:41:02 -07:00
Julian Knutsen
9884b3dd33
chore(api): mark new exported packages experimental before v1.3.0 (#6036)
Maintainer decision D-7: the ~52k-line exported Go surface added since
v1.2.2 should not freeze as a v1 compatibility commitment at the 1.3.0
tag. backend/ and backend/conformance/ already carried a Stability
section; this adds the matching disclaimer to the other new root-level
exported packages.

Doc comments only, no behavior change.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-29 16:01:30 -07:00
Julian Knutsen
f624530287
fix(events): journal delete and cascade dep_remove rows carry the request actor; notice when reading a disabled journal (#5985) (#6061)
* fix(events): thread the request actor through the issueops delete door

`bd delete --actor A` journaled its `delete` row and every cascade
`dep_remove` row with actor='' — the #5985 finding. The actor was in hand
at the role body (DeleteInTx already passes req.Actor to the reference
rewrite) and dropped one call below it.

Widen the delete workers with an explicit `actor string` parameter, the
house style PR #5908 used for the rest of the journal (never ambient
context): DeleteResolvedSetInTx, DeleteIssue(s)InTx, deleteIssueRowInTx,
and the RecordDependencyRemovals* family. DeleteInTx passes req.Actor and
SweepInTx passes SweepRequest.Actor, so sweep deletions become attributable
for free.

The genuinely actorless system surfaces — storage.DeleteIssue(s),
Tx.DeleteIssue, the dolt wisp deletes, the source-repo wipe behind
`bd repo remove` — pass "" explicitly, which the 0066 contract reads as
system/unknown. Their comments now say why rather than claiming the
plumbing cannot carry an actor.

No storage.Storage interface change and no migration: 0066 already added
`actor VARCHAR(255) NOT NULL DEFAULT ''`.

The domain/db repository call sites keep their existing "" for now; the
next commit threads the UOW door's actor to them.

Refs #5985

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(events): thread the request actor through the domain repository delete seam

The UOW door (proxied-server `bd delete`, HTTP API deleteIssues, `bd sweep`
over a unit of work) had the actor as far down as domain.deleteMany and lost
it at the repository interface, so its `delete` and cascade `dep_remove` rows
landed with actor=''.

Widen the seam the way PR #5908 widened IssueRepository.MovePersistence, for
the same reason: an explicit trailing `actor string` on
IssueSQLRepository.Delete / DeleteByIDs and DependencySQLRepository.
DeleteAllForIDs. deleteMany passes the actor its use case was already given,
so DeleteIssue / DeleteWisp / DeleteIssues / DeleteWisps keep their surfaces
unchanged and both doors now agree.

No variadic and no default: a new caller has to say whose delete this is, or
say "" and mean it.

Refs #5985

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(events): say when the journal being read is disabled; correct the actor docs

Zero rows is indistinguishable from caught-up. A consumer polling a workspace
whose writers never enabled the journal gets a successful, empty read forever
and concludes it is up to date — the "nothing to read and no way to tell why"
trap behind the field report's "0 rows" claim, which was default-off
activation and not a write-path gap.

`bd events export` and `bd events tail` now print a one-line stderr notice when
the target workspace resolves to disabled, and still serve whatever rows exist:
exporting the ledger a now-disabled workspace recorded while it WAS enabled is
legitimate, so this is a notice and not a refusal. It is the CLI mirror of the
HTTP API's EventsJournalDisabled 409, which can refuse because it has no
historical-export case. stderr, not the JSONL stream, and the exit code is
unchanged.

The default stays off. Flipping it changes write amplification and retention
for every workspace, which is not release-branch material.

Also fixes two now-false statements about attribution — the `bd events tail`
record contract and the docs page both said deletes never carry an actor — and
documents the requirement that every WRITER workspace enable the journal, not
just the one a consumer reads.

The golden gains the delete/dep_remove attribution, regenerated deliberately.
It keeps an actorless delete alongside the attributed one: the fixture used to
be the only evidence a consumer had, and reading it as "deletes are never
attributed" would mis-resolve every delete conflict.

Refs #5985

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(events): pin delete/cascade attribution at the DB on every plumbing

Four levels, because the drop happened at a seam no single one of them can
see:

- internal/storage/dolt: a ROLE-path delete (store.Deleter(), Force, an
  explicit actor) reads back `deleter-1` on both the delete row and the
  cascade dep_remove row. The store.DeleteIssue stanza in
  TestEventsJournal_ActorAttribution keeps asserting '' and its comment now
  says WHY — that surface is the actorless system interface, so the pin is
  meaningful instead of aspirational.
- internal/storage/domain/db: the repository seam itself — Delete,
  DeleteByIDs and DeleteAllForIDs each journal under the actor they are
  handed — plus the cascade through the use case. journalRow gains Actor, so
  the existing suite can see the column at all.
- internal/storage/uow: the same promise through the unit-of-work Deleter,
  the door #5908's review caught drifting once already.
- internal/storage/embeddeddolt: a per-op matrix over the DEFAULT LOCAL
  WORKSPACE. One mutation of every journaled kind, asserted at the DB, both
  directions — every attributed op names its actor, and the only rows that
  may carry none are the derived is_blocked updates.
- cmd/bd: #5985's repro verbatim through the real binary, and the
  disabled-journal notice (present on export and tail, on stderr, absent
  when enabled).

Also corrects the two remaining "actorless delete plumbing" claims in the
journalops.Row and issueops.RecordEventInTx contract comments.

Closes #5985

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(events): fix the CLI repro's flag and read stdout where stderr now speaks

`bd delete` has no --yes; --force is what makes it a real delete rather than
a preview.

TestRoutedCreateJournalsIntoTheTargetWorkspace asserted "the launching
workspace journaled nothing" against COMBINED output, which the new
disabled-journal notice now legitimately writes to. Its subject is journal
ROWS, so it reads stdout.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-29 04:14:23 -07:00
Bee
67556264c4
feat(events-journal): record the mutating actor on every journal row (#5908)
* feat(events-journal): record the mutating actor on every journal row (bd-mbrxm)

The bd_events_journal row recorded op/ts/issue_id/payloads but never WHO
performed the mutation, so downstream attribution (e.g. same-field,
different-actor conflict detection over the journal) had nothing to key on.

- Schema: `actor VARCHAR(255) NOT NULL DEFAULT ''` on bd_events_journal, on
  both migration planes (0066 + ignored/0025) so the two-door shape converges.
- Record*InTx takes the actor explicitly (no ambient ctx) — every call site
  already sits beside an audit-event emit that has the actor in hand; thread
  that same value (incl. the UOW door's MovePersistence). Comment rows carry
  the comment's author. Blank = unattributed (derived maintenance, deletes —
  follow-up bd-zxt49 — and pre-column rows); never user attribution.
- `bd events tail/export` JSON gains an additive, omitempty `actor` field;
  the wire vocabulary is otherwise untouched (openapi spec, reference doc,
  CHANGELOG; golden regenerated deliberately).
- CLI bundle: direct-DDL override for 0066 in cliCompatibleMigrationSQL —
  dolt 2.2.0 (CI's pin) no-ops the prepared ALTER (dolthub/dolt#11345), so
  without it the parity oracle sees actor only on the runtime side. Measured:
  AllMigrationsSQL() through 2.2.0 lands bd_events_journal WITHOUT actor and
  2.3.1 WITH; with the override both land it. String assertions + a
  requireDoltColumnShape guard pin it without a Dolt binary.

Verified (enumerated): go build ./...; gofmt; go vet; migration hygiene
(BASE_SHA=07c163df0); internal/storage/schema (string test + CLI-apply test
under dolt 2.3.1 AND 2.2.0); internal/storage/domain/...; eventsjournal;
journalops; httpapi (wire-tag bijection incl. actor); storage/dolt
-run 'Journal|EventsJournal|ActorAttribution' against real dolt;
cmd/bd -run Events (golden); storage/uow -p 1 (-timeout 90m): every test green except 3
timeout-shaped reds (ConcurrentInstantiation lock-acquire, EndToEnd 30s
init-schema, PreexistingDirty docker reaper) in a /private/tmp worktree
under box load 40-68; the same 3 at origin/main in that worktree also
red, and at THIS commit in the primary clone all 3 PASS (130s) — box
flake, not the diff.

* docs(events-journal): align seq:4 example with the actorless golden fixture

Maintainer review follow-up on PR #5908 (bd-mbrxm). Both reviewers flagged that
the reference JSONL example's seq:4 is_blocked derived-maintenance row carried
"actor":"worker-1", contradicting the record-contract field table (derived
is_blocked recomputes are actorless) and the golden fixture
cmd/bd/testdata/events_journal_records.jsonl, which emits that same seq:4/bd-100
row without an actor. Drop the actor member so the doc example mirrors the
fixture byte-for-byte and consumers do not misclassify a system recompute as a
user write.

The other, optional review nit (the "stray typographic quote" in the
insertEventRow doc comment) is intentionally left as-is: that glyph is gofmt's
canonical rendering of '' in a Go 1.19+ doc comment (TeX-style quoting turns two
ASCII apostrophes into U+201D), so the reviewers' literal '' suggestion is a
no-op the enforced pre-commit gofmt reverts on every commit. It is cosmetic and
non-gating; the DDL and INSERT are already correct.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-23 13:55:59 -07:00
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