Phase 3 (R20): epoch-transition enforcement + minted-address CAS - gastownhall/beads#6136 (#6664)

* test(conformance): un-skip R16 CAS + R20 epoch tests with honest not-implemented stubs

Wires all 10 ExpectedRevisionFixture-gated Run* functions and both
EpochFixture-gated Run* functions to real (non-nil) hooks on all three
storage legs (dolt, embeddeddolt, uow), replacing the Phase 0 all-nil
fixtures that made these cases t.Skip.

Every wired hook is an unconditional "not implemented yet" stub rather
than a partial-real implementation. This is deliberate: every Run*
function under test calls its primary hook (CompareAndSetVersion, or
CurrentEpoch/MintUnderEpoch) first, before any other hook, so a stub
that errors unconditionally on that first call guarantees deterministic
RED with zero risk of an accidental pass -- a concern that's concrete,
not hypothetical, since at least one case
(RunExpectedRevisionAcceptsAWriteNamingNoVersion) would go green under
a partially-real read/unconditional-write strategy backed by Phase 1's
already-persisted current_revision/store_epoch columns.

Each case now fails for its documented reason: most via a direct
t.Fatalf quoting the stub's "not implemented" error, and two
(RefusalIsDistinguishableFromNotFound,
RefusalIsDistinguishableFromValidationFailure) via a clean want/got
mismatch against the sentinel errors they expect.

Explicitly out of scope and untouched: CrossRecordInvariantFixture
(R16.1) and the non-epoch RetentionFixture cases (R17) -- confirmed via
test run that TestRetentionContract still reports PASS with all 13
subtests SKIP on every leg.

TestEveryLegWiresEveryRoleContract (internal/storage/leg_contract_wiring_test.go)
is a source-level AST naming check independent of hook nil-ness; all 12
entrypoints were already called by every leg pre-change, so this lock
was satisfied before and remains satisfied after.

Sentinel error messages reference be-x5jqd.3 (R16 CAS implementation)
and be-x5jqd.4 (R20 epoch enforcement implementation), the two builder
children this un-skip unblocks.

Verified via go build ./..., go vet ./..., and go test -tags cgo across
all three legs: all 10 R16 + 2 R20 subtests FAIL for the documented
reason, TestRetentionContract unaffected.

Bead: be-x5jqd.1

* feat: green — Implement R20 epoch-transition enforcement (refs be-x5jqd.4)

* fix(epoch): honor R20-n's retained-mapping exception in StillServes/Resolve

StillServesInTx and ResolveEpochInTx only ever checked whether the
literal queried address's own row matched the current epoch. Per R20-n
(#5898 rev 9), a version that survives an epoch transition keeps its
prior-epoch address resolving once its id has been carried forward into
the current epoch (via CurrentAddressForInTx or a fresh
MintUnderEpochInTx) — that carried-forward row wasn't being consulted,
so a legitimately retained address would wrongly stop resolving.

Add mintedIDHasAddressAtEpochInTx and consult it as a fallback in both
functions when the queried address's own row is stale. Addresses whose
id was never carried forward are unaffected (row.mintedID has no row
at the current epoch, same false/GoneReorganization answer as before).

Round-2 response to be-rskwc's causal_disproof finding: the merge-base
commit FAILed honestly on this defect, this branch's tdd_green SKIPped
instead (attribution_evidence). This fix is real and verified via a new
sqlmock unit test (TestStillServesInTxHonorsARetainedMapping et al.),
but does not by itself flip
TestEpochContract/EpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed
from SKIP to PASS: that test's own construction mints two records
identically and never carries either forward before comparing
StillServes on both, so no backend implementation can make them differ
(escalation follows on a needs-mayor bead).

refs be-x5jqd.4, be-rskwc round 2

* test(feat): red — harden EpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed (refs be-9fiaw)

Per mayor ruling on be-9fiaw: fix the test rather than waive it. The
fixture already lets record-a survive an epoch bump by minting it again
under the new epoch; record-b, never re-minted, does not survive. That
asymmetry was previously only discovered after the fact (skip if
StillServes agreed for both addresses), which meant the case could pass
by observing either polarity. Assert the concrete expected values
instead: servesA must be true, servesB must be false. This makes the
case deterministically exercise both halves of R20-n, and closes a
latent gap where a backend with the polarity reversed could have
silently passed via the old discover-then-swap logic.

* fix(schema): renumber epoch_minted_addresses to 0070, linearizing our own slot collision (refs be-hs42e.7)

R20's epoch_minted_addresses and R7.1's removed_restriction both claimed
migration slot 0069 on parallel sibling branches. Neither contained the
other, so nothing in either branch's own CI could see the union: each was
green alone, and the second to merge would panic checkNoDuplicateVersions at
store open -- before any command's RunE, so every bd invocation bricks rather
than one package reddening. Same hazard bee reproduced for #6358 vs #6008.

This linearizes them instead of leaving it to merge order. R7.1 keeps 0069:
it is published beneath #6661 and cannot move without rewriting a branch a
reviewer is reading. R20 stops being a sibling, rebases onto R7.1, and takes
the next contiguous slot.

Contiguity is why the renumber could not be done pre-emptively in either
branch alone: TestAllMigrationsSQLAppliesThroughDoltCLIAndRecordsLatestVersion
asserts COUNT(*) == LatestVersion(), so a jump to a far slot fails until the
gap is filled. The order had to be settled first.

- migrations/0069_add_epoch_minted_addresses.{up,down}.sql -> 0070_*
- migration_0069_add_epoch_minted_addresses_test.go -> migration_0070_*, with
  TestLatestVersionIncludesMigration0069 -> ...0070 (want 70)
- 0069_add_removed_restriction_test.go retires its own LatestVersion pin in
  favour of 0070's, keeping the one-pin-at-a-time chain 0068 -> 0069 -> 0070

cli_migrations.go needs no change: its only override is R7.1's guarded
PREPARE, which keeps 0069. The epoch migration is a plain unguarded
CREATE TABLE IF NOT EXISTS and needs none.

Verified: TestEmbeddedMigrationSourcesHaveNoDuplicateVersions,
TestLatestVersionIncludesMigration0070,
TestAllMigrationsSQLAppliesThroughDoltCLIAndRecordsLatestVersion (applies the
full 0001..0070 chain through the dolt CLI),
TestBundleMigrationsWithPreparedALTERAreOverriddenOrJustified and
TestAllMigrationsSQLUsesDirectDDLForKnownCLIIncompatibilities all pass.
go build ./... and go vet ./... clean.

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

* test(feat): red — Fix PR #6664: restore R16 honest-skip (stale be-x5jqd.3 premise) + address bee's 2 blockers on epoch_cas.go (refs be-ah0jf)

* feat: green — Fix PR #6664: restore R16 honest-skip (stale be-x5jqd.3 premise) + address bee's 2 blockers on epoch_cas.go (refs be-ah0jf)

* test(feat): red — Review: Fix PR #6664: restore R16 honest-skip (stale be-x5jqd.3 premise) + address bee's 2 blockers on epoch_cas.go (refs be-yj55d)

* feat: green — Review: Fix PR #6664: restore R16 honest-skip (stale be-x5jqd.3 premise) + address bee's 2 blockers on epoch_cas.go (refs be-yj55d)

* docs(epoch): cite epoch_minted_addresses as migration 0071

Upstream's 0069_widen_issue_versions_datetime_precision (#6675) took slot
0069 first, so removed_restriction moved to 0070 and epoch_minted_addresses
to 0071. The three epoch_cas.go headers still named 0070.

Rebase note (maintainer): the migration is now 0072, per the landing-order
ruling (#6943's participation_generation is 0070 and #6661's
removed_restriction is 0071); the commit "chore(schema): renumber
epoch_minted_addresses to 0072 after #6661's 0071" updates these three
headers.

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

* test(feat): red — move #6664's Dolt server leg to post-transaction publish for store_epoch and epoch_minted_addresses (latent lost-update pattern)

Tests only. On the commit before this one they fail for these reasons:

- the server leg publishes store_epoch / epoch_minted_addresses inside the open
  SQL transaction (DOLT_ADD before COMMIT) for BumpEpoch, MintUnderEpoch and
  CurrentAddressFor: the lost-update hazard documented on doltAddAndCommitInTx
- MintUnderEpoch and CurrentAddressFor stage only epoch_minted_addresses, so the
  first mint leaves store_epoch modified in the working set, on both legs
  (#6664 Major 2, reproduced with Status() on a real server and embedded)
- BumpEpoch must surface a Dolt commit that fails after its SQL commit, while
  the mint paths keep their rows
- ensureStoreEpochRow seeds with INSERT IGNORE and reads the row back

TestMintOverlappingABumpCommitsAnAddressThatIsAlreadyGone characterizes current
behaviour and passes now: a mint overlapping a bump commits an address the bump
already voided. Its doc comment records why that is left as it is.

* feat: green — move #6664's Dolt server leg to post-transaction publish for store_epoch and epoch_minted_addresses (latent lost-update pattern)

Server leg (internal/storage/dolt/epoch_cas.go): BumpEpoch, MintUnderEpoch and
CurrentAddressFor no longer stage and Dolt-commit inside the open SQL
transaction. The two mint paths publish through runIssueOperationTxWithMessage,
which commits the SQL transaction first. BumpEpoch commits it, then publishes
with doltAddAndCommitPostTx and RETURNS a failed Dolt commit: a bump that is
committed but unpublished must not read as success.

Both legs: a mint stages store_epoch with epoch_minted_addresses, because the
first mint inserts the singleton row (#6664 Major 2). The set lives in
issueops.EpochMintDirtyTables so the legs cannot drift from what the body writes.

issueops: ensureStoreEpochRow seeds with INSERT IGNORE and reads the row back,
as version_history.go does for the same row.

Not changed, on purpose: a mint overlapping a concurrent bump can still commit an
address the bump already voided. Dolt has no lock for it and the only conflicting
write would overwrite bumped_at/bumped_reason; see the doc comment on
TestMintOverlappingABumpCommitsAnAddressThatIsAlreadyGone. One comment in that
test file is reworded; no test logic changed since the red commit.

* chore(bazel): bazel-sync (gazelle) for the two new epoch test files

Only the two go_test srcs entries for the test files this branch adds:
epoch_cas_publish_test.go (dolt) and epoch_cas_status_test.go (embeddeddolt).
gazelle wanted nothing else for them (no deps change).

* test(conformance): add the optional EpochFixture.LoseVersion capability

Record survival explicitly instead of inferring it (gastownhall/beads#6664,
review 5360880888, Major 1). Once an address stays served unless its own row
says the store lost it, the only way for the contract to produce a Gone
address is an explicit loss, so the contract needs a way to say "the store
lost this Version".

LoseVersion is additive and optional: no existing field changes signature,
and a nil LoseVersion makes the cases that need one skip with a named reason.
It is its own commit so that it can be judged, or replaced, on its own: the
same semantics could ride on BumpEpoch taking a lost set, and only the
plumbing would differ. Nothing uses it yet.

* chore(epoch): add signature-only stubs for the survival rework

The tests that follow exercise BumpEpochCarryingInTx, LoseVersionInTx,
ErrEpochAddressNotServed and the BumpEpochCarrying and LoseVersion store
methods (gastownhall/beads#6664, review 5360880888). Stubs give those names
so the tree builds and the tests fail for their real, behavioural reasons
instead of failing to compile.

No logic: ErrEpochAddressNotServed is a sentinel, BumpEpochCarrying advances
the counter exactly as BumpEpoch does and carries nothing, and LoseVersion
returns "not implemented". The next commit adds the tests; the one after
replaces these bodies.

* test(feat): red — record survival explicitly in epoch_minted_addresses, make CurrentAddressFor read-only, carry on a token-scheme change

Tests for the survival rework of gastownhall/beads#6664 (review 5360880888:
Major 1, Minors 3 and 4). Every test is written before any production change.

- Contract: the earlier mint-driven R20-n case is restated as three named
  phases (a survivor and a lost Version, loss is terminal, survival needs no
  upkeep), plus three new cases for a token-scheme change (carry the live
  lineages and only those, a carried address keeps resolving across later
  bumps, a lost address stays Gone across a scheme change). All three legs
  register them and wire LoseVersion and the carrying bump.
- Shared body: unit tests for the row-based resolver (exactly the address's
  row and the epoch, fail closed on a row from a future epoch), a read-only
  CurrentAddressFor with typed errors, LoseVersion, a bump that writes only
  store_epoch, a mint that never hands back a lost address, and the
  per-database counter (Minor 3). Minor 4 gets a guard that no address in the
  test file is written by hand.
- Real engine: the carry on the embedded leg (one carry row per live id, the
  lineage root, the collision rule, a row from a future epoch, a rewound
  counter, database-wide, lost lineages), the publication sets of every
  writer, and on the server leg the overlap of a mint with a bump (now a Live
  survivor) and a deterministic mint-after-loss interleaving that must not
  revive the lost address.
- Migration 0071 byte pin and a real-dolt shape check for carried_from,
  gone_at_epoch, the carried_from index and the gone-not-before-mint CHECK.

These fail on the current code, and some do not build yet because
BumpEpochCarryingInTx, LoseVersionInTx, ErrEpochAddressNotServed and the store
methods they exercise do not exist.

* feat: green — record survival explicitly in epoch_minted_addresses, make CurrentAddressFor read-only, carry on a token-scheme change

The survival rework of gastownhall/beads#6664 (review 5360880888: Major 1,
Minors 3 and 4). An address's status is now a function of its own row and the
current epoch, never inferred from other rows.

- Migration 0071 (edited in place; no new slot, no ALTER): the table gains
  carried_from, gone_at_epoch, an index on carried_from and a CHECK that a loss
  epoch is not before the mint epoch.
- Shared body: Live unless gone_at_epoch is set, and a row from an epoch that
  has not happened yet fails closed; the chain query is deleted. CurrentAddressFor
  only reads and returns typed errors. LoseVersion marks a whole lineage lost,
  once, guarded by gone_at_epoch IS NULL. BumpEpochCarrying (token-scheme change)
  writes one carry row per live lineage naming the lineage root, resolves a
  shared-id collision by carrying the newest and losing the rest, and fails if a
  row already sits at the new epoch. A mint only inserts its own root row and
  never hands back an address that is not served. A restore or reinit bump
  still writes only store_epoch.
- Both Dolt legs: BumpEpochCarrying publishes store_epoch and
  epoch_minted_addresses, LoseVersion publishes epoch_minted_addresses and
  returns a failed publication, and CurrentAddressFor runs on the read path and
  publishes nothing. The per-database epoch counter (Minor 3) and the
  requirement that a caller of the carrying bump hold the workspace gate
  exclusively are documented where they apply.

One change to tests written in the previous commit: the three real-server
publication probes that only need a clean working set now open a database of
their own, as the overlap tests do, instead of queueing on the shared test
database's schema-init lock. Its five-second acquire timeout ran out under load
and failed two of them; no assertion changed.

* test(dolt): run the epoch contract on a database of its own

TestEpochContract set up through setupTestStore, which puts every parallel
test on the shared test database and queues their schema initialization on one
lock with a five-second acquire timeout. Under host load a setup that waits
behind another parallel test's runs out of it and fails at its first line with
"schema migration lock unavailable: timeout". That failed the unchanged
first-mint test twice in the dolt lane once this change had added tests to it,
and the contract's own setup is exposed to the same timeout.

The contract now opens a database of its own, the way the overlap tests and the
publication probes already do, so this change adds no contention on the shared
database's lock. No assertion changed.

* docs: replace internal tracker ids in the epoch comments and test names with plain descriptions

Comment and text edits only; no behavior changes and no line is added or
removed (21 lines are replaced one for one). Each replaced line named an
internal tracker id in a header, a test comment, a failure message or the
migration header; it now says what it meant in plain words or cites the
upstream issue or pull request. The EpochFixture API lines and the already
published commit messages are left as they were.

* ci: list this PR's embedded storage tests in the embedded shard manifest

#7156 made the embedded-Dolt tier's shard manifests exact-once (50 cmd
shards, 15 storage shards), so every embedded test must be listed. This PR
adds eleven embedded storage tests and no embedded cmd tests; this commit is
exactly what the generators write for them:

  python3 scripts/ci/gen_embedded_cmd_shard_manifest.py 50 --weights=duration --write
  python3 scripts/ci/gen_embedded_storage_shard_manifest.py 15 --weights=duration --write

Incremental: 11 lines added, none moved; the cmd manifest is unchanged.

Rebase note (maintainer): regenerated on current main, whose embedded storage
manifest uses a 40-shard block; the generator's incremental output placed
these tests at shards 7, 9, 11, 20, 21, 28, 31, 32, 33, 34 and 36 of 40, one
test per shard (gen_embedded_storage_shard_manifest.py 40 --weights=duration
--write; --check passes).

* chore(bazel): bazel-sync for the epoch sources and migration 0071

The BUILD files did not list epoch_cas.go in the dolt, embeddeddolt and
issueops libraries, issueops' epoch_cas_test.go, or migration 0071 and its
test, so Bazel could not compile those packages' tests. This is exactly the
patch make bazel-sync writes (gazelle plus go_srcs.py; the PR's BUILD-sync
CI step printed it): 4 files, 6 lines, nothing else.

Rebase note (maintainer): the migration is now 0072, per the landing-order
ruling (#6943's participation_generation is 0070 and #6661's
removed_restriction is 0071); the commit "chore(schema): renumber
epoch_minted_addresses to 0072 after #6661's 0071" renames these BUILD
entries. On the rebased base, this commit's internal/storage/schema/BUILD.bazel
hunk is merged with the base's 0070 and 0071 entries.

* chore(schema): renumber epoch_minted_addresses to 0072 after #6661's 0071

Migrations are numbered by landing order. #6943 (participation_generation,
the versioned-history write fence) owns main-plane 0070 and #6661
(removed_restriction) owns 0071, so this PR's epoch_minted_addresses
migration moves to the next free slot, 0072. The rename is done here, as one
maintainer commit, rather than inside the replayed commits, so the history
shows exactly what changed relative to the PR as reviewed.

- migrations/0071_add_epoch_minted_addresses.{up,down}.sql become 0072_*.
  Neither header names its own number, so the SQL and its comments are
  unchanged. Neither file exists on main, #6943 or #6661, so this is not an
  edit to a shipped migration.
- cli_migrations.go needs nothing: the migration is a plain CREATE TABLE IF
  NOT EXISTS with no CLI-bundle override.
- migration_0071_add_epoch_minted_addresses_test.go becomes
  migration_0072_add_epoch_minted_addresses_test.go; its consts, tests and
  messages say 0072, it owns the one LatestVersion pin (72), and its slot
  history now records the move past #6943's 0070.
  TestLatestVersionIncludesMigration0071 in #6661's removed_restriction test
  was already retired to a pointer comment by the rebase's resolution of
  "renumber epoch_minted_addresses to 0070"; that comment now names
  TestLatestVersionIncludesMigration0072 and its file.
- BUILD.bazel embedsrcs/srcs, and the three epoch_cas.go headers (dolt,
  embeddeddolt, issueops) that cite the migration number.

The intermediate commits of the rebase are not expected to build, for two
reasons:

- a duplicate migration version: the PR's epoch_minted_addresses migration
  shares 0069 with main's 0069_widen_issue_versions_datetime_precision until
  the PR's own "renumber epoch_minted_addresses to 0070", and from there
  shares 0071 with #6661's removed_restriction until this commit;
- a helper-name collision: from the PR's "feat: green — Fix PR #6664: restore
  R16 honest-skip ... (refs be-ah0jf)" on, internal/storage/issueops declares
  readStoreEpochInTx twice, once in #6943's version_history.go and once in
  this PR's epoch_cas.go, until "fix(epoch): rename #6664's read-only
  store_epoch read past #6943's readStoreEpochInTx" later in this stack.

This commit ends the duplicate version, but it still does not compile on its
own because of the collision; the stack builds from the rename commit on.

Checked at the tip of the stack, where the rename has landed: go test
./internal/storage/schema/... with the dolt CLI lane
(including TestAllMigrationsSQLAppliesThroughDoltCLIAndRecordsLatestVersion
and TestMigration0072RecordsSurvivalInTheAddressTableThroughDoltCLI), and
scripts/check-migration-hygiene.sh with BASE_SHA=origin/main and
BASE_SHA=vh/6661-rebase.

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

* test(epoch): waive #6664's three new epoch contracts on main's http leg

main gained an HTTP storage leg (#7247) after this PR's base, and
TestEveryLegWiresEveryRoleContract requires every leg to name or waive every
role contract. This PR adds three EpochFixture cases
(RunTokenSchemeChangeCarriesLiveAddressesAndOnlyThose,
RunACarriedAddressKeepsResolvingAcrossLaterBumps and
RunALostAddressStaysGoneAcrossASchemeChange); dolt, embeddeddolt and uow wire
them, and the http leg did not name them.

They are waived on the http leg with the existing
retentionEpochNoRoleWaiverReason, which already covers every other
RetentionFixture/EpochFixture case there: EpochFixture is raw storage hooks
(CurrentEpoch, BumpEpoch, MintUnderEpoch, StillServes, Resolve,
CurrentAddressFor, LoseVersion) with no publicops role behind them,
and internal/httpclient is a remote client with no epoch counter or address
table of its own. The constant's doc comment now counts eighteen cases.

Test-only; no production code changes. After this, the http leg's only
unnamed entrypoints are #6943's seven RunParticipationGeneration* contracts,
whose waivers belong to #6943.

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

* fix(epoch): rename #6664's read-only store_epoch read past #6943's readStoreEpochInTx

#6943's "a create stamps participation even when the row is flagged
no-history" (7c00d65fa6) adds readStoreEpochInTx to version_history.go: the
mint's read of store_epoch, which SEEDS the singleton row when it is absent.
This PR's epoch_cas.go already declared a readStoreEpochInTx of its own, so
the package stopped compiling once #6664 was stacked on that commit.

The two cannot be folded into one. This PR's helper is deliberately
read-only: an absent row answers epoch 1 without writing, so
CurrentEpochInTx, StillServesInTx, ResolveEpochInTx, CurrentAddressForInTx and
LoseVersionInTx never write from a read (review item B4, pinned by
TestCurrentAddressForNeverReseedsAnAbsentStoreEpochRow and
TestCurrentAddressForWritesAndPublishesNothing). Calling #6943's seeding read
from those paths would break that.

So #6664's helper becomes readStoreEpochWithoutSeedingInTx, and its doc
comment says why it is not readStoreEpochInTx. The five call sites and the
ensureStoreEpochRow comment that names it follow. No behavior changes on
either side: #6943's mint path keeps its seeding read, and this PR's read-only
paths keep theirs. (ensureStoreEpochRow, which BumpEpochInTx and
MintUnderEpochInTx use, now has the same body as #6943's readStoreEpochInTx;
it is left as it is rather than folded in here.)

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

* test(storage): say exactly why the retention and epoch contracts stay waived on http

All but four of the participation-generation contracts (#6943's write
fence) now run over the served wire
(internal/httpclient/served_participation_generation_test.go): their subject
is a create or an update, which the client can send, and the fixture reads
the reference store's raw columns. The four stay waived, because the
mutation each needs has no form on the wire. This checked whether the
eighteen RetentionFixture/EpochFixture cases waived on the http leg,
including the three this PR adds, can be wired the same way. They cannot,
cheaply or otherwise, without a new wire operation:

- every EpochFixture hook (CurrentEpoch, BumpEpoch, MintUnderEpoch,
  StillServes, Resolve, CurrentAddressFor, LoseVersion) is the operation
  under test, not a seed or a raw read. Those operations are methods on the
  concrete *DoltStore and *EmbeddedDoltStore over issueops' *InTx bodies, on
  no storage interface, no publicops role and no wire operation. Every call
  path into them starts in a test: the methods are called only from each
  store leg's own _test.go files (its EpochFixture, which the conformance
  contracts drive, and its epoch tests), and the *InTx bodies only from those
  methods, from each other and from tests (the uow leg's fixture through a
  test-only type assertion, and issueops' and the dolt leg's own tests). No
  command, role or server handler reaches them, so no client mutation
  touches epoch state either;
- RetentionFixture's hooks (Resolve, Remove, Hold, ForceRemove, Erase, Mint)
  are implemented by no backend yet (every store leg wires them nil and its
  cases skip), and the wire has no removal, hold, erasure or gone/unknown
  resolve to bind them to.

Binding the epoch hooks to the reference store behind the served env would
pass, but as a property of that store, which the store legs already pin,
never of the client. So the waivers stay; retentionEpochNoRoleWaiverReason's
comment and reason string now say the above, in the shape #6661 gave
asOfReadNoHTTPWireWaiverReason, instead of the earlier general "raw storage
hooks with no publicops role" wording.

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

* fix(epoch): report applied-but-unpublished epoch writes as indeterminate, bound address length, verify dup-key mints

Maintainer fixup for the #6664 review (adopt-pr attempt 1, iteration 1).

Major 1, applied writes reported as failed. An epoch writer whose SQL
commit has landed, or may have, now wraps storage.ErrCommitIndeterminate
on both legs and hands back what it applied, so nothing replays a bump
that has already advanced the counter:
- embedded BumpEpoch and BumpEpochCarrying return the new epoch with the
  error (failedBump), and MintUnderEpoch its address;
- server bumps wrap the sentinel on every Dolt failure after the SQL
  commit, including a failed staged-set read (unpublishedBump), and so
  does LoseVersion; an indeterminate SQL commit returns the epoch or
  address it may have committed, and a definite (typed MySQL) commit
  error returns neither.
Tests: TestEpochWritesReportAnUnpublishedCommitAsIndeterminate (new,
embedded, through an afterSQLCommit seam in runTransactionWithMessage);
on the server leg TestEpochWritesMarkAFailedStagedReadIndeterminate,
TestEpochWritesReturnWhatAnIndeterminateSQLCommitMayHaveApplied and
TestEpochWritesReturnNothingWhenTheSQLCommitFailsDefinitely, and the
sentinel asserted in every publication-failure test.

Major 2, address overflow. MintUnderEpochInTx refuses a pair whose
address would outgrow epoch_minted_addresses.address (VARCHAR(255)) at
the widest epoch the counter can reach, with a typed
ErrEpochAddressTooLong, so a carry can never fail on a lineage that
gained an epoch digit.

Major 3, duplicate-key mint. A duplicate key from the mint's INSERT is
no longer success: the row is read again and the mint stands only if
this transaction sees it served; a Gone row fails the mint with
ErrEpochAddressNotServed, an unreadable one with the duplicate-key
error. Measured on dolt-sql-server 2.2.0, the stale-snapshot INSERT does
not report a duplicate key at all: its COMMIT fails with Error 1213 and
the retried mint answers ErrEpochAddressNotServed
(TestAMintRacingTheMintAndLossOfItsAddressConflictsAtCommit).

Minors:
- absent store_epoch row: sqlmock cases pin that CurrentEpoch,
  StillServes, Resolve, CurrentAddressFor and LoseVersion never seed it;
  switching any of the five to the seeding reader now fails the test;
- the server publication tests mint their address instead of writing it
  by hand, and TestEpochCASTestsBuildEveryAddressWithEpochAddress scans
  that file too (issueops_test gains //internal/storage/dolt:go_srcs as
  data);
- stale text: the duplicate-key and carry comments, the issueops
  header's CompareAndSetVersionInTx citation, the embedded header's
  parity claim, and the 0072 header's "upserts the same row" (0072 is
  past the frozen floor).

Declined, for the owner:
- a scheme-change carry voids an older live lineage re-minted after a
  restore: rule (a), document and pin it, or rule (b), resolve the loser
  to the winner's carry, is a design call about R20-n, not a review fix;
- the uow epoch fixtures' in-transaction DOLT_COMMIT('-Am'): test-only
  fixtures with no production caller; routing them through RunTxScoped
  is follow-up work.

Validation: go build ./...; go vet; nogo (bazel --config=nogo) on
issueops, dolt and embeddeddolt; issueops epoch tests; the dolt epoch
tests against a real dolt-sql-server (56 pass) and the fake-backed
publication tests; embedded epoch tests with BEADS_TEST_EMBEDDED_DOLT=1;
uow epoch contract; the schema package; the address guard under bazel
in the local sandbox. All 14 overlay mutants of the fixes are killed.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Jim Wordelman <mayor@quad341.uk>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
This commit is contained in:
Jim Wordelman 2026-10-18 21:20:57 +00:00 • committed by GitHub
commit 5c9c02ab77
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
26 changed files with 5131 additions and 130 deletions

View file

@ -205,6 +205,7 @@
40 7 TestEmbeddedIssueOperationsUpdateMetadataReplaceClearsAndValidates
40 7 TestEmbeddedLenientOpenWarning_DataBehind
40 7 TestEmbeddedRelationsLeavesTheCallersRequestAlone
40 7 TestLoseVersionLeavesTheEpochTablesCommitted
40 7 TestMergeAndSettleWithStrategy_ResolvesDeclinedConflict
40 8 TestDeleterContract
@ -217,6 +218,7 @@
40 8 TestGetIssueCommentsPageEmbedded
40 8 TestListWisps
40 9 TestBumpEpochCarryingNeitherCarriesNorServesARowFromAFutureEpoch
40 9 TestEmbeddedDependencyEditorRefusesCrossPlaneCycle
40 9 TestEmbeddedDependencyEditorSameTypeReAddIsIdempotent
40 9 TestEmbeddedDependencyEditorSnapshotsTheRequest
@ -237,6 +239,7 @@
40 10 TestRunInTransactionPostCommitStageFailureIsIndeterminate
40 10 TestWithPeerAuth_WarnsWhenStoredPeerSuppressesAmbientPasswordAmbient
40 11 TestABumpUnderOneStoreIDMovesTheEpochSeenThroughEveryStoreID
40 11 TestEmbeddedBatchCreateFirstVersionCarriesCreationTimeEdges
40 11 TestEmbeddedClaimerRefusalMessagesCarryTheirFragments
40 11 TestEmbeddedGuardedUpdateMintsOnceAfterItsPatches
@ -338,6 +341,7 @@
40 19 TestRemoteVerbsPresentStoredPeerCredentials
40 19 TestRenameLabelMintsOneVersionPerTouchedBead
40 20 TestBumpEpochCarryingCarriesOnlyTheLineageHoldingTheNewestRow
40 20 TestCreateIssue
40 20 TestEmbeddedCheckedWrappersRouteTheirPreconditions
40 20 TestEmbeddedIssueOperationsCreateRoutesInfraTypesToWisps
@ -349,6 +353,7 @@
40 20 TestHeartbeatRejectsWispEmbedded
40 20 TestIgnoredCursorHealNeverResurrectsRolledBackVersions
40 21 TestBumpEpochCarryingCarriesTheLiveRowsOfEveryStoreInTheDatabase
40 21 TestCreateRejectsCrossTableIDCollision
40 21 TestEmbeddedBatchCloserItemsAnswerToTheCloseGuards
40 21 TestEmbeddedDependencyEditorAcceptsATypeOutsideTheConstants
@ -435,6 +440,7 @@
40 27 TestRemoteGitDataRefOnEngine
40 27 TestSweeperContract
40 28 TestBumpEpochCarryingDoesNotCarryALostLineage
40 28 TestEmbeddedBatchCloserForceBypassesOnlyClosePolicy
40 28 TestEmbeddedBatchCloserSettlesTheDependersOfWhatItClosed
40 28 TestEmbeddedClaimerClaimsAnUnassignedOpenIssueAndAnswersTheBareRow
@ -472,6 +478,7 @@
40 30 TestLegacyTrackedIgnoredCursorUnwedgesPull
40 30 TestUpdateMergeOps_DoltEngine_TwoIssues
40 31 TestBumpEpochCarryingWritesOneCarryRowPerLiveIDNamingTheLineageRoot
40 31 TestDualWriteContract
40 31 TestEmbeddedDependencyEditorAcceptsAForeignRepoTarget
40 31 TestEmbeddedDependencyEditorMaintainsBlockedStateAcrossPlanes
@ -484,6 +491,7 @@
40 31 TestReadyCounterContract
40 31 TestWithPeerAuth_KeyMismatchFailsClosed
40 32 TestCurrentAddressForNeverReseedsAnAbsentStoreEpochRow
40 32 TestEmbeddedClaimerGrantsALiveLeaseOnTheRowItWonAndLeavesARefusedOneAlone
40 32 TestEmbeddedDependencyEditorRefusesAMissingLocalTarget
40 32 TestEmbeddedDirtyTablesGate_BlocksReopenThenWorkingSetReconcileRecovers
@ -504,11 +512,13 @@
40 33 TestEmbeddedRelationsResolvesTheAnchorIDExactly
40 33 TestEmbeddedSyncCommitsConfigBeforeMerge
40 33 TestEventsAutoPruneThrottleSkipsTheSecondPass
40 33 TestFirstMintLeavesTheEpochTablesCommitted
40 33 TestGetDependentRecordsEmbedded
40 33 TestPruneEventsBatchDeletesTheLowestSeqsOnly
40 33 TestTreeWalkerContract
40 34 TestAddLabel
40 34 TestBumpEpochCarryingLeavesTheEpochTablesCommitted
40 34 TestDecryptPassword_KeyMismatchNamesTheLocalKey
40 34 TestEmbeddedBlockedRecheckRecordsUnblockingWrites
40 34 TestEmbeddedDependencyEditorAttributesItsEventsToTheActor
@ -532,6 +542,7 @@
40 35 TestReadyWorkWithMissingDeferredParentTables
40 35 TestReclaimExpiredLeaseSurvivesRestartEmbedded
40 36 TestBumpEpochCarryingFailsAndRollsBackWhenARowAlreadyExistsAtTheNewEpoch
40 36 TestCommenterContract
40 36 TestConcurrentOpenReturnsCached
40 36 TestEmbeddedBatchCloserAllRefusedBatchRecordsNoHistory
@ -554,6 +565,7 @@
40 37 TestEmbeddedMergeAndSettleReportsOperatorConflicts
40 37 TestEmbeddedReaderListBriefDropsTheFreeFormTextAndNothingElse
40 37 TestEmbeddedReaderListNaturalNumericIDSortTrimsAfterTheFetch
40 37 TestEpochWritesReportAnUnpublishedCommitAsIndeterminate
40 37 TestIgnoredCursorHealRespectsOverrideUnderBroaderPattern
40 38 TestCreateIssues

View file

@ -769,7 +769,21 @@ type EpochFixture struct {
// Version now resolves to under the new epoch. A nil hook means this
// backend cannot report that, and the case that needs it skips with
// that reason.
//
// It only reads: it mints nothing and changes no state. It returns the
// address it was given when nothing carried the Version to a new one,
// and an error for an address the store does not serve.
CurrentAddressFor func(ctx context.Context, storeID string, oldAddress Address) (Address, error)
// LoseVersion records that storeID no longer serves the Version named by
// address. That address, and every address the same Version was carried
// to or from by a token-scheme change, resolves GoneReorganization from
// then on, in every later epoch: an epoch voids what the store lost,
// never what it still serves (R20-n). It is idempotent, never revives
// anything, and returns an error for an address storeID never minted. A
// nil LoseVersion means this backend cannot record a loss, and the cases
// that need one skip with that reason.
LoseVersion func(ctx context.Context, storeID string, address Address) error
}
// RunAnEpochBumpIsTriggeredOnlyByRestoreReinitOrSchemeChange pins R20-m: a
@ -819,94 +833,258 @@ func RunAnEpochBumpIsTriggeredOnlyByRestoreReinitOrSchemeChange(t *testing.T, ct
// RunEpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed pins R20-n — "Rev7
// tightening... the clause most likely to be gotten wrong" in the
// architecture doc's own words. A prior-epoch Address goes
// GoneReorganization UNLESS the backend still serves that Version, in which
// case it must stay Live AND additionally report the Address it now
// resolves to under the new epoch.
// architecture doc's own words: an epoch voids what the store lost, never
// what it still serves.
//
// StillServes is an ORACLE here, not a control: this case cannot make a real
// backend keep serving one address and drop another, since Phase 0 wires no
// real backend. It asks StillServes what the fixture (once real) decided,
// and checks the rest of the contract's promise against that decision for
// both outcomes.
// Survival is RECORDED, never inferred (gastownhall/beads#6664, bee-ghosttrack
// review 5360880888, Major 1). An earlier form of this case made a Version
// survive by minting it again in every later epoch, and treated a Version
// nobody minted again as lost. That reads loss off the absence of a mint, so
// it could not express a Version the store lost after minting it, and it
// voided every survivor that nobody happened to mint again. Here a restore or
// a destructive reinit leaves every address row alone: an address the store
// still serves stays Live at its own address with no upkeep, and the only way
// an address goes Gone is LoseVersion saying so.
//
// Each phase is a named subtest, so a backend that cannot record a loss skips
// only the phases that need LoseVersion, and a failure names its phase.
func RunEpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed(t *testing.T, ctx context.Context, fixture EpochFixture) {
t.Helper()
if fixture.MintUnderEpoch == nil {
t.Skip("this backend has no way to mint a Version under a known epoch (MintUnderEpoch is nil)")
}
if fixture.BumpEpoch == nil {
t.Skip("this backend has no epoch concept yet (BumpEpoch is nil)")
}
if fixture.StillServes == nil {
t.Skip("this backend cannot report whether it still serves a prior-epoch Version (StillServes is nil)")
}
if fixture.Resolve == nil {
t.Skip("this backend does not yet report retention state (Resolve is nil)")
}
if fixture.CurrentAddressFor == nil {
t.Skip("this backend cannot report a still-served Version's new Address (CurrentAddressFor is nil)")
}
store := epochStore(fixture, "voids")
epochSkipUnlessReady(t, fixture, false)
addrA, err := fixture.MintUnderEpoch(ctx, store, "record-a")
if err != nil {
t.Fatalf("MintUnderEpoch(record-a): %v", err)
// survivor-and-lost: of two Versions minted before a transition, the one
// the store loses goes Gone and the other stays Live at the address it
// already had, with no re-mint, for both triggers that leave addresses
// alone.
t.Run("survivor-and-lost", func(t *testing.T) {
if fixture.LoseVersion == nil {
t.Skip(epochLoseVersionSkip)
}
for _, trigger := range []EpochBumpTrigger{EpochBumpTriggerRestore, EpochBumpTriggerDestructiveReinit} {
t.Run(trigger.String(), func(t *testing.T) {
store := epochStore(fixture, "survivor-"+trigger.String())
addrA := epochMintAddress(t, ctx, fixture, store, "record-a")
addrB := epochMintAddress(t, ctx, fixture, store, "record-b")
newEpoch := epochBumpTo(t, ctx, fixture, store, trigger)
epochLoseAddress(t, ctx, fixture, store, addrB)
epochRequireLive(t, ctx, fixture, store, addrA, newEpoch,
"record-a was never lost, so the transition leaves it served at its own address with no re-mint (R20-n's exception)")
epochRequireGone(t, ctx, fixture, store, addrB, newEpoch,
"record-b was lost, so the transition voids it (R20-n)")
current := epochCurrentAddress(t, ctx, fixture, store, addrA)
epochRequireLive(t, ctx, fixture, store, current, newEpoch,
"the address CurrentAddressFor reports for a survivor must be served")
epochRequireLive(t, ctx, fixture, store, addrA, newEpoch,
"asking CurrentAddressFor must not retire or move the survivor's address")
if lostCurrent, err := fixture.CurrentAddressFor(ctx, store, addrB); err == nil {
t.Errorf("CurrentAddressFor(a lost address) = %s with no error, want an error: a lost Version has no current address", lostCurrent)
}
epochRequireGone(t, ctx, fixture, store, addrB, newEpoch,
"CurrentAddressFor on a lost address must not bring it back")
})
}
})
// gone-is-terminal: once an address is lost it stays lost. A later mint of
// the same id starts a new lineage under a new address, and neither that
// mint nor CurrentAddressFor revives the lost one (bee-ghosttrack's
// assertion for Major 1: a read-only lookup must not mint a replacement
// that makes a lost address look served).
t.Run("gone-is-terminal", func(t *testing.T) {
if fixture.LoseVersion == nil {
t.Skip(epochLoseVersionSkip)
}
store := epochStore(fixture, "terminal")
lost := epochMintAddress(t, ctx, fixture, store, "record-g")
epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerRestore)
epochLoseAddress(t, ctx, fixture, store, lost)
laterEpoch := epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerRestore)
fresh := epochMintAddress(t, ctx, fixture, store, "record-g")
if fresh == lost {
t.Fatalf("MintUnderEpoch(record-g) returned %s, the address already lost: a lost address is never handed out again", lost)
}
epochRequireLive(t, ctx, fixture, store, fresh, laterEpoch,
"a fresh mint of the id is a new lineage and is served")
epochRequireGone(t, ctx, fixture, store, lost, laterEpoch,
"a later mint of the same id must not revive a lost address")
if replacement, err := fixture.CurrentAddressFor(ctx, store, lost); err == nil {
t.Errorf("CurrentAddressFor(a lost address) = %s with no error, want an error: asking where a lost address resolves must not mint a replacement", replacement)
}
epochRequireGone(t, ctx, fixture, store, lost, laterEpoch,
"CurrentAddressFor on a lost address must not revive it")
// Losing it a second time is a no-op that leaves the fresh lineage
// alone.
epochLoseAddress(t, ctx, fixture, store, lost)
epochRequireLive(t, ctx, fixture, store, fresh, laterEpoch,
"losing the old address again must leave the fresh lineage served")
})
// survival-needs-no-upkeep: with nothing lost, an address stays Live across
// any number of counter-only transitions without being minted again, and a
// later mint of the same id neither retires it nor revives anything. This
// is the phase the earlier, mint-driven form failed: it answered Gone for
// every survivor nobody minted again.
t.Run("survival-needs-no-upkeep", func(t *testing.T) {
store := epochStore(fixture, "upkeep")
kept := epochMintAddress(t, ctx, fixture, store, "record-c")
epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerRestore)
epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerDestructiveReinit)
finalEpoch := epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerRestore)
epochRequireLive(t, ctx, fixture, store, kept, finalEpoch,
"nothing was lost, so three counter-only transitions leave the address served without a re-mint")
fresh := epochMintAddress(t, ctx, fixture, store, "record-c")
if fresh == kept {
t.Fatalf("MintUnderEpoch(record-c) returned %s again after three bumps, want a new address for the new epoch", kept)
}
epochRequireLive(t, ctx, fixture, store, kept, finalEpoch,
"a later mint of the same id must not retire a served address")
epochRequireLive(t, ctx, fixture, store, fresh, finalEpoch,
"the fresh mint is served")
current := epochCurrentAddress(t, ctx, fixture, store, kept)
epochRequireLive(t, ctx, fixture, store, current, finalEpoch,
"the current address of a survivor must be served")
epochRequireLive(t, ctx, fixture, store, kept, finalEpoch,
"asking for the current address must not change the survivor")
})
}
// RunTokenSchemeChangeCarriesLiveAddressesAndOnlyThose pins R20-n's retained
// mapping for the one trigger that changes how addresses are encoded. A
// token-scheme-change bump gives every Version the store still serves a new
// address under the new epoch and keeps the old address resolving, so a holder
// of the old address is neither stranded nor pointed at something else. A
// Version the store already lost gets no new address and stays Gone.
func RunTokenSchemeChangeCarriesLiveAddressesAndOnlyThose(t *testing.T, ctx context.Context, fixture EpochFixture) {
t.Helper()
epochSkipUnlessReady(t, fixture, true)
store := epochStore(fixture, "scheme-change")
addrA := epochMintAddress(t, ctx, fixture, store, "record-a")
addrB := epochMintAddress(t, ctx, fixture, store, "record-b")
// record-b is lost in the epoch it was minted in, which a store may do.
epochLoseAddress(t, ctx, fixture, store, addrB)
newEpoch := epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerTokenSchemeChange)
epochRequireLive(t, ctx, fixture, store, addrA, newEpoch,
"record-a is still served after the scheme change, through the retained mapping")
epochRequireGone(t, ctx, fixture, store, addrB, newEpoch,
"record-b was lost before the scheme change, which must not carry it")
carried := epochCurrentAddress(t, ctx, fixture, store, addrA)
if carried == addrA {
t.Errorf("CurrentAddressFor(%s) = the same address after a token-scheme change, want a new one: a scheme change re-encodes every served address, which is what tells a carry from a no-op", addrA)
}
addrB, err := fixture.MintUnderEpoch(ctx, store, "record-b")
if err != nil {
t.Fatalf("MintUnderEpoch(record-b): %v", err)
epochRequireLive(t, ctx, fixture, store, carried, newEpoch,
"the carried address must be served under the new epoch")
epochRequireLive(t, ctx, fixture, store, addrA, newEpoch,
"the old address must keep resolving after its carried address is looked up")
if again := epochCurrentAddress(t, ctx, fixture, store, carried); again != carried {
t.Errorf("CurrentAddressFor(%s) = %s, want the carried address itself: from the newest address the mapping is already current", carried, again)
}
if lostCurrent, err := fixture.CurrentAddressFor(ctx, store, addrB); err == nil {
t.Errorf("CurrentAddressFor(a lost address) = %s with no error, want an error: a lost Version is not carried", lostCurrent)
}
}
// RunACarriedAddressKeepsResolvingAcrossLaterBumps pins that a carried mapping
// is recorded once and then simply persists: later counter-only transitions do
// not change it, and a second token-scheme change extends it to the newest
// address without breaking any older one. Every address of the Version points
// directly at the newest address (one hop from any member), never along a
// chain.
func RunACarriedAddressKeepsResolvingAcrossLaterBumps(t *testing.T, ctx context.Context, fixture EpochFixture) {
t.Helper()
epochSkipUnlessReady(t, fixture, false)
store := epochStore(fixture, "carried-later")
addrA := epochMintAddress(t, ctx, fixture, store, "record-a")
epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerRestore)
epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerTokenSchemeChange)
addrA1 := epochCurrentAddress(t, ctx, fixture, store, addrA)
if addrA1 == addrA {
t.Fatalf("CurrentAddressFor(%s) = the same address after a token-scheme change, want a new one", addrA)
}
newEpoch, err := fixture.BumpEpoch(ctx, store, EpochBumpTriggerRestore)
if err != nil {
t.Fatalf("BumpEpoch: %v", err)
// Two counter-only transitions, with nothing minted in between.
epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerRestore)
counterEpoch := epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerDestructiveReinit)
epochRequireLive(t, ctx, fixture, store, addrA, counterEpoch,
"the original address must still resolve after counter-only transitions")
epochRequireLive(t, ctx, fixture, store, addrA1, counterEpoch,
"the carried address must still resolve after counter-only transitions")
if got := epochCurrentAddress(t, ctx, fixture, store, addrA); got != addrA1 {
t.Errorf("CurrentAddressFor(%s) = %s, want %s: a counter-only transition does not change the mapping", addrA, got, addrA1)
}
servesA, err := fixture.StillServes(ctx, store, addrA)
if err != nil {
t.Fatalf("StillServes(%s): %v", addrA, err)
// A second scheme change carries the Version again.
secondEpoch := epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerTokenSchemeChange)
addrA2 := epochCurrentAddress(t, ctx, fixture, store, addrA)
if addrA2 == addrA || addrA2 == addrA1 {
t.Fatalf("CurrentAddressFor(%s) = %s after a second scheme change, want an address different from %s and %s", addrA, addrA2, addrA, addrA1)
}
servesB, err := fixture.StillServes(ctx, store, addrB)
if err != nil {
t.Fatalf("StillServes(%s): %v", addrB, err)
for _, member := range []Address{addrA, addrA1, addrA2} {
epochRequireLive(t, ctx, fixture, store, member, secondEpoch,
"every address of a carried Version must resolve after a second scheme change")
}
if servesA == servesB {
t.Skip("this scenario needs one still-served and one no-longer-served address to exercise both halves of R20-n; StillServes reported the same answer for both, so this fixture gives this case nothing to contrast")
if got := epochCurrentAddress(t, ctx, fixture, store, addrA1); got != addrA2 {
t.Errorf("CurrentAddressFor(%s) = %s, want %s: every address of the Version points straight at the newest one", addrA1, got, addrA2)
}
stillServed, noLongerServed := addrA, addrB
if servesB && !servesA {
stillServed, noLongerServed = addrB, addrA
finalEpoch := epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerRestore)
epochRequireLive(t, ctx, fixture, store, addrA2, finalEpoch,
"the newest carried address must still resolve after a later restore")
}
// RunALostAddressStaysGoneAcrossASchemeChange pins that loss is terminal even
// across a token-scheme change. Losing a Version loses every address of its
// lineage at once, and a later scheme change must not carry a lost lineage
// back into service.
func RunALostAddressStaysGoneAcrossASchemeChange(t *testing.T, ctx context.Context, fixture EpochFixture) {
t.Helper()
epochSkipUnlessReady(t, fixture, true)
store := epochStore(fixture, "lost-scheme-change")
addrA := epochMintAddress(t, ctx, fixture, store, "record-a")
epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerTokenSchemeChange)
addrA1 := epochCurrentAddress(t, ctx, fixture, store, addrA)
lostEpoch := epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerRestore)
// One lineage, two addresses: losing either loses both.
epochLoseAddress(t, ctx, fixture, store, addrA)
epochRequireGone(t, ctx, fixture, store, addrA, lostEpoch,
"the original address of a lost Version must be Gone")
epochRequireGone(t, ctx, fixture, store, addrA1, lostEpoch,
"the carried address of a lost Version must be Gone too")
schemeEpoch := epochBumpTo(t, ctx, fixture, store, EpochBumpTriggerTokenSchemeChange)
epochRequireGone(t, ctx, fixture, store, addrA, schemeEpoch,
"a later scheme change must not carry a lost lineage back into service")
epochRequireGone(t, ctx, fixture, store, addrA1, schemeEpoch,
"a later scheme change must not carry a lost lineage back into service")
for _, lostAddress := range []Address{addrA, addrA1} {
if current, err := fixture.CurrentAddressFor(ctx, store, lostAddress); err == nil {
t.Errorf("CurrentAddressFor(%s) = %s with no error, want an error: a lost lineage has no current address", lostAddress, current)
}
}
voidedAnswer, err := fixture.Resolve(ctx, store, noLongerServed)
if err != nil {
t.Fatalf("Resolve(no-longer-served): %v", err)
}
if voidedAnswer.Restriction != RestrictionGoneReorganization {
t.Errorf("Resolve(a prior-epoch Address no longer served) = %s, want RestrictionGoneReorganization (R20-n)", voidedAnswer.Restriction)
}
if voidedAnswer.Epoch == nil {
t.Fatal("Resolve(a prior-epoch Address no longer served).Epoch = nil, want the current epoch populated (R20-n: the answer must name the current epoch, not just Restriction alone)")
} else if *voidedAnswer.Epoch != newEpoch {
t.Errorf("Resolve(a prior-epoch Address no longer served).Epoch = %d, want the current epoch %d", *voidedAnswer.Epoch, newEpoch)
}
keptAnswer, err := fixture.Resolve(ctx, store, stillServed)
if err != nil {
t.Fatalf("Resolve(still-served): %v", err)
}
if keptAnswer.Restriction != RestrictionLive {
t.Errorf("Resolve(a prior-epoch Address the backend still serves) = %s, want RestrictionLive (R20-n's exception)", keptAnswer.Restriction)
}
newAddr, err := fixture.CurrentAddressFor(ctx, store, stillServed)
if err != nil {
t.Fatalf("CurrentAddressFor(%s): %v", stillServed, err)
}
if newAddr == "" {
t.Error("CurrentAddressFor(a still-served prior-epoch Address) returned an empty Address, want a real one under the new epoch")
fresh := epochMintAddress(t, ctx, fixture, store, "record-a")
if fresh == addrA || fresh == addrA1 {
t.Fatalf("MintUnderEpoch(record-a) returned %s, an address of the lost lineage: a lost address is never handed out again", fresh)
}
epochRequireLive(t, ctx, fixture, store, fresh, schemeEpoch,
"a fresh mint of the id after the loss is a new lineage and is served")
}
// --- fixture helpers -------------------------------------------------------
@ -953,6 +1131,137 @@ func epochStore(fixture EpochFixture, tag string) string {
return fixture.IssuePrefix + "-epoch-store-" + tag
}
// epochLoseVersionSkip is the skip reason of every phase that needs
// EpochFixture.LoseVersion.
const epochLoseVersionSkip = "this backend cannot record that the store lost a Version (LoseVersion is nil)"
// epochSkipUnlessReady skips the case when the fixture lacks a capability the
// epoch cases need. The cases that record a loss also need LoseVersion. The
// all-nil wiring test runs every case against an empty fixture, so each case
// must call this before it touches any of them.
func epochSkipUnlessReady(t *testing.T, fixture EpochFixture, needsLoseVersion bool) {
t.Helper()
if fixture.MintUnderEpoch == nil {
t.Skip("this backend has no way to mint a Version under a known epoch (MintUnderEpoch is nil)")
}
if fixture.BumpEpoch == nil {
t.Skip("this backend has no epoch concept yet (BumpEpoch is nil)")
}
if fixture.StillServes == nil {
t.Skip("this backend cannot report whether it still serves a prior-epoch Version (StillServes is nil)")
}
if fixture.Resolve == nil {
t.Skip("this backend does not yet report retention state (Resolve is nil)")
}
if fixture.CurrentAddressFor == nil {
t.Skip("this backend cannot report a still-served Version's new Address (CurrentAddressFor is nil)")
}
if needsLoseVersion && fixture.LoseVersion == nil {
t.Skip(epochLoseVersionSkip)
}
}
// epochMintAddress mints id on store, failing the case if minting fails.
func epochMintAddress(t *testing.T, ctx context.Context, fixture EpochFixture, store, id string) Address {
t.Helper()
address, err := fixture.MintUnderEpoch(ctx, store, id)
if err != nil {
t.Fatalf("MintUnderEpoch(%s, %s): %v", store, id, err)
}
return address
}
// epochBumpTo bumps store's epoch for trigger and returns the epoch it
// reports. Epochs are captured from the return value, never assumed: the
// counter is one per database, shared by every store the suite uses.
func epochBumpTo(t *testing.T, ctx context.Context, fixture EpochFixture, store string, trigger EpochBumpTrigger) int {
t.Helper()
epoch, err := fixture.BumpEpoch(ctx, store, trigger)
if err != nil {
t.Fatalf("BumpEpoch(%s, %s): %v", store, trigger, err)
}
return epoch
}
// epochLoseAddress records that store lost the Version behind address.
func epochLoseAddress(t *testing.T, ctx context.Context, fixture EpochFixture, store string, address Address) {
t.Helper()
if err := fixture.LoseVersion(ctx, store, address); err != nil {
t.Fatalf("LoseVersion(%s, %s): %v", store, address, err)
}
}
// epochCurrentAddress asks where address now resolves, failing the case on an
// error or an empty answer.
func epochCurrentAddress(t *testing.T, ctx context.Context, fixture EpochFixture, store string, address Address) Address {
t.Helper()
current, err := fixture.CurrentAddressFor(ctx, store, address)
if err != nil {
t.Fatalf("CurrentAddressFor(%s, %s): %v", store, address, err)
}
if current == "" {
t.Fatalf("CurrentAddressFor(%s, %s) returned an empty Address, want a real one", store, address)
}
return current
}
// epochRequireLive asserts that address is served at epoch: StillServes is true
// and Resolve answers RestrictionLive naming that epoch. why says what the
// assertion is checking, for the failure message.
func epochRequireLive(t *testing.T, ctx context.Context, fixture EpochFixture, store string, address Address, epoch int, why string) {
t.Helper()
serves, err := fixture.StillServes(ctx, store, address)
if err != nil {
t.Fatalf("StillServes(%s): %v", address, err)
}
if !serves {
t.Errorf("StillServes(%s) = false, want true: %s", address, why)
}
answer, err := fixture.Resolve(ctx, store, address)
if err != nil {
t.Fatalf("Resolve(%s): %v", address, err)
}
if answer.Restriction != RestrictionLive {
t.Errorf("Resolve(%s) = %s, want RestrictionLive: %s", address, answer.Restriction, why)
}
epochRequireAnswerEpoch(t, answer, address, epoch, why)
}
// epochRequireGone asserts that address is no longer served at epoch:
// StillServes is false and Resolve answers RestrictionGoneReorganization
// naming that epoch.
func epochRequireGone(t *testing.T, ctx context.Context, fixture EpochFixture, store string, address Address, epoch int, why string) {
t.Helper()
serves, err := fixture.StillServes(ctx, store, address)
if err != nil {
t.Fatalf("StillServes(%s): %v", address, err)
}
if serves {
t.Errorf("StillServes(%s) = true, want false: %s", address, why)
}
answer, err := fixture.Resolve(ctx, store, address)
if err != nil {
t.Fatalf("Resolve(%s): %v", address, err)
}
if answer.Restriction != RestrictionGoneReorganization {
t.Errorf("Resolve(%s) = %s, want RestrictionGoneReorganization: %s", address, answer.Restriction, why)
}
epochRequireAnswerEpoch(t, answer, address, epoch, why)
}
// epochRequireAnswerEpoch asserts that a Live or Gone answer names the current
// epoch (R20-n: the answer carries the epoch, not just the Restriction).
func epochRequireAnswerEpoch(t *testing.T, answer RetentionAnswer, address Address, epoch int, why string) {
t.Helper()
if answer.Epoch == nil {
t.Errorf("Resolve(%s).Epoch = nil, want the current epoch %d: %s", address, epoch, why)
return
}
if *answer.Epoch != epoch {
t.Errorf("Resolve(%s).Epoch = %d, want the current epoch %d: %s", address, *answer.Epoch, epoch, why)
}
}
// sameRetentionAnswer compares two RetentionAnswer values by content rather
// than identity, so a case can assert "this did not change" without
// depending on the concrete Restriction the backend happened to pick.

View file

@ -129,5 +129,14 @@ func TestVersionedHistoryPhase0RunsInFullSkipMode(t *testing.T) {
t.Run("EpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed", func(t *testing.T) {
RunEpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed(t, ctx, fixture)
})
t.Run("TokenSchemeChangeCarriesLiveAddressesAndOnlyThose", func(t *testing.T) {
RunTokenSchemeChangeCarriesLiveAddressesAndOnlyThose(t, ctx, fixture)
})
t.Run("ACarriedAddressKeepsResolvingAcrossLaterBumps", func(t *testing.T) {
RunACarriedAddressKeepsResolvingAcrossLaterBumps(t, ctx, fixture)
})
t.Run("ALostAddressStaysGoneAcrossASchemeChange", func(t *testing.T) {
RunALostAddressStaysGoneAcrossASchemeChange(t, ctx, fixture)
})
})
}

View file

@ -29,6 +29,7 @@ go_library(
"dependency_editor.go",
"edgereader.go",
"ephemeral_routing.go",
"epoch_cas.go",
"errors.go",
"events.go",
"federation.go",
@ -221,6 +222,7 @@ go_test(
"edge_reader_contract_test.go",
"empty_commit_test.go",
"ephemeral_routing_test.go",
"epoch_cas_publish_test.go",
"errors_test.go",
"event_commit_boundary_test.go",
"events_since_test.go",

View file

@ -0,0 +1,248 @@
package dolt
import (
"context"
"database/sql"
"errors"
"fmt"
storeops "github.com/steveyegge/beads/internal/storage/issueops"
)
// CurrentEpoch, BumpEpoch, BumpEpochCarrying, MintUnderEpoch, LoseVersion,
// StillServes, Resolve and CurrentAddressFor give this leg R20's
// epoch-transition enforcement
// (gastownhall/beads#5898 revision 9, #6136),
// backed by store_epoch (migration 0067) and epoch_minted_addresses
// (migration 0072).
//
// UNLIKE MetadataCAS, THIS ROLE HAS NO PUBLIC issueops INTERFACE: the
// conformance contract's own seven epoch hooks are bare function types (see
// backend/conformance.EpochFixture) — so there is no role accessor to
// return one of, and these are direct methods on *DoltStore instead of a
// wrapper struct.
//
// These also have no domain-repository exposure: the unit-of-work leg
// reaches internal/storage/issueops's epoch Tx functions directly rather
// than through the domain issue repository (see internal/storage/uow's own
// epoch wiring), so nothing forces these types out of issueops into the
// root storage package. Method signatures here use plain types plus
// storeops.EpochResolveResult directly; backend/conformance's own
// Address/EpochBumpTrigger/RetentionAnswer vocabulary is translated only in
// this leg's contract-test file, per internal/storage/issueops/epoch_cas.go's
// header.
//
// Method names match backend/conformance.EpochFixture's own field names
// verbatim.
//
// PUBLICATION ORDER. The four writers
// commit their SQL transaction FIRST and stage and Dolt-commit afterwards,
// never from inside the open transaction. doltAddAndCommitInTx builds the Dolt
// commit from the transaction's BEGIN-time snapshot, so under concurrent
// writers it writes every row changed in the meantime back to its old value,
// and store_epoch and epoch_minted_addresses are append-only: a row lost that
// way is never rewritten (the HAZARD block on that helper).
//
// AN ERROR RETURNED AFTER THE SQL COMMIT MUST NOT BE REPLAYED. Every error a
// writer returns once its SQL commit has landed, or may have, wraps
// ErrCommitIndeterminate, the storage-wide no-replay sentinel: a replayed bump
// advances the counter a second time. A bump returns the epoch it committed, or
// would have, with that error, and a mint its address; the caller learns which
// by reading CurrentEpoch or StillServes, never by writing again. The embedded
// leg does the same.
// CurrentEpoch reports storeID's current epoch generation.
//
// The epoch counter is per database, not per store. storeID appears only in
// error text; one bump advances the epoch seen through every storeID that
// shares this database.
func (s *DoltStore) CurrentEpoch(ctx context.Context, storeID string) (int, error) {
var epoch int
if err := s.withReadTx(ctx, func(tx *sql.Tx) error {
var err error
epoch, err = storeops.CurrentEpochInTx(ctx, tx, storeID)
return err
}); err != nil {
return 0, err
}
return epoch, nil
}
// BumpEpoch advances storeID's epoch generation by one for reason.
//
// A Dolt commit that fails after the SQL commit is RETURNED, where the mint
// paths below log it and carry on: a bump is rare and
// operator-driven, and its caller (the restore trigger) must not report a
// restore complete while the bump is committed but unpublished. In that case
// the bump HAS applied: the epoch returned is the new one, the row is durable
// in the working set and rides the next Dolt commit, and the error wraps
// ErrCommitIndeterminate so that nothing bumps again to retry. A SQL commit
// whose result was lost is returned the same way, with the epoch it would have
// committed (failedBump).
//
// The epoch counter is per database, not per store. storeID appears only in
// error text; one bump advances the epoch seen through every storeID that
// shares this database.
func (s *DoltStore) BumpEpoch(ctx context.Context, storeID, reason string) (int, error) {
var epoch int
if err := s.withRetryTx(ctx, func(tx *sql.Tx) error {
var err error
epoch, err = storeops.BumpEpochInTx(ctx, tx, storeID, reason)
return err
}); err != nil {
return failedBump(storeID, epoch, err)
}
if err := s.doltAddAndCommitPostTx(ctx, []string{"store_epoch"},
fmt.Sprintf("bd: bump epoch for %s (%s)", storeID, reason)); err != nil {
return epoch, unpublishedBump(storeID, epoch, err)
}
return epoch, nil
}
// failedBump is what a bump returns when its SQL transaction reports an error.
// An error wrapping ErrCommitIndeterminate came from the commit of a body that
// ran to completion, so the commit may have landed: the epoch that body set is
// returned with it, and the caller reads CurrentEpoch to learn which. Any other
// error means nothing landed.
func failedBump(storeID string, epoch int, err error) (int, error) {
if errors.Is(err, ErrCommitIndeterminate) {
return epoch, fmt.Errorf("epoch bump for %s may have applied (epoch %d): %w", storeID, epoch, err)
}
return 0, err
}
// unpublishedBump is the error for a bump whose SQL commit landed and whose
// Dolt commit then failed. It wraps ErrCommitIndeterminate whatever the cause:
// doltAddAndCommitPostTx returns some failures without it (a staged-set read
// that fails, a breaker that refuses the commit), and those causes are no more
// replayable than the rest once the counter has moved.
func unpublishedBump(storeID string, epoch int, err error) error {
return fmt.Errorf("epoch bump for %s applied (epoch %d) but its Dolt commit failed: %w: %w", storeID, epoch, err, ErrCommitIndeterminate)
}
// BumpEpochCarrying is the token-scheme-change bump: BumpEpoch, and also the
// carry of every live address in the database to the new epoch
// (storeops.BumpEpochCarryingInTx). It writes store_epoch and
// epoch_minted_addresses, so it publishes both. It surfaces a failed Dolt
// commit exactly as BumpEpoch does, and the bump has applied in that case: the
// epoch returned is the new one and the caller must not bump again to retry.
// A lost SQL commit result is returned as BumpEpoch returns it (failedBump).
//
// The epoch counter is per database, not per store. storeID appears only in
// error text; one bump advances the epoch seen through every storeID that
// shares this database.
//
// CALLERS MUST HOLD THE WORKSPACE GATE (internal/workspacegate) EXCLUSIVELY FOR
// THE BUMP, as a restore does: see storeops.BumpEpochCarryingInTx.
func (s *DoltStore) BumpEpochCarrying(ctx context.Context, storeID, reason string) (int, error) {
var epoch int
if err := s.withRetryTx(ctx, func(tx *sql.Tx) error {
var err error
epoch, err = storeops.BumpEpochCarryingInTx(ctx, tx, storeID, reason)
return err
}); err != nil {
return failedBump(storeID, epoch, err)
}
if err := s.doltAddAndCommitPostTx(ctx, []string{"store_epoch", "epoch_minted_addresses"},
fmt.Sprintf("bd: carry addresses to epoch %d for %s (%s)", epoch, storeID, reason)); err != nil {
return epoch, unpublishedBump(storeID, epoch, err)
}
return epoch, nil
}
// MintUnderEpoch mints id's address under storeID's current epoch.
//
// It publishes like every issue mutation, through
// runIssueOperationTxWithMessage: a Dolt commit that fails after the SQL commit
// is logged, not returned. The mint is durable in the working set and rides the
// next Dolt commit, and mints are frequent and automated, so failing one over a
// missing history commit would only turn a harmless gap into caller errors. A
// SQL commit whose result was lost is returned, wrapping
// ErrCommitIndeterminate, together with the address the mint may have
// committed; StillServes says whether it did.
//
// A mint whose transaction overlaps a BumpEpoch reads the epoch before the bump
// and commits an address minted under the epoch the bump replaced. That address
// is a Live survivor: a restore or reinit bump writes no address rows, and an
// address's status is read from its own row. TestMintOverlappingABumpLeavesALiveSurvivor
// records that interleaving, and TestAMintAfterAConcurrentLossNeverRevivesTheLostAddress
// the one that must never bring a lost address back.
func (s *DoltStore) MintUnderEpoch(ctx context.Context, storeID, id string) (string, error) {
var address string
if err := s.runIssueOperationTxWithMessage(ctx, func(tx *sql.Tx) (storeops.ChangedTables, string, error) {
var err error
address, err = storeops.MintUnderEpochInTx(ctx, tx, storeID, id)
if err != nil {
return nil, "", err
}
return storeops.EpochMintDirtyTables(),
fmt.Sprintf("bd: mint %s under epoch for %s", id, storeID), nil
}); err != nil {
if errors.Is(err, ErrCommitIndeterminate) {
return address, err
}
return "", err
}
return address, nil
}
// StillServes reports whether address is still served under storeID's
// current epoch.
func (s *DoltStore) StillServes(ctx context.Context, storeID, address string) (bool, error) {
var serves bool
if err := s.withReadTx(ctx, func(tx *sql.Tx) error {
var err error
serves, err = storeops.StillServesInTx(ctx, tx, storeID, address)
return err
}); err != nil {
return false, err
}
return serves, nil
}
// Resolve answers R20's epoch-only restriction for address.
func (s *DoltStore) Resolve(ctx context.Context, storeID, address string) (storeops.EpochResolveResult, error) {
var result storeops.EpochResolveResult
if err := s.withReadTx(ctx, func(tx *sql.Tx) error {
var err error
result, err = storeops.ResolveEpochInTx(ctx, tx, storeID, address)
return err
}); err != nil {
return storeops.EpochResolveResult{}, err
}
return result, nil
}
// CurrentAddressFor reports the address oldAddress now resolves to: the newest
// address of its lineage, or oldAddress itself when nothing carried it. It only
// reads, so it runs on this leg's read path and publishes nothing.
func (s *DoltStore) CurrentAddressFor(ctx context.Context, storeID, oldAddress string) (string, error) {
var address string
if err := s.withReadTx(ctx, func(tx *sql.Tx) error {
var err error
address, err = storeops.CurrentAddressForInTx(ctx, tx, storeID, oldAddress)
return err
}); err != nil {
return "", err
}
return address, nil
}
// LoseVersion records that storeID no longer serves the Version named by
// address (storeops.LoseVersionInTx). It writes epoch_minted_addresses, so it
// publishes that table, and unlike a mint it RETURNS a failed Dolt commit: a
// loss its caller believes recorded must not be left unpublished. The loss has
// applied in that case, and the error wraps ErrCommitIndeterminate like a
// bump's, although replaying a loss is a no-op.
func (s *DoltStore) LoseVersion(ctx context.Context, storeID, address string) error {
if err := s.withRetryTx(ctx, func(tx *sql.Tx) error {
return storeops.LoseVersionInTx(ctx, tx, storeID, address)
}); err != nil {
return err
}
if err := s.doltAddAndCommitPostTx(ctx, []string{"epoch_minted_addresses"},
fmt.Sprintf("bd: lose version %s for %s", address, storeID)); err != nil {
return fmt.Errorf("loss of %s for %s recorded but its Dolt commit failed: %w: %w", address, storeID, err, ErrCommitIndeterminate)
}
return nil
}

View file

@ -0,0 +1,949 @@
package dolt
import (
"context"
"database/sql"
"database/sql/driver"
"errors"
"fmt"
"slices"
"strings"
"sync/atomic"
"testing"
"time"
mysql "github.com/go-sql-driver/mysql"
storeops "github.com/steveyegge/beads/internal/storage/issueops"
)
// These tests pin WHERE and HOW this leg publishes the R20 epoch tables
// (store_epoch, epoch_minted_addresses) to Dolt history
// (gastownhall/beads#6664).
//
// The first group runs on the sequence-capturing driver from
// dolt_commit_ordering_test.go, so it needs no running Dolt server: the
// ordering contract and the staged-table lists are properties of the SQL
// this leg sends, not of Dolt. The tests after them run against a real server:
// the first reproduces bee-ghosttrack's own probe (dolt_status after the first
// mint), the next three apply it to the carrying bump, to a recorded loss and to
// the read-only CurrentAddressFor, and the last three choreograph how a mint
// behaves beside a concurrent bump, beside a concurrent loss, and beside another
// transaction's mint and loss of its own address on that server.
const epochPublishStoreID = "epoch-store"
const epochPublishMintedID = "record-a"
// epochPublishAddress is the address of epochPublishMintedID under epoch 1, the
// one the fake serves as minted. It is minted on a fake of its own rather than
// written by hand: the fake serves a row at any address, so a hand-written one
// would go stale unnoticed if the encoding moved
// (TestEpochCASTestsBuildEveryAddressWithEpochAddress in issueops scans this
// file for one).
func epochPublishAddress() string {
f := newEpochFake()
db := sql.OpenDB(f.connector)
defer func() { _ = db.Close() }()
address, err := (&DoltStore{db: db}).MintUnderEpoch(context.Background(), epochPublishStoreID, epochPublishMintedID)
if err != nil {
panic(fmt.Sprintf("mint %s on a fresh epoch fake: %v", epochPublishMintedID, err))
}
return address
}
// epochFake is a *DoltStore's driver for the epoch methods: it serves the
// reads the shared epoch Tx functions make, keeps the singleton's epoch moving
// when the bump's UPDATE runs, and can refuse every DOLT_COMMIT.
type epochFake struct {
rec *seqRecorder
connector *seqConnector
epoch atomic.Int64
// publishErr, when set before the call under test, fails every
// CALL DOLT_COMMIT: the SQL transaction is fine, only publication is not.
publishErr error
// stagedReadErr, when set, fails the staged-set read stageAndCommit makes
// between DOLT_ADD and DOLT_COMMIT, a failure it returns without
// ErrCommitIndeterminate because nothing has reached Dolt history yet.
stagedReadErr error
}
func newEpochFake() *epochFake {
f := &epochFake{rec: &seqRecorder{}}
f.epoch.Store(1)
f.connector = &seqConnector{rec: f.rec}
f.connector.queryErr = func(query string) error {
switch {
case strings.Contains(query, "UPDATE store_epoch"):
f.epoch.Add(1)
case strings.Contains(query, "DOLT_COMMIT") && f.publishErr != nil:
return f.publishErr
case strings.Contains(query, "FROM dolt_status WHERE staged") && f.stagedReadErr != nil:
return f.stagedReadErr
}
return nil
}
f.connector.rows = func(query string) (driver.Rows, bool) {
switch {
case strings.Contains(query, "FROM store_epoch"):
return &valRows{cols: []string{"epoch"}, vals: [][]driver.Value{{f.epoch.Load()}}}, true
case strings.Contains(query, "FROM epoch_minted_addresses WHERE address"):
// Every address is already minted, so CurrentAddressFor has an
// old address to look up and MintUnderEpoch has nothing to insert.
// A read that asks for the survival columns gets a Live row nothing
// carried; a read that does not gets the three-column shape.
if strings.Contains(query, "carried_from") {
return &valRows{
cols: []string{"store_id", "minted_id", "minted_epoch", "carried_from", "gone_at_epoch"},
vals: [][]driver.Value{{epochPublishStoreID, epochPublishMintedID, int64(1), nil, nil}},
}, true
}
return &valRows{
cols: []string{"store_id", "minted_id", "minted_epoch"},
vals: [][]driver.Value{{epochPublishStoreID, epochPublishMintedID, int64(1)}},
}, true
}
return nil, false
}
return f
}
// epochArgConnector is the sequence-capturing connector plus the table each
// DOLT_ADD stages, which the sequence recorder drops.
type epochArgConnector struct{ *seqConnector }
func (c epochArgConnector) Connect(ctx context.Context) (driver.Conn, error) {
conn, err := c.seqConnector.Connect(ctx)
if err != nil {
return nil, err
}
return &epochArgConn{seqConn: conn.(*seqConn)}, nil
}
type epochArgConn struct{ *seqConn }
func (c *epochArgConn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Rows, error) {
if strings.Contains(query, "DOLT_ADD") && len(args) == 1 {
c.parent.rec.add(c.id, fmt.Sprintf("STAGE %v", args[0].Value))
}
return c.seqConn.QueryContext(ctx, query, args)
}
// epochPublishCall is one epoch method that writes.
type epochPublishCall struct {
name string
call func(ctx context.Context, s *DoltStore) error
// staged is the exact set of tables the call stages for its Dolt commit,
// sorted.
staged []string
// logsPublishFailure is true for the call that carries on past a failed Dolt
// commit; every other call returns it.
logsPublishFailure bool
}
func epochPublishCalls() []epochPublishCall {
return []epochPublishCall{
{
name: "BumpEpoch",
staged: []string{"store_epoch"},
call: func(ctx context.Context, s *DoltStore) error {
_, err := s.BumpEpoch(ctx, epochPublishStoreID, "restore")
return err
},
},
{
name: "BumpEpochCarrying",
staged: []string{"epoch_minted_addresses", "store_epoch"},
call: func(ctx context.Context, s *DoltStore) error {
_, err := s.BumpEpochCarrying(ctx, epochPublishStoreID, "token-scheme-change")
return err
},
},
{
name: "MintUnderEpoch",
staged: []string{"epoch_minted_addresses", "store_epoch"},
logsPublishFailure: true,
call: func(ctx context.Context, s *DoltStore) error {
_, err := s.MintUnderEpoch(ctx, epochPublishStoreID, epochPublishMintedID)
return err
},
},
{
name: "LoseVersion",
staged: []string{"epoch_minted_addresses"},
call: func(ctx context.Context, s *DoltStore) error {
return s.LoseVersion(ctx, epochPublishStoreID, epochPublishAddress())
},
},
}
}
func epochPublishIndex(events []string, pred func(string) bool) int {
for i, ev := range events {
if pred(ev) {
return i
}
}
return -1
}
// TestEpochWritesPublishToDoltOnlyAfterTheSQLCommit is the ordering contract
// of dolt_commit_ordering_test.go applied to the epoch methods. Staging and
// Dolt-committing store_epoch or epoch_minted_addresses inside the still-open
// SQL transaction is the lost-update hazard documented on doltAddAndCommitInTx
// (LatentLabsSpace/NEXUS#92), and it costs more here than on issues: both
// tables are append-only, so a row reverted to its BEGIN-time value is never
// rewritten.
func TestEpochWritesPublishToDoltOnlyAfterTheSQLCommit(t *testing.T) {
for _, tc := range epochPublishCalls() {
t.Run(tc.name, func(t *testing.T) {
f := newEpochFake()
db := sql.OpenDB(f.connector)
defer func() { _ = db.Close() }()
if err := tc.call(context.Background(), &DoltStore{db: db}); err != nil {
t.Fatalf("%s: %v", tc.name, err)
}
events := f.rec.snapshot()
commitIdx := epochPublishIndex(events, func(ev string) bool { return ev == "COMMIT" })
addIdx := epochPublishIndex(events, func(ev string) bool { return strings.Contains(ev, "DOLT_ADD") })
doltCommitIdx := epochPublishIndex(events, func(ev string) bool { return strings.Contains(ev, "DOLT_COMMIT") })
if commitIdx == -1 || addIdx == -1 || doltCommitIdx == -1 {
t.Fatalf("%s: want a SQL COMMIT, a DOLT_ADD and a DOLT_COMMIT; events: %v", tc.name, events)
}
if addIdx < commitIdx {
t.Errorf("%s: DOLT_ADD ran INSIDE the open transaction (index %d < COMMIT index %d) — lost-update ordering hazard; events: %v",
tc.name, addIdx, commitIdx, events)
}
if doltCommitIdx < commitIdx {
t.Errorf("%s: DOLT_COMMIT ran INSIDE the open transaction (index %d < COMMIT index %d) — lost-update ordering hazard; events: %v",
tc.name, doltCommitIdx, commitIdx, events)
}
})
}
}
// TestEpochWritesStageExactlyTheTablesTheyChange is the server-leg half of
// gastownhall/beads#6664 Major 2 (bee-ghosttrack, review 5360880888): the
// first mint on a store lazily inserts store_epoch's singleton
// (ensureStoreEpochRow), so a mint that stages only epoch_minted_addresses
// leaves the epoch row modified and uncommitted, and the Dolt commit holds
// minted rows without the epoch row they depend on. It states the rule for
// every writer, with exact sets: a restore or reinit bump changes only the
// counter, the carrying bump and a mint change both tables, and a recorded loss
// changes only address rows. A writer that stages less leaves rows behind in
// the working set, and one that stages more commits rows it did not write.
func TestEpochWritesStageExactlyTheTablesTheyChange(t *testing.T) {
for _, tc := range epochPublishCalls() {
t.Run(tc.name, func(t *testing.T) {
f := newEpochFake()
db := sql.OpenDB(epochArgConnector{f.connector})
defer func() { _ = db.Close() }()
if err := tc.call(context.Background(), &DoltStore{db: db}); err != nil {
t.Fatalf("%s: %v", tc.name, err)
}
var staged []string
for _, ev := range f.rec.snapshot() {
if table, ok := strings.CutPrefix(ev, "STAGE "); ok {
staged = append(staged, table)
}
}
slices.Sort(staged)
staged = slices.Compact(staged)
if !slices.Equal(staged, tc.staged) {
t.Errorf("%s staged %v, want exactly %v (Major 2: a table the call writes must be committed with it, and one it does not write must not be)", tc.name, staged, tc.staged)
}
})
}
}
// TestBumpEpochSurfacesAPublicationFailureAfterTheSQLCommit pins how a bump
// reports a failed publication: a bump whose SQL transaction
// committed but whose Dolt commit failed must tell its caller, because a
// restore trigger must not report a restore complete over an unpublished
// bump. The bump itself must survive: it is durable in the working set, so a
// failed history commit is an error to report, never a reason to roll back.
func TestBumpEpochSurfacesAPublicationFailureAfterTheSQLCommit(t *testing.T) {
f := newEpochFake()
f.publishErr = errors.New("dolt commit refused")
db := sql.OpenDB(f.connector)
defer func() { _ = db.Close() }()
epoch, err := (&DoltStore{db: db}).BumpEpoch(context.Background(), epochPublishStoreID, "restore")
requirePublicationFailureReported(t, "BumpEpoch", f, err, f.publishErr)
if epoch != 2 {
t.Errorf("BumpEpoch returned epoch %d with the publication error, want 2: the bump applied, the error only says its Dolt commit did not", epoch)
}
}
// requirePublicationFailureReported checks what a writer that reports a failed
// Dolt commit must show once its SQL transaction committed: the transaction was
// committed and never rolled back, and the error it returned wraps the failure
// (cause) and ErrCommitIndeterminate, so that nothing replays a write that has
// already applied.
func requirePublicationFailureReported(t *testing.T, name string, f *epochFake, err, cause error) {
t.Helper()
events := f.rec.snapshot()
if !slices.Contains(events, "COMMIT") || slices.Contains(events, "ROLLBACK") {
t.Errorf("%s: a failed Dolt commit must not undo the write: want the SQL transaction COMMITTED and never rolled back; events: %v", name, events)
}
if err == nil {
t.Fatalf("%s = nil error although its Dolt commit failed: the caller would report success for a write that is committed but unpublished; events: %v", name, events)
}
if !errors.Is(err, cause) {
t.Errorf("%s error = %v, want it to wrap the Dolt commit failure %v", name, err, cause)
}
if !errors.Is(err, ErrCommitIndeterminate) {
t.Errorf("%s error = %v, want it to wrap ErrCommitIndeterminate: the write has applied, and a caller that takes the error for a write that did not would replay it", name, err)
}
}
// TestBumpEpochCarryingSurfacesAPublicationFailureAfterTheSQLCommit holds the
// carrying bump to the rule BumpEpoch is held to above. It writes the address
// rows of every live Version as well as the counter, and a token-scheme change
// must not report success over a bump that is committed but unpublished. The
// bump applied, so the epoch comes back with the error and the caller must not
// bump again to retry.
func TestBumpEpochCarryingSurfacesAPublicationFailureAfterTheSQLCommit(t *testing.T) {
f := newEpochFake()
f.publishErr = errors.New("dolt commit refused")
db := sql.OpenDB(f.connector)
defer func() { _ = db.Close() }()
epoch, err := (&DoltStore{db: db}).BumpEpochCarrying(context.Background(), epochPublishStoreID, "token-scheme-change")
requirePublicationFailureReported(t, "BumpEpochCarrying", f, err, f.publishErr)
if epoch != 2 {
t.Errorf("BumpEpochCarrying returned epoch %d with the publication error, want 2: the bump applied, the error only says its Dolt commit did not", epoch)
}
}
// TestLoseVersionSurfacesAPublicationFailureAfterTheSQLCommit pins the same rule
// for a recorded loss: a loss its caller believes recorded must not be left
// unpublished. Unlike a mint, a loss is rare and deliberate, so a failed Dolt
// commit is an error to report, never one to log.
func TestLoseVersionSurfacesAPublicationFailureAfterTheSQLCommit(t *testing.T) {
f := newEpochFake()
f.publishErr = errors.New("dolt commit refused")
db := sql.OpenDB(f.connector)
defer func() { _ = db.Close() }()
err := (&DoltStore{db: db}).LoseVersion(context.Background(), epochPublishStoreID, epochPublishAddress())
requirePublicationFailureReported(t, "LoseVersion", f, err, f.publishErr)
}
// TestEpochWritesMarkAFailedStagedReadIndeterminate holds the writers that
// return a failed publication to the no-replay rule for the failure
// stageAndCommit itself returns as a plain error: its staged-set read before
// DOLT_COMMIT. Nothing has reached Dolt history at that point, but the write's
// SQL commit has landed, so a bump replayed on that error would advance the
// counter a second time. The error must say so as a failed DOLT_COMMIT does.
func TestEpochWritesMarkAFailedStagedReadIndeterminate(t *testing.T) {
for _, tc := range epochPublishCalls() {
if tc.logsPublishFailure {
continue // a mint logs a failed publication and returns nil
}
t.Run(tc.name, func(t *testing.T) {
f := newEpochFake()
f.stagedReadErr = errors.New("staged-set read failed")
db := sql.OpenDB(f.connector)
defer func() { _ = db.Close() }()
err := tc.call(context.Background(), &DoltStore{db: db})
requirePublicationFailureReported(t, tc.name, f, err, f.stagedReadErr)
})
}
}
// TestEpochWritesReturnWhatAnIndeterminateSQLCommitMayHaveApplied pins what each
// writer hands back when its SQL commit's result is lost (ErrCommitIndeterminate,
// which withRetryTx never retries): the commit may have landed, so a bump
// returns the epoch it would have committed and a mint its address, as a bump
// does when only its Dolt commit fails. The caller then reads CurrentEpoch or
// StillServes to learn which; a zero value would read as nothing applied and
// invite the replay the sentinel forbids.
func TestEpochWritesReturnWhatAnIndeterminateSQLCommitMayHaveApplied(t *testing.T) {
ctx := context.Background()
open := func(t *testing.T) (*DoltStore, *epochFake) {
t.Helper()
f := newEpochFake()
f.connector.commitErr = func() error { return testConnectionLoss }
db := sql.OpenDB(f.connector)
t.Cleanup(func() { _ = db.Close() })
return &DoltStore{db: db}, f
}
requireIndeterminate := func(t *testing.T, name string, f *epochFake, err error) {
t.Helper()
if !errors.Is(err, ErrCommitIndeterminate) || !errors.Is(err, testConnectionLoss) {
t.Fatalf("%s = %v, want the lost commit response wrapped in ErrCommitIndeterminate", name, err)
}
if events := f.rec.snapshot(); slices.ContainsFunc(events, func(ev string) bool { return strings.Contains(ev, "DOLT_COMMIT") }) {
t.Errorf("%s published a SQL commit whose result was lost; events: %v", name, events)
}
}
t.Run("BumpEpoch", func(t *testing.T) {
s, f := open(t)
epoch, err := s.BumpEpoch(ctx, epochPublishStoreID, "restore")
requireIndeterminate(t, "BumpEpoch", f, err)
if epoch != 2 {
t.Errorf("BumpEpoch returned epoch %d with an indeterminate commit, want 2, the epoch it may have committed", epoch)
}
})
t.Run("BumpEpochCarrying", func(t *testing.T) {
s, f := open(t)
epoch, err := s.BumpEpochCarrying(ctx, epochPublishStoreID, "token-scheme-change")
requireIndeterminate(t, "BumpEpochCarrying", f, err)
if epoch != 2 {
t.Errorf("BumpEpochCarrying returned epoch %d with an indeterminate commit, want 2, the epoch it may have committed", epoch)
}
})
t.Run("MintUnderEpoch", func(t *testing.T) {
s, f := open(t)
address, err := s.MintUnderEpoch(ctx, epochPublishStoreID, epochPublishMintedID)
requireIndeterminate(t, "MintUnderEpoch", f, err)
if want := epochPublishAddress(); address != want {
t.Errorf("MintUnderEpoch returned address %q with an indeterminate commit, want %s, the address it may have committed", address, want)
}
})
t.Run("LoseVersion", func(t *testing.T) {
s, f := open(t)
requireIndeterminate(t, "LoseVersion", f, s.LoseVersion(ctx, epochPublishStoreID, epochPublishAddress()))
})
}
// TestEpochWritesReturnNothingWhenTheSQLCommitFailsDefinitely is the other side
// of that rule: a commit error the server answered with (a typed MySQL error,
// which withRetryTx neither retries nor marks indeterminate) means nothing
// landed. Each body ran to the end and computed an epoch or an address, and
// neither may come back with the error.
func TestEpochWritesReturnNothingWhenTheSQLCommitFailsDefinitely(t *testing.T) {
ctx := context.Background()
refused := &mysql.MySQLError{Number: 1105, Message: "commit refused"}
open := func(t *testing.T) *DoltStore {
t.Helper()
f := newEpochFake()
f.connector.commitErr = func() error { return refused }
db := sql.OpenDB(f.connector)
t.Cleanup(func() { _ = db.Close() })
return &DoltStore{db: db}
}
requireDefinite := func(t *testing.T, name string, err error) {
t.Helper()
if !errors.Is(err, refused) || errors.Is(err, ErrCommitIndeterminate) {
t.Fatalf("%s = %v, want the refused commit, not marked ErrCommitIndeterminate", name, err)
}
}
t.Run("BumpEpoch", func(t *testing.T) {
epoch, err := open(t).BumpEpoch(ctx, epochPublishStoreID, "restore")
requireDefinite(t, "BumpEpoch", err)
if epoch != 0 {
t.Errorf("BumpEpoch returned epoch %d with a refused commit, want 0: nothing applied", epoch)
}
})
t.Run("BumpEpochCarrying", func(t *testing.T) {
epoch, err := open(t).BumpEpochCarrying(ctx, epochPublishStoreID, "token-scheme-change")
requireDefinite(t, "BumpEpochCarrying", err)
if epoch != 0 {
t.Errorf("BumpEpochCarrying returned epoch %d with a refused commit, want 0: nothing applied", epoch)
}
})
t.Run("MintUnderEpoch", func(t *testing.T) {
address, err := open(t).MintUnderEpoch(ctx, epochPublishStoreID, epochPublishMintedID)
requireDefinite(t, "MintUnderEpoch", err)
if address != "" {
t.Errorf("MintUnderEpoch returned address %q with a refused commit, want none: nothing applied", address)
}
})
}
// TestMintPathsKeepTheirRowsWhenPublicationFails is the other half of that
// rule: swallow-and-log stays acceptable for the frequent, automated mint
// paths, so a failed Dolt commit does not fail a mint whose SQL transaction
// committed (the runIssueOperationTxWithMessage contract: a nil error means
// the data is durable in the working set).
func TestMintPathsKeepTheirRowsWhenPublicationFails(t *testing.T) {
for _, tc := range epochPublishCalls() {
if !tc.logsPublishFailure {
continue // the bumps and the loss surface the failure instead, see above
}
t.Run(tc.name, func(t *testing.T) {
f := newEpochFake()
f.publishErr = errors.New("dolt commit refused")
db := sql.OpenDB(f.connector)
defer func() { _ = db.Close() }()
err := tc.call(context.Background(), &DoltStore{db: db})
events := f.rec.snapshot()
if !slices.Contains(events, "COMMIT") || slices.Contains(events, "ROLLBACK") {
t.Errorf("%s: a failed Dolt commit must not roll the mint back: want the SQL transaction COMMITTED; events: %v", tc.name, events)
}
if err != nil {
t.Errorf("%s = %v, want nil: the mint's data is durable, so a failed history commit is logged, not returned", tc.name, err)
}
})
}
}
// TestCurrentAddressForWritesAndPublishesNothing pins that CurrentAddressFor is a
// read on this leg: it answers from the address's own row, the carry rows and
// the counter, and sends no INSERT, UPDATE or DELETE and no DOLT_ADD or
// DOLT_COMMIT. The read path opens an ordinary transaction and rolls it back, so
// a write it made would vanish without an error; the statements it sends are the
// only place a stray write shows.
func TestCurrentAddressForWritesAndPublishesNothing(t *testing.T) {
f := newEpochFake()
db := sql.OpenDB(f.connector)
defer func() { _ = db.Close() }()
address := epochPublishAddress()
current, err := (&DoltStore{db: db}).CurrentAddressFor(context.Background(), epochPublishStoreID, address)
if err != nil {
t.Fatalf("CurrentAddressFor: %v", err)
}
if current != address {
t.Errorf("CurrentAddressFor(%s) = %s, want the address itself: the fake serves it as a Live row nothing carried", address, current)
}
for _, ev := range f.rec.snapshot() {
statement := strings.ToUpper(strings.TrimSpace(ev))
for _, verb := range []string{"INSERT", "UPDATE", "DELETE", "REPLACE"} {
if strings.HasPrefix(statement, verb) {
t.Errorf("CurrentAddressFor sent %q: a lookup must not write", ev)
}
}
if strings.Contains(statement, "DOLT_ADD") || strings.Contains(statement, "DOLT_COMMIT") {
t.Errorf("CurrentAddressFor sent %q: a lookup has nothing to publish to Dolt history", ev)
}
}
}
// epochTablesInWorkingSet lists the R20 epoch tables that still appear in
// dolt_status, staged or not: after a write has been published, neither may.
func epochTablesInWorkingSet(status *DoltStatus) []string {
var dirty []string
for _, entry := range append(slices.Clone(status.Staged), status.Unstaged...) {
if entry.Table == "store_epoch" || entry.Table == "epoch_minted_addresses" {
dirty = append(dirty, fmt.Sprintf("%s (%s)", entry.Table, entry.Status))
}
}
return dirty
}
// TestFirstMintLeavesTheEpochTablesCommitted reproduces bee-ghosttrack's probe
// for gastownhall/beads#6664 Major 2 on a real server: Status() after the
// first mint on a fresh store read unstaged=[{store_epoch modified}].
func TestFirstMintLeavesTheEpochTablesCommitted(t *testing.T) {
store, cleanup := setupTestStore(t)
defer cleanup()
ctx, cancel := testContext(t)
defer cancel()
// A fresh branch: store_epoch has no row, so this mint is what seeds it.
if _, err := store.MintUnderEpoch(ctx, epochPublishStoreID, epochPublishMintedID); err != nil {
t.Fatalf("MintUnderEpoch on a fresh store: %v", err)
}
status, err := store.Status(ctx)
if err != nil {
t.Fatalf("Status: %v", err)
}
if dirty := epochTablesInWorkingSet(status); len(dirty) > 0 {
t.Errorf("after the first mint the working set still holds %v: the mint's Dolt commit must include the singleton row it seeded", dirty)
}
}
// TestBumpEpochCarryingLeavesTheEpochTablesCommitted applies the same probe to
// the carrying bump, which writes two tables: the counter, and one carry row per
// live address in epoch_minted_addresses. Publishing only the counter would
// leave those rows modified and uncommitted in the working set.
func TestBumpEpochCarryingLeavesTheEpochTablesCommitted(t *testing.T) {
skipIfNoServer(t)
ctx, cancel := testContext(t)
defer cancel()
store := newMultiConnectionEpochStore(t, ctx, "epoch_carry_published")
if _, err := store.MintUnderEpoch(ctx, epochPublishStoreID, epochPublishMintedID); err != nil {
t.Fatalf("MintUnderEpoch: %v", err)
}
newEpoch, err := store.BumpEpochCarrying(ctx, epochPublishStoreID, "token-scheme-change")
if err != nil {
t.Fatalf("BumpEpochCarrying: %v", err)
}
// The carry row is what makes the publication more than the counter: without
// it this test would pass for a bump that wrote nothing but store_epoch.
var carryRows int
if err := store.db.QueryRowContext(ctx,
"SELECT COUNT(*) FROM epoch_minted_addresses WHERE minted_id = ? AND minted_epoch = ?",
epochPublishMintedID, newEpoch,
).Scan(&carryRows); err != nil {
t.Fatalf("count the carry rows: %v", err)
}
if carryRows != 1 {
t.Fatalf("epoch_minted_addresses holds %d rows for %s at epoch %d after the carrying bump, want exactly 1 carry row", carryRows, epochPublishMintedID, newEpoch)
}
status, err := store.Status(ctx)
if err != nil {
t.Fatalf("Status: %v", err)
}
if dirty := epochTablesInWorkingSet(status); len(dirty) > 0 {
t.Errorf("after the carrying bump the working set still holds %v: its Dolt commit must include the carry rows", dirty)
}
}
// TestLoseVersionLeavesTheEpochTablesCommitted applies the probe to a recorded
// loss, which changes only epoch_minted_addresses: the row it marks must be in
// the Dolt commit, not left modified in the working set.
func TestLoseVersionLeavesTheEpochTablesCommitted(t *testing.T) {
skipIfNoServer(t)
ctx, cancel := testContext(t)
defer cancel()
store := newMultiConnectionEpochStore(t, ctx, "epoch_loss_published")
address, err := store.MintUnderEpoch(ctx, epochPublishStoreID, epochPublishMintedID)
if err != nil {
t.Fatalf("MintUnderEpoch: %v", err)
}
if err := store.LoseVersion(ctx, epochPublishStoreID, address); err != nil {
t.Fatalf("LoseVersion: %v", err)
}
serves, err := store.StillServes(ctx, epochPublishStoreID, address)
if err != nil {
t.Fatalf("StillServes: %v", err)
}
if serves {
t.Fatalf("StillServes(%s) = true after LoseVersion, want false: the loss must have taken effect for the working-set check below to mean anything", address)
}
status, err := store.Status(ctx)
if err != nil {
t.Fatalf("Status: %v", err)
}
if dirty := epochTablesInWorkingSet(status); len(dirty) > 0 {
t.Errorf("after LoseVersion the working set still holds %v: its Dolt commit must include the row it marked", dirty)
}
}
// TestCurrentAddressForLeavesAnAbsentStoreEpochRowAbsent is what remains of the
// check that CurrentAddressFor committed a re-seeded singleton row. A store
// whose singleton row is absent is legitimate state — migration 0067 starts the
// table empty and treats "no row" as epoch 1 — and CurrentAddressFor used to
// re-seed it through ensureStoreEpochRow exactly as a first mint does. It only
// reads now: it answers from that default, leaves the singleton absent, and
// leaves nothing in the working set to commit.
func TestCurrentAddressForLeavesAnAbsentStoreEpochRowAbsent(t *testing.T) {
skipIfNoServer(t)
ctx, cancel := testContext(t)
defer cancel()
store := newMultiConnectionEpochStore(t, ctx, "epoch_lookup_absent_row")
address, err := store.MintUnderEpoch(ctx, epochPublishStoreID, epochPublishMintedID)
if err != nil {
t.Fatalf("MintUnderEpoch: %v", err)
}
// Settle everything so far, then leave the singleton row absent with a
// clean working set.
if _, err := store.CommitAll(ctx, "test: settle the first mint"); err != nil {
t.Fatalf("CommitAll: %v", err)
}
if _, err := store.db.ExecContext(ctx, "DELETE FROM store_epoch"); err != nil {
t.Fatalf("delete the singleton row: %v", err)
}
if _, err := store.CommitAll(ctx, "test: absent singleton row"); err != nil {
t.Fatalf("CommitAll: %v", err)
}
current, err := store.CurrentAddressFor(ctx, epochPublishStoreID, address)
if err != nil {
t.Fatalf("CurrentAddressFor: %v", err)
}
if current != address {
t.Errorf("CurrentAddressFor(%s) = %s, want the address itself: nothing carried it, and a lookup must not mint a replacement", address, current)
}
var singletonRows int
if err := store.db.QueryRowContext(ctx, "SELECT COUNT(*) FROM store_epoch").Scan(&singletonRows); err != nil {
t.Fatalf("count the store_epoch rows: %v", err)
}
if singletonRows != 0 {
t.Errorf("store_epoch holds %d rows after CurrentAddressFor, want 0: a lookup must not re-seed the singleton", singletonRows)
}
status, err := store.Status(ctx)
if err != nil {
t.Fatalf("Status: %v", err)
}
if dirty := epochTablesInWorkingSet(status); len(dirty) > 0 {
t.Errorf("after CurrentAddressFor the working set still holds %v: a lookup must leave nothing to commit", dirty)
}
}
// newMultiConnectionEpochStore opens a store on its own database with several
// connections to one branch, as in production server mode. setupTestStore pins
// a single connection, which cannot overlap two transactions. A store of its own
// also never queues on the shared test database's schema-init lock, whose
// five-second acquire timeout runs out when many parallel tests set up at once
// on a loaded host, so the publication probes that need a database of their own
// for no other reason use it too.
func newMultiConnectionEpochStore(t *testing.T, ctx context.Context, name string) *DoltStore {
t.Helper()
store, err := New(ctx, &Config{
Path: t.TempDir(),
ServerHost: "127.0.0.1",
ServerPort: testServerPort,
Database: fmt.Sprintf("%s_%d", name, time.Now().UnixNano()),
MaxOpenConns: 4,
CreateIfMissing: true,
CommitterName: "test",
CommitterEmail: "test@example.com",
})
if err != nil {
t.Fatalf("create store: %v", err)
}
t.Cleanup(func() { _ = store.Close() })
return store
}
// TestMintOverlappingABumpLeavesALiveSurvivor measures, on a real server, an
// outcome bee-ghosttrack marked "Unverified" (gastownhall/beads#6664, review
// 5360880888): a mint whose transaction overlaps a BumpEpoch reads the epoch
// before the bump, does not conflict with it (the two write different tables),
// and commits an address minted under the epoch the bump has just replaced.
//
// That address is a Live survivor, and that is the right answer. A restore or
// destructive-reinit bump writes no address rows: it advances only the counter,
// and an address's status is read from its own row, which says only that it was
// minted in an epoch that has happened. So an address minted before the bump is
// still served after it, however the two interleave, exactly as if the two
// calls had run back to back. (Before survival was recorded, this interleaving
// committed an address that already read GoneReorganization, because the bump
// voided every address nobody minted again; that outcome no longer exists.)
//
// The engine does not prevent the overlap, and this test depends on that.
// Measured: SELECT ... FOR UPDATE and LOCK IN SHARE MODE take no lock, and a
// write that changes no value (UPDATE store_epoch SET epoch = epoch matches 0
// rows) is not a write to the merge. Only a write that CHANGES a cell the bump
// also changes conflicts (Error 1213), and a mint has no cell of its own to
// change. That is also why the token-scheme-change bump, the one bump that reads
// address rows, needs its caller to hold the workspace gate exclusively, as a
// restore does: a mint cannot be made to conflict with it.
//
// If this test fails because the bump timed out or the mint's commit
// conflicted, the engine now prevents the overlap: revisit that requirement and
// this test together.
func TestMintOverlappingABumpLeavesALiveSurvivor(t *testing.T) {
skipIfNoServer(t)
ctx, cancel := testContext(t)
defer cancel()
store := newMultiConnectionEpochStore(t, ctx, "epoch_overlap")
// Seed the singleton so the mint below only reads the epoch.
if _, err := store.MintUnderEpoch(ctx, epochPublishStoreID, "seed"); err != nil {
t.Fatalf("seed mint: %v", err)
}
mintTx, err := store.db.BeginTx(ctx, nil)
if err != nil {
t.Fatalf("begin mint transaction: %v", err)
}
defer func() { _ = mintTx.Rollback() }()
address, err := storeops.MintUnderEpochInTx(ctx, mintTx, epochPublishStoreID, epochPublishMintedID)
if err != nil {
t.Fatalf("mint inside the open transaction: %v", err)
}
// The bump runs on another connection while the mint transaction is open.
bumpCtx, cancelBump := context.WithTimeout(ctx, 10*time.Second)
defer cancelBump()
bumpedEpoch, err := store.BumpEpoch(bumpCtx, epochPublishStoreID, "restore")
if err != nil {
t.Fatalf("BumpEpoch beside an open mint transaction: %v: the engine now holds the bump back, so the overlap this test documents is prevented", err)
}
if err := mintTx.Commit(); err != nil {
t.Fatalf("mint commit after a concurrent bump: %v: the engine now conflicts the mint, so the overlap this test documents is prevented", err)
}
serves, err := store.StillServes(ctx, epochPublishStoreID, address)
if err != nil {
t.Fatalf("StillServes: %v", err)
}
if !serves {
t.Errorf("address %s, minted before a bump that committed first, is no longer served: a restore or reinit bump writes no address rows, so the address must survive it", address)
}
answer, err := store.Resolve(ctx, epochPublishStoreID, address)
if err != nil {
t.Fatalf("Resolve: %v", err)
}
if answer.Restriction != storeops.EpochRestrictionLive {
t.Errorf("Resolve(%s) = %v, want EpochRestrictionLive: the address survived the bump", address, answer.Restriction)
}
if answer.Epoch == nil {
t.Errorf("Resolve(%s).Epoch = nil, want the current epoch %d", address, bumpedEpoch)
} else if *answer.Epoch != bumpedEpoch {
t.Errorf("Resolve(%s).Epoch = %d, want the current epoch %d", address, *answer.Epoch, bumpedEpoch)
}
}
// TestAMintAfterAConcurrentLossNeverRevivesTheLostAddress choreographs, with no
// timing in it, the interleaving that could bring a lost address back: one
// transaction reads the address Live, another commits the loss of it, and the
// first then mints the same id and commits.
//
// The first transaction read the address before the loss committed, so its
// snapshot holds a Live row and the mint finds nothing to do. A mint never
// writes an existing row (it inserts a root row for a new address and otherwise
// touches nothing), so the first transaction commits no write at all and has
// nothing to conflict with the loss. The loss is the only change to the row, so
// the address ends Gone: no interleaving of a mint and a loss may revive it.
//
// If this test fails because the loss was held back, or because the first
// transaction saw the loss, the engine changed the premise (an open transaction
// reads its own snapshot, and a commit that wrote nothing conflicts with
// nothing) and the interleaving needs another look.
func TestAMintAfterAConcurrentLossNeverRevivesTheLostAddress(t *testing.T) {
skipIfNoServer(t)
ctx, cancel := testContext(t)
defer cancel()
store := newMultiConnectionEpochStore(t, ctx, "epoch_loss_overlap")
address, err := store.MintUnderEpoch(ctx, epochPublishStoreID, epochPublishMintedID)
if err != nil {
t.Fatalf("seed mint: %v", err)
}
// The first transaction reads the address Live and stays open.
mintTx, err := store.db.BeginTx(ctx, nil)
if err != nil {
t.Fatalf("begin the first transaction: %v", err)
}
defer func() { _ = mintTx.Rollback() }()
serves, err := storeops.StillServesInTx(ctx, mintTx, epochPublishStoreID, address)
if err != nil {
t.Fatalf("StillServesInTx inside the first transaction: %v", err)
}
if !serves {
t.Fatalf("address %s reads as not served inside the first transaction before any loss: the seed mint did not leave it Live", address)
}
// The loss commits on another connection while the first transaction is open.
lossCtx, cancelLoss := context.WithTimeout(ctx, 10*time.Second)
defer cancelLoss()
if err := store.LoseVersion(lossCtx, epochPublishStoreID, address); err != nil {
t.Fatalf("LoseVersion beside an open transaction: %v (if the engine now holds the loss back, the interleaving this test choreographs is prevented)", err)
}
// The first transaction now mints the same id, which is the same address.
minted, err := storeops.MintUnderEpochInTx(ctx, mintTx, epochPublishStoreID, epochPublishMintedID)
if err != nil {
t.Fatalf("mint inside the first transaction after the loss committed: %v: the transaction should still read the address Live from its own snapshot, and if it now sees the loss this test no longer exercises the interleaving it choreographs", err)
}
if minted != address {
t.Fatalf("mint returned %s, want the same address %s: minting the same id under the same epoch reproduces its address", minted, address)
}
if err := mintTx.Commit(); err != nil {
t.Fatalf("commit of the first transaction: %v: a mint must not write an existing row, so it has nothing to conflict with the loss", err)
}
serves, err = store.StillServes(ctx, epochPublishStoreID, address)
if err != nil {
t.Fatalf("StillServes: %v", err)
}
if serves {
t.Errorf("address %s is served again after a mint overlapped its loss: no interleaving may revive a lost address", address)
}
answer, err := store.Resolve(ctx, epochPublishStoreID, address)
if err != nil {
t.Fatalf("Resolve: %v", err)
}
if answer.Restriction != storeops.EpochRestrictionGoneReorganization {
t.Errorf("Resolve(%s) = %v, want EpochRestrictionGoneReorganization: the loss is the only change to the row", address, answer.Restriction)
}
}
// TestAMintRacingTheMintAndLossOfItsAddressConflictsAtCommit measures what
// upsertEpochMintedAddressInTx says about Dolt. One transaction reads before
// the address exists; another mints the address and loses it, and both commit;
// the first then mints the same id. Its snapshot holds no row at the address,
// so it inserts one, and the INSERT does not fail as a duplicate key: Dolt
// checks the key against the transaction's snapshot. The two inserts conflict at
// COMMIT instead (Error 1213), which withRetryTx answers by running the mint
// again, and run again against the committed row, the mint refuses the address
// (ErrEpochAddressNotServed) rather than reviving a lost one.
//
// If the first transaction's INSERT fails as a duplicate key, the engine now
// checks keys past the snapshot, and the re-read in
// upsertEpochMintedAddressInTx answers this race instead of the commit; if the
// commit succeeds, the engine merged the two rows, and the race needs another
// look.
func TestAMintRacingTheMintAndLossOfItsAddressConflictsAtCommit(t *testing.T) {
skipIfNoServer(t)
ctx, cancel := testContext(t)
defer cancel()
store := newMultiConnectionEpochStore(t, ctx, "epoch_mint_race")
// Seed the singleton so the first transaction's mint only reads the epoch.
if _, err := store.MintUnderEpoch(ctx, epochPublishStoreID, "seed"); err != nil {
t.Fatalf("seed mint: %v", err)
}
// The first transaction reads before the address exists and stays open.
mintTx, err := store.db.BeginTx(ctx, nil)
if err != nil {
t.Fatalf("begin the first transaction: %v", err)
}
defer func() { _ = mintTx.Rollback() }()
if _, err := storeops.CurrentEpochInTx(ctx, mintTx, epochPublishStoreID); err != nil {
t.Fatalf("CurrentEpochInTx inside the first transaction: %v", err)
}
// Another connection mints the address and loses it while the first is open.
otherCtx, cancelOther := context.WithTimeout(ctx, 10*time.Second)
defer cancelOther()
address, err := store.MintUnderEpoch(otherCtx, epochPublishStoreID, epochPublishMintedID)
if err != nil {
t.Fatalf("MintUnderEpoch beside an open transaction: %v", err)
}
if err := store.LoseVersion(otherCtx, epochPublishStoreID, address); err != nil {
t.Fatalf("LoseVersion beside an open transaction: %v", err)
}
// The first transaction mints the same id, which is the same address.
minted, err := storeops.MintUnderEpochInTx(ctx, mintTx, epochPublishStoreID, epochPublishMintedID)
if err != nil {
t.Fatalf("mint inside the first transaction: %v: the INSERT now sees a row committed after the transaction's snapshot, so the duplicate-key re-read answers this race, not the commit", err)
}
if minted != address {
t.Fatalf("mint returned %s, want the same address %s: minting the same id under the same epoch reproduces its address", minted, address)
}
err = mintTx.Commit()
if err == nil {
t.Fatalf("the first transaction committed its insert of %s over the committed, lost row: the engine merged the two inserts, and a lost address may come back", address)
}
if !isSerializationError(err) {
t.Fatalf("commit of the first transaction = %v, want a serialization failure (Error 1213), the conflict withRetryTx runs the mint again on", err)
}
// Run again, as withRetryTx runs it, the mint reads the committed row.
if _, err := store.MintUnderEpoch(ctx, epochPublishStoreID, epochPublishMintedID); !errors.Is(err, storeops.ErrEpochAddressNotServed) {
t.Errorf("mint of %s run again after the conflict = %v, want ErrEpochAddressNotServed: the committed row is lost", epochPublishMintedID, err)
}
serves, err := store.StillServes(ctx, epochPublishStoreID, address)
if err != nil {
t.Fatalf("StillServes: %v", err)
}
if serves {
t.Errorf("address %s is served again after a mint raced its mint and loss: no interleaving may revive a lost address", address)
}
}

View file

@ -8,11 +8,21 @@ import (
)
// TestExpectedRevisionContract wires this leg into the R16/R17
// expected-revision contract. Phase 0 leaves every hook nil in every
// backend's fixture kit (architecture §12), so each case below skips by
// name; this file exists so TestEveryLegWiresEveryRoleContract counts this
// leg, and so the cases start running for real the moment this leg's fixture
// kit grows a non-nil hook.
// expected-revision contract. Every hook is nil (architecture §12's Phase 0
// default), so each case below skips by name; this file exists so
// TestEveryLegWiresEveryRoleContract counts this leg, and so the cases
// start running for real the moment this leg grows a real
// CompareAndSetVersion (gastownhall/beads#6358).
//
// This leg previously wired every hook to an honest "not implemented" stub
// instead of leaving them nil, so each case ran for real and
// failed for that documented reason rather than skipping. That premise —
// that a later slice would give this leg its CompareAndSetVersion — went
// stale once review moved the real implementation to
// gastownhall/beads#6358 instead; a stub whose failure message blames a
// bead that will never land it is worse than an honest skip, so this file
// reverts to nil hooks (gastownhall/beads#6664, bee-ghosttrack review
// 5268699223).
func TestExpectedRevisionContract(t *testing.T) {
ctx := context.Background()
fixture := conformance.ExpectedRevisionFixture{IssuePrefix: "erev"}

View file

@ -5,6 +5,7 @@ import (
"testing"
"github.com/steveyegge/beads/backend/conformance"
storeops "github.com/steveyegge/beads/internal/storage/issueops"
)
// TestRetentionContract wires this leg into the R20 retention contract.
@ -57,11 +58,20 @@ func TestRetentionContract(t *testing.T) {
})
}
// TestEpochContract wires this leg into the R20 epoch contract. Same Phase 0
// all-nil state as TestRetentionContract above.
// TestEpochContract runs the R20 epoch contract (gastownhall/beads#5898
// revision 9, #6136) against the server-backed
// store, which reaches internal/storage/issueops's epoch Tx functions
// through this leg's own retrying write transaction or read transaction
// (DoltStore.BumpEpoch/BumpEpochCarrying/MintUnderEpoch/LoseVersion and
// DoltStore.CurrentEpoch/StillServes/Resolve/CurrentAddressFor) — see
// internal/storage/dolt/epoch_cas.go.
//
// All three legs run that one shared body, so this is not an independent
// vote on the design — it is the check on THIS leg's wrapper and this file's
// own conformance-vocabulary translation.
func TestEpochContract(t *testing.T) {
ctx := context.Background()
fixture := conformance.EpochFixture{IssuePrefix: "epch"}
fixture, ctx, cleanup := newEpochDoltFixture(t, "epch")
defer cleanup()
t.Run("AnEpochBumpIsTriggeredOnlyByRestoreReinitOrSchemeChange", func(t *testing.T) {
conformance.RunAnEpochBumpIsTriggeredOnlyByRestoreReinitOrSchemeChange(t, ctx, fixture)
@ -69,4 +79,127 @@ func TestEpochContract(t *testing.T) {
t.Run("EpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed", func(t *testing.T) {
conformance.RunEpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed(t, ctx, fixture)
})
t.Run("TokenSchemeChangeCarriesLiveAddressesAndOnlyThose", func(t *testing.T) {
conformance.RunTokenSchemeChangeCarriesLiveAddressesAndOnlyThose(t, ctx, fixture)
})
t.Run("ACarriedAddressKeepsResolvingAcrossLaterBumps", func(t *testing.T) {
conformance.RunACarriedAddressKeepsResolvingAcrossLaterBumps(t, ctx, fixture)
})
t.Run("ALostAddressStaysGoneAcrossASchemeChange", func(t *testing.T) {
conformance.RunALostAddressStaysGoneAcrossASchemeChange(t, ctx, fixture)
})
}
// newEpochDoltFixture wires this leg's *DoltStore into the R20 epoch
// contract. Like newExpectedRevisionDoltFixture, this fixture needs none of
// roleFixtureKit's CreateIssue/CreateWisp/QueryScalar/CountHistory hooks —
// it has no fields for them — so it does not route through
// newDoltRoleFixtureKit at all; IssuePrefix is set directly, the same value
// the kit would have set verbatim.
func newEpochDoltFixture(t *testing.T, prefix string) (conformance.EpochFixture, context.Context, func()) {
t.Helper()
skipIfNoServer(t)
// A database of its own, not setupTestStore's branch on the shared one. The
// shared database's schema-init lock has a five-second acquire timeout, and a
// setup that queues behind another parallel test's runs out of it under load.
// The context is built after the open, so the open cannot drain its deadline.
openCtx, cancelOpen := testContext(t)
store := newMultiConnectionEpochStore(t, openCtx, "epoch_contract")
cancelOpen()
ctx, cancel := testContext(t)
return conformance.EpochFixture{
IssuePrefix: prefix,
CurrentEpoch: epochDoltCurrentEpoch(store),
BumpEpoch: epochDoltBumpEpoch(store),
MintUnderEpoch: epochDoltMintUnderEpoch(store),
StillServes: epochDoltStillServes(store),
Resolve: epochDoltResolve(store),
CurrentAddressFor: epochDoltCurrentAddressFor(store),
LoseVersion: epochDoltLoseVersion(store),
}, ctx, cancel
}
func epochDoltCurrentEpoch(store *DoltStore) func(ctx context.Context, storeID string) (int, error) {
return func(ctx context.Context, storeID string) (int, error) {
return store.CurrentEpoch(ctx, storeID)
}
}
// epochDoltBumpEpoch dispatches on the typed trigger: a token-scheme change is
// the one bump that also carries every live address to the new epoch, and a
// restore or destructive reinit advances only the counter. The dispatch lives
// in this file, the translation boundary, because the shared body has no
// switch on the reason string.
func epochDoltBumpEpoch(store *DoltStore) func(ctx context.Context, storeID string, trigger conformance.EpochBumpTrigger) (int, error) {
return func(ctx context.Context, storeID string, trigger conformance.EpochBumpTrigger) (int, error) {
if trigger == conformance.EpochBumpTriggerTokenSchemeChange {
return store.BumpEpochCarrying(ctx, storeID, trigger.String())
}
return store.BumpEpoch(ctx, storeID, trigger.String())
}
}
func epochDoltMintUnderEpoch(store *DoltStore) func(ctx context.Context, storeID, id string) (conformance.Address, error) {
return func(ctx context.Context, storeID, id string) (conformance.Address, error) {
address, err := store.MintUnderEpoch(ctx, storeID, id)
if err != nil {
return "", err
}
return conformance.Address(address), nil
}
}
func epochDoltStillServes(store *DoltStore) func(ctx context.Context, storeID string, address conformance.Address) (bool, error) {
return func(ctx context.Context, storeID string, address conformance.Address) (bool, error) {
return store.StillServes(ctx, storeID, string(address))
}
}
func epochDoltResolve(store *DoltStore) func(ctx context.Context, storeID string, address conformance.Address) (conformance.RetentionAnswer, error) {
return func(ctx context.Context, storeID string, address conformance.Address) (conformance.RetentionAnswer, error) {
result, err := store.Resolve(ctx, storeID, string(address))
if err != nil {
return conformance.RetentionAnswer{}, err
}
return epochResolveResultToConformance(result), nil
}
}
func epochDoltCurrentAddressFor(store *DoltStore) func(ctx context.Context, storeID string, oldAddress conformance.Address) (conformance.Address, error) {
return func(ctx context.Context, storeID string, oldAddress conformance.Address) (conformance.Address, error) {
address, err := store.CurrentAddressFor(ctx, storeID, string(oldAddress))
if err != nil {
return "", err
}
return conformance.Address(address), nil
}
}
func epochDoltLoseVersion(store *DoltStore) func(ctx context.Context, storeID string, address conformance.Address) error {
return func(ctx context.Context, storeID string, address conformance.Address) error {
return store.LoseVersion(ctx, storeID, string(address))
}
}
// epochRestrictionToConformance translates this leg's local
// storeops.EpochRestriction into backend/conformance's own Restriction
// vocabulary — the contract-test file is the translation boundary, per
// epoch_cas.go's package doc.
func epochRestrictionToConformance(r storeops.EpochRestriction) conformance.Restriction {
switch r {
case storeops.EpochRestrictionLive:
return conformance.RestrictionLive
case storeops.EpochRestrictionGoneReorganization:
return conformance.RestrictionGoneReorganization
default:
return conformance.RestrictionUnknown
}
}
func epochResolveResultToConformance(r storeops.EpochResolveResult) conformance.RetentionAnswer {
return conformance.RetentionAnswer{
Restriction: epochRestrictionToConformance(r.Restriction),
ProducingStore: r.ProducingStore,
Epoch: r.Epoch,
}
}

View file

@ -26,6 +26,7 @@ go_library(
"dependency_editor.go",
"detection.go",
"edgereader.go",
"epoch_cas.go",
"federation.go",
"get_issue.go",
"graph_counter.go",
@ -150,6 +151,8 @@ go_test(
"dualwrite_history_contract_test.go",
"dualwrite_participation_generation_contract_test.go",
"edge_reader_contract_test.go",
"epoch_cas_publish_internal_test.go",
"epoch_cas_status_test.go",
"events_since_test.go",
"expected_revision_contract_test.go",
"external_dependencies_test.go",

View file

@ -0,0 +1,197 @@
//go:build cgo
package embeddeddolt
import (
"context"
"database/sql"
"errors"
"fmt"
"github.com/steveyegge/beads/internal/storage"
storeops "github.com/steveyegge/beads/internal/storage/issueops"
)
// CurrentEpoch, BumpEpoch, BumpEpochCarrying, MintUnderEpoch, LoseVersion,
// StillServes, Resolve and CurrentAddressFor give this leg R20's
// epoch-transition enforcement
// (gastownhall/beads#5898 revision 9, #6136),
// backed by store_epoch (migration 0067) and epoch_minted_addresses
// (migration 0072). See internal/storage/dolt/epoch_cas.go's matching
// header comment for why these are direct methods on *EmbeddedDoltStore
// rather than a wrapper struct or root-storage-package types.
//
// The writers publish after their SQL transaction commits, and a failed Dolt
// commit is returned (runTransactionWithMessage), so all four meet the
// ordering the server leg is held to. They also return what the server leg
// returns once the SQL commit has landed or may have: runTransactionWithMessage
// wraps every such error in storage.ErrCommitIndeterminate, and a bump hands
// back the epoch its body set (failedBump) and a mint its address, never the
// zero value that would read as nothing applied. Unlike the server leg's mint,
// which logs a failed Dolt commit, this mint returns it, as every write on this
// leg does. A mint must still stage store_epoch (storeops.EpochMintDirtyTables):
// its first use inserts the singleton row.
// CurrentEpoch reports storeID's current epoch generation.
//
// The epoch counter is per database, not per store. storeID appears only in
// error text; one bump advances the epoch seen through every storeID that
// shares this database.
func (s *EmbeddedDoltStore) CurrentEpoch(ctx context.Context, storeID string) (int, error) {
var epoch int
if err := s.withConn(ctx, false, func(tx *sql.Tx) error {
var err error
epoch, err = storeops.CurrentEpochInTx(ctx, tx, storeID)
return err
}); err != nil {
return 0, err
}
return epoch, nil
}
// BumpEpoch advances storeID's epoch generation by one for reason. An error
// wrapping storage.ErrCommitIndeterminate comes back with the epoch the bump
// committed, or may have: the caller must not bump again to retry.
//
// The epoch counter is per database, not per store. storeID appears only in
// error text; one bump advances the epoch seen through every storeID that
// shares this database.
func (s *EmbeddedDoltStore) BumpEpoch(ctx context.Context, storeID, reason string) (int, error) {
var epoch int
if err := s.runIssueOperationTxWithMessage(ctx, func(tx *sql.Tx) (storeops.ChangedTables, string, error) {
var err error
epoch, err = storeops.BumpEpochInTx(ctx, tx, storeID, reason)
if err != nil {
return nil, "", err
}
return storeops.ChangedTables{"store_epoch": true},
fmt.Sprintf("bd: bump epoch for %s (%s)", storeID, reason), nil
}); err != nil {
return failedBump(storeID, epoch, err)
}
return epoch, nil
}
// failedBump is what a bump returns when it fails. An error wrapping
// storage.ErrCommitIndeterminate comes from a body that ran to completion and a
// SQL commit that landed or may have (runTransactionWithMessage), so the epoch
// that body set is returned with it, and the caller reads CurrentEpoch to learn
// which. Any other error means nothing landed.
func failedBump(storeID string, epoch int, err error) (int, error) {
if errors.Is(err, storage.ErrCommitIndeterminate) {
return epoch, fmt.Errorf("epoch bump for %s may have applied (epoch %d): %w", storeID, epoch, err)
}
return 0, err
}
// BumpEpochCarrying is the token-scheme-change bump: BumpEpoch, and also the
// carry of every live address in the database to the new epoch
// (storeops.BumpEpochCarryingInTx). It writes store_epoch and
// epoch_minted_addresses, so it publishes both.
//
// The epoch counter is per database, not per store. storeID appears only in
// error text; one bump advances the epoch seen through every storeID that
// shares this database.
//
// It fails as BumpEpoch does (failedBump).
//
// CALLERS MUST HOLD THE WORKSPACE GATE (internal/workspacegate) EXCLUSIVELY FOR
// THE BUMP, as a restore does: see storeops.BumpEpochCarryingInTx.
func (s *EmbeddedDoltStore) BumpEpochCarrying(ctx context.Context, storeID, reason string) (int, error) {
var epoch int
if err := s.runIssueOperationTxWithMessage(ctx, func(tx *sql.Tx) (storeops.ChangedTables, string, error) {
var err error
epoch, err = storeops.BumpEpochCarryingInTx(ctx, tx, storeID, reason)
if err != nil {
return nil, "", err
}
return storeops.ChangedTables{"store_epoch": true, "epoch_minted_addresses": true},
fmt.Sprintf("bd: carry addresses to epoch %d for %s (%s)", epoch, storeID, reason), nil
}); err != nil {
return failedBump(storeID, epoch, err)
}
return epoch, nil
}
// MintUnderEpoch mints id's address under storeID's current epoch. An error
// wrapping storage.ErrCommitIndeterminate comes back with the address the mint
// committed, or may have; StillServes says whether it did.
//
// Embedded transactions serialize (see recheckBlockedAfterCommit), so a mint
// cannot overlap a BumpEpoch here the way it can on the server leg (see
// TestMintOverlappingABumpLeavesALiveSurvivor in the dolt package).
func (s *EmbeddedDoltStore) MintUnderEpoch(ctx context.Context, storeID, id string) (string, error) {
var address string
if err := s.runIssueOperationTxWithMessage(ctx, func(tx *sql.Tx) (storeops.ChangedTables, string, error) {
var err error
address, err = storeops.MintUnderEpochInTx(ctx, tx, storeID, id)
if err != nil {
return nil, "", err
}
return storeops.EpochMintDirtyTables(),
fmt.Sprintf("bd: mint %s under epoch for %s", id, storeID), nil
}); err != nil {
if errors.Is(err, storage.ErrCommitIndeterminate) {
return address, err
}
return "", err
}
return address, nil
}
// StillServes reports whether address is still served under storeID's
// current epoch.
func (s *EmbeddedDoltStore) StillServes(ctx context.Context, storeID, address string) (bool, error) {
var serves bool
if err := s.withConn(ctx, false, func(tx *sql.Tx) error {
var err error
serves, err = storeops.StillServesInTx(ctx, tx, storeID, address)
return err
}); err != nil {
return false, err
}
return serves, nil
}
// Resolve answers R20's epoch-only restriction for address.
func (s *EmbeddedDoltStore) Resolve(ctx context.Context, storeID, address string) (storeops.EpochResolveResult, error) {
var result storeops.EpochResolveResult
if err := s.withConn(ctx, false, func(tx *sql.Tx) error {
var err error
result, err = storeops.ResolveEpochInTx(ctx, tx, storeID, address)
return err
}); err != nil {
return storeops.EpochResolveResult{}, err
}
return result, nil
}
// CurrentAddressFor reports the address oldAddress now resolves to: the newest
// address of its lineage, or oldAddress itself when nothing carried it. It only
// reads, so it runs on a read-only connection and publishes nothing.
func (s *EmbeddedDoltStore) CurrentAddressFor(ctx context.Context, storeID, oldAddress string) (string, error) {
var address string
if err := s.withConn(ctx, false, func(tx *sql.Tx) error {
var err error
address, err = storeops.CurrentAddressForInTx(ctx, tx, storeID, oldAddress)
return err
}); err != nil {
return "", err
}
return address, nil
}
// LoseVersion records that storeID no longer serves the Version named by
// address (storeops.LoseVersionInTx). It writes epoch_minted_addresses, so it
// publishes that table, and a failed Dolt commit is returned, wrapping
// storage.ErrCommitIndeterminate: a loss its caller believes recorded must not
// be left unpublished.
func (s *EmbeddedDoltStore) LoseVersion(ctx context.Context, storeID, address string) error {
return s.runIssueOperationTxWithMessage(ctx, func(tx *sql.Tx) (storeops.ChangedTables, string, error) {
if err := storeops.LoseVersionInTx(ctx, tx, storeID, address); err != nil {
return nil, "", err
}
return storeops.ChangedTables{"epoch_minted_addresses": true},
fmt.Sprintf("bd: lose version %s for %s", address, storeID), nil
})
}

View file

@ -0,0 +1,141 @@
//go:build cgo
package embeddeddolt
import (
"context"
"errors"
"path/filepath"
"testing"
"github.com/steveyegge/beads/internal/storage"
)
// These tests are this leg's half of the publication-failure rule for the R20
// epoch writers (gastownhall/beads#6664); the server leg's half is
// internal/storage/dolt/epoch_cas_publish_test.go. A write whose SQL commit has
// landed and whose Dolt commit then fails must wrap
// storage.ErrCommitIndeterminate and hand back what it applied, so that nothing
// replays a bump that has already advanced the counter.
// withFailedPublication runs write with every Dolt commit after its SQL commit
// refused: afterSQLCommit marks store read-only in that window, so the rows have
// landed when withMutatingDBConn refuses to stage and commit them.
func withFailedPublication(t *testing.T, store *EmbeddedDoltStore, write func()) {
t.Helper()
saved := afterSQLCommit
afterSQLCommit = func() { store.readOnly = true }
defer func() {
afterSQLCommit = saved
store.readOnly = false
}()
write()
}
func TestEpochWritesReportAnUnpublishedCommitAsIndeterminate(t *testing.T) {
skipUnlessEmbeddedDolt(t)
ctx := context.Background()
store, err := Open(ctx, filepath.Join(t.TempDir(), ".beads"), "epochpub", "main")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = store.Close() })
const storeID = "epochpub-store"
requireUnpublished := func(t *testing.T, name string, err error) {
t.Helper()
if !errors.Is(err, ErrReadOnly) {
t.Fatalf("%s = %v, want the refused Dolt commit (ErrReadOnly)", name, err)
}
if !errors.Is(err, storage.ErrCommitIndeterminate) {
t.Fatalf("%s = %v, want it to wrap storage.ErrCommitIndeterminate: the write has applied, and a caller that takes the error for a write that did not would replay it", name, err)
}
}
currentEpoch := func(t *testing.T) int {
t.Helper()
epoch, err := store.CurrentEpoch(ctx, storeID)
if err != nil {
t.Fatalf("CurrentEpoch: %v", err)
}
return epoch
}
stillServes := func(t *testing.T, address string) bool {
t.Helper()
serves, err := store.StillServes(ctx, storeID, address)
if err != nil {
t.Fatalf("StillServes(%s): %v", address, err)
}
return serves
}
for _, tc := range []struct {
name string
bump func(ctx context.Context, storeID, reason string) (int, error)
}{
{name: "BumpEpoch", bump: store.BumpEpoch},
{name: "BumpEpochCarrying", bump: store.BumpEpochCarrying},
} {
t.Run(tc.name, func(t *testing.T) {
before := currentEpoch(t)
var epoch int
var err error
withFailedPublication(t, store, func() {
epoch, err = tc.bump(ctx, storeID, "publication fails")
})
requireUnpublished(t, tc.name, err)
if epoch != before+1 {
t.Errorf("%s returned epoch %d with the publication error, want %d: the bump applied, the error only says its Dolt commit did not", tc.name, epoch, before+1)
}
if got := currentEpoch(t); got != before+1 {
t.Errorf("CurrentEpoch after an unpublished %s = %d, want %d", tc.name, got, before+1)
}
})
}
t.Run("MintUnderEpoch", func(t *testing.T) {
var address string
var err error
withFailedPublication(t, store, func() {
address, err = store.MintUnderEpoch(ctx, storeID, "record-a")
})
requireUnpublished(t, "MintUnderEpoch", err)
if address == "" {
t.Fatal("MintUnderEpoch returned no address with the publication error, want the address it minted")
}
if !stillServes(t, address) {
t.Errorf("StillServes(%s) = false after an unpublished mint, want the minted address served", address)
}
})
t.Run("LoseVersion", func(t *testing.T) {
address, err := store.MintUnderEpoch(ctx, storeID, "record-b")
if err != nil {
t.Fatalf("MintUnderEpoch: %v", err)
}
withFailedPublication(t, store, func() {
err = store.LoseVersion(ctx, storeID, address)
})
requireUnpublished(t, "LoseVersion", err)
if stillServes(t, address) {
t.Errorf("StillServes(%s) = true after an unpublished loss, want the loss applied", address)
}
})
// A write refused before its SQL commit applied nothing, so its error must
// not claim it may have.
t.Run("a bump refused before its SQL commit", func(t *testing.T) {
before := currentEpoch(t)
store.readOnly = true
epoch, err := store.BumpEpoch(ctx, storeID, "refused")
store.readOnly = false
if !errors.Is(err, ErrReadOnly) || errors.Is(err, storage.ErrCommitIndeterminate) {
t.Fatalf("BumpEpoch on a read-only store = %v, want ErrReadOnly, not marked storage.ErrCommitIndeterminate", err)
}
if epoch != 0 {
t.Errorf("BumpEpoch on a read-only store returned epoch %d, want 0", epoch)
}
if got := currentEpoch(t); got != before {
t.Errorf("CurrentEpoch after a refused bump = %d, want %d", got, before)
}
})
}

View file

@ -0,0 +1,562 @@
//go:build cgo
package embeddeddolt_test
import (
"context"
"database/sql"
"fmt"
"slices"
"testing"
"github.com/steveyegge/beads/internal/storage"
storeops "github.com/steveyegge/beads/internal/storage/issueops"
)
// These tests are the embedded-leg half of gastownhall/beads#6664 Major 2
// (bee-ghosttrack, review 5360880888).
// MintUnderEpoch and CurrentAddressFor staged only epoch_minted_addresses,
// while ensureStoreEpochRow lazily inserts store_epoch's singleton row on
// first use, so that row stayed modified and uncommitted. The embedded leg
// never published inside the transaction as the server leg did; it is not free
// of this omission.
//
// The tests after those run the rest of the epoch write surface on the real
// engine: the token-scheme-change carry (BumpEpochCarrying), the explicit loss
// (LoseVersion), and CurrentAddressFor, which only reads. They check what the
// statement-level unit tests cannot: set semantics across rows, a bump that
// rolls back, and what the working set holds once each write is published.
// epochTablesInWorkingSet lists the R20 epoch tables that still appear in
// dolt_status, staged or not: after a write has been published, neither may.
func epochTablesInWorkingSet(status *storage.Status) []string {
var dirty []string
for _, entry := range append(slices.Clone(status.Staged), status.Unstaged...) {
if entry.Table == "store_epoch" || entry.Table == "epoch_minted_addresses" {
dirty = append(dirty, fmt.Sprintf("%s (%s)", entry.Table, entry.Status))
}
}
return dirty
}
// TestFirstMintLeavesTheEpochTablesCommitted reproduces bee-ghosttrack's probe
// (Status() after the first mint on a fresh store read
// unstaged=[{store_epoch modified}]) on the embedded leg.
func TestFirstMintLeavesTheEpochTablesCommitted(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
// A pristine store: store_epoch has no row, so this mint is what seeds it.
if _, err := te.store.MintUnderEpoch(ctx, "epoch-store", "record-a"); err != nil {
t.Fatalf("MintUnderEpoch on a fresh store: %v", err)
}
status, err := te.store.Status(ctx)
if err != nil {
t.Fatalf("Status: %v", err)
}
if dirty := epochTablesInWorkingSet(status); len(dirty) > 0 {
t.Errorf("after the first mint the working set still holds %v: the mint's Dolt commit must include the singleton row it seeded", dirty)
}
}
// TestCurrentAddressForNeverReseedsAnAbsentStoreEpochRow is the successor of the
// test that pinned CurrentAddressFor committing a store_epoch row it re-seeded.
// CurrentAddressFor no longer writes anything (gastownhall/beads#6664,
// bee-ghosttrack review 5360880888, Major 1: a lookup must not mint), so the
// same setup now pins the opposite. A store whose singleton row is absent is
// legitimate state — migration 0067 starts the table empty and treats "no row"
// as epoch 1 — and CurrentAddressFor answers from that default: it returns the
// address it was given, leaves the working set clean, and does not create the
// row.
func TestCurrentAddressForNeverReseedsAnAbsentStoreEpochRow(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
address, err := te.store.MintUnderEpoch(ctx, "epoch-store", "record-a")
if err != nil {
t.Fatalf("MintUnderEpoch: %v", err)
}
// Settle everything so far, then leave the singleton row absent with a
// clean working set.
if _, err := te.store.CommitAll(ctx, "test: settle the first mint"); err != nil {
t.Fatalf("CommitAll: %v", err)
}
te.exec(t, ctx, "DELETE FROM store_epoch")
if _, err := te.store.CommitAll(ctx, "test: absent singleton row"); err != nil {
t.Fatalf("CommitAll: %v", err)
}
got, err := te.store.CurrentAddressFor(ctx, "epoch-store", address)
if err != nil {
t.Fatalf("CurrentAddressFor: %v", err)
}
if got != address {
t.Errorf("CurrentAddressFor = %s, want the address it was given (%s): nothing carried the Version, so it resolves to itself", got, address)
}
var rows int
te.queryScalar(t, ctx, "SELECT COUNT(*) FROM store_epoch", nil, &rows)
if rows != 0 {
t.Errorf("store_epoch holds %d rows after CurrentAddressFor, want 0: a lookup must not re-create the singleton row", rows)
}
status, err := te.store.Status(ctx)
if err != nil {
t.Fatalf("Status: %v", err)
}
if dirty := epochTablesInWorkingSet(status); len(dirty) > 0 {
t.Errorf("after CurrentAddressFor the working set holds %v: a lookup changes nothing, so there is nothing to commit", dirty)
}
}
// TestBumpEpochCarryingLeavesTheEpochTablesCommitted is the publication rule
// for the token-scheme-change bump. It writes store_epoch (the counter) and
// epoch_minted_addresses (the carry rows), so its Dolt commit has to stage
// both: a bump that staged only store_epoch would leave the carry rows
// modified and uncommitted.
func TestBumpEpochCarryingLeavesTheEpochTablesCommitted(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
const store = "epoch-store"
epochMint(t, ctx, te, store, "record-a")
newEpoch := epochCarry(t, ctx, te, store)
// The carry has to have happened for the check below to mean anything.
if got := epochRowsAt(t, ctx, te, store, newEpoch); got != 1 {
t.Fatalf("after the carrying bump to epoch %d the store holds %d rows minted at that epoch, want 1 carry row", newEpoch, got)
}
status, err := te.store.Status(ctx)
if err != nil {
t.Fatalf("Status: %v", err)
}
if dirty := epochTablesInWorkingSet(status); len(dirty) > 0 {
t.Errorf("after the carrying bump the working set still holds %v: its Dolt commit must include the carry rows as well as the counter", dirty)
}
}
// TestLoseVersionLeavesTheEpochTablesCommitted is the same rule for an explicit
// loss, which writes epoch_minted_addresses alone: a loss the caller believes
// recorded must not be left modified and uncommitted.
func TestLoseVersionLeavesTheEpochTablesCommitted(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
const store = "epoch-store"
address := epochMint(t, ctx, te, store, "record-a")
if err := te.store.LoseVersion(ctx, store, address); err != nil {
t.Fatalf("LoseVersion: %v", err)
}
// The loss has to have been recorded for the check below to mean anything.
epoch, err := te.store.CurrentEpoch(ctx, store)
if err != nil {
t.Fatalf("CurrentEpoch: %v", err)
}
epochRequireGone(t, ctx, te, store, address, epoch, "LoseVersion recorded the loss of this address")
status, err := te.store.Status(ctx)
if err != nil {
t.Fatalf("Status: %v", err)
}
if dirty := epochTablesInWorkingSet(status); len(dirty) > 0 {
t.Errorf("after LoseVersion the working set still holds %v: the loss must be published with the row it changed", dirty)
}
}
// TestBumpEpochCarryingWritesOneCarryRowPerLiveIDNamingTheLineageRoot pins the
// write surface of the token-scheme-change bump on the real engine
// (gastownhall/beads#6664, bee-ghosttrack review 5360880888, Major 1): the bump
// records the carry itself, one row per live id at the new epoch, instead of
// leaving it to be inferred from a later mint. Each carry row names the lineage
// ROOT in carried_from, so a second carry still names the first root, lineages
// stay flat, and every address of a lineage is one lookup from the newest.
func TestBumpEpochCarryingWritesOneCarryRowPerLiveIDNamingTheLineageRoot(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
const store = "epoch-store"
rootA := epochMint(t, ctx, te, store, "record-a")
rootB := epochMint(t, ctx, te, store, "record-b")
firstEpoch := epochCarry(t, ctx, te, store)
if got := epochRowsAt(t, ctx, te, store, firstEpoch); got != 2 {
t.Fatalf("after the carrying bump to epoch %d the store holds %d rows minted at that epoch, want 2: one carry row per live id", firstEpoch, got)
}
carryA := epochRowAddress(t, ctx, te, store, "record-a", firstEpoch)
carryB := epochRowAddress(t, ctx, te, store, "record-b", firstEpoch)
for _, c := range []struct{ id, carry, root string }{
{"record-a", carryA, rootA},
{"record-b", carryB, rootB},
} {
if carriedFrom := epochCarriedFrom(t, ctx, te, c.carry); !carriedFrom.Valid || carriedFrom.String != c.root {
t.Errorf("the carry row of %s names carried_from %v, want its root %s", c.id, carriedFrom, c.root)
}
if goneAt := epochGoneAt(t, ctx, te, c.carry); goneAt.Valid {
t.Errorf("the carry row of %s is already marked gone at epoch %d, want it live", c.id, goneAt.Int64)
}
}
for _, c := range []struct{ old, carry string }{{rootA, carryA}, {rootB, carryB}} {
if got, err := te.store.CurrentAddressFor(ctx, store, c.old); err != nil || got != c.carry {
t.Errorf("CurrentAddressFor(%s) = %q, %v, want the carry address %s", c.old, got, err, c.carry)
}
epochRequireServed(t, ctx, te, store, c.old, "the old address keeps resolving through the carry")
epochRequireServed(t, ctx, te, store, c.carry, "the carry address is served under the new epoch")
}
// A second carry still names the first ROOT, not the previous carry row.
secondEpoch := epochCarry(t, ctx, te, store)
secondCarryA := epochRowAddress(t, ctx, te, store, "record-a", secondEpoch)
if carriedFrom := epochCarriedFrom(t, ctx, te, secondCarryA); !carriedFrom.Valid || carriedFrom.String != rootA {
t.Errorf("the second carry row of record-a names carried_from %v, want the first root %s: carried_from names the root, never the previous carry", carriedFrom, rootA)
}
for _, member := range []string{rootA, carryA} {
if got, err := te.store.CurrentAddressFor(ctx, store, member); err != nil || got != secondCarryA {
t.Errorf("CurrentAddressFor(%s) = %q, %v, want %s: every address of the lineage points straight at the newest one", member, got, err, secondCarryA)
}
}
}
// TestBumpEpochCarryingCarriesOnlyTheLineageHoldingTheNewestRow pins the
// collision rule. A mint never retires an address, so one id can have two live
// lineages: here a second root minted after a restore. Both cannot receive an
// address, because an address is a function of the store, the id and the epoch
// and so is one per id per epoch. The lineage holding the newest row is
// carried, and the other is marked gone at the bump's epoch: over-voiding is
// the safe direction, reviving is not.
func TestBumpEpochCarryingCarriesOnlyTheLineageHoldingTheNewestRow(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
const store = "epoch-store"
first := epochMint(t, ctx, te, store, "record-x")
epochBump(t, ctx, te, store)
second := epochMint(t, ctx, te, store, "record-x")
if first == second {
t.Fatalf("minting record-x again after a bump returned %s, want a second root for the new epoch", first)
}
newEpoch := epochCarry(t, ctx, te, store)
carry := epochRowAddress(t, ctx, te, store, "record-x", newEpoch)
if carriedFrom := epochCarriedFrom(t, ctx, te, carry); !carriedFrom.Valid || carriedFrom.String != second {
t.Errorf("the carry row names carried_from %v, want %s: the lineage holding the newest row is the one carried", carriedFrom, second)
}
if goneAt := epochGoneAt(t, ctx, te, first); !goneAt.Valid || goneAt.Int64 != int64(newEpoch) {
t.Errorf("the losing lineage's root has gone_at_epoch %v, want %d: it is marked gone at the epoch of the bump", goneAt, newEpoch)
}
if rows := epochCarryRowsOf(t, ctx, te, first); rows != 0 {
t.Errorf("%d carry rows name the losing lineage's root, want 0: a lineage that lost the collision is not carried", rows)
}
epochRequireGone(t, ctx, te, store, first, newEpoch, "the lineage that lost the collision is no longer served")
epochRequireServed(t, ctx, te, store, second, "the lineage holding the newest row is still served")
if got, err := te.store.CurrentAddressFor(ctx, store, second); err != nil || got != carry {
t.Errorf("CurrentAddressFor(%s) = %q, %v, want the carry address %s", second, got, err, carry)
}
if got, err := te.store.CurrentAddressFor(ctx, store, first); err == nil {
t.Errorf("CurrentAddressFor(the losing lineage's root) = %s with no error, want an error: a lost lineage has no current address", got)
}
}
// TestBumpEpochCarryingNeitherCarriesNorServesARowFromAFutureEpoch pins how the
// carry treats an anomaly a rewound counter can leave behind: a row minted in
// an epoch that has not happened yet. It is not carried, and it is not served
// either: a status read fails closed rather than trusting it. The carried live
// row beside it is what makes the check mean anything.
func TestBumpEpochCarryingNeitherCarriesNorServesARowFromAFutureEpoch(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
const store = "epoch-store"
live := epochMint(t, ctx, te, store, "record-a")
future := epochMint(t, ctx, te, store, "record-future")
te.exec(t, ctx, "UPDATE epoch_minted_addresses SET minted_epoch = minted_epoch + 5 WHERE address = ?", future)
newEpoch := epochCarry(t, ctx, te, store)
if got := epochRowsAt(t, ctx, te, store, newEpoch); got != 1 {
t.Fatalf("after the carrying bump to epoch %d the store holds %d rows minted at that epoch, want 1: the live row is carried and the row from a future epoch is not", newEpoch, got)
}
carry := epochRowAddress(t, ctx, te, store, "record-a", newEpoch)
if carriedFrom := epochCarriedFrom(t, ctx, te, carry); !carriedFrom.Valid || carriedFrom.String != live {
t.Errorf("the carry row names carried_from %v, want %s", carriedFrom, live)
}
if rows := epochCarryRowsOf(t, ctx, te, future); rows != 0 {
t.Errorf("%d carry rows name the future-epoch row, want 0: a row from an epoch that has not happened is not carried", rows)
}
epochRequireServed(t, ctx, te, store, live, "the live row is served")
epochRequireGone(t, ctx, te, store, future, newEpoch, "a row minted in an epoch that has not happened yet fails closed")
}
// TestBumpEpochCarryingFailsAndRollsBackWhenARowAlreadyExistsAtTheNewEpoch pins
// the one place a duplicate key always fails the write. A mint whose insert
// collides with a row reads it and keeps the address when the row is served,
// but a row already sitting at the carry's address means the epoch counter
// rewound. The bump must then fail and roll back whole, including its increment
// of the counter, rather than report a carry it did not make.
func TestBumpEpochCarryingFailsAndRollsBackWhenARowAlreadyExistsAtTheNewEpoch(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
const store = "epoch-store"
epochMint(t, ctx, te, store, "record-a")
startEpoch, err := te.store.CurrentEpoch(ctx, store)
if err != nil {
t.Fatalf("CurrentEpoch: %v", err)
}
nextEpoch := epochBump(t, ctx, te, store)
epochMint(t, ctx, te, store, "record-a") // a row now exists at nextEpoch
te.exec(t, ctx, "UPDATE store_epoch SET epoch = ? WHERE id = 1", startEpoch)
if got, err := te.store.BumpEpochCarrying(ctx, store, "token-scheme-change"); err == nil {
t.Errorf("BumpEpochCarrying = epoch %d with no error although a row already exists at epoch %d: the counter rewound, so the carry must fail the bump", got, nextEpoch)
}
epoch, err := te.store.CurrentEpoch(ctx, store)
if err != nil {
t.Fatalf("CurrentEpoch: %v", err)
}
if epoch != startEpoch {
t.Errorf("CurrentEpoch = %d after the failed bump, want %d: a failed carry rolls the counter's increment back with it", epoch, startEpoch)
}
}
// TestBumpEpochCarryingCarriesTheLiveRowsOfEveryStoreInTheDatabase pins why the
// carry is database-wide. The epoch counter is per database, so one bump moves
// the epoch seen through every storeID; carrying only the rows of the storeID
// that asked would strand every other store's addresses at the scheme boundary.
func TestBumpEpochCarryingCarriesTheLiveRowsOfEveryStoreInTheDatabase(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
const first, second = "epoch-store-one", "epoch-store-two"
oldFirst := epochMint(t, ctx, te, first, "record-a")
oldSecond := epochMint(t, ctx, te, second, "record-b")
newEpoch := epochCarry(t, ctx, te, first) // made under the first storeID only
for _, c := range []struct{ store, id, old string }{
{first, "record-a", oldFirst},
{second, "record-b", oldSecond},
} {
carry := epochRowAddress(t, ctx, te, c.store, c.id, newEpoch)
if carriedFrom := epochCarriedFrom(t, ctx, te, carry); !carriedFrom.Valid || carriedFrom.String != c.old {
t.Errorf("the carry row of %s in %s names carried_from %v, want its root %s", c.id, c.store, carriedFrom, c.old)
}
if got, err := te.store.CurrentAddressFor(ctx, c.store, c.old); err != nil || got != carry {
t.Errorf("CurrentAddressFor(%s) in %s = %q, %v, want the carry address %s", c.old, c.store, got, err, carry)
}
epochRequireServed(t, ctx, te, c.store, c.old, "the old address keeps resolving through the carry")
epochRequireServed(t, ctx, te, c.store, carry, "the carry address is served under the new epoch")
}
}
// TestBumpEpochCarryingDoesNotCarryALostLineage pins that loss is terminal for
// the carry: a lineage the store lost before the bump gets no carry row and
// stays Gone, while the live lineage beside it is carried.
func TestBumpEpochCarryingDoesNotCarryALostLineage(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
const store = "epoch-store"
kept := epochMint(t, ctx, te, store, "record-kept")
lost := epochMint(t, ctx, te, store, "record-lost")
if err := te.store.LoseVersion(ctx, store, lost); err != nil {
t.Fatalf("LoseVersion(%s): %v", lost, err)
}
newEpoch := epochCarry(t, ctx, te, store)
if got := epochRowsAt(t, ctx, te, store, newEpoch); got != 1 {
t.Fatalf("after the carrying bump to epoch %d the store holds %d rows minted at that epoch, want 1: only the live lineage is carried", newEpoch, got)
}
epochRowAddress(t, ctx, te, store, "record-kept", newEpoch)
if rows := epochCarryRowsOf(t, ctx, te, lost); rows != 0 {
t.Errorf("%d carry rows name the lost lineage's root, want 0: a lost lineage is not carried", rows)
}
epochRequireGone(t, ctx, te, store, lost, newEpoch, "the carry must not bring a lost lineage back")
if got, err := te.store.CurrentAddressFor(ctx, store, lost); err == nil {
t.Errorf("CurrentAddressFor(a lost address) = %s with no error, want an error", got)
}
epochRequireServed(t, ctx, te, store, kept, "the live lineage is served")
}
// TestABumpUnderOneStoreIDMovesTheEpochSeenThroughEveryStoreID pins the fact the
// bump documentation states: the epoch counter is per database, not per store,
// and storeID appears only in error text. It deliberately pins no guard in the
// shared body, because the conformance suite uses several synthetic storeIDs in
// one database.
func TestABumpUnderOneStoreIDMovesTheEpochSeenThroughEveryStoreID(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
const one, two = "epoch-store-one", "epoch-store-two"
for _, bump := range []struct {
name string
run func() (int, error)
}{
{"BumpEpoch", func() (int, error) { return te.store.BumpEpoch(ctx, one, "restore") }},
{"BumpEpochCarrying", func() (int, error) { return te.store.BumpEpochCarrying(ctx, one, "token-scheme-change") }},
} {
before, err := te.store.CurrentEpoch(ctx, two)
if err != nil {
t.Fatalf("CurrentEpoch(%s): %v", two, err)
}
after, err := bump.run()
if err != nil {
t.Fatalf("%s(%s): %v", bump.name, one, err)
}
seen, err := te.store.CurrentEpoch(ctx, two)
if err != nil {
t.Fatalf("CurrentEpoch(%s): %v", two, err)
}
if after != before+1 || seen != after {
t.Errorf("%s under %s moved the epoch from %d to %d, and CurrentEpoch under %s reads %d: the counter is per database, so one bump advances the epoch every storeID sees", bump.name, one, before, after, two, seen)
}
}
}
// epochMint mints id under store, failing the test if the mint fails.
func epochMint(t *testing.T, ctx context.Context, te *testEnv, store, id string) string {
t.Helper()
address, err := te.store.MintUnderEpoch(ctx, store, id)
if err != nil {
t.Fatalf("MintUnderEpoch(%s, %s): %v", store, id, err)
}
return address
}
// epochBump moves the epoch with the counter-only bump (a restore, which
// writes no address rows) and returns the new epoch.
func epochBump(t *testing.T, ctx context.Context, te *testEnv, store string) int {
t.Helper()
epoch, err := te.store.BumpEpoch(ctx, store, "restore")
if err != nil {
t.Fatalf("BumpEpoch(%s): %v", store, err)
}
return epoch
}
// epochCarry runs the token-scheme-change bump, which also carries every live
// address to the new epoch, and returns the new epoch.
func epochCarry(t *testing.T, ctx context.Context, te *testEnv, store string) int {
t.Helper()
epoch, err := te.store.BumpEpochCarrying(ctx, store, "token-scheme-change")
if err != nil {
t.Fatalf("BumpEpochCarrying(%s): %v", store, err)
}
return epoch
}
// epochRowsAt counts the rows of store that were minted at epoch. After a
// carrying bump to epoch that is the number of carry rows it wrote, plus any
// row the test minted there itself.
func epochRowsAt(t *testing.T, ctx context.Context, te *testEnv, store string, epoch int) int {
t.Helper()
var count int
te.queryScalar(t, ctx, "SELECT COUNT(*) FROM epoch_minted_addresses WHERE store_id = ? AND minted_epoch = ?",
[]any{store, epoch}, &count)
return count
}
// epochRowAddress returns the address of the one row of id in store minted at
// epoch, failing the test unless there is exactly one.
func epochRowAddress(t *testing.T, ctx context.Context, te *testEnv, store, id string, epoch int) string {
t.Helper()
var count int
te.queryScalar(t, ctx, "SELECT COUNT(*) FROM epoch_minted_addresses WHERE store_id = ? AND minted_id = ? AND minted_epoch = ?",
[]any{store, id, epoch}, &count)
if count != 1 {
t.Fatalf("store %s holds %d rows for %s minted at epoch %d, want exactly 1", store, count, id, epoch)
}
var address string
te.queryScalar(t, ctx, "SELECT address FROM epoch_minted_addresses WHERE store_id = ? AND minted_id = ? AND minted_epoch = ?",
[]any{store, id, epoch}, &address)
return address
}
// epochCarriedFrom reads address's carried_from: not Valid for a row that was
// minted fresh.
func epochCarriedFrom(t *testing.T, ctx context.Context, te *testEnv, address string) sql.NullString {
t.Helper()
var carriedFrom sql.NullString
te.queryScalar(t, ctx, "SELECT carried_from FROM epoch_minted_addresses WHERE address = ?",
[]any{address}, &carriedFrom)
return carriedFrom
}
// epochGoneAt reads address's gone_at_epoch: not Valid while the address is
// live.
func epochGoneAt(t *testing.T, ctx context.Context, te *testEnv, address string) sql.NullInt64 {
t.Helper()
var goneAt sql.NullInt64
te.queryScalar(t, ctx, "SELECT gone_at_epoch FROM epoch_minted_addresses WHERE address = ?",
[]any{address}, &goneAt)
return goneAt
}
// epochCarryRowsOf counts the carry rows that name root as their lineage root.
func epochCarryRowsOf(t *testing.T, ctx context.Context, te *testEnv, root string) int {
t.Helper()
var count int
te.queryScalar(t, ctx, "SELECT COUNT(*) FROM epoch_minted_addresses WHERE carried_from = ?",
[]any{root}, &count)
return count
}
// epochRequireServed fails unless the store serves address: StillServes is true
// and Resolve answers Live. why says what the assertion checks.
func epochRequireServed(t *testing.T, ctx context.Context, te *testEnv, store, address, why string) {
t.Helper()
serves, err := te.store.StillServes(ctx, store, address)
if err != nil {
t.Fatalf("StillServes(%s): %v", address, err)
}
if !serves {
t.Errorf("StillServes(%s) = false, want true: %s", address, why)
}
result, err := te.store.Resolve(ctx, store, address)
if err != nil {
t.Fatalf("Resolve(%s): %v", address, err)
}
if result.Restriction != storeops.EpochRestrictionLive {
t.Errorf("Resolve(%s).Restriction = %d, want Live (%d): %s", address, result.Restriction, storeops.EpochRestrictionLive, why)
}
}
// epochRequireGone fails unless address is no longer served at epoch:
// StillServes is false and Resolve answers GoneReorganization naming epoch.
func epochRequireGone(t *testing.T, ctx context.Context, te *testEnv, store, address string, epoch int, why string) {
t.Helper()
serves, err := te.store.StillServes(ctx, store, address)
if err != nil {
t.Fatalf("StillServes(%s): %v", address, err)
}
if serves {
t.Errorf("StillServes(%s) = true, want false: %s", address, why)
}
result, err := te.store.Resolve(ctx, store, address)
if err != nil {
t.Fatalf("Resolve(%s): %v", address, err)
}
if result.Restriction != storeops.EpochRestrictionGoneReorganization {
t.Errorf("Resolve(%s).Restriction = %d, want GoneReorganization (%d): %s", address, result.Restriction, storeops.EpochRestrictionGoneReorganization, why)
}
if result.Epoch == nil {
t.Errorf("Resolve(%s).Epoch = nil, want the current epoch %d: %s", address, epoch, why)
} else if *result.Epoch != epoch {
t.Errorf("Resolve(%s).Epoch = %d, want the current epoch %d: %s", address, *result.Epoch, epoch, why)
}
}

View file

@ -10,11 +10,21 @@ import (
)
// TestExpectedRevisionContract wires this leg into the R16/R17
// expected-revision contract. Phase 0 leaves every hook nil in every
// backend's fixture kit (architecture §12), so each case below skips by
// name; this file exists so TestEveryLegWiresEveryRoleContract counts this
// leg, and so the cases start running for real the moment this leg's fixture
// kit grows a non-nil hook.
// expected-revision contract. Every hook is nil (architecture §12's Phase 0
// default), so each case below skips by name; this file exists so
// TestEveryLegWiresEveryRoleContract counts this leg, and so the cases
// start running for real the moment this leg grows a real
// CompareAndSetVersion (gastownhall/beads#6358).
//
// This leg previously wired every hook to an honest "not implemented" stub
// instead of leaving them nil, so each case ran for real and
// failed for that documented reason rather than skipping. That premise —
// that a later slice would give this leg its CompareAndSetVersion — went
// stale once review moved the real implementation to
// gastownhall/beads#6358 instead; a stub whose failure message blames a
// bead that will never land it is worse than an honest skip, so this file
// reverts to nil hooks (gastownhall/beads#6664, bee-ghosttrack review
// 5268699223).
func TestExpectedRevisionContract(t *testing.T) {
ctx := context.Background()
fixture := conformance.ExpectedRevisionFixture{IssuePrefix: "erev"}

View file

@ -4,9 +4,12 @@ package embeddeddolt_test
import (
"context"
"testing"
"github.com/steveyegge/beads/backend/conformance"
"github.com/steveyegge/beads/internal/storage/embeddeddolt"
storeops "github.com/steveyegge/beads/internal/storage/issueops"
)
// TestRetentionContract wires this leg into the R20 retention contract.
@ -59,11 +62,31 @@ func TestRetentionContract(t *testing.T) {
})
}
// TestEpochContract wires this leg into the R20 epoch contract. Same Phase 0
// all-nil state as TestRetentionContract above.
// TestEpochContract runs the R20 epoch contract (gastownhall/beads#5898
// revision 9, #6136) against the embedded-Dolt-
// backed store, which reaches internal/storage/issueops's epoch Tx
// functions through this leg's own issue-operation transaction
// (EmbeddedDoltStore.BumpEpoch/BumpEpochCarrying/MintUnderEpoch/LoseVersion)
// or a read-only connection (EmbeddedDoltStore.CurrentEpoch/StillServes/
// Resolve/CurrentAddressFor) — see internal/storage/embeddeddolt/epoch_cas.go.
//
// All three legs run that one shared body, so this is not an independent
// vote on the design — it is the check on THIS leg's wrapper and this file's
// own conformance-vocabulary translation.
func TestEpochContract(t *testing.T) {
ctx := context.Background()
fixture := conformance.EpochFixture{IssuePrefix: "epch"}
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "epch")
ctx := t.Context()
fixture := conformance.EpochFixture{
IssuePrefix: "epch",
CurrentEpoch: epochEmbeddedCurrentEpoch(te.store),
BumpEpoch: epochEmbeddedBumpEpoch(te.store),
MintUnderEpoch: epochEmbeddedMintUnderEpoch(te.store),
StillServes: epochEmbeddedStillServes(te.store),
Resolve: epochEmbeddedResolve(te.store),
CurrentAddressFor: epochEmbeddedCurrentAddressFor(te.store),
LoseVersion: epochEmbeddedLoseVersion(te.store),
}
t.Run("AnEpochBumpIsTriggeredOnlyByRestoreReinitOrSchemeChange", func(t *testing.T) {
conformance.RunAnEpochBumpIsTriggeredOnlyByRestoreReinitOrSchemeChange(t, ctx, fixture)
@ -71,4 +94,98 @@ func TestEpochContract(t *testing.T) {
t.Run("EpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed", func(t *testing.T) {
conformance.RunEpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed(t, ctx, fixture)
})
t.Run("TokenSchemeChangeCarriesLiveAddressesAndOnlyThose", func(t *testing.T) {
conformance.RunTokenSchemeChangeCarriesLiveAddressesAndOnlyThose(t, ctx, fixture)
})
t.Run("ACarriedAddressKeepsResolvingAcrossLaterBumps", func(t *testing.T) {
conformance.RunACarriedAddressKeepsResolvingAcrossLaterBumps(t, ctx, fixture)
})
t.Run("ALostAddressStaysGoneAcrossASchemeChange", func(t *testing.T) {
conformance.RunALostAddressStaysGoneAcrossASchemeChange(t, ctx, fixture)
})
}
func epochEmbeddedCurrentEpoch(store *embeddeddolt.EmbeddedDoltStore) func(ctx context.Context, storeID string) (int, error) {
return func(ctx context.Context, storeID string) (int, error) {
return store.CurrentEpoch(ctx, storeID)
}
}
// epochEmbeddedBumpEpoch chooses the bump by the typed trigger: only a
// token-scheme-change bump carries live addresses to the new epoch, and the
// other two triggers move the counter alone. The choice lives here, in the
// contract-test translation layer, because the shared body has no switch on
// the reason string.
func epochEmbeddedBumpEpoch(store *embeddeddolt.EmbeddedDoltStore) func(ctx context.Context, storeID string, trigger conformance.EpochBumpTrigger) (int, error) {
return func(ctx context.Context, storeID string, trigger conformance.EpochBumpTrigger) (int, error) {
if trigger == conformance.EpochBumpTriggerTokenSchemeChange {
return store.BumpEpochCarrying(ctx, storeID, trigger.String())
}
return store.BumpEpoch(ctx, storeID, trigger.String())
}
}
func epochEmbeddedMintUnderEpoch(store *embeddeddolt.EmbeddedDoltStore) func(ctx context.Context, storeID, id string) (conformance.Address, error) {
return func(ctx context.Context, storeID, id string) (conformance.Address, error) {
address, err := store.MintUnderEpoch(ctx, storeID, id)
if err != nil {
return "", err
}
return conformance.Address(address), nil
}
}
func epochEmbeddedStillServes(store *embeddeddolt.EmbeddedDoltStore) func(ctx context.Context, storeID string, address conformance.Address) (bool, error) {
return func(ctx context.Context, storeID string, address conformance.Address) (bool, error) {
return store.StillServes(ctx, storeID, string(address))
}
}
func epochEmbeddedResolve(store *embeddeddolt.EmbeddedDoltStore) func(ctx context.Context, storeID string, address conformance.Address) (conformance.RetentionAnswer, error) {
return func(ctx context.Context, storeID string, address conformance.Address) (conformance.RetentionAnswer, error) {
result, err := store.Resolve(ctx, storeID, string(address))
if err != nil {
return conformance.RetentionAnswer{}, err
}
return epochResolveResultToConformance(result), nil
}
}
func epochEmbeddedCurrentAddressFor(store *embeddeddolt.EmbeddedDoltStore) func(ctx context.Context, storeID string, oldAddress conformance.Address) (conformance.Address, error) {
return func(ctx context.Context, storeID string, oldAddress conformance.Address) (conformance.Address, error) {
address, err := store.CurrentAddressFor(ctx, storeID, string(oldAddress))
if err != nil {
return "", err
}
return conformance.Address(address), nil
}
}
func epochEmbeddedLoseVersion(store *embeddeddolt.EmbeddedDoltStore) func(ctx context.Context, storeID string, address conformance.Address) error {
return func(ctx context.Context, storeID string, address conformance.Address) error {
return store.LoseVersion(ctx, storeID, string(address))
}
}
// epochRestrictionToConformance translates this leg's local
// storeops.EpochRestriction into backend/conformance's own Restriction
// vocabulary — the contract-test file is the translation boundary, per
// epoch_cas.go's package doc.
func epochRestrictionToConformance(r storeops.EpochRestriction) conformance.Restriction {
switch r {
case storeops.EpochRestrictionLive:
return conformance.RestrictionLive
case storeops.EpochRestrictionGoneReorganization:
return conformance.RestrictionGoneReorganization
default:
return conformance.RestrictionUnknown
}
}
func epochResolveResultToConformance(r storeops.EpochResolveResult) conformance.RetentionAnswer {
return conformance.RetentionAnswer{
Restriction: epochRestrictionToConformance(r.Restriction),
ProducingStore: r.ProducingStore,
Epoch: r.Epoch,
}
}

View file

@ -50,6 +50,7 @@ func (s *EmbeddedDoltStore) runTransactionWithMessage(ctx context.Context, fn fu
}); err != nil {
return err
}
afterSQLCommit()
// Anything the body minted ran with versioned history scoped on this
// store's transaction (withConn), so its version rows must be staged with
@ -67,6 +68,11 @@ func (s *EmbeddedDoltStore) runTransactionWithMessage(ctx context.Context, fn fu
return nil
}
// afterSQLCommit runs between runTransactionWithMessage's SQL commit and the
// Dolt commit that publishes it. It is a no-op outside tests, which use it to
// fail the publication of a write whose rows have already landed.
var afterSQLCommit = func() {}
func wrapCommitIndeterminate(op string, err error) error {
return fmt.Errorf("%s: %w: %w", op, err, storage.ErrCommitIndeterminate)
}

View file

@ -53,6 +53,7 @@ go_library(
"edge_counts.go",
"edges.go",
"epic_closure.go",
"epoch_cas.go",
"errors.go",
"events.go",
"execution.go",
@ -164,6 +165,7 @@ go_test(
"dependency_tree_test.go",
"edge_counts_test.go",
"edge_role_requests_test.go",
"epoch_cas_test.go",
"execution_test.go",
"filters_test.go",
"gate_fields_test.go",
@ -212,6 +214,7 @@ go_test(
],
data = glob(["testdata/**"]) + [
":go_srcs",
"//internal/storage/dolt:go_srcs",
"//internal/storage/domain/db:go_srcs",
"//internal/storage/schema:migrations",
"//internal/storage/versioncontrolops:go_srcs",

View file

@ -0,0 +1,680 @@
package issueops
import (
"context"
"database/sql"
"errors"
"fmt"
"math"
"strings"
"time"
"github.com/steveyegge/beads/internal/storage/dberrors"
)
// This file implements R20 epoch-transition enforcement (gastownhall/beads#5898
// revision 9, #6136): a store-wide epoch generation
// counter (store_epoch, migration 0067) plus a durable record of the
// addresses minted under each generation (epoch_minted_addresses, migration
// 0072), used to answer whether a previously-minted address is still served
// by the store's current epoch. It adds no RetentionFixture/R17 resolve,
// remove, hold, force-remove, erase, or mint logic — R20 epoch reasoning is
// evaluated entirely on its own (out of scope for this slice).
//
// ALL THREE LEGS SHARE THIS BODY, the same way they share
// CompareAndSetMetadataKeyInTx: the two Dolt-backed stores wrap it in their
// own transaction, and the unit-of-work provider reaches it through its own
// leg-specific adapter. Each leg's own contract-test file is the
// translation boundary to and from backend/conformance's
// Address/EpochBumpTrigger/RetentionAnswer vocabulary — this file knows
// nothing about the conformance package.
//
// ADDRESSES ARE NEVER RECOMPUTED FROM store_epoch. Each is a deterministic
// token over (storeID, id, the epoch current at mint time) — see
// epochAddress — persisted once at mint: a later mint of the same id under a
// bumped epoch produces a DIFFERENT address and a new row, and every
// address's row survives to answer StillServes/Resolve after the epoch moves
// on.
//
// SURVIVAL IS RECORDED ON THE ROW, NEVER INFERRED (gastownhall/beads#6664,
// bee-ghosttrack review 5360880888, Major 1). An address is served unless its
// own row says gone_at_epoch, and a row minted in an epoch that has not
// happened yet is not served: the answer is a function of the address's row
// and the current epoch, and nothing reads another row to reach it. Gone is
// terminal. Two writers set gone_at_epoch, both guarded by IS NULL so that
// nothing already lost is touched and nothing is ever cleared:
// LoseVersionInTx, for a Version the store lost, and BumpEpochCarryingInTx,
// for the losing lineage when two live lineages of one id meet at a
// token-scheme change.
//
// A restore or a destructive reinit moves the counter and writes no address
// row (BumpEpochInTx), so every address that was served stays Live at its own
// address with no re-mint. A token-scheme change is the one bump that writes
// address rows (BumpEpochCarryingInTx): it carries every live lineage to the
// new epoch with one carry row whose carried_from names the lineage's ROOT
// address, never the previous carry, so lineages stay flat and any member of
// one reaches its newest address in a single indexed lookup.
//
// THE EPOCH COUNTER IS PER DATABASE, NOT PER STORE (gastownhall/beads#6664,
// bee-ghosttrack review 5360880888, Minor 3). store_epoch has no store_id
// column, and storeID appears only in error text: one bump advances the epoch
// seen through every storeID that shares the database. There is deliberately
// no storeID guard in this body, because the conformance suite uses several
// synthetic storeIDs in one database.
//
// epochAddress'S ENCODING IS LENGTH-PREFIXED, NOT BARE-COLON-JOINED
// (gastownhall/beads#6664, bee-ghosttrack review 5268699223, item B2): a
// colon inside storeID or id can no longer shift the (storeID, id, epoch)
// field boundary onto a different triple the way the old "epch:%s:%s:%d"
// form allowed. MintUnderEpochInTx additionally refuses a storeID or id
// containing ":" outright (validateEpochAddressInputs) so an address stays
// readable by eye without needing to count length prefixes — belt and
// braces, not a correctness dependency of epochAddress itself. Given that,
// upsertEpochMintedAddressInTx's exists branch is a pure no-op: an
// address's row existing now provably means its stored triple already
// matches the incoming one, so there is nothing left to write.
// EpochRestriction is this file's own local answer vocabulary for R20 —
// deliberately not backend/conformance.Restriction (see package doc above).
// It omits GoneRetention/GoneErasure: those are RetentionFixture/R17
// outcomes this slice does not produce.
type EpochRestriction int
const (
EpochRestrictionLive EpochRestriction = iota
EpochRestrictionGoneReorganization
EpochRestrictionUnknown
)
// EpochResolveResult is ResolveEpochInTx's answer. Epoch is non-nil exactly
// when the answer required comparing an epoch (Live and GoneReorganization);
// it is nil for Unknown, which never looks store_epoch up at all.
type EpochResolveResult struct {
Restriction EpochRestriction
ProducingStore string
Epoch *int
}
// ErrEpochAddressNotFound means the address named was never minted by
// storeID — distinct from an ordinary "gone" answer, which requires having
// minted the address in the first place.
var ErrEpochAddressNotFound = errors.New("epoch CAS: address not minted by this store")
// ErrEpochAddressNotServed means the address exists in this store but the
// store does not serve it: its lineage was lost, or it was minted in an epoch
// that has not happened yet. It is distinct from ErrEpochAddressNotFound so a
// caller can tell an address the store never minted from one it minted and no
// longer serves.
var ErrEpochAddressNotServed = errors.New("epoch CAS: address exists in this store but is not served")
// ErrEpochAddressSeparator means a storeID or id passed to
// MintUnderEpochInTx contains ":", the character epochAddress's encoding
// uses as a field delimiter (gastownhall/beads#6664, bee-ghosttrack review
// 5268699223, item B2b). epochAddress's length-prefixed encoding does not
// actually depend on this for correctness (see epochAddress's own doc
// comment), but refusing it outright keeps a minted address readable by eye.
var ErrEpochAddressSeparator = errors.New("epoch CAS: storeID or id contains \":\", epochAddress's field separator")
// ErrEpochAddressTooLong means a storeID and id compose an address that
// epoch_minted_addresses.address, a VARCHAR(255) PRIMARY KEY (migration 0072),
// may not hold. MintUnderEpochInTx refuses such a pair before it reads or
// writes anything, so the caller gets this error instead of a raw driver error
// from the INSERT. The bound is charged at the widest epoch the INT counter can
// reach, not the current one: a token-scheme change re-encodes every live pair
// at the new epoch (BumpEpochCarryingInTx), so a pair that fit at epoch 9 must
// still fit at epoch 10, or the carry, and with it every later scheme change,
// would fail database-wide.
var ErrEpochAddressTooLong = errors.New("epoch CAS: storeID and id compose an address longer than epoch_minted_addresses.address holds")
// maxEpochAddressLen is the width of epoch_minted_addresses.address,
// VARCHAR(255). The check against it counts bytes, which are never fewer than
// the characters the column counts, so it refuses no later than the column
// would.
const maxEpochAddressLen = 255
// epochAddress is a minted address: a deterministic token over storeID, id,
// and the epoch current at mint time, so re-minting the same id under the
// same epoch always reproduces the same address. storeID and id are
// length-prefixed, not just colon-joined (gastownhall/beads#6664,
// bee-ghosttrack review 5268699223, item B2a): reading exactly len(storeID)
// bytes for the first field and len(id) bytes for the second makes the
// (storeID, id) boundary unambiguous no matter what characters either one
// contains, so two different triples can never collide on the same address.
// MintUnderEpochInTx also refuses a storeID or id containing ":" outright
// (validateEpochAddressInputs, item B2b) so an address stays readable by
// eye without relying on that.
func epochAddress(storeID, id string, epoch int) string {
return fmt.Sprintf("epch:%d:%s:%d:%s:%d", len(storeID), storeID, len(id), id, epoch)
}
// validateEpochAddressInputs rejects a storeID or id containing ":" before
// MintUnderEpochInTx mints an address from them (item B2b above), and a pair
// whose address would not fit the address column at the widest epoch
// (ErrEpochAddressTooLong).
func validateEpochAddressInputs(storeID, id string) error {
if strings.Contains(storeID, ":") {
return fmt.Errorf("%w: storeID %q", ErrEpochAddressSeparator, storeID)
}
if strings.Contains(id, ":") {
return fmt.Errorf("%w: id %q", ErrEpochAddressSeparator, id)
}
if n := len(epochAddress(storeID, id, math.MaxInt32)); n > maxEpochAddressLen {
return fmt.Errorf("%w: %d bytes at the widest epoch, limit %d", ErrEpochAddressTooLong, n, maxEpochAddressLen)
}
return nil
}
// ensureStoreEpochRow lazily initializes store_epoch's singleton row
// (migration 0067; the table starts empty) to epoch 1 on first use, and
// reports the current epoch either way. Only BumpEpochInTx and
// MintUnderEpochInTx call this: both are about to write regardless, so
// creating the row here is not a surprising extra side effect. Every
// read-only path calls readStoreEpochWithoutSeedingInTx instead
// (gastownhall/beads#6664, bee-ghosttrack review 5268699223, item B4): a write
// from what callers reasonably expect to be a read is surprising at best, and
// a hard failure against a genuinely read-only connection at worst.
//
// The seed follows version_history.go's seed of the same row (gastownhall/
// beads#6664, bee-ghosttrack review 5360880888): read first, so the INSERT
// happens once per store rather than once per mint; INSERT IGNORE, so a row
// that turns up between the read and the write is not an error; and read the
// row back, so the epoch reported is what the row holds even when the seed was
// ignored, not the 1 it would have written.
func ensureStoreEpochRow(ctx context.Context, tx DBTX) (int, error) {
var epoch int
err := tx.QueryRowContext(ctx, `SELECT epoch FROM store_epoch WHERE id = 1`).Scan(&epoch)
if errors.Is(err, sql.ErrNoRows) {
if _, err := tx.ExecContext(ctx, `INSERT IGNORE INTO store_epoch (id, epoch) VALUES (1, 1)`); err != nil {
return 0, fmt.Errorf("initialize store_epoch: %w", err)
}
err = tx.QueryRowContext(ctx, `SELECT epoch FROM store_epoch WHERE id = 1`).Scan(&epoch)
}
if err != nil {
return 0, fmt.Errorf("read store_epoch: %w", err)
}
return epoch, nil
}
// EpochMintDirtyTables names the tables a mint (MintUnderEpochInTx) can leave
// modified, for the leg that publishes them to Dolt history. A token-scheme
// bump (BumpEpochCarryingInTx) leaves the same two tables modified. store_epoch is in the set although a mint
// never updates it: ensureStoreEpochRow INSERTs the singleton row on first use,
// so a mint that published only epoch_minted_addresses would leave that row
// modified and uncommitted, and the Dolt commit would hold minted rows without
// the epoch row they depend on (gastownhall/beads#6664 Major 2, bee-ghosttrack
// review 5360880888). Staging a table that turns out to be clean is free.
func EpochMintDirtyTables() ChangedTables {
return ChangedTables{"epoch_minted_addresses": true, "store_epoch": true}
}
// readStoreEpochWithoutSeedingInTx reports the current epoch without writing:
// store_epoch's singleton row starting absent (migration 0067) and its
// epoch being 1 are the same state, so a read-only caller can answer from
// that default instead of initializing the row the way ensureStoreEpochRow
// does (item B4 above). It is deliberately not version_history.go's
// readStoreEpochInTx, which seeds the row when it is absent. CurrentEpochInTx,
// StillServesInTx, ResolveEpochInTx, CurrentAddressForInTx and
// LoseVersionInTx all read this way; only BumpEpochInTx and
// MintUnderEpochInTx, which are about to write regardless, use
// ensureStoreEpochRow.
func readStoreEpochWithoutSeedingInTx(ctx context.Context, tx DBTX) (int, error) {
var epoch int
err := tx.QueryRowContext(ctx, `SELECT epoch FROM store_epoch WHERE id = 1`).Scan(&epoch)
if errors.Is(err, sql.ErrNoRows) {
return 1, nil
}
if err != nil {
return 0, fmt.Errorf("read store_epoch: %w", err)
}
return epoch, nil
}
// epochMintedAddress is one row as read from epoch_minted_addresses.
// carriedFrom is NULL for a root row (a fresh mint) and otherwise the address of
// the lineage's root; goneAtEpoch is NULL while the store serves the row and
// otherwise the epoch it was lost in.
type epochMintedAddress struct {
storeID string
mintedID string
mintedEpoch int
carriedFrom sql.NullString
goneAtEpoch sql.NullInt64
}
// served reports whether the store serves the row at epoch. A row is served
// unless it was lost, and a row minted in an epoch that has not happened yet
// fails closed rather than being trusted.
func (r epochMintedAddress) served(epoch int) bool {
return !r.goneAtEpoch.Valid && r.mintedEpoch <= epoch
}
// lineageRoot is the address every member of the row's lineage names: the
// row's carried_from when it is a carry row, and its own address when it is a
// root.
func (r epochMintedAddress) lineageRoot(address string) string {
if r.carriedFrom.Valid {
return r.carriedFrom.String
}
return address
}
// readEpochMintedAddressInTx reads address's row, if any. found is false
// (with a zero-value row and nil error) when address was never minted —
// distinguishing "not found" from an actual query error is the caller's
// job, the same way readExpectedRevisionRowInTx's callers do it.
func readEpochMintedAddressInTx(ctx context.Context, tx DBTX, address string) (epochMintedAddress, bool, error) {
var row epochMintedAddress
err := tx.QueryRowContext(ctx,
`SELECT store_id, minted_id, minted_epoch, carried_from, gone_at_epoch FROM epoch_minted_addresses WHERE address = ?`, address,
).Scan(&row.storeID, &row.mintedID, &row.mintedEpoch, &row.carriedFrom, &row.goneAtEpoch)
if errors.Is(err, sql.ErrNoRows) {
return epochMintedAddress{}, false, nil
}
if err != nil {
return epochMintedAddress{}, false, fmt.Errorf("epoch CAS: read minted address %s: %w", address, err)
}
return row, true, nil
}
// upsertEpochMintedAddressInTx writes address's row. exists (from the
// caller's own prior read) says whether one already does: if so, this is a
// pure no-op (gastownhall/beads#6664, bee-ghosttrack review 5268699223,
// item B2c) — epochAddress is now injective (item B2a), so an existing row
// at this exact address provably already carries this exact (storeID,
// mintedID, mintedEpoch) triple, and the old exists-branch UPDATE (which
// had no store_id/minted_id guard) could only ever have mattered by
// rewriting a DIFFERENT triple's row out from under it on an address
// collision the new encoding no longer allows.
//
// A duplicate-key error from the INSERT is NOT success. It means a row the
// caller's read did not find: another transaction inserted it, and that
// transaction or a later one may already have lost it, so taking the error as
// the benign race of two minters inserting the same row (item B3) could hand
// back an address that reads Gone. The row is read again and trusted only as
// far as this transaction can see it: served at mintedEpoch, the mint stands,
// because the row is the one it would have inserted; present but not served,
// the mint fails with ErrEpochAddressNotServed, as it does when the caller's
// own read finds such a row; not visible at all, the mint fails with the
// duplicate-key error, and a new transaction, which reads the committed row,
// answers it.
//
// On Dolt, the only supported backend, the INSERT does not hit that error for
// a row committed after the transaction's snapshot: it checks the snapshot,
// and the two inserts of one address conflict at COMMIT instead (Error 1213),
// which withRetryTx answers by running the mint again against the committed
// row (TestAMintRacingTheMintAndLossOfItsAddressConflictsAtCommit in the dolt
// package). FOR UPDATE is a parse-only no-op there, so no locking read could
// see further than the re-read does.
func upsertEpochMintedAddressInTx(ctx context.Context, tx DBTX, address, storeID, mintedID string, mintedEpoch int, exists bool) error {
if exists {
return nil
}
_, err := tx.ExecContext(ctx,
`INSERT INTO epoch_minted_addresses (address, store_id, minted_id, minted_epoch, minted_at) VALUES (?, ?, ?, ?, ?)`,
address, storeID, mintedID, mintedEpoch, time.Now().UTC(),
)
if err == nil {
return nil
}
if !dberrors.IsDuplicateKey(err) {
return fmt.Errorf("epoch CAS: insert minted address %s: %w", address, err)
}
row, found, readErr := readEpochMintedAddressInTx(ctx, tx, address)
switch {
case readErr != nil:
return errors.Join(fmt.Errorf("epoch CAS: insert minted address %s: %w", address, err), readErr)
case !found:
return fmt.Errorf("epoch CAS: insert minted address %s: another transaction holds a row at it that this one cannot read, so whether the store serves it is unknown: %w", address, err)
case !row.served(mintedEpoch):
return fmt.Errorf("epoch CAS: mint %s under epoch for %s: %w: %s", mintedID, storeID, ErrEpochAddressNotServed, address)
}
return nil
}
// CurrentEpochInTx reports storeID's current epoch generation. store_epoch
// has no store_id column: migration 0067 established it as one physical
// counter per database, matching production reality (one logical store per
// database already) — storeID is accepted here only to satisfy
// EpochFixture's hook signature.
//
// The epoch counter is per database, not per store. storeID appears only in
// error text; one bump advances the epoch seen through every storeID that
// shares this database.
func CurrentEpochInTx(ctx context.Context, tx DBTX, storeID string) (int, error) {
epoch, err := readStoreEpochWithoutSeedingInTx(ctx, tx)
if err != nil {
return 0, fmt.Errorf("epoch CAS: current epoch for %s: %w", storeID, err)
}
return epoch, nil
}
// BumpEpochInTx advances storeID's epoch generation by one and records why
// (R20-a: a bump is triggered only by restore, destructive-reinit, or
// token-scheme-change — the leg adapter converts the fixture's
// conformance.EpochBumpTrigger to this plain string via trigger.String(),
// keeping that vocabulary out of this file per the package doc above).
//
// It writes store_epoch and nothing else: a restore or a destructive reinit
// leaves every address row alone, so every address that was served stays Live
// at its own address. A token-scheme change, which does write address rows,
// calls BumpEpochCarryingInTx instead.
//
// The epoch counter is per database, not per store. storeID appears only in
// error text; one bump advances the epoch seen through every storeID that
// shares this database.
func BumpEpochInTx(ctx context.Context, tx DBTX, storeID, reason string) (int, error) {
if _, err := ensureStoreEpochRow(ctx, tx); err != nil {
return 0, fmt.Errorf("epoch CAS: bump epoch for %s: %w", storeID, err)
}
if _, err := tx.ExecContext(ctx,
`UPDATE store_epoch SET epoch = epoch + 1, bumped_at = ?, bumped_reason = ? WHERE id = 1`,
time.Now().UTC(), reason,
); err != nil {
return 0, fmt.Errorf("epoch CAS: bump epoch for %s: %w", storeID, err)
}
var newEpoch int
if err := tx.QueryRowContext(ctx, `SELECT epoch FROM store_epoch WHERE id = 1`).Scan(&newEpoch); err != nil {
return 0, fmt.Errorf("epoch CAS: read epoch after bump for %s: %w", storeID, err)
}
return newEpoch, nil
}
// BumpEpochCarryingInTx is BumpEpochInTx for a token-scheme change, the one
// trigger that changes how addresses are encoded. It advances the epoch exactly
// as BumpEpochInTx does and also records the carry: every lineage the store
// still serves gets one new row at the new epoch, whose address is the
// deterministic token for (store, id, new epoch) and whose carried_from names
// the lineage's ROOT address. The old addresses keep resolving, and
// CurrentAddressForInTx reports the new one from any member of the lineage.
//
// The carry is DATABASE-WIDE on purpose. The counter is per database, so this
// bump moves the epoch every storeID sees, and carrying only storeID's rows
// would strand every other store's addresses at the scheme boundary. storeID is
// used for error text only, exactly as in BumpEpochInTx. It costs one read of
// every live row and one insert per live id, in one transaction: acceptable
// because a scheme change is a once-per-change migration, not a runtime path.
//
// Two live lineages of one id cannot both receive an address, because an
// address is a function of (store, id, epoch) and so is one per id per epoch.
// The lineage holding the newest row is carried, and every other lineage of
// that id is marked gone at the new epoch (the safe direction: over-void, never
// revive). Lineages already lost are not read, so they are never carried, and a
// row minted in an epoch that has not happened yet is not read either: it stays
// not served. A row already sitting at a carry's address means the counter
// rewound, so that is a failure of the bump: no re-read can settle it the way
// a mint settles a duplicate key (upsertEpochMintedAddressInTx).
//
// CALLERS MUST HOLD THE WORKSPACE GATE (internal/workspacegate) EXCLUSIVELY FOR
// THE BUMP, as a restore does. This is the one epoch operation that needs
// mints excluded by contract: the store cannot make a mint conflict with a bump
// (a mint has no cell of its own to change), so a mint that commits after this
// bump read the live rows would leave a live row that was never carried.
func BumpEpochCarryingInTx(ctx context.Context, tx DBTX, storeID, reason string) (int, error) {
newEpoch, err := BumpEpochInTx(ctx, tx, storeID, reason)
if err != nil {
return 0, err
}
candidates, err := readEpochCarryCandidatesInTx(ctx, tx, newEpoch)
if err != nil {
return 0, fmt.Errorf("epoch CAS: carry addresses to epoch %d for %s: %w", newEpoch, storeID, err)
}
// The candidates are ordered newest first within each (store, id), so the
// first row of a group holds the lineage that wins it.
type lineageKey struct{ storeID, mintedID string }
var groups []lineageKey
winningRoot := map[lineageKey]string{}
type losingLineage struct{ storeID, root string }
var losers []losingLineage
seenLoser := map[losingLineage]bool{}
for _, c := range candidates {
key := lineageKey{c.storeID, c.mintedID}
winner, seen := winningRoot[key]
if !seen {
winningRoot[key] = c.root()
groups = append(groups, key)
continue
}
if loser := (losingLineage{c.storeID, c.root()}); c.root() != winner && !seenLoser[loser] {
seenLoser[loser] = true
losers = append(losers, loser)
}
}
for _, loser := range losers {
if err := loseLineageInTx(ctx, tx, loser.storeID, loser.root, newEpoch); err != nil {
return 0, fmt.Errorf("epoch CAS: carry addresses to epoch %d for %s: %w", newEpoch, storeID, err)
}
}
for _, key := range groups {
address := epochAddress(key.storeID, key.mintedID, newEpoch)
if _, err := tx.ExecContext(ctx,
`INSERT INTO epoch_minted_addresses (address, store_id, minted_id, minted_epoch, minted_at, carried_from) VALUES (?, ?, ?, ?, ?, ?)`,
address, key.storeID, key.mintedID, newEpoch, time.Now().UTC(), winningRoot[key],
); err != nil {
return 0, fmt.Errorf("epoch CAS: carry %s to epoch %d for %s: %w", key.mintedID, newEpoch, storeID, err)
}
}
return newEpoch, nil
}
// epochCarryCandidate is one live row below the new epoch, as
// BumpEpochCarryingInTx reads it.
type epochCarryCandidate struct {
address string
storeID string
mintedID string
carriedFrom sql.NullString
}
// root is the address of the candidate's lineage root.
func (c epochCarryCandidate) root() string {
if c.carriedFrom.Valid {
return c.carriedFrom.String
}
return c.address
}
// readEpochCarryCandidatesInTx reads every row the store still serves below
// newEpoch, newest first within each (store, id). Rows already lost are not
// read, and neither are rows minted at or above newEpoch: those are anomalies
// and stay not served. The result is read to the end before any other statement
// runs on the transaction.
func readEpochCarryCandidatesInTx(ctx context.Context, tx DBTX, newEpoch int) ([]epochCarryCandidate, error) {
rows, err := tx.QueryContext(ctx,
`SELECT address, store_id, minted_id, carried_from FROM epoch_minted_addresses WHERE gone_at_epoch IS NULL AND minted_epoch < ? ORDER BY store_id, minted_id, minted_epoch DESC`,
newEpoch,
)
if err != nil {
return nil, fmt.Errorf("read live addresses: %w", err)
}
defer func() { _ = rows.Close() }()
var candidates []epochCarryCandidate
for rows.Next() {
var c epochCarryCandidate
if err := rows.Scan(&c.address, &c.storeID, &c.mintedID, &c.carriedFrom); err != nil {
return nil, fmt.Errorf("scan live address: %w", err)
}
candidates = append(candidates, c)
}
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("read live addresses: %w", err)
}
return candidates, nil
}
// loseLineageInTx marks the lineage rooted at root gone at epoch: the root's own
// row, then every carry row that names it. Each statement is guarded by
// gone_at_epoch IS NULL, so a row already lost is never touched and nothing is
// ever cleared. It is the only place gone_at_epoch is written, shared by
// LoseVersionInTx and BumpEpochCarryingInTx.
func loseLineageInTx(ctx context.Context, tx DBTX, storeID, root string, epoch int) error {
if _, err := tx.ExecContext(ctx,
`UPDATE epoch_minted_addresses SET gone_at_epoch = ? WHERE address = ? AND store_id = ? AND gone_at_epoch IS NULL`,
epoch, root, storeID,
); err != nil {
return fmt.Errorf("mark %s lost at epoch %d: %w", root, epoch, err)
}
if _, err := tx.ExecContext(ctx,
`UPDATE epoch_minted_addresses SET gone_at_epoch = ? WHERE carried_from = ? AND store_id = ? AND gone_at_epoch IS NULL`,
epoch, root, storeID,
); err != nil {
return fmt.Errorf("mark the carries of %s lost at epoch %d: %w", root, epoch, err)
}
return nil
}
// MintUnderEpochInTx mints id's address under storeID's CURRENT epoch,
// deterministically (epochAddress): minting the same id again under the
// same epoch reproduces the same address and is an idempotent no-op upsert
// of the same row.
//
// A mint only ever INSERTS its own root row. It never updates another row, so
// no mint can retire or revive an address, and it never hands back an address
// the store does not serve: a row already sitting at the computed address is
// only possible when the lineage was minted in this epoch and lost in this same
// epoch, and the mint then returns ErrEpochAddressNotServed instead of an
// address that reads Gone. That includes a row another transaction inserts
// after this one read: on Dolt the two inserts conflict at COMMIT and the mint
// runs again against the committed row, and an INSERT that reports the row as
// a duplicate key reads it again first (upsertEpochMintedAddressInTx).
//
// A storeID or id containing ":" is refused (ErrEpochAddressSeparator), and so
// is a pair whose address could outgrow the address column at some epoch
// (ErrEpochAddressTooLong), before anything is read or written.
func MintUnderEpochInTx(ctx context.Context, tx DBTX, storeID, id string) (string, error) {
if err := validateEpochAddressInputs(storeID, id); err != nil {
return "", fmt.Errorf("epoch CAS: mint %s under epoch for %s: %w", id, storeID, err)
}
epoch, err := ensureStoreEpochRow(ctx, tx)
if err != nil {
return "", fmt.Errorf("epoch CAS: mint %s under epoch for %s: %w", id, storeID, err)
}
address := epochAddress(storeID, id, epoch)
row, found, err := readEpochMintedAddressInTx(ctx, tx, address)
if err != nil {
return "", err
}
if found && !row.served(epoch) {
return "", fmt.Errorf("epoch CAS: mint %s under epoch for %s: %w: %s", id, storeID, ErrEpochAddressNotServed, address)
}
if err := upsertEpochMintedAddressInTx(ctx, tx, address, storeID, id, epoch, found); err != nil {
return "", err
}
return address, nil
}
// StillServesInTx reports whether address is still served under storeID's
// CURRENT epoch. The answer is read from the address's own row and the epoch and
// from nothing else: the row's gone_at_epoch says whether the store lost it, and
// a row minted in an epoch that has not happened yet is not served. An address
// that survived a restore or a destructive reinit therefore stays served with no
// upkeep, and an address from a different store, or one never minted, is not
// served either.
func StillServesInTx(ctx context.Context, tx DBTX, storeID, address string) (bool, error) {
row, found, err := readEpochMintedAddressInTx(ctx, tx, address)
if err != nil {
return false, err
}
if !found || row.storeID != storeID {
return false, nil
}
epoch, err := readStoreEpochWithoutSeedingInTx(ctx, tx)
if err != nil {
return false, fmt.Errorf("epoch CAS: still serves %s for %s: %w", address, storeID, err)
}
return row.served(epoch), nil
}
// ResolveEpochInTx answers R20's epoch-only restriction for address: Live while
// the store serves it, GoneReorganization once the store lost it (a
// reorganization, not a retention or erasure outcome; RetentionFixture/R17
// states are out of scope here), and Unknown for an address this store never
// minted. Like StillServesInTx it reads only the address's own row and the
// epoch. ProducingStore is always storeID: this file has no lineage/replica
// model to attribute a foreign store to (unlike RetentionFixture's cross-store
// answers).
func ResolveEpochInTx(ctx context.Context, tx DBTX, storeID, address string) (EpochResolveResult, error) {
row, found, err := readEpochMintedAddressInTx(ctx, tx, address)
if err != nil {
return EpochResolveResult{}, err
}
if !found || row.storeID != storeID {
return EpochResolveResult{Restriction: EpochRestrictionUnknown, ProducingStore: storeID}, nil
}
epoch, err := readStoreEpochWithoutSeedingInTx(ctx, tx)
if err != nil {
return EpochResolveResult{}, fmt.Errorf("epoch CAS: resolve %s for %s: %w", address, storeID, err)
}
if row.served(epoch) {
return EpochResolveResult{Restriction: EpochRestrictionLive, ProducingStore: storeID, Epoch: &epoch}, nil
}
return EpochResolveResult{Restriction: EpochRestrictionGoneReorganization, ProducingStore: storeID, Epoch: &epoch}, nil
}
// CurrentAddressForInTx reports the address oldAddress now resolves to: the
// newest address of its lineage, or oldAddress itself when nothing carried the
// Version to a new address. It only reads. It executes no INSERT, UPDATE or
// DELETE, because a lookup that minted an address could make a lost address
// look served again (gastownhall/beads#6664, bee-ghosttrack review 5360880888,
// Major 1), and both Dolt legs run it on a read-write transaction that is
// always rolled back, so a stray write would vanish silently instead of
// failing. oldAddress must be one storeID minted (ErrEpochAddressNotFound
// otherwise) and still serves (ErrEpochAddressNotServed otherwise).
func CurrentAddressForInTx(ctx context.Context, tx DBTX, storeID, oldAddress string) (string, error) {
row, found, err := readEpochMintedAddressInTx(ctx, tx, oldAddress)
if err != nil {
return "", err
}
if !found || row.storeID != storeID {
return "", fmt.Errorf("epoch CAS: current address for %s: %w: %s", storeID, ErrEpochAddressNotFound, oldAddress)
}
epoch, err := readStoreEpochWithoutSeedingInTx(ctx, tx)
if err != nil {
return "", fmt.Errorf("epoch CAS: current address for %s: %w", storeID, err)
}
if !row.served(epoch) {
return "", fmt.Errorf("epoch CAS: current address for %s: %w: %s", storeID, ErrEpochAddressNotServed, oldAddress)
}
var newest string
err = tx.QueryRowContext(ctx,
`SELECT address FROM epoch_minted_addresses WHERE carried_from = ? AND store_id = ? AND gone_at_epoch IS NULL AND minted_epoch <= ? ORDER BY minted_epoch DESC LIMIT 1`,
row.lineageRoot(oldAddress), storeID, epoch,
).Scan(&newest)
if errors.Is(err, sql.ErrNoRows) {
return oldAddress, nil
}
if err != nil {
return "", fmt.Errorf("epoch CAS: current address for %s: read the newest carry of %s: %w", storeID, oldAddress, err)
}
return newest, nil
}
// LoseVersionInTx records that storeID no longer serves the Version named by
// address: it marks the lineage ROOT's own row and every carry row of that
// root gone at the current epoch, so every address of the Version resolves
// GoneReorganization from then on. Each statement is guarded by
// gone_at_epoch IS NULL, so nothing already lost is touched and nothing is ever
// cleared (Gone is terminal). Losing a lineage that is already lost matches no
// rows and returns nil, so a retried transaction may replay it. address must be
// one storeID minted, or ErrEpochAddressNotFound is returned and nothing is
// written. A lineage member minted in an epoch that has not happened yet
// violates the table's gone-not-before-mint check, and the resulting error is
// returned rather than papered over.
func LoseVersionInTx(ctx context.Context, tx DBTX, storeID, address string) error {
row, found, err := readEpochMintedAddressInTx(ctx, tx, address)
if err != nil {
return err
}
if !found || row.storeID != storeID {
return fmt.Errorf("epoch CAS: lose version for %s: %w: %s", storeID, ErrEpochAddressNotFound, address)
}
epoch, err := readStoreEpochWithoutSeedingInTx(ctx, tx)
if err != nil {
return fmt.Errorf("epoch CAS: lose version %s for %s: %w", address, storeID, err)
}
if err := loseLineageInTx(ctx, tx, storeID, row.lineageRoot(address), epoch); err != nil {
return fmt.Errorf("epoch CAS: lose version %s for %s: %w", address, storeID, err)
}
return nil
}

File diff suppressed because it is too large Load diff

View file

@ -106,8 +106,10 @@ func init() {
"RunImporterWiresTheCrossPlaneEdgeBetweenItsRows": importerOneAccessorWaiverReason,
"RunImporterReportsTheCycleEdgeItDropped": importerOneAccessorWaiverReason,
"RunACarriedAddressKeepsResolvingAcrossLaterBumps": retentionEpochNoRoleWaiverReason,
"RunADestructiveOperationEnumeratesAffectedAddressesFirst": retentionEpochNoRoleWaiverReason,
"RunAHoldPreventsRemovalAndReportsInRetainedBounds": retentionEpochNoRoleWaiverReason,
"RunALostAddressStaysGoneAcrossASchemeChange": retentionEpochNoRoleWaiverReason,
"RunAStoreThatRemovesStateStillAnswersGoneDurably": retentionEpochNoRoleWaiverReason,
"RunAStoreWithNoLineageKnowledgeAnswersUnknownNotGone": retentionEpochNoRoleWaiverReason,
"RunAnAddressNeverResolvesToADifferentState": retentionEpochNoRoleWaiverReason,
@ -121,6 +123,7 @@ func init() {
"RunRemovalNeverReassignsASurvivingAddress": retentionEpochNoRoleWaiverReason,
"RunRemovalReasonIsRetentionErasureOrReorganizationDistinctly": retentionEpochNoRoleWaiverReason,
"RunRemovalReportsTheSurvivingRetainedWindow": retentionEpochNoRoleWaiverReason,
"RunTokenSchemeChangeCarriesLiveAddressesAndOnlyThose": retentionEpochNoRoleWaiverReason,
"RunAdvisoryLeaseAloneDoesNotPreventTheInvariantViolation": crossRecordInvariantNoRoleWaiverReason,
"RunCrossRecordInvariantSurvivesTwoPassingPerRecordGuards": crossRecordInvariantNoRoleWaiverReason,
@ -185,30 +188,44 @@ const cycleTracksWireGapWaiverReason = "issueops.DetectCyclesRequest.IncludeTrac
"\"L-cycles-tracks\" — rather than silently answering the narrower walk); no slice through S13 adds a wire " +
"parameter for it, so closing this is a new, not-yet-numbered slice rather than a missing test line"
// retentionEpochNoRoleWaiverReason covers the fifteen RetentionFixture and
// EpochFixture cases: PERMANENTLY unservable over HTTP, not merely unwired
// yet.
// retentionEpochNoRoleWaiverReason covers the eighteen RetentionFixture and
// EpochFixture cases (backend/conformance/retention_epoch_contract.go).
// All but four of the participation-generation cases run on this leg because
// their subject is a create or an update the client can send
// (internal/httpclient/served_participation_generation_test.go; those four
// stay waived under participationGenerationWireGapWaiverReason). These
// cases are different: every hook of these two fixtures IS the operation
// under test, and none has a form on the wire:
// - EpochFixture's hooks (CurrentEpoch, BumpEpoch, MintUnderEpoch,
// StillServes, Resolve, CurrentAddressFor, LoseVersion) are the R20 epoch
// operations themselves: methods on the concrete *DoltStore and
// *EmbeddedDoltStore over issueops' *InTx bodies, on no storage
// interface, no publicops role and no wire operation. Every call path
// into them starts in a test: the methods are called only from each
// store leg's own _test.go files (its EpochFixture, which the
// backend/conformance contracts drive, and its epoch tests), and the
// *InTx bodies only from those methods, from each other and from tests
// (the uow leg's fixture, through a test-only type assertion, and
// issueops' and the dolt leg's own tests). No command, role or server
// handler reaches them, so no client mutation touches epoch state either.
// - RetentionFixture's hooks (Resolve, Remove, Hold, ForceRemove, Erase,
// Mint) are retention operations no backend implements yet: every
// store leg wires them nil and its cases skip, and the wire has no
// removal, hold, erasure or gone/unknown resolve to bind them to.
//
// Both fixtures are RAW STORAGE HOOKS, not a publicops role: RetentionFixture
// and EpochFixture (backend/conformance/retention_epoch_contract.go) carry no
// publicops.XXX field at all, only closures like Resolve, Remove, Hold,
// Erase, Mint, CurrentEpoch, and BumpEpoch that reach past every role
// straight at a backend's own address/epoch/retention bookkeeping — the same
// bookkeeping a storage engine keeps about itself, not a capability it was
// ever going to publish to a caller. dolt, embeddeddolt, and uow all wire
// this contract because all three ARE storage engines with that bookkeeping
// to show; the http leg is a REMOTE CLIENT of one, with no address table,
// epoch counter, or retention window of its own to report — there is nothing
// behind this door for a wire operation to open onto, now or in a later
// slice, unless some future design gives retention/epoch state its own
// publicops role and wire surface. That would be a new role, not a missing
// test line, which is why this is a named waiver rather than a ceiling
// entry.
const retentionEpochNoRoleWaiverReason = "RetentionFixture and EpochFixture carry raw address/epoch/retention " +
"storage hooks (Resolve, Remove, Hold, Erase, Mint, CurrentEpoch, BumpEpoch, ...) with no publicops role " +
"behind them; dolt, embeddeddolt and uow wire this contract because they ARE the storage engine this " +
"bookkeeping belongs to, and the http leg is a remote client with no such bookkeeping of its own to report " +
"— there is no role or wire surface for this to ever route through unless one is designed from scratch"
// Binding the hooks to the reference store behind the served env would run
// the epoch cases green, but as a property of that store, never of the
// client; the store legs already pin it. The waiver stands until retention or
// epoch state gets a publicops role and a wire operation of its own, which
// would be a new role, not a missing test line.
const retentionEpochNoRoleWaiverReason = "every RetentionFixture/EpochFixture hook is the operation under test and " +
"none has a form on the http wire: the R20 epoch operations (CurrentEpoch, BumpEpoch, MintUnderEpoch, " +
"StillServes, Resolve, CurrentAddressFor, LoseVersion) are concrete-store methods on no storage interface, " +
"publicops role or wire operation, reached only from tests (each store leg's fixture and epoch tests call the " +
"methods, the uow fixture calls the issueops bodies through a test-only type assertion), and the retention " +
"hooks (Resolve, Remove, Hold, ForceRemove, Erase, Mint) are implemented by no backend and have no wire " +
"removal, hold, erasure or resolve; binding them to the served env's reference store would test that store, " +
"not the client"
// crossRecordInvariantNoRoleWaiverReason covers the seven CrossRecordInvariantFixture
// cases, for the same shape of reason as retentionEpochNoRoleWaiverReason.

View file

@ -121,6 +121,7 @@ go_library(
"migrations/ignored/0028_add_wisps_participation_generation.up.sql",
"migrations/0070_add_participation_generation.up.sql",
"migrations/0071_add_removed_restriction.up.sql",
"migrations/0072_add_epoch_minted_addresses.up.sql",
],
importpath = "github.com/steveyegge/beads/internal/storage/schema",
visibility = ["//:__subpackages__"],
@ -156,6 +157,7 @@ go_test(
"migration_0069_datetime_precision_test.go",
"migration_0070_add_participation_generation_test.go",
"migration_0071_add_removed_restriction_test.go",
"migration_0072_add_epoch_minted_addresses_test.go",
"migration_body_drain_test.go",
"migration_freeze_test.go",
"migration_watchdog_test.go",

View file

@ -22,19 +22,11 @@ import (
const migration0071Up = "0071_add_removed_restriction.up.sql"
const migration0071Down = "0071_add_removed_restriction.down.sql"
// TestLatestVersionIncludesMigration0071 pins the real next free slot this
// phase claims, superseding 0070's own version of this test
// (migration_0070_add_participation_generation_test.go). Deliberately a
// hardcoded literal for the same reason 0067's, 0068's, 0069's and 0070's
// were: LatestVersion() drifting to 71 for the wrong reason should still be
// caught by this test failing to explain why 71 is removed-restriction-shaped,
// which the CLI test below checks.
func TestLatestVersionIncludesMigration0071(t *testing.T) {
const want = 71
if got := LatestVersion(); got != want {
t.Fatalf("LatestVersion() = %d, want %d (the migration slot claimed for issue_versions.removed_restriction)", got, want)
}
}
// TestLatestVersionIncludesMigration0071 (pinning LatestVersion() == 71) is
// superseded by TestLatestVersionIncludesMigration0072
// (migration_0072_add_epoch_minted_addresses_test.go) now that 0072 claims
// the next free slot -- only one such pin lives at a time, matching how this
// test itself already superseded 0070's own version.
// TestMigration0071AddsRemovedRestriction is a pure-Go, DB-independent check
// of the frozen migration bytes themselves — it runs even where no `dolt`

View file

@ -0,0 +1,184 @@
package schema
import (
"os"
"strings"
"testing"
"github.com/steveyegge/beads/internal/testutil"
)
// R20's epoch-transition enforcement (gastownhall/beads#5898 revision 9,
// #6136) adds one brand-new table,
// epoch_minted_addresses -- see
// migrations/0072_add_epoch_minted_addresses.up.sql for the full rationale.
// This migration is a plain, unguarded
// CREATE TABLE IF NOT EXISTS with no ALTER and no PREPARE, so it needs none
// of 0067/0068's CLI-hazard-override tests (already covered, for every
// migration including this one, by TestBundleMigrationsWithPreparedALTERAreOverriddenOrJustified
// and TestAllMigrationsSQLUsesDirectDDLForKnownCLIIncompatibilities).
// TestLatestVersionIncludesMigration0072 pins the real next free slot this
// phase claims, superseding 0071's own version of this test
// (migration_0071_add_removed_restriction_test.go; only one such pin lives at
// a time, the same way 0071's superseded 0070's).
//
// This slice originally claimed 0069 too. It was renumbered because
// R7.1's removed_restriction migration -- a PARALLEL SIBLING of this branch,
// not an ancestor -- had also claimed 0069, and the two are now linearized:
// R7.1 goes first (it is published beneath gastownhall/beads#6661), this one
// takes the next contiguous slot. Both then moved up one more slot when
// upstream's 0069_widen_issue_versions_datetime_precision
// (gastownhall/beads#6675) landed first, and once more when
// gastownhall/beads#6943's 0070_add_participation_generation (the
// versioned-history write fence) was ordered ahead of them: migrations are
// numbered by landing order, so R7.1 is 0071 and this is 0072.
// Two files sharing a
// version number panic checkNoDuplicateVersions at store open, before any
// command's RunE, which bricks every bd invocation rather than merely
// reddening a package -- see the same hazard on #6358 vs #6008.
//
// Deliberately a hardcoded literal for the same reason 0070's and 0071's
// were: LatestVersion() drifting to 72 for the wrong reason (an unrelated
// migration landing first) should still be caught by this test failing to
// explain why 72 is epoch-minted-addresses-shaped.
func TestLatestVersionIncludesMigration0072(t *testing.T) {
const want = 72
if got := LatestVersion(); got != want {
t.Fatalf("LatestVersion() = %d, want %d (epoch_minted_addresses migration slot claimed by gastownhall/beads#6664)", got, want)
}
}
const migration0072Up = "0072_add_epoch_minted_addresses.up.sql"
const migration0072Down = "0072_add_epoch_minted_addresses.down.sql"
// TestMigration0072RecordsSurvivalInTheAddressTable is a pure-Go,
// DB-independent check of the frozen migration bytes: it runs even where no
// `dolt` binary is available.
//
// An address's survival is RECORDED on its own row, not inferred from other
// rows (gastownhall/beads#6664, bee-ghosttrack review 5360880888, Major 1):
// carried_from names the root address of the lineage a token-scheme change
// carried the row from, and gone_at_epoch is the epoch the store lost it in.
// Both are NULL for a fresh mint. The index serves the two lookups that
// follow a lineage (the newest carry of a root, and every carry of a root to
// lose), and the CHECK is the database-level tripwire against a stale or
// rewound epoch being written into a loss marker. It is >=, not >, because a
// carry row is born at the new epoch and can be lost in that same epoch.
//
// The migration is edited IN PLACE and gains no ALTER and no second slot:
// 0072 has never been applied to a store, and an ALTER over an already-applied
// copy of the earlier shape would be a migration slot nothing may claim.
func TestMigration0072RecordsSurvivalInTheAddressTable(t *testing.T) {
upSQL, err := MigrationSQL(migration0072Up)
if err != nil {
t.Fatalf("MigrationSQL(%s) error = %v, want the migration file to exist", migration0072Up, err)
}
for _, want := range []string{
"CREATE TABLE IF NOT EXISTS epoch_minted_addresses",
"address VARCHAR(255) NOT NULL,",
"store_id VARCHAR(255) NOT NULL,",
"minted_id VARCHAR(255) NOT NULL,",
"minted_epoch INT NOT NULL,",
"minted_at DATETIME NOT NULL,",
"carried_from VARCHAR(255) NULL,",
"gone_at_epoch INT NULL,",
"PRIMARY KEY (address),",
"INDEX idx_epoch_minted_addresses_carried_from (carried_from),",
"CONSTRAINT ck_epoch_minted_addresses_gone_not_before_mint CHECK (gone_at_epoch IS NULL OR gone_at_epoch >= minted_epoch)",
} {
if !strings.Contains(upSQL, want) {
t.Errorf("0072 up migration missing %q\nfull SQL:\n%s", want, upSQL)
}
}
// Only the statements count here: the header comments describe the
// migration in words that would otherwise trip these checks.
statements := strings.ToUpper(stripSQLLineComments(upSQL))
if strings.Contains(statements, "ALTER TABLE") {
t.Error("0072 up migration must not ALTER anything: the survival columns belong to its own CREATE TABLE, because the migration is edited in place while no store has applied it")
}
if strings.Contains(statements, "PREPARE") {
t.Error("0072 up migration must stay plain DDL: CREATE TABLE IF NOT EXISTS needs no guarded PREPARE, and adding one would put it on the pre-2.3 CLI hazard path")
}
if got := strings.Count(statements, "CREATE TABLE"); got != 1 {
t.Errorf("0072 up migration has %d CREATE TABLE statements, want exactly 1", got)
}
// Only migrations/*.up.sql is embedded, so the down side reads from disk by
// package-relative path, as migration 0067's test does.
downBytes, err := os.ReadFile("migrations/" + migration0072Down)
if err != nil {
t.Fatalf("read %s: %v, want the migration file to exist", migration0072Down, err)
}
if !strings.Contains(string(downBytes), "DROP TABLE IF EXISTS epoch_minted_addresses") {
t.Errorf("0072 down migration must drop epoch_minted_addresses, got:\n%s", downBytes)
}
}
// TestMigration0072RecordsSurvivalInTheAddressTableThroughDoltCLI applies the
// full migration bundle through a real `dolt` binary (skipped without one, see
// testutil.RequireDoltBinary) and checks what a pure-Go SQL-text check cannot:
// the column types and nullability Dolt reports, the index it actually built,
// and that the CHECK is enforced on both INSERT and UPDATE, with the boundary
// it is meant to have.
func TestMigration0072RecordsSurvivalInTheAddressTableThroughDoltCLI(t *testing.T) {
testutil.RequireDoltBinary(t)
dir := t.TempDir()
runDoltCommand(t, dir, "init", "--name", "test", "--email", "test@example.com")
runDoltSQL(t, dir, AllMigrationsSQL())
requireDoltColumnShape(t, dir, "epoch_minted_addresses", "carried_from", "varchar(255)", "YES")
requireDoltDataType(t, dir, "epoch_minted_addresses", "gone_at_epoch", "int", "YES")
// The five columns the mint writes keep their shape, so the mint's
// five-column INSERT is unchanged.
requireDoltColumnShape(t, dir, "epoch_minted_addresses", "address", "varchar(255)", "NO")
requireDoltColumnShape(t, dir, "epoch_minted_addresses", "minted_epoch", "int", "NO")
requireDoltNoRows(t, dir, "SELECT address FROM epoch_minted_addresses", "epoch_minted_addresses")
requireDoltCount(t, dir,
`SELECT COUNT(*) AS c FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'epoch_minted_addresses' AND INDEX_NAME = 'idx_epoch_minted_addresses_carried_from' AND COLUMN_NAME = 'carried_from'`,
"1")
// A fresh mint writes the five original columns and is a root row: both
// survival columns come out NULL with no change to the INSERT.
runDoltSQL(t, dir, `INSERT INTO epoch_minted_addresses (address, store_id, minted_id, minted_epoch, minted_at) VALUES ('root-a', 'store', 'record-a', 3, '2026-09-01 00:00:00')`)
requireDoltCount(t, dir, `SELECT COUNT(*) AS c FROM epoch_minted_addresses WHERE address = 'root-a' AND carried_from IS NULL AND gone_at_epoch IS NULL`, "1")
// A carry row names the lineage root.
runDoltSQL(t, dir, `INSERT INTO epoch_minted_addresses (address, store_id, minted_id, minted_epoch, minted_at, carried_from) VALUES ('carry-a', 'store', 'record-a', 5, '2026-09-01 00:00:00', 'root-a')`)
requireDoltCount(t, dir, `SELECT COUNT(*) AS c FROM epoch_minted_addresses WHERE carried_from = 'root-a'`, "1")
// The CHECK: an epoch lost in may not precede the epoch minted in.
if err := runDoltSQLExpectingError(t, dir, `UPDATE epoch_minted_addresses SET gone_at_epoch = 2 WHERE address = 'root-a'`); err == nil {
t.Error("UPDATE gone_at_epoch below minted_epoch succeeded, want the CHECK constraint to reject it")
}
if err := runDoltSQLExpectingError(t, dir, `INSERT INTO epoch_minted_addresses (address, store_id, minted_id, minted_epoch, minted_at, gone_at_epoch) VALUES ('bad-b', 'store', 'record-b', 4, '2026-09-01 00:00:00', 3)`); err == nil {
t.Error("INSERT with gone_at_epoch below minted_epoch succeeded, want the CHECK constraint to reject it")
}
// Equal is allowed: a carry row is born at the new epoch and can be lost in
// that same epoch.
runDoltSQL(t, dir, `UPDATE epoch_minted_addresses SET gone_at_epoch = 3 WHERE address = 'root-a'`)
requireDoltCount(t, dir, `SELECT COUNT(*) AS c FROM epoch_minted_addresses WHERE address = 'root-a' AND gone_at_epoch = 3`, "1")
// A later epoch is allowed too.
runDoltSQL(t, dir, `UPDATE epoch_minted_addresses SET gone_at_epoch = 9 WHERE address = 'carry-a'`)
requireDoltCount(t, dir, `SELECT COUNT(*) AS c FROM epoch_minted_addresses WHERE address = 'carry-a' AND gone_at_epoch = 9`, "1")
// The address stays the primary key.
if err := runDoltSQLExpectingError(t, dir, `INSERT INTO epoch_minted_addresses (address, store_id, minted_id, minted_epoch, minted_at) VALUES ('root-a', 'store', 'record-a', 3, '2026-09-01 00:00:00')`); err == nil {
t.Error("duplicate address insert succeeded, want primary key violation")
}
}
// stripSQLLineComments drops "--" comment lines so a check over a migration's
// statements is not tripped by the prose in its header.
func stripSQLLineComments(sqlText string) string {
var kept []string
for _, line := range strings.Split(sqlText, "\n") {
if strings.HasPrefix(strings.TrimSpace(line), "--") {
continue
}
kept = append(kept, line)
}
return strings.Join(kept, "\n")
}

View file

@ -0,0 +1 @@
DROP TABLE IF EXISTS epoch_minted_addresses;

View file

@ -0,0 +1,64 @@
-- epoch_minted_addresses: durable storage for R20 epoch-transition
-- enforcement (gastownhall/beads#5898 revision 9,
-- #6136). Independent of store_epoch (0067, #6135) -- that table holds only
-- the store-wide singleton epoch counter (the current generation number);
-- this table tracks the individual addresses minted under each generation,
-- which store_epoch has no room to hold. It is also independent of
-- expected_revision_records (R16, #6133) and any RetentionFixture/R17
-- table: R20 epoch reasoning is evaluated on its own, without consulting
-- retention/erasure state, and this migration adds no R17 resolve, remove,
-- hold, force-remove, erase, or mint logic.
--
-- One row per minted address, not one row per id: MintUnderEpoch is
-- deterministic in (store_id, id, epoch) -- see epochAddress() in
-- internal/storage/issueops/epoch_cas.go -- so minting the same id again
-- under the same epoch reproduces the same address and finds the same
-- row, while a later mint of that id under a bumped epoch produces a
-- DIFFERENT address and adds a new row alongside the old one. Old rows are
-- kept: StillServes and Resolve answer for any address from its own row,
-- whatever epoch it was minted in.
--
-- Survival is RECORDED on the row, never inferred from other rows
-- (gastownhall/beads#6664, bee-ghosttrack review 5360880888, Major 1).
-- gone_at_epoch is NULL while the store serves the address and otherwise the
-- epoch the store lost it in; it is set once and never cleared, so a lost
-- address stays lost. carried_from is NULL for a fresh mint, and for a row a
-- token-scheme change carried to a new epoch it is the address of the
-- lineage's ROOT (never the previous carry), so every member of a lineage is
-- one indexed lookup from the newest. The index on carried_from serves exactly
-- the two lookups that follow a lineage: the newest carry of a root, and every
-- carry of a root when the lineage is lost. The CHECK is a database-level
-- tripwire against a stale or rewound epoch being written into a loss marker;
-- it is >=, not >, because a carry row is born at the new epoch and can be lost
-- in that same epoch.
--
-- address is the PRIMARY KEY: it is the deterministic token the fixture's
-- StillServes/Resolve/CurrentAddressFor hooks look addresses up by, so it
-- must be unique and indexed; it is never recomputed from the other columns
-- at read time; it is written once, whatever the epoch was at mint time.
--
-- store_id and minted_id are VARCHAR(255) for parity with this schema's
-- other identifier columns. minted_epoch is INT to match store_epoch.epoch's
-- own type. minted_at is DATETIME, not a nanosecond-precision integer: unlike
-- expected_revision_records.change_at_nanos (R16, 0069 on that slice), no
-- R20 contract case compares minted_at for exact round-tripping -- it exists
-- for observability only, so it follows store_epoch.bumped_at's own
-- DATETIME precedent rather than needing BIGINT.
--
-- Plain, unguarded CREATE TABLE IF NOT EXISTS: a brand-new main-plane table
-- with no ALTER, no PREPARE, and no dolt-ignored (clone-local) table
-- involved, so none of cli_migrations.go's CLI-bundle overrides, an
-- ignored/ twin, or a nondeterminism-allowlist entry apply
-- (scripts/check-migration-hygiene.sh checks B-E).
CREATE TABLE IF NOT EXISTS epoch_minted_addresses (
address VARCHAR(255) NOT NULL,
store_id VARCHAR(255) NOT NULL,
minted_id VARCHAR(255) NOT NULL,
minted_epoch INT NOT NULL,
minted_at DATETIME NOT NULL,
carried_from VARCHAR(255) NULL,
gone_at_epoch INT NULL,
PRIMARY KEY (address),
INDEX idx_epoch_minted_addresses_carried_from (carried_from),
CONSTRAINT ck_epoch_minted_addresses_gone_not_before_mint CHECK (gone_at_epoch IS NULL OR gone_at_epoch >= minted_epoch)
);

View file

@ -8,11 +8,21 @@ import (
)
// TestExpectedRevisionContract wires this leg into the R16/R17
// expected-revision contract. Phase 0 leaves every hook nil in every
// backend's fixture kit (architecture §12), so each case below skips by
// name; this file exists so TestEveryLegWiresEveryRoleContract counts this
// leg, and so the cases start running for real the moment this leg's fixture
// kit grows a non-nil hook.
// expected-revision contract. Every hook is nil (architecture §12's Phase 0
// default), so each case below skips by name; this file exists so
// TestEveryLegWiresEveryRoleContract counts this leg, and so the cases
// start running for real the moment this leg grows a real
// CompareAndSetVersion (gastownhall/beads#6358).
//
// This leg previously wired every hook to an honest "not implemented" stub
// instead of leaving them nil, so each case ran for real and
// failed for that documented reason rather than skipping. That premise —
// that a later slice would give this leg its CompareAndSetVersion — went
// stale once review moved the real implementation to
// gastownhall/beads#6358 instead; a stub whose failure message blames a
// bead that will never land it is worse than an honest skip, so this file
// reverts to nil hooks (gastownhall/beads#6664, bee-ghosttrack review
// 5268699223).
func TestExpectedRevisionContract(t *testing.T) {
ctx := context.Background()
fixture := conformance.ExpectedRevisionFixture{IssuePrefix: "erev"}

View file

@ -2,9 +2,11 @@ package uow
import (
"context"
"fmt"
"testing"
"github.com/steveyegge/beads/backend/conformance"
storeops "github.com/steveyegge/beads/internal/storage/issueops"
)
// TestRetentionContract wires this leg into the R20 retention contract.
@ -57,11 +59,28 @@ func TestRetentionContract(t *testing.T) {
})
}
// TestEpochContract wires this leg into the R20 epoch contract. Same Phase 0
// all-nil state as TestRetentionContract above.
// TestEpochContract runs the R20 epoch contract (gastownhall/beads#5898
// revision 9, #6136) against the unit-of-work
// provider, which reaches the same internal/storage/issueops's epoch Tx
// functions the two store backends wrap — directly against the unit of
// work's own runner (the *baseUOW/base.tx.Runner() pattern
// expected_revision_contract_test.go's expectedRevisionUOWMutateOutside and
// commenter_contract_test.go's SeedCommentAt both use), NOT through the
// domain issue repository: EpochFixture's seven hooks are store-singleton/
// administrative operations with no natural correspondence to
// IssueUseCase's per-issue CRUD/notification semantics, so unlike
// CompareAndSetVersion there is no domain/use-case method to route through
// in the first place — every hook below needs the escape hatch, not just
// one.
//
// One provider for the whole suite (each newUOWRoleFixtureProvider boots a
// real Dolt sql-server) and NO t.Parallel: this backend has no per-test
// copy-on-write branch, so store_epoch/epoch_minted_addresses are
// database-global and a parallel subtest would corrupt another subtest's
// row — same reasoning as TestExpectedRevisionContract's.
func TestEpochContract(t *testing.T) {
ctx := context.Background()
fixture := conformance.EpochFixture{IssuePrefix: "epch"}
fixture := newUOWEpochFixture(t, ctx, "epch")
t.Run("AnEpochBumpIsTriggeredOnlyByRestoreReinitOrSchemeChange", func(t *testing.T) {
conformance.RunAnEpochBumpIsTriggeredOnlyByRestoreReinitOrSchemeChange(t, ctx, fixture)
@ -69,4 +88,184 @@ func TestEpochContract(t *testing.T) {
t.Run("EpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed", func(t *testing.T) {
conformance.RunEpochBumpVoidsOnlyAddressesOfVersionsNoLongerServed(t, ctx, fixture)
})
t.Run("TokenSchemeChangeCarriesLiveAddressesAndOnlyThose", func(t *testing.T) {
conformance.RunTokenSchemeChangeCarriesLiveAddressesAndOnlyThose(t, ctx, fixture)
})
t.Run("ACarriedAddressKeepsResolvingAcrossLaterBumps", func(t *testing.T) {
conformance.RunACarriedAddressKeepsResolvingAcrossLaterBumps(t, ctx, fixture)
})
t.Run("ALostAddressStaysGoneAcrossASchemeChange", func(t *testing.T) {
conformance.RunALostAddressStaysGoneAcrossASchemeChange(t, ctx, fixture)
})
}
// newUOWEpochFixture wires this leg's UnitOfWorkProvider into the R20 epoch
// contract. Like newUOWExpectedRevisionFixture, this fixture needs none of
// roleFixtureKit's CreateIssue/CreateWisp/QueryScalar/CountHistory hooks —
// it has no fields for them — so it does not route through
// newUOWRoleFixtureKit at all.
func newUOWEpochFixture(t *testing.T, ctx context.Context, prefix string) conformance.EpochFixture {
t.Helper()
provider := newUOWRoleFixtureProvider(t, ctx, prefix)
return conformance.EpochFixture{
IssuePrefix: prefix,
CurrentEpoch: epochUOWCurrentEpoch(provider),
BumpEpoch: epochUOWBumpEpoch(provider),
MintUnderEpoch: epochUOWMintUnderEpoch(provider),
StillServes: epochUOWStillServes(provider),
Resolve: epochUOWResolve(provider),
CurrentAddressFor: epochUOWCurrentAddressFor(provider),
LoseVersion: epochUOWLoseVersion(provider),
}
}
// epochUOWRunner recovers the *baseUOW a given attempt's UnitOfWork actually
// is, the same type assertion expectedRevisionUOWMutateOutside makes: Tx.
// Runner() is unexported outside this package and none of the seven epoch
// operations has a domain/use-case method to reach it through instead.
func epochUOWRunner(uw UnitOfWork) (storeops.DBTX, error) {
base, ok := uw.(*baseUOW)
if !ok {
return nil, fmt.Errorf("epoch CAS: unit of work %T does not expose the runner the epoch Tx functions need", uw)
}
return base.tx.Runner(), nil
}
func epochUOWCurrentEpoch(provider UnitOfWorkProvider) func(ctx context.Context, storeID string) (int, error) {
return func(ctx context.Context, storeID string) (int, error) {
return RunTxRead(ctx, provider, func(ctx context.Context, uw UnitOfWork) (int, error) {
runner, err := epochUOWRunner(uw)
if err != nil {
return 0, err
}
return storeops.CurrentEpochInTx(ctx, runner, storeID)
})
}
}
// epochUOWBumpEpoch chooses the bump by the typed trigger: only a
// token-scheme-change bump carries live addresses to the new epoch, and the
// other two triggers move the counter alone. The choice lives here, in the
// contract-test translation layer, because the shared body has no switch on
// the reason string.
func epochUOWBumpEpoch(provider UnitOfWorkProvider) func(ctx context.Context, storeID string, trigger conformance.EpochBumpTrigger) (int, error) {
return func(ctx context.Context, storeID string, trigger conformance.EpochBumpTrigger) (int, error) {
return RunTxResult(ctx, provider, func(ctx context.Context, uw UnitOfWork) (int, string, error) {
runner, err := epochUOWRunner(uw)
if err != nil {
return 0, "", err
}
bump := storeops.BumpEpochInTx
if trigger == conformance.EpochBumpTriggerTokenSchemeChange {
bump = storeops.BumpEpochCarryingInTx
}
epoch, err := bump(ctx, runner, storeID, trigger.String())
if err != nil {
return 0, "", err
}
return epoch, fmt.Sprintf("bd: bump epoch for %s (%s)", storeID, trigger.String()), nil
})
}
}
func epochUOWMintUnderEpoch(provider UnitOfWorkProvider) func(ctx context.Context, storeID, id string) (conformance.Address, error) {
return func(ctx context.Context, storeID, id string) (conformance.Address, error) {
address, err := RunTxResult(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, string, error) {
runner, err := epochUOWRunner(uw)
if err != nil {
return "", "", err
}
address, err := storeops.MintUnderEpochInTx(ctx, runner, storeID, id)
if err != nil {
return "", "", err
}
return address, fmt.Sprintf("bd: mint %s under epoch for %s", id, storeID), nil
})
if err != nil {
return "", err
}
return conformance.Address(address), nil
}
}
func epochUOWStillServes(provider UnitOfWorkProvider) func(ctx context.Context, storeID string, address conformance.Address) (bool, error) {
return func(ctx context.Context, storeID string, address conformance.Address) (bool, error) {
return RunTxRead(ctx, provider, func(ctx context.Context, uw UnitOfWork) (bool, error) {
runner, err := epochUOWRunner(uw)
if err != nil {
return false, err
}
return storeops.StillServesInTx(ctx, runner, storeID, string(address))
})
}
}
func epochUOWResolve(provider UnitOfWorkProvider) func(ctx context.Context, storeID string, address conformance.Address) (conformance.RetentionAnswer, error) {
return func(ctx context.Context, storeID string, address conformance.Address) (conformance.RetentionAnswer, error) {
result, err := RunTxRead(ctx, provider, func(ctx context.Context, uw UnitOfWork) (storeops.EpochResolveResult, error) {
runner, err := epochUOWRunner(uw)
if err != nil {
return storeops.EpochResolveResult{}, err
}
return storeops.ResolveEpochInTx(ctx, runner, storeID, string(address))
})
if err != nil {
return conformance.RetentionAnswer{}, err
}
return epochResolveResultToConformance(result), nil
}
}
func epochUOWCurrentAddressFor(provider UnitOfWorkProvider) func(ctx context.Context, storeID string, oldAddress conformance.Address) (conformance.Address, error) {
return func(ctx context.Context, storeID string, oldAddress conformance.Address) (conformance.Address, error) {
address, err := RunTxRead(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) {
runner, err := epochUOWRunner(uw)
if err != nil {
return "", err
}
return storeops.CurrentAddressForInTx(ctx, runner, storeID, string(oldAddress))
})
if err != nil {
return "", err
}
return conformance.Address(address), nil
}
}
func epochUOWLoseVersion(provider UnitOfWorkProvider) func(ctx context.Context, storeID string, address conformance.Address) error {
return func(ctx context.Context, storeID string, address conformance.Address) error {
return RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) {
runner, err := epochUOWRunner(uw)
if err != nil {
return "", err
}
if err := storeops.LoseVersionInTx(ctx, runner, storeID, string(address)); err != nil {
return "", err
}
return fmt.Sprintf("bd: lose version %s for %s", address, storeID), nil
})
}
}
// epochRestrictionToConformance translates this leg's local
// storeops.EpochRestriction into backend/conformance's own Restriction
// vocabulary — the contract-test file is the translation boundary, per
// epoch_cas.go's package doc.
func epochRestrictionToConformance(r storeops.EpochRestriction) conformance.Restriction {
switch r {
case storeops.EpochRestrictionLive:
return conformance.RestrictionLive
case storeops.EpochRestrictionGoneReorganization:
return conformance.RestrictionGoneReorganization
default:
return conformance.RestrictionUnknown
}
}
func epochResolveResultToConformance(r storeops.EpochResolveResult) conformance.RetentionAnswer {
return conformance.RetentionAnswer{
Restriction: epochRestrictionToConformance(r.Restriction),
ProducingStore: r.ProducingStore,
Epoch: r.Epoch,
}
}