bd versions + a config switch for versioned history — the minimum cut that makes versioned beads usable (#6138) (#6661)

* test(conformance): author R7.1 as-of-read conformance contract

Adds a new Phase 0 conformance contract for R7.1 (as-of reads,
gastownhall/beads#6136, design doc #5898 rev 9) -- no fixture existed for
this anywhere in backend/conformance/, so this is authored from scratch,
not un-skipped.

AsOfReadFixture supplies three hooks: Resolve (the read under test),
MintAt (seeds a version at a controlled accept-time), and
MakeUnanswerable (arranges a Gone/Unknown refusal independently of
RetentionFixture/EpochFixture's own removal machinery, since R7.1's
refusal is a sibling contract to R17/R20, not a dependent of them).

Five Run* functions cover the bead's five required-coverage points
verbatim:
- selector accepts either an instant or a version address, and both name
  the same answer when they resolve to the same version;
- resolution returns the latest version at-or-before T, with a version
  accepted after T strictly excluded even when close by;
- a served result reports the exact address it served;
- an unanswerable read refuses as a typed Gone*/Unknown outcome with a
  reason, and never substitutes a neighboring version, the nearest
  surviving version, or current state -- asserted directly by requiring
  Address == "" on every refusal;
- local completeness only (TC3): a lineage minted into one of two stores
  resolves there and refuses Unknown (FR-06) on the store that never
  received it, asserting nothing about agreement between the two.

The file's doc comment states the Memory-plane-consumer-policy non-goal
explicitly (closed-before-T boundary, sibling exclusion, supersession
exclusion are consumer policy per #5877, not part of this primitive) so
the gap reads as deliberate scope, not an oversight.

Wired onto all three storage legs (dolt, embeddeddolt, uow) with
unconditional "not implemented" stubs rather than partial-real hooks, so
every case fails via MintAt on its first fixture call -- deterministic
RED with no risk of an accidental pass, per the precedent set by
be-x5jqd.1. Sentinel error messages reference be-x5jqd.5, the
implementation child this suite is written ahead of.

TestEveryLegWiresEveryRoleContract requires zero waivers: all 5 new
entrypoints are fully wired (not nil) on all three legs.

Branch cut from the rebased be-2h167 head (5fdfb92fe5).

Verified via go build ./..., go vet ./..., gofmt -l, and go test -tags
cgo across all three legs: all 5 new subtests (8 counting the 4-way
Gone/Unknown table) FAIL for the documented reason,
TestEveryLegWiresEveryRoleContract passes cleanly on all three legs, and
TestVersionedHistoryPhase0RunsInFullSkipMode is unaffected.

Bead: be-x5jqd.2

* fix(history): refuse metadata integers binary64 cannot hold exactly (refs be-wdlod, #6358 follow-up)

canonicalDurableState canonicalizes numbers per RFC 8785 (JCS), which
renders every number as an IEEE-754 binary64 double regardless of
magnitude. An integer-valued metadata literal past 2^53-1 therefore
rounds to a DIFFERENT VALUE on the way into durable_state -- not a
formatting change, a value change -- which can collapse two distinct
issue states onto one durable_state and therefore one content token.

refuseUnrepresentableIntegers is the fix: an admission gate, one layer
above the JCS step, that parses each JSON number literal exactly with
math/big (never float64 -- float64 rounding is the exact thing being
guarded against) and refuses whenever the literal's VALUE, not its
spelling, is an integer whose magnitude exceeds 2^53-1. Value-not-form
matters because the first cut of this gate skipped any literal
containing '.', 'e', or 'E' outright, reasoning that non-integer forms
round-trip losslessly -- true for genuinely fractional literals, but
not for an integer VALUE spelled in decimal or exponential form: QA
found that 9007199254740993.0 and 9.007199254740993e15 walked straight
past that first gate and canonicalized to the same colliding target as
the bare literal. The predicate now inspects the value via
big.Rat.SetString/.IsInt, so all three spellings are refused alike.

1e300 is refused too, no notation carve-out: it denotes the integer
10^300, and binary64 spacing near that magnitude is roughly 2^248 --
vastly wider than the collision window at the 2^53 boundary this gate
exists to close. Admitting that spelling while refusing 9007199254740993
would be the same defect with a bigger window (mayor's ruling, citing
this collision-window argument as decisive). Non-integer values stay
admissible past the bound (1.5e300 is fine): ES6 shortest-round-trip
formatting is a bijection on doubles, so two non-integer literals
collide only if they already denoted the same double before this gate
ever ran, and a fractional literal never carried a promise of exact
decimal storage the way an integer -- an id, a count, a timestamp --
carries a promise of exactness that silent rounding would corrupt.

jcsCanonicalize is canonicalDurableState's RFC 8785 step pulled out on
its own, below the gate rather than behind it, because refusing 1e300
puts the admission policy at odds with one of this store's own spec-
conformance fixtures: testdata/jcs/input/values.json, one of the 10
official RFC 8785 vectors shipped verbatim from the spec's reference
suite (not authored here), itself contains 1E30. RFC 8785 conformance
is a claim about the canonicalizer, not about this store's admission
policy, so TestCanonicalDurableStateIsJCS now runs all 10 shipped
vectors -- values.json included, still asserting 1E30 folds to 1e+30
per spec -- through the ungated jcsCanonicalize, while its two local ad
hoc cases keep exercising the full gated canonicalDurableState, since
neither conflicts and both are more faithful to production traffic that
way. The gate's own refusal of that magnitude is pinned separately, on
its own terms, in version_history_integer_admission_test.go.

Severity is MINOR, not MAJOR: Dolt's JSON column type already
renormalizes metadata to float64 on every read regardless of this gate
(measured on dolt 2.2.3: 9007199254740993 reads back as
9007199254740992, 1e300 as 1e+300), which converges two distinct
in-memory states to one stored state before any version row is minted.
The collision this gate closes is therefore unreachable through normal
bd update traffic on this backend; it stays real for off-path writes --
bd sql, a hand-written JSONL import, or a TEXT-column backend -- which
is why this landed as a follow-up rather than gating Phase 2 itself.

Verified clean: a full module compile; static analysis over the
storage tree; the complete issueops package suite (260 subtests); the
schema package suite; and the broader storage tree, apart from one
dolt-package test that fails identically against the pre-this-diff
baseline (a Dolt server port collision with a concurrent session's
process on this host) -- confirmed pre-existing and environmental, not
caused by this change.

* feat(issueops): implement R7.1 as-of read's store-layer primitive (be-x5jqd.5)

Turns backend/conformance/versioned_read_contract.go (authored RED in
6aefdce60, gastownhall/beads#5898 rev 9, #6136) towards GREEN. This
commit lands the shared production seam; wiring the three per-leg
fixtures (dolt, embeddeddolt, uow) onto it is a follow-up commit.

asof_read.go (new): AsOfReadInTx resolves an AsOfSelector (an instant
or a previously-served version address) to one issue_versions row --
the latest version accepted at or before T, everything later strictly
excluded -- and reports either its state and address, or a typed
refusal (gone-retention/gone-erasure/gone-reorganization/unknown) with
a reason. storeID is accepted only for signature parity with the
fixture hook shape (Design D: the conformance suite's own ad hoc
dispatch string selects among per-leg isolated test stores; issue_versions
carries no store_id column, matching CurrentEpochInTx's precedent).
AsOfRestriction is string-backed, unlike R20's int-backed
EpochRestriction, because it round-trips directly through the new
removed_restriction column with a plain cast.

Migration 0069 adds issue_versions.removed_restriction VARCHAR(30),
nullable (NULL = live, never a stored value). Sits alongside removed_at/
removed_reason (migration 0067, virgin until this slice); AsOfReadInTx
only READS all three -- a future R17 is the real writer via hold/remove/
erase primitives, no collision. Guarded PREPARE + CLI direct-DDL
override + schema_test.go hygiene entries, all modeled on 0068's
pattern; TestLatestVersionIncludesMigration0068 is superseded per the
one-pin-at-a-time convention.

version_history.go: splits RecordVersionInTx into a versionedHistoryEnabled-
gated wrapper and a new exported RecordVersionAtInTx, both delegating to
a shared recordVersionAtInTx(..., at time.Time) body. RecordVersionAtInTx
is test-support only -- ungated, caller-chosen timestamp -- so an as-of-
read fixture's MintAt hook can mint version rows dated in the past
without flipping a store's history-enabled flag. No behavior change for
existing RecordVersionInTx callers.

The new/moved code shifted which function each completeness guard sees
as the enclosing write site, so all three needed updating, not bypassing:
- row_lock_guard_test.go's funcNameExemptions key moves from
  RecordVersionInTx to recordVersionAtInTx (the write's new actual
  enclosing function), reasoning extended to cover both callers.
- journal_completeness_test.go's beadDMLExemptions and
  version_completeness_test.go's versionExemptions each gain a
  RecordVersionAtInTx entry mirroring RecordVersionInTx's own (test-
  support twin, no production caller, no mutation of its own to
  journal/mint beyond the seam itself).

Also fixed a latent test-helper gotcha found while writing the 0069
Dolt-CLI test: queryDoltCSV trims the whole `dolt sql -r csv` output
before parsing, so a row whose ONLY selected column is NULL renders as
a bare blank line that strings.TrimSpace silently swallows when it's
the trailing line, collapsing "one row, NULL value" into "zero rows".
Fixed by selecting a non-NULL anchor column (issue_id) alongside the
column under test.

Verification performed: full module compile and static analysis, gofmt
clean; the complete internal/storage/schema suite with the real-Dolt-CLI
lane enabled; and the complete internal/storage/issueops suite,
including every completeness/row-lock structural guard -- all clean.

* feat(issueops): wire dolt, embeddeddolt, and uow onto R7.1 as-of read (be-x5jqd.5)

Turns backend/conformance/versioned_read_contract.go fully GREEN
(authored RED in 6aefdce60, gastownhall/beads#5898 rev 9, #6136): this
follows up on 4da98a9a8's shared production seam by wiring all three
storage legs' AsOfReadFixture (Resolve/MintAt/MakeUnanswerable) onto
issueops.AsOfReadInTx, per that commit's own stated plan.

Each leg's asOfReadHarness is Design D's dispatch table: the
conformance suite invents storeID strings to select among N isolated
stores, and isolating them is entirely the harness's job --
AsOfReadInTx itself stays storeID-oblivious. The three legs differ
only in how they get that isolation cheaply:
  - dolt: one shared testcontainer, N randomly-named databases
  - embeddeddolt: N fully independent on-disk databases
  - uow: one shared dolt sql-server subprocess (NewDoltServerUOWProvider's
    adoption semantics collapse repeat calls against the same root dir
    onto the same process), N randomly-named databases

All three harnesses are Fatalf/Skip-free below their own
TestAsOfReadContract body: AsOfReadFixture's hooks carry no *testing.T
of their own and run from inside t.Run subtest closures (sometimes
nested two deep), where FailNow/SkipNow would panic with "subtest may
have called FailNow on a parent test". Failures instead flow back as a
plain error into conformance.RunAsOfReadXXX, which Fatalfs correctly
on the subtest's own goroutine.

Two small companion fixes surfaced while wiring the legs on:

  - issueops.asOfVersionAddress -> AsOfVersionAddress (exported): each
    leg's MintAt needs to build the exact token its own
    RecordVersionAtInTx write will resolve against, from a different
    package than issueops.

  - recordVersionAtInTx now truncates `at` to whole seconds before
    writing it to issue_versions.change_at (DATETIME, migration 0067).
    Measured on dolt 2.2.3: the column ROUNDS a sub-second value rather
    than truncating it, so a change_at of 13:32:04.77 lands at 13:32:05
    -- strictly later than the instant it was meant to record. That
    breaks resolveAsOfRevisionInTx's "at or before T" comparison
    (asof_read.go) for any T between the true instant and the rounded-
    up one. This is a production correctness fix, not test-only:
    RecordVersionInTx hits the identical hazard on every real
    time.Now().UTC() call whose nanosecond component rounds up.

Verification performed:
  - uow: TestAsOfReadContract green standalone (5 subtests, 4 nested
    restriction variants) and the full uow package green in isolation
    (673s, includes pre-existing TestReleaserContract and everything
    else). A `go test ./internal/storage/...` full-tree sweep flagged
    uow FAIL via a 600s hang inside TestReleaserContract's migration
    lock -- traced to cross-package parallel resource contention from
    running the whole storage tree's dolt-sql-server-spinning suites
    concurrently, not a regression: the same test is clean when the
    package runs alone.
  - embeddeddolt: TestAsOfReadContract green (22.89s, all subtests and
    all 4 restriction variants).
  - dolt: skipped on this host -- no Docker for the leg's testcontainer,
    the same pre-existing skipIfNoDolt gate the whole dolt package
    already runs under, unrelated to this change.
  - TestEveryLegWiresEveryRoleContract and
    TestEveryContractImporterInTheStorageTreeIsRegistered both pass for
    all three legs.
  - gofmt clean; whole-module build and vet clean.

Bead: be-x5jqd.5

* feat(versions): bd versions + a config switch for versioned history (refs be-hs42e.6.2)

Versioned history has been buildable but not usable: migrations 0067+ create
issue_versions, and the Phase 2 writer fills it, but SetVersionedHistoryEnabled
was a Go method nothing in cmd/bd ever called. There was no supported way for a
person to turn the feature on, and no way at all to read it back without raw
Dolt SQL. This adds the switch and a reader.

- versioned-history.enabled (env BD_VERSIONED_HISTORY_ENABLED), default off,
  applied at the top of wireStorageDecorators. It MUST run on the raw store:
  the capability is a type assertion and no decorator forwards it, so applying
  it after a wrap would silently leave history off while the config said it was
  on. TestVersionedHistoryConfigAppliesToTheRawStore pins the ordering, and
  fails rather than skips if a decorator ever starts forwarding.

- storage.VersionLister + issueops.ListVersionsInTx over issue_versions, on the
  dolt and embeddeddolt legs. A narrow capability rather than a Storage method,
  following ExternalRefHistoryQuerier: a backend that cannot know must be able
  to say so instead of answering "none".

- bd versions <id>, with three distinguishable outcomes rather than two. Off,
  unsupported, and empty are different answers with different fixes; an empty
  list is a claim about the bead, and returning it for the other two would be a
  wrong answer rather than an empty one. The four removal restrictions render
  as four sentences, and unknown (no lineage knowledge here) is not gone.

- REV is printed as a local ordinal with a footer saying so. It is deliberately
  NOT presented as a citable address: AsOfVersionAddress mints over the ordinal,
  two clones can both hold revision 8 of the same bead, and the durable
  version_id primary key has not landed. An address printed now would break
  every citation once it does.

- bd version <id> now points at bd versions <id> instead of printing bd's own
  build and looking like the bead has no history. Bare bd version is unchanged.

No migration: 0067/0068/0069 already carry every column this reads.

Verified on a scratch store: create + 2 updates + close with the flag on lists
4 attributed versions; with the flag off, 0 rows in issue_versions and the
command refuses naming the key.

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

* fix(versions): emit local_revision, not revision, in --json (bee's #5898 consumer read)

types.Issue already ships `json:"revision"` (types.go:1206) and it is the
row-lock CAS token — an unrelated value, and a string where this one is an
int64. Emitting "revision" from the versions payload would put two meanings
and two types on one key in the place machines read: the `bd version`
collision again, with worse consequences, since a script that learned one
shape gets the other and cannot tell.

local_revision also carries the non-citability with the value rather than
only in a footer no script parses, and needs no rename when version_id lands
beside it.

Raised by @bee-ghosttrack's consumer read on #5898, who reported a couple of
hundred script files parsing `bd … --json` — this is the part of the surface
they would actually touch. Pinned by
TestVersionsJSONDoesNotCollideWithIssueRevision.

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

* fix(versions): make the advertised switch actually switch it on (#6661 review)

@bee-ghosttrack's blocking finding: the help text and the off-refusal both
told the user to run `bd config set versioned-history.enabled true`, and that
command did not turn the feature on. The key is not yaml-only, so `bd config
set` routed it to the workspace DATABASE; both readers called config.GetBool,
which is viper (yaml + env) only. The user ran exactly what they were told,
was told it was set, and recording stayed off — configured on, actually off,
one layer up from the decorator-ordering hazard this command already guards.

Takes bee's option (b): read the switch from the store's own config, where
`bd config set` already writes it. That also makes recording a property of
the STORE rather than of whoever is calling, which is what closes finding 2 —
two clients of one sql-server can no longer disagree about whether a write is
recorded.

The two planes are OR'd rather than ranked. The hazard is a write that fails
to record, never one that records when it needn't, so either saying yes is
enough and neither can silently switch the other off. BD_VERSIONED_HISTORY_ENABLED
still works for a one-off run. A store with no settings plane (proxied, no-db)
falls back to viper instead of failing the command.

Also from that review:

- finding 3: the read no longer refuses just because recording is off. A store
  that recorded for a month and was switched off HAS versions; refusing made a
  claim about the store from a fact about this invocation's config, which
  VersionLister's own doc says are independent. Rows are listed either way,
  with a note when recording is currently off; refuse-with-remedy only when
  off AND empty.
- finding 4: an unresolved id with no versions is "no such bead", not "none
  yet". Falling through on an unresolved id stays right — a deleted bead can
  still have versions — but only until the answer is empty.
- finding 5: the ordering test's escape hatch is t.Fatal, not t.Skip; a skip
  returned before the assertion that actually guards the ordering. The
  storage_chain.go doc cited a test name that never existed. version_lister.go
  promised a list of compile-time assertions that was not there; the
  assertions now exist in each leg's own package, where they can compile.
- `versioned-history.` is a recognized config prefix, so the set no longer
  prints "not a recognized config key" immediately before confirming the set.

Test: TestVersionedHistorySwitchRoundTrip_Embedded drives the real
`bd config set` through to a real `bd versions` against a real store, with
BD_VERSIONED_HISTORY_ENABLED cleared so a pass proves the store setting
carried it alone. This is the round trip bee asked for, and it is the only
shape that could have caught the original defect — a fake-backed unit test
cannot see a disagreement between two real planes.

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

* docs(versions): name what the OR'd switch planes cost (#6661 review)

@bee-ghosttrack, round 2: with the two planes OR'd rather than ranked, the
consequence worth naming is that once the store setting says on,
BD_VERSIONED_HISTORY_ENABLED=0 cannot countermand it for a single run. The
help now says so, and says where to turn it off instead.

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

* fix(versions): gate the wiring store read on the capability, not a recover (#6661 review)

@bee-ghosttrack's round-3 blocking finding. wireStorageDecorators reads the
versioned-history switch off the raw store on every bd invocation, and did so
before anything established that the store could use the answer. cmd/bd's own
fakeProbingDoltStore embeds a nil storage.DoltStorage, so the promoted
WorkspaceConfig SIGSEGV'd at wiring time -- and a panic takes the whole test
binary down, which is why one unguarded read showed up as two red CI steps
(Test (macos-latest), PR Core (wrapper timing)) rather than one failed test.

Takes the fix bee prescribed: assert storage.VersionedHistoryConfigurer first
and read the store plane only when the store could act on the answer.

The previous round fixed this with a recover plus a WorkspaceConfig on the
fake, and left a comment arguing that no capability assertion could work. That
argument was wrong, and wrong in a specific way worth recording: it reasoned
about asserting WorkspaceConfig, which IS declared on storage.DoltStorage and
so matches every store including the nil-embedding fake. bee proposed
asserting VersionedHistoryConfigurer, which is a different interface --
SetVersionedHistoryEnabled is NOT part of DoltStorage, so the fake does not
promote it and does not satisfy it. The comment rebutted a fix that had not
been proposed. It now states what is actually true.

So the fake goes back to byte-identical with the pushed head: the wiring fix
fixes that test without touching it, as bee said it would, and the fake keeps
the "only the methods below may be called" constraint its own doc asserts.

The recover stays, as a backstop rather than the guard. It covers what the
assertion does not: versionedHistoryEnabled is also called from `bd versions`,
where the read is the point and no capability gate precedes it, and a store
that DOES implement the capability can still have a half-built settings plane.

The viper plane is still read first and unconditionally, so a set-but-unsupported
store still reaches applyVersionedHistoryConfig and still gets its warning. Only
the store-plane read is gated. The one case that loses a warning is a store whose
own settings plane says true but which lacks the capability -- and `bd config
set` could not have written that plane on such a store to begin with.

Tests, split so each layer fails for its own reason:

- TestWireStorageDecoratorsSkipsTheStoreReadForANonConfigurer asserts calls == 0,
  not merely that it survived. "It survived" is what the recover delivers too,
  which is how this regressed the first time.
- TestWireStorageDecoratorsSurvivesAStoreThatCannotAnswer keeps the recover's
  case, now on a store that IS a configurer so the guard lets it through.
- TestVersionedHistoryEnabledForWiringReadsTheStoreWhenItCanRecord pins that the
  guard did not stop reading the plane finding 1 existed to start reading.

Mutation-verified both ways: removing the guard fails the first test on
calls=1/want=0 while everything still "passes" by surviving; removing the
recover leaves the first test green and fails only the second.

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

* test(versions): name the embedded round-trip so CI selects it (#6661 review)

@bee-ghosttrack's round-3 finding 2. The round-trip test that proves the two
config planes agree ran only on the author's machine.

.github/scripts/embedded-test-shard.sh discovers what to run with
`grep -rh '^func TestEmbedded' cmd/bd/*_embedded_test.go` and validates
manifest entries against ^TestEmbedded[A-Za-z0-9_]+$.
TestVersionedHistorySwitchRoundTrip_Embedded matched neither, so the only
lane that sets BEADS_TEST_EMBEDDED_DOLT=1 for cmd/bd never selected it; the
generic Test jobs run without that env, where the test's own guard skipped it.
Skipped and passed look alike from outside, which is what made it invisible.

Renaming is the whole fix -- a test absent from the shard manifest still gets
a shard from the fallback distribution. Verified by running the script's own
selector over the tree and confirming the new name is discovered.

The rationale is now a comment on the test, because the old name reads more
naturally and nothing else in the file explains why the prefix is load-bearing.

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

* test(versions): drop the dead fixture, name the empty arm (#6661 review)

@bee-ghosttrack's round-3 finding 3. TestVersionsRefusesWhenFlagOff built a
backend holding one recorded version, handed it to nothing, and ended in
`_ = backend`.

The fixture was load-bearing for the assertion the test was named after --
that the read was refused BEFORE the backend was consulted. Finding 3 removed
that behaviour on purpose, so the assertion went with it; the fixture stayed
behind, unused, under a name still promising the old contract.

Renamed to TestVersionsOffAndEmptyRefusesWithRemedy for what it actually pins,
moved beside TestVersionsOffButRecordedStillLists so the two read as the pair
they are -- recording off decides the FOOTER, never whether to read; off with
rows lists them, off and empty is the one case that refuses -- and the dead
fixture is gone.

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

* fix(proxy): give bd versions a capability row, a typed refusal (#6661)

main's proxied-server capability registry (#6582) requires every command
path to carry a row, and TestProxyCapabilityRegistryCoversCommandTree
fails for `bd versions`, which this PR adds.

It is refused, reason unimplemented, rather than permitted. It is a pure
read (issueops.ListVersionsInTx in one read transaction), so nothing
about it is unsafe on a shared backend and "design" would be wrong. But
it reaches the backend only through the optional storage.VersionLister,
which the dolt and embedded stores implement and the uow provider does
not. Permitting it would open the proxied provider in the root pre-run
(starting the proxy and dolt) and then fail untyped at
errVersionsUnsupported. The row refuses with proxy.versions.unsupported
before any side effect, and its tracking names the missing piece: a
VersionLister over the proxied uow provider (tracker #6132).

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

* test(uow): register verified shutdown cleanup in TestAsOfReadContract (#6661)

main's TestEveryServerFixtureRegistersVerifiedCleanup (#6441) requires
every server fixture to use verifiedShutdownCleanup(t, storeRootDir)
instead of calling proxy.Shutdown directly, so a shutdown that refuses
cannot leave a live dolt sql-server behind a green run. TestAsOfReadContract
still had its own proxy.Shutdown cleanup that only logged the error.

The cleanup is registered at the same point, so the LIFO ordering the
harness relies on (every provider closed before the shared server stops)
is unchanged.

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

* style(schema): gofmt cli_migrations.go after the 0070 renumber

The rebase onto upstream's 0069_widen_issue_versions_datetime_precision
(#6675) joined its const and the renumbered 0070 comment without the
separating blank line, which make fmt-check rejects.

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

* fix(history): stop flooring change_at now that 0069 widened it (refs be-hs42e.10)

recordVersionAtInTx carried `at = at.Truncate(time.Second)`. That was correct
while 0067's plain DATETIME was in force: Dolt's datetime(0) does not truncate
sub-second input, it ROUNDS half-up, so a change_at could be stored strictly
LATER than the instant it recorded and break AsOfReadInTx's "latest version
accepted at or before T". Flooring first left nothing to round.

Migration 0069 widened change_at and removed_at to DATETIME(6), which removes
the rounding entirely and makes the floor actively harmful — it threw away the
microseconds the widening exists to keep. Two versions minted in the same
second collapsed onto one stored value and stopped being distinguishable by
change_at, which defeats --at, the only PORTABLE selector the read surface
offers while revision stays a per-store ordinal and no durable version address
has shipped.

This was measured, not inferred. On a store carrying both the widening and the
floor, four versions minted inside one second all read back 15:40:38.000000:
the column could hold microseconds and the writer refused to supply them. Two
correct fixes cancelling each other, and only the second one was visible.

removed_at needs no matching change: MarkLatestVersionRemovedInTx already
passes time.Now().UTC() straight through and was never floored. Audited rather
than assumed.

Pinned by TestRecordVersionKeepsSubSecondChangeAt (embeddeddolt), which mints
two versions 500ms apart inside one second and asserts both that the
fractional part survives and that the two differ. Verified it FAILS with the
floor restored — reporting exactly the 11:04:07.000000 collapse — and passes
without it, so it is a real guard rather than a test that passes either way.
The column's own half of the contract stays pinned by
TestMigration0069ChangeAtSurvivesSubSecondPrecisionThroughDoltCLI.

Also drops this branch's own tx-minting guard commit, which upstream landed
independently as #6833.

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

* test(feat): red — Activate versioned history in every store and provider factory, each store reading its own #6661 switch (stacked on #6661) (refs be-qxq70)

Tests first, all failing on the right reasons at fb6e219d6a (#6661's head):
- D1: on real embedded stores a routed update, a routed close and
  `bd create --repo` into a rig whose OWN row is on each gain 0
  issue_versions rows, want 1; the control (a write inside the rig) gains 1.
- D3: BD_VERSIONED_HISTORY_ENABLED=1 records into no routed store, and =0 is
  shown not to switch off a store whose row is on.
- D4: TestEveryStoreConstructionActivatesVersionedHistory flags all 9 store and
  provider factories, and its mutation probe reports "probed 0 of 9".
- wiring: wireStorageDecorators still reads the store's row (1 read) and
  switches it on; activation belongs to the factories.
- internal/versionedhistory (does not exist yet) and the doctor repair opener:
  the resolver, the provider read (K1), the error-vs-absent diagnostics and the
  shared-activation requirement.

* feat: green — Activate versioned history in every store and provider factory, each store reading its own #6661 switch (stacked on #6661) (refs be-qxq70)

Stacked on #6661 (fb6e219d6a). #6661's plane and approved commits are
unchanged: the switch stays a row of the store's own config table, OR'd with
viper, and `bd config set versioned-history.enabled true` still writes that
row and not config.yaml.

The defect: applyVersionedHistoryConfig ran only from wireStorageDecorators, so
the one store a command opens for its own workspace was activated and every
store built by newDoltStoreFromConfig (prefix-routed update/close, `bd create
--repo`, the direct-mode open) was not. With the switch on they recorded no
issue_versions row while the command reported success.

- Activation moves to where a store or unit-of-work provider is constructed
  (the store_factory.go/_nocgo.go twins, uow_factory.go's two provider
  constructors, the personal-migration planning store, and bd doctor's repair
  opener), on the raw store, before anything can wrap it. wireStorageDecorators
  no longer activates, so each store's row is read once per open.
- One resolver, in internal/versionedhistory, reachable from doctor/fix which
  cannot import package main. #6661's semantics are preserved: one key
  spelling, viper first, then the capability check, then the row read, with
  the recover backstop. The behavior-preserving refactor of #6661's
  versioned_history_switch.go / storage_chain.go is the only edit to files
  #6661 introduced; the resolver tests moved with the code, assertions
  unchanged.
- K1: a provider has no DoltStorage, so its row is read through a unit of work
  (NewUOW + ConfigUseCase().GetConfig) at construction: a pooled connection,
  one SELECT, rolled back. The constructors have already run initSchema, so
  this starts no server and creates nothing. It does not fall back to viper
  alone.
- A row read that errors resolves to off but is reported under BD_DEBUG; an
  absent row stays silent.
- Docs (configuration.md), a CHANGELOG entry, and a hint at `bd config set ...
  true` time that the setting replicates and is single-writer only.

The bazel-sync run also wanted unrelated BUILD entries for files that already
exist at #6661's head (versions.go, versioned_read_contract.go, ...); they are
not part of this change and are left out.

* test(feat): green — a served mutation records from the provider's own row, on a real server (refs be-qxq70)

K1 is the one place the resolver cannot ask a DoltStorage: `bd serve` against a
server-mode workspace writes through a unit-of-work provider, so its flag is
read through NewUOW + ConfigUseCase().GetConfig at construction. The fakes in
internal/versionedhistory prove the read; this proves it WORKS against a real
Dolt server at that moment (pool open, database selected, schema migrated).

Two server-mode workspaces on the shared test container: the one whose own row
says on records a served HTTP mutation (+1 issue_versions row), the one with no
row records none.

Measured both ways: passes with the provider activation in place, and fails
("added 0 issue_versions row(s), want 1") with it deleted from both provider
constructors in uow_factory.go.

Proxied lane only (BEADS_TEST_PROXIED_SERVER=1 BEADS_TEST_ENV_RUN_DOLT=1
TESTCONTAINERS_RYUK_DISABLED=true), like TestServeActivatesTheEventsJournal, so
it skips in a plain make test.

* test(feat): red — #6661 review round, small items: findings 2, 4, 5, 6 and 8

Tests for the small findings in the second review round on #6661.

- 2: `bd versions` must decide "recording" from the store's own setting.
  BD_VERSIONED_HISTORY_ENABLED=1 with the store's row unset and nothing
  recorded must refuse, not answer "none yet"; the help text must not offer
  the variable as a per-run switch for a read.
- 4: `bd versions --json` is one object, {"versions": [...], "recording":
  bool}, with [] rather than null when nothing is recorded.
- 5: AsOfReadInTx reports any stored removed_restriction outside its four
  values, "live" included, as unknown.
- 6: the 0070 header spells the restriction vocabulary with the underscore
  spellings the code stores and compares.
- 8: `bd version <arg>` exits 1 and points at `bd versions <arg>`. This one
  pins behaviour the branch already has, so it passes at red; it was shown
  to fail with the guard removed.

Item 7 is a comment-only fix and has no test.

* feat: green — #6661 review round, small items: findings 2, 4, 5, 6 and 7

- 2: `bd versions` reports the store's own setting. It read the environment
  and config.yaml as well, so BD_VERSIONED_HISTORY_ENABLED=1 made a store that
  never recorded answer "No versions recorded yet" instead of refusing with
  the remedy. It only reads, so those planes cannot make the store record.
  The "for one run" hint is dropped from the help and the refusal, since it
  could only ever produce the wrong answer.
- 4: `bd versions --json` is always {"versions": [...], "recording": bool},
  with [] rather than null when nothing is recorded. Previously a bare array,
  or null, and no recording flag.
- 5: AsOfReadInTx reports a stored removed_restriction outside its four
  values, "live" included, as unknown instead of passing it through.
- 6: the 0070 header and its test use the underscore spellings the code
  stores and compares. 0070 is unreleased, and this changes its content hash.
- 7: comment only. DATETIME(6) still rounds to the microsecond; the comment
  said 0069 removed the rounding entirely.

* test(fix): red — #6661 number admission: fractions past the bound, exponent cost, pre-enable scan

Tests for the review round on the number-admission gate, written before the change:

- a fraction whose nearest double is at or past 2^53 is refused (9007199254740993.5,
  9007199254740994.5, 9007199254740991.5), and the gate is closed under its own
  canonicalization, checked as a property over a corpus
- classification depends on magnitude, not on the size of an exponent: 1e100000000 and
  -1e400 are refusals, 1e-100000000 and 1e-400 are admitted, and allocation does not grow
  with the exponent
- the sentinel's text names the I-JSON exact-integer range
- CheckMetadataVersionable agrees with the mint, and FindUnversionableMetadata finds what
  the mint would refuse and skips what it never versions
- bd config set versioned-history.enabled true refuses, writing nothing, over rows the mint
  would refuse, and false never scans

Guards that pass before and after by design: the verdict on every literal as the store
returns it, the mint's refusal writing nothing, and, on the server and embedded legs, the
store-level property that no two literals reading back as different numbers share a canonical
form. Those store tests also log what each Dolt holds for a number outside the range when
history is off, and pin that a later write to such a row is refused once history is on.

* fix: green — #6661 number admission: the nearest-double rule, ParseFloat classification, a pre-enable scan at the switch

The admission gate now refuses a JSON number literal if and only if the binary64 nearest to it
has magnitude above 2^53-1, or it overflows, whatever the literal's spelling:

- a fraction that rounds to or past 2^53 (9007199254740993.5, 9007199254740994.5,
  9007199254740991.5) is refused, so the gate is closed under its own canonicalization
- literals are classified with strconv.ParseFloat, linear in their length, so 1e1000000 no
  longer builds a million-digit integer inside the writer's transaction; an overflow is the
  sentinel and a magnitude too small for binary64 is admitted; math/big is gone
- the sentinel reads "number is outside the I-JSON exact-integer range (magnitude above
  2^53-1)"; ErrIntegerNotRepresentable keeps its name, with a comment saying why
- ordinary fractions such as 0.1 stay admitted; no verdict on a value the store hands back
  changes

The header now says what the mint's refusal is: an integrity backstop inside the writer's
transaction, not an admission policy for metadata.

bd config set versioned-history.enabled true now checks the store first. It reads every issue
the mint would version, runs the mint's own function over each one's metadata
(issueops.CheckMetadataVersionable, through issueops.FindUnversionableMetadata), and refuses,
writing nothing, while any is refused, printing the count, the ids and the fix. There is no
override; setting it false never scans. The environment and config.yaml planes do not pass
through the command and rely on the refusal at write time.

Also: docs and a CHANGELOG entry, and comments in the existing admission tests that described
the old rule.

* test(fix): keep the exponent-cost allocation test stable under the race detector

TestNumberAdmissionAllocationsDoNotGrowWithTheExponent compared two
independently averaged allocation counts with a strict >. Under -race
sync.Pool drops one Put in four at random, and the refusal's fmt.Errorf
takes its printer from a pool, so a call now and then allocates one more
than it would. The test failed on most runs of `go test -race -short`, the
flag set of the required lane, and never without -race.

That noise only ever adds allocations, so compare the fewest allocations
over many single-call samples instead. The comparison stays strict, and it
still fails on the exact big.Rat gate this test exists to keep out (49
allocations for 1e1000000 against 36 for 1e400). The doc comment no longer
claims the count is deterministic under -race.

* test(fix): red — set-many skips the pre-enable scan; pin what the scan reads

bd config set-many versioned-history.enabled=true switches versioned history
on with no pre-enable scan: only bd config set makes it. With a row holding a
number outside the I-JSON exact-integer range the setting is turned on and the
next write to that row fails. The new embedded test drives the real verb over
such a row and expects the whole batch to be refused, writing nothing.

The scan's own embedded test only used open issues, so deleting AllFlag or
IncludeAllTypes, or replacing the unlimited Limit, left it green. It now adds a
closed, a pinned and a gate offender, and a second test imports more rows than
one default page and expects every one of them counted.

* fix: green — bd config set-many runs the pre-enable scan for versioned-history.enabled

bd config set refuses to turn versioned history on while an issue holds
metadata a version could not record. bd config set-many writes the same
setting through a validation loop of its own and made no such check, so it
switched history on over a row whose next write then failed. It now runs the
same check for that one key inside its validation loop, before any pair of
the batch is written, so a refusal stores nothing. The check reads through
the accessor it already used on both routes: the store the command has
opened on the direct route, the provider on the proxied one.

* chore: strip internal tracker ids from the comments and tests across #6661's range

Comment and test-text changes only; no behaviour changes. Across every commit from the
merge-base with upstream main to here, the comments and tests named internal tracker ids
(one bead id in eleven comments and in one test failure message, an example id in the
`bd version` guard's comment, and an internal decision's attribution in the huge-exponent
admission test). They now cite gastownhall/beads#5898 and #6136 only, which is what a reader
of the public branch can follow.

The 0070 migration's header comment is one of the edits. That migration is new on this branch
(it does not exist on upstream main), so the change is not an edit to a shipped migration, but
it does change the file's content hash; the schema tests that compute hashes are self-consistent.

Text that already exists on upstream main is left as it is, even where it mentions an id: this
commit does not rewrite lines the range did not add.

* chore(bazel): bazel-sync (gazelle) for the #6661 range

* fix(bazel): give fix_test the store.go its activation guard parses

TestVersionedHistoryDoctorRepairOpenerUsesTheSharedActivation parses
store.go from its working directory. `go test` runs in the package
directory, so the file is there. A Bazel test only sees its declared
runfiles, so the test failed with

    parse store.go: open store.go: no such file or directory

in //cmd/bd/doctor/fix:fix_test (--config=ci) and in shard 1 of
//cmd/bd/doctor/fix:fix_dolt_test (--config=doltserver), which runs the
same binary through data = [":fix_test"].

Declare store.go as data on fix_test.

* test(fix): red — the pre-enable scan must check the whole issue, as the mint does

bd config set versioned-history.enabled true runs a check over every issue
before it turns history on. The check looked at each issue's metadata alone,
while the mint canonicalizes the whole issue. A gate's timeout is a
time.Duration that a version holds as nanoseconds, so a gate whose timeout is
past 2^53-1 ns (about 104.25 days) holds a number outside the I-JSON
exact-integer range: the mint refuses every write to it, the scan never
looked, and the switch could be turned on over it.

- The agreement test's domain widens from metadata documents to whole issues:
  the metadata corpus, plus timeouts at 2500h (admitted), 2600h, 8760h and
  -2600h (refused), exactly 2^53-1 ns (admitted) and 2^53 ns (refused).
- The scan test covers a gate over 105 days and expects the verdict to name
  the field, "timeout".
- The mint-level refusal test covers the same gate and expects the refusal to
  name the field as well as the literal, for a number in metadata too.
- An end-to-end test on the direct route and one on the proxied route create
  gates with bd gate create --timeout, expect the enable to refuse and name
  them, and expect the issues the scan names to be exactly the issues whose
  next write the mint refuses.
- Three guards keep the scan's lite read from hiding a number: every column it
  leaves out is a string or a list of strings, nothing the mint adds and the
  scan does not load can hold a number, and no exported check over part of an
  issue exists beside the one the mint runs. Each guard is also run against
  shapes it must refuse, so it cannot pass by finding nothing.

The new symbols (CheckIssueVersionable, FindUnversionable and the Field of
UnversionableIssue) do not exist yet, so the issueops tests do not build.

* fix: green — the pre-enable scan runs the mint's own check over the whole issue

The check behind bd config set versioned-history.enabled true looked at each
issue's metadata alone. The mint canonicalizes the whole issue, and a gate's
timeout, a time.Duration held as nanoseconds, is a number outside the I-JSON
exact-integer range once it is past 2^53-1 ns (about 104.25 days). The mint
refuses every write to such a gate, the scan cleared the switch over it, and
the first write after that failed.

CheckIssueVersionable is now exactly canonicalDurableState's refusal over the
whole issue, and FindUnversionable runs it over every issue the mint would
version. It replaces FindUnversionableMetadata, and CheckMetadataVersionable
is gone, so no check over part of an issue is exported beside the one the mint
runs. A refusal names the top-level field it found the value in ("metadata",
"timeout") as well as the literal, on the mint and on the scan; the field is
located only after a refusal, so a write that is admitted still reads the
document once. A gate timeout above 2^53-1 ns is unrecordable by policy: it is
refused at the write, named by field and documented, not re-encoded.

The refusal at the switch gives the fix for each field. For a number in
metadata that is bd update --metadata or --unset-metadata, which works with
history on or off because a version is recorded from the state after the write.
For a gate timeout, which bd update cannot change, it is removing the gate with
bd delete, or setting the timeout_ns column with bd sql while history is off;
bd sql needs a server-backed store, and the text says so. It also says the
check runs once, now: a writer that does not record (an older bd, bd sql, a
pull from a clone that had history off) can add such a row afterwards, and the
first write to it then fails with the same refusal. Making the check and the
write of the setting one transaction would narrow that window, not close it.

Corrected in the comments, the docs and the changelog as well: an import is not
a path that skips the mint, since it goes through the same batch create; and
Dolt's JSON column collapses duplicate keys when it stores a document, so on a
Dolt store neither the scan nor the mint can see one, and the duplicate-key
refusal is a defence for a backend that keeps them.

* test(fix): red — the listing must answer as the as-of read does; the SDK opens must be accounted for

Three review findings on the versioned-history change and one wording fix,
tests first.

- A removed version's restriction. AsOfReadInTx answers a stored value outside
  the four-value vocabulary (a NULL or empty column, "live", a hyphenated or
  arbitrary string) as unknown, but ListVersionsInTx hands the column back as
  stored, for every row, and the label bd versions prints passes such a string
  through. A table test runs the listing and the as-of read on the same stored
  value, for a version that was removed and one that was not, and expects the
  same answer, and none for a version that was never removed. The label gets
  the same out-of-vocabulary values and is expected to render what unknown
  renders.
- The SDK's store opens. The shared construction guard now scans the repository
  root as well, so the Go SDK's five opens (Open, OpenFromConfig and OpenGated,
  and OpenBestAvailable in each build-tag twin) are noticed. Nothing accounts
  for them yet, so both guards fail on exactly those five sites.
- A bytes bound beside the allocation-count bound on the number admission
  gate. A classifier that builds the number it is asked about makes one
  allocation whatever the exponent, so the count bound passes it, and the bytes
  grow. The fewest bytes one call allocates for a literal with a huge exponent
  must be no more than for a small one plus a margin. It passes today, because
  the gate never builds the number; it fails for a gate that does.
- The refusal at the switch names the gate remedy as bd delete <id> --force,
  says that without --force bd only previews, and says that removing the gate
  unblocks anything it was blocking. The embedded and proxied end-to-end tests
  expect all three.

* fix: green — the listing answers as the as-of read does; the SDK opens are accounted for

Three review findings on the versioned-history change and one wording fix.

A removed version's restriction. A stored removed_restriction is a free string,
and only the four values of the vocabulary are answers. The as-of read already
reported anything else (a NULL or empty column, "live", a hyphenated or
arbitrary string) as unknown, but the listing handed the column back as stored,
for every row, and the label bd versions prints passed it through.
NormalizeRemovedRestriction is now the one place that decision is made.
AsOfReadInTx calls it; ListVersionsInTx calls it for a version that was removed
and gives a version that was not removed no restriction; and restrictionLabel
renders through it. The listing, its JSON and the label now say what the as-of
read says for the same row.

The SDK's store opens. The Go SDK's five opens (Open, OpenFromConfig and
OpenGated, and OpenBestAvailable in each build-tag twin) apply neither per-store
switch, the events journal's or versioned history's, and they still do not.
Applying them would change the library's behavior for every embedder, so that
is a separate change; this one declares the boundary. The shared construction
guard now accounts for the five with one exemption reason that is true of both
switches, so a new SDK open is noticed rather than missed, and its staleness
check keeps the exemptions honest. The docs gain one bullet saying that writers
built on the SDK do not apply the switch.

The bytes bound on the number admission gate needs no production change: the
gate never builds the number, which is what the bound pins.

The refusal at the switch now names the gate remedy as bd delete <id> --force,
says that without --force bd only previews, and says that removing the gate
also unblocks anything it was blocking. The docs line says the same. For a gate
that blocks an issue, bd delete without --force prints a preview and exits 1,
and with --force the gate is removed and what it blocked is ready again.

* test(bazel): declare the root package's Go source as data for //cmd/bd:bd_test

The shared store-construction scan now reads the repository root, where the Go
SDK's opens live, but //cmd/bd:bd_test declared none of the root package's
source. Under bazel test the scan therefore saw an empty directory, reported
the five SDK exemptions as no longer matching a store construction site, and
failed the events-journal guard, while go test, which sees the whole checkout,
passed.

List the root in tools/bazel/go_srcs.py so the generator emits its managed
go_srcs filegroup there, and add that filegroup to bd_test's data. The new
block is the generator's own output and nothing else changes.

* ci: list the switch scan's proxied gate-timeout test in the 30-shard manifest

Upstream main (#7129) moved the proxied-server tier to 30 duration-balanced
shards, and TestProxiedShardManifestGeneratorNotStale requires every
TestProxiedServer*/TestServerMode* test exactly once in that block. This
branch adds TestProxiedServerVersionedHistorySwitchRefusesAnUnrecordableGateTimeout
(cmd/bd/versioned_history_switch_scan_proxied_integration_test.go), so the
block needs its line. Written by the generator itself:
python3 scripts/ci/gen_proxied_shard_manifest.py 30 --weights=duration --write
(one line, shard 8); --check exits 0 afterwards.

Rebase note (maintainer): regenerated on current main, whose proxied-server
tier uses 34 shards; the generator's incremental output
(gen_proxied_shard_manifest.py 34 --weights=duration --write) placed this
test at shard 6 of the 34-shard block.

* ci: list the PR's embedded versioned-history tests in the embedded shard manifests

#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 five embedded cmd tests and three embedded storage 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: 8 lines added, none moved.

Rebase note (maintainer): regenerated on current main, whose embedded
manifests use 100 cmd shards and 40 storage shards; the generator's
incremental output placed these tests at cmd shards 55
(TestEmbeddedVersionedHistorySwitchScansEveryRowNotOnePage), 56
(...SwitchRoundTrip), 57 (...SwitchRefusesUnversionableMetadata), 58
(...SwitchRefusesAnUnrecordableGateTimeout) and 59
(...SetManyRefusesUnversionableMetadata) of the 100-shard block, and at
storage shards 5 (TestRecordVersionKeepsSubSecondChangeAt), 6
(TestVersionedHistoryKeepsNumbersTheStoreDistinguishesApart) and 23
(TestAsOfReadContract) of the 40-shard block.

* test: exempt OpenBestAvailableWith, where #7188 moved the SDK's store construction

Upstream #7188 split beads.OpenBestAvailable: it now delegates to the new
OpenBestAvailableWith, which builds the store. This PR's two construction
guards (TestEveryStoreConstructionActivatesTheEventsJournal and
TestEveryStoreConstructionActivatesVersionedHistory) share one exemption
list keyed by function, so after merging main they flagged
OpenBestAvailableWith as an unexempted construction site and reported the
OpenBestAvailable entries as stale. The two build-tag twins' keys now name
OpenBestAvailableWith. The reason is unchanged: it is the SDK's library
surface for embedders, and no code in the bd binary calls it. gofmt
realigned the three neighbouring entries.

* chore(schema): renumber removed_restriction to 0071 after #6943's 0070

Migrations are numbered by landing order. #6943 (participation_generation,
the versioned-history write fence) lands first and owns main-plane 0070 and
ignored/0028, so this PR's removed_restriction migration moves to the next
free slot, 0071. 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; the intermediate commits of the rebase carry
a duplicate 0070 and are not expected to build.

- migrations/0070_add_removed_restriction.{up,down}.sql become 0071_*, with
  their header comments updated (the SQL itself is unchanged). Neither file
  exists on main or on #6943, so this is not an edit to a shipped migration.
- cli_migrations.go: the CLI-bundle override is keyed to the new file name
  and renamed cliMigration0071AddRemovedRestriction, and its const now sits
  after 0070's.
- migration_0070_add_removed_restriction_test.go becomes
  migration_0071_add_removed_restriction_test.go; its tests and messages say
  0071, and it now owns the one LatestVersion pin (71).
  TestLatestVersionIncludesMigration0070 in #6943's participation_generation
  test is superseded by it and replaced by the usual pointer comment, and
  0069's pointer comment now names the 0070 file that superseded it.
- schema_test.go hygiene comments, BUILD.bazel embedsrcs/srcs, and the
  asof_read.go comment that cited the migration number.

Checked: go test ./internal/storage/schema/... (with the dolt CLI lane,
including TestAllMigrationsSQLAppliesThroughDoltCLIAndRecordsLatestVersion)
and scripts/check-migration-hygiene.sh against origin/main and against
#6943's tip.

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

* test(versions): reconcile #6661's tests and docs with #6943's write fence

#6943's write fence (design §16.2b) makes an update-shaped write to a legacy
record -- one whose participation_generation is NULL because it was created
while versioned history was off -- a skip, not a refusal: the fence returns
before the snapshot is canonicalized, so nothing is versioned and the mint's
admission gate never runs. Several of #6661's tests seed rows with history
off and then expect a later write to them to be versioned or refused, and
several comments say every later write to an offending row fails. On a tree
that carries both PRs those tests fail and those comments are wrong.

This ports, without changing their substance, the fence-integration commits
Jim Wordelman wrote for the donnabox integration fork, where both PRs were
already folded together:

- eff898db80 / 5d2e5a2ac4 (issueops, dolt, embeddeddolt): the mocked mint
  sequence scripts the fence's participation_generation read; the number
  fidelity test splits phase 2 into 2a (a legacy row is written, not
  versioned, not refused, stays NULL) and 2b (a participating row is
  refused and left untouched); TestRecordVersionInTxSkipsALegacyRowBefore-
  TheAdmissionGate pins the fence's order against the gate.
- e0ad9d1e3c / 1528022dfa (cmd/bd): the switch round trip and the routing/env
  end-to-end tests build the rows they expect a version for after the setting
  is on, and assert that the pre-setting seeds gain nothing.
- 18b9015bf5 (cmd/bd): the embedded and proxied gate-timeout scan tests assert
  the whole scan-vs-mint truth table (legacy offenders are named by the scan
  but not refused by the mint; participating offenders are both).
- 5929ebd50c / 8ce872be03 (comments, CHANGELOG, configuration reference): the
  mint's refusal binds rows that participate in history; the pre-enable scan
  cannot see participation, so it over-approximates in the safe direction.

Left out on purpose: the fork's mintSkipsRow helper and defer-wake sweep
change, and its bd doctor "Versionable Issues" check and the docs that point
at it; none of those are part of #6661 or #6943.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Jim Wordelman <jim@wordelman.name>

* test(versions): adapt #6661's guards to what main changed under it

Three test-side adjustments for code that landed on main after #6661's last
merge of it; no production code changes.

- internal/storage/leg_contract_wiring_test.go: main gained an HTTP storage
  leg, and TestEveryLegWiresEveryRoleContract requires every leg to name or
  waive every role contract. The five R7.1 as-of read contracts this PR adds
  are a storage capability the HTTP client does not serve (internal/httpclient
  answers AsOf with an explicit unsupported error, and the wire has no
  instant/address selector or gone/unknown refusal), so they are waived on
  the http leg with that reason, as the donnabox integration fork does.
- cmd/bd/versioned_history_construction_test.go: main split
  newDoltStoreFromConfig into two thin wrappers over openDoltStoreFromConfig,
  which is where the activation defer now lives (this rebase's resolution of
  the activation commit), so the factory guard keys on that body.
- cmd/bd/versioned_history_serve_e2e_test.go: main's
  TestProxiedGatedTestsRunInTheProxiedLane requires a test that skips unless
  BEADS_TEST_PROXIED_SERVER=1 to be one the proxied lane selects, so
  TestVersionedHistoryServeActivatesTheProviderFromItsOwnRow becomes
  TestProxiedServerVersionedHistoryServeActivatesTheProviderFromItsOwnRow,
  and the 34-shard proxied manifest gains its line (written by
  gen_proxied_shard_manifest.py 34 --weights=duration --write, incremental;
  --check passes).

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

* chore(bazel): emit go_srcs.py's managed blocks for internal/versionedhistory

Main's tools/bazel/go_srcs.py now manages a repo_files filegroup block in
every package BUILD file, lists those filegroups in the root BUILD.bazel's
aggregates, and lists every go_library in tools/bazel's release_cross_build
target. internal/versionedhistory is a package this PR adds, so after the
rebase those managed blocks were stale and TestBazelGoSrcsBlocksCurrent
(go test ./scripts/...) failed. This is the generator's own output
(python3 tools/bazel/go_srcs.py) and nothing else; --check passes
afterwards.

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

* fix(versions): don't publish change_agent in bd versions --json

`bd versions <id> --json` prints storage.IssueVersion as-is, so every JSON
tag on that struct is part of a public contract. Provenance V2
(gastownhall/beads#7510, as ruled by the maintainer) removes the ad hoc
agent field in favour of an actor chain; shipping a "change_agent" key now
would make a public contract out of a field that is on its way out.

IssueVersion.ChangeAgent is now tagged json:"-". Nothing else changes: the
issue_versions.change_agent column (migration 0067) stays, ListVersionsInTx
still reads it, change_actor and change_message are still published, and
the human listing never showed the agent. No doc or golden named the key.

TestVersionsJSONDoesNotPublishChangeAgent pins the absence with a non-empty
value, so an omitempty-style regression would still fail, and pins that
change_actor and change_message are still there.

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

* test(issueops): pin what the unfenced test-support mint does on #6943's new paths

#6943's two fixes to the shared mint body -- (a) no issues row means no
mint and no error, and (b) a create-shaped call on a new issues-table row
flagged no-history stamps participation_generation without minting -- were
written for its two kinds. This PR's shared body has a third,
mintUnfenced, behind RecordVersionAtInTx (the R7.1 as-of fixtures'
controlled-timestamp mint). The rebase resolution decided what (a) and (b)
mean for it; this pins that decision:

- (a) applies. It is the plane rule (FR-8: the table that holds the row
  decides its plane), not the fence, and the unfenced kind already honoured
  the flag-based form of the same rule (IsWisp). Without it, an unfenced
  mint for an unflagged wisps-table row would insert a version row that no
  issues row points at. The shared body's issues-table read now runs for
  all three kinds; only the update kind acts on the value it reads.
- (b) does not apply. The unfenced mint never declares participation, so a
  flagged row returns right after the snapshot, as before: no read, no
  stamp.
- The fence still does not apply: a legacy row is minted, and the closing
  UPDATE advances current_revision alone.

TestRecordVersionAtInTxKeepsThePlaneRuleButNotTheFence scripts each of
those three sequences exactly with sqlmock.
TestTestSupportMintsStayOutsideTheShapeSplit places RecordVersionAtInTx
outside #6943's create / dual-shape / update classification explicitly (it
is the seam's exempt twin, not a mutation entry point or mint site): it must
be in none of the shape lists, stay in versionExemptions, and reach neither
RecordVersionForCreateInTx (it never stamps) nor RecordVersionInTx (whose
gate and fence would stop the as-of fixtures minting history-off rows). The
row-lock guard's exemption comment for recordVersionAtInTx already names the
stamp-only UPDATE: #6943's own wording of it (all three UPDATE issues
statements) was carried into that exemption when the as-of read commit was
replayed.

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

* test(storage): say exactly why the as-of read contracts stay waived on http

#6943 now runs most of its participation-generation contracts 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. This checked whether the
five R7.1 as-of read contracts can be wired the same way. They cannot,
cheaply or otherwise, without a new wire operation:

- their subject is the read itself (AsOfReadFixture.Resolve), and R7.1's
  read, issueops.AsOfReadInTx, is reached by no publicops role and served
  by no wire operation;
- the wire carries neither selector (an instant or a served version
  address) nor the gone/unknown refusal the read answers with;
- the client's only point-in-time read, DoltStorage.AsOf, is a Dolt
  commit-ref read, not R7.1, and is on the client's D8 unsupported
  allowlist.

Binding Resolve 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 waiver stays; its comment and reason string now say
the above instead of the earlier shorthand ("HTTP AsOf is explicitly
unsupported"), which conflated the client's commit-ref AsOf with R7.1.

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

* docs(versions): describe what the write fence does to beads that predate recording

With #6943's write fence (design §16.2b) a bead that existed before
versioned history was turned on (participation_generation NULL) is legacy:
an update-shaped write to it is skipped, so it is never versioned however
often it is edited. Several user-facing strings from #6661 still described
the behaviour before the fence, and an independent review reproduced each
with a built bd (a legacy bead edited twice after enabling still lists no
versions; a legacy bead the switch refuses over is written without refusal
under BD_VERSIONED_HISTORY_ENABLED=1). Text only; no behaviour changes.

- bd versions help: only beads created while recording is on are versioned;
  a bead that already existed is legacy and editing it records nothing; no
  backfill. (Was: "a bead edited yesterday shows nothing until it is
  edited again".)
- bd versions empty listing: drops "yet" and says why the list is empty -- a
  bead created while recording is on always has its create version, so an
  empty list means the bead predates recording (or was made by a writer
  that was not recording), or is no-history or a wisp. The line still
  starts "No versions recorded for <id>", which the switch round-trip test
  pins.
- bd versions with recording off: only beads created after it is turned on
  are versioned.
- bd config set versioned-history.enabled true refusal: Jim's scan stays as
  conservative as he made it -- it cannot see participation, and a legacy
  row can still be minted create-shaped if it re-enters the issues plane --
  but the text now says a listed issue's writes are refused only if it
  participates (created while history was on, or entered the issues plane
  while it was on), and that legacy issues are listed because the check
  cannot tell. The closing line says the same of a value a non-recording
  writer adds later.
- docs/reference/configuration.md: the section opener says every accepted
  change to an issue created while history is on is snapshotted, and that a
  pre-existing issue is legacy; the "participates" parenthetical drops "or
  written" (a write never stamps participation; only a create-shaped mint
  does) and names entering the issues plane, matching the refusal text.

CHANGELOG already says "if it participates in history" and is unchanged.

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

* fix(versions): keep updated_at across update-shaped version mints

The update-shaped mint ended with UPDATE issues SET current_revision = ?
WHERE id = ?. current_revision always changes there, so the column's
ON UPDATE CURRENT_TIMESTAMP clause fired: with versioned history on, every
label, dependency or import write moved issues.updated_at to the session's
wall clock (local time, read back as UTC). An import with
RejectStaleUpserts then stored the wall clock instead of the source's
updated_at, and the source's next genuine edit was rejected as stale. The
statement now assigns updated_at to itself, the rule #4298, blocked_state.go's
mark/unmark templates and the create-shaped mint statements already follow,
so history on leaves updated_at exactly where history off does. It is the
one statement every production update-shaped mint ends with.

Tests:
- TestEmbeddedMintLeavesUpdatedAtWhereHistoryOffDoes (embeddeddolt) ages a
  bead, adds and removes a label and a dependency, and runs two
  RejectStaleUpserts imports, with history off first as the control. With
  the fix reverted, history on fails all six arms (updated_at reads the
  wall clock, and the later source edit is rejected as stale); history off
  passes either way.
- RunParticipationGenerationFlagOffSkipsUpdateOnParticipatingRecord, wired
  on the dolt, embeddeddolt, uow and http legs: a record created with the
  flag on and updated with it off mints nothing and keeps its
  current_revision. Every other flag-off case uses a legacy record, which
  the fence stops first, so with RecordVersionInTx's gate removed this is
  the only case that fails, on all four legs. That gate is the single entry
  for every production update-shaped mint, so the one update arm covers
  label and close writes too.
- The sqlmock pin of the statement (version_history_preenable_scan_test.go)
  and the journal-completeness exemption comment follow the new SQL.
- The createbatchequiv issues_updated_at goldens of small, depadd,
  import458 and import458-reject-stale are re-recorded. They pinned the
  wall-clock bump, so each row minted a second time (eq-n2; eq-db1 and
  eq-dl; eq-b3 and eq-b250) had dropped out of the compared set; CI's
  embedded and server legs both printed the new digests. Recorded on
  embedded Dolt, the fix-reverted tree reproduces every committed golden
  byte for byte, HEAD moves only these four digests, and its rows equal
  the history-off rows in every scenario. GoldenDirEnv's comment lists it
  as the goldens' third deliberate change.
- The new embedded test has its line in the storage shard manifest
  (gen_embedded_storage_shard_manifest.py 40 --weights=duration --write),
  so TestStorageEmbeddedShardManifestGeneratorNotStale stays green. It sits
  after TestEmbeddedEveryAcceptedLifecycleMutationMintsOneVersion rather
  than at the end of the file, where #7646 appends its own test, so the two
  PRs still merge without a conflict in that file.

Docs:
- CHANGELOG: the feature's two entries under ### Fixed described fixes to a
  switch no released bd has. One ### Added entry replaces them, covering
  bd versions, the versioned-history.enabled switch and its per-store
  semantics, the pre-enable check, the single-writer caveat, migration 0071
  and the bd version <arg> refusal.
- The bd versions help, its recording-off refusal and empty-listing note,
  and the opening paragraph of the configuration doc's Versioned Issue
  History section now state the rule the pre-enable refusal prints: a bead
  participates if it was created, or entered the issues plane (a wisp
  promoted or made persistent), while recording was on.

bd version: the "did you mean bd versions" refusal now runs after the
command's metrics event is created, like the other in-RunE argument
refusals, so a mistyped bd version <id> is counted as a version invocation
instead of going uncounted.

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

---------

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 17:28:16 +00:00 • committed by GitHub
commit 9c6f6e15cd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
86 changed files with 9156 additions and 111 deletions

View file

@ -133,14 +133,19 @@
100 54 TestEmbeddedSearchConcurrent
100 55 TestEmbeddedUndefer
100 55 TestEmbeddedVersionedHistorySwitchScansEveryRowNotOnePage
100 56 TestEmbeddedDepNoCycleCheck
100 56 TestEmbeddedVersionedHistorySwitchRoundTrip
100 57 TestEmbeddedQueryConcurrent
100 57 TestEmbeddedVersionedHistorySwitchRefusesUnversionableMetadata
100 58 TestEmbeddedDepAAddRejectionsAndBulk
100 58 TestEmbeddedVersionedHistorySwitchRefusesAnUnrecordableGateTimeout
100 59 TestEmbeddedDeferAutoWake
100 59 TestEmbeddedVersionedHistorySetManyRefusesUnversionableMetadata
100 60 TestEmbeddedCommentsCLI
100 60 TestEmbeddedRoutedWriteMissDoesNotCreateTargetDatabase

View file

@ -186,6 +186,7 @@
40 5 TestEmbeddedClaimerRefusesIncompleteRequestsAndAnAbsentIDWithoutTouchingState
40 5 TestEmbeddedIssueOperationsCloseAndReopenAWisp
40 5 TestEmbeddedReaderListKeysetPositionResumesTheCreatedDescIDAscOrder
40 5 TestRecordVersionKeepsSubSecondChangeAt
40 5 TestWithPeerAuth
40 6 TestCreateBatchFastPathsMatchPerRowApplyWaitsFor_Embedded
@ -195,6 +196,7 @@
40 6 TestEmbeddedRelationsAnswersAWispTargetInTheOutDirection
40 6 TestPromoteStillWorksWithCollisionGuard
40 6 TestSearchWithMissingWispPlaneTables
40 6 TestVersionedHistoryKeepsNumbersTheStoreDistinguishesApart
40 7 TestConcurrencyMultiProcess
40 7 TestEmbeddedBatchCloserRecordsOneHistoryEntryForWhatLanded
@ -208,6 +210,7 @@
40 8 TestDeleterContract
40 8 TestEmbeddedDependencyEditorRoutesWispSourcedRemovalToTheWispPlane
40 8 TestEmbeddedMergeAndSettleDirtyWorkingSetSurvivesRefusedMerge
40 8 TestEmbeddedMintLeavesUpdatedAtWhereHistoryOffDoes
40 8 TestEmbeddedReaderGetBriefDepsProjectsTheDependencyRows
40 8 TestEmbeddedRelationsOrdersNeighborsFromBothPlanesTogether
40 8 TestEmbeddedReopenIssueCategorySemantics
@ -369,6 +372,7 @@
40 22 TestLeaseLifecycleEmbedded
40 22 TestPolicyBlockingAnnotatorForeignOpensAreSublinear
40 23 TestAsOfReadContract
40 23 TestEmbeddedBatchCloserBackendFailureReturnsNoOutcomes
40 23 TestEmbeddedBatchCloserClaimNextHydratesWhenSomethingClosed
40 23 TestEmbeddedDependencyEditorAcceptsBlockingAcrossIssueTypes

View file

@ -69,6 +69,7 @@
34 6 TestProxiedServerServeReadsTheJournalItJustWrote
34 6 TestProxiedServerSwarm
34 6 TestProxiedServerUpdate2B
34 6 TestProxiedServerVersionedHistorySwitchRefusesAnUnrecordableGateTimeout
34 6 TestProxiedServerWispList
34 7 TestProxiedServerCloseConcurrent
@ -254,6 +255,7 @@
34 30 TestProxiedServerStatus
34 30 TestProxiedServerTodo
34 30 TestProxiedServerUpdate2
34 30 TestProxiedServerVersionedHistoryServeActivatesTheProviderFromItsOwnRow
34 31 TestProxiedServerCloseBeadGate
34 31 TestProxiedServerComment

View file

@ -246,6 +246,19 @@ exports_files(
visibility = ["//internal/httpclient/encode:__pkg__"],
)
# --- begin go_srcs (managed by tools/bazel/go_srcs.py; run `make bazel-sync`) ---
filegroup(
name = "go_srcs",
srcs = glob(
["**/*.go"],
allow_empty = True,
),
visibility = ["//:__subpackages__"],
)
# --- end go_srcs ---
# --- begin repo_files (managed by tools/bazel/go_srcs.py; run `make bazel-sync`) ---
filegroup(
@ -413,6 +426,7 @@ filegroup(
"//internal/utils:repo_doc_files",
"//internal/validation:repo_doc_files",
"//internal/versioncheck:repo_doc_files",
"//internal/versionedhistory:repo_doc_files",
"//internal/workapi:repo_doc_files",
"//internal/workapi/storecounter:repo_doc_files",
"//internal/workapi/storequerier:repo_doc_files",
@ -647,6 +661,7 @@ filegroup(
"//internal/utils:repo_go_srcs",
"//internal/validation:repo_go_srcs",
"//internal/versioncheck:repo_go_srcs",
"//internal/versionedhistory:repo_go_srcs",
"//internal/workapi:repo_go_srcs",
"//internal/workapi/storecounter:repo_go_srcs",
"//internal/workapi/storequerier:repo_go_srcs",
@ -866,6 +881,7 @@ filegroup(
"//internal/utils:repo_go_test_srcs",
"//internal/validation:repo_go_test_srcs",
"//internal/versioncheck:repo_go_test_srcs",
"//internal/versionedhistory:repo_go_test_srcs",
"//internal/workapi:repo_go_test_srcs",
"//internal/workapi/storecounter:repo_go_test_srcs",
"//internal/workapi/storequerier:repo_go_test_srcs",
@ -1094,6 +1110,7 @@ filegroup(
"//internal/utils:repo_other_files",
"//internal/validation:repo_other_files",
"//internal/versioncheck:repo_other_files",
"//internal/versionedhistory:repo_other_files",
"//internal/workapi:repo_other_files",
"//internal/workapi/storecounter:repo_other_files",
"//internal/workapi/storequerier:repo_other_files",

View file

@ -9,6 +9,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- `bd versions <id>` lists the versions recorded for a bead, and
`versioned-history.enabled` turns recording on. While it is on, every
accepted change to a bead created while it is on, or that enters the issues
plane while it is on (a wisp promoted or made persistent), stores a
snapshot of it as a row of `issue_versions` in the same transaction. It is
off by default and nothing is backfilled: a bead already on the issues
plane when it is turned on is legacy, and editing it records nothing. A
recorded write leaves `updated_at` where an unrecorded one would, so
`bd import`'s stale check sees the same timestamps either way.
`bd versions --json` answers `{"versions": [...], "recording": bool}`; the
command still lists what was recorded after recording is turned off, and
proxied-server and HTTP workspaces refuse it. The setting is a row of each
store's `config` table (`bd config set versioned-history.enabled true`),
and every store reads its own when it is opened: a write routed into
another workspace (a prefix-routed `bd update` or `bd close`,
`bd create --repo`) follows the target store's row, a proxied-server
provider reads it when it is constructed, and a long-lived `bd serve`
keeps the value it read until it restarts.
`BD_VERSIONED_HISTORY_ENABLED=1` (or a `config.yaml` value) turns
recording on for every store the process opens, and never turns it off.
The row replicates on `bd dolt push`/`pull`, and recording is single-writer
only: two clones recording at once can mint the same revision and fail the
pull, and a write from a writer that is not recording is folded into the
next recorded version under that version's actor, so keep recording on for
every writer of a store or off for all of them. Turning it on with
`bd config set` first checks every issue the store would version and
refuses, writing nothing, while any holds a number outside the I-JSON
exact-integer range (magnitude above 2^53-1, however it is spelled) in its
metadata or in a gate's timeout (held as nanoseconds, so about 104.25
days), and prints the count, the ids, the field and the fix. There is no
override, and the check runs once; after that, a recorded write that would
hold such a number fails atomically. Migration 0071 adds a nullable
`removed_restriction` column to `issue_versions`. `bd version` now refuses
an argument and suggests `bd versions <arg>`, instead of printing bd's
build for a mistyped `bd version bd-123`.
- `bd blocked --flags` prints the blocked flag for each id read from stdin
(one per line; blank lines and repeats ignored), with `--json` as
`[{"id","is_blocked"}]` in the order the ids were given, omitting an id that

View file

@ -65,6 +65,7 @@ go_library(
"transaction_parity.go",
"tree_walker_contract.go",
"version_reconciler_contract.go",
"versioned_read_contract.go",
"workspaceconfig_contract.go",
],
importpath = "github.com/steveyegge/beads/backend/conformance",

View file

@ -267,6 +267,65 @@ func RunParticipationGenerationProceedsForPromotedRecord(t *testing.T, ctx conte
}
}
// RunParticipationGenerationFlagOffSkipsUpdateOnParticipatingRecord pins the
// switch's off half for a record the fence would let through: created with
// the flag on (so participation_generation is stamped), then updated after
// the flag is turned back off, it must mint nothing. ProceedsForPromotedRecord
// shows the fence passes such a record, so only the flag stands between this
// update and a mint. No other case can see a writer that ignores the flag on
// updates: every other flag-off record is legacy, and the fence stops those
// first.
func RunParticipationGenerationFlagOffSkipsUpdateOnParticipatingRecord(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) {
t.Helper()
if err := fixture.SetFlag(ctx, true); err != nil {
t.Fatalf("enabling versioned history: %v", err)
}
id := fixture.IssuePrefix + "-flag-off-skip"
if err := fixture.Mutate(ctx, id); err != nil {
t.Fatalf("mutating %s: %v", id, err)
}
if gen, err := fixture.ParticipationGeneration(ctx, id); err != nil {
t.Fatalf("reading participation_generation for %s: %v", id, err)
} else if gen == nil {
t.Fatalf("participation_generation for %s is NULL immediately after a create with the flag on — "+
"this case cannot test the flag against a record the fence would have stopped anyway", id)
}
if err := fixture.SetFlag(ctx, false); err != nil {
t.Fatalf("disabling versioned history: %v", err)
}
beforeRevision, err := fixture.CurrentRevision(ctx, id)
if err != nil {
t.Fatalf("reading current_revision for %s: %v", id, err)
}
beforeCount, err := fixture.VersionRowCount(ctx, id)
if err != nil {
t.Fatalf("counting version rows for %s: %v", id, err)
}
if err := fixture.MutateExisting(ctx, id); err != nil {
t.Fatalf("mutating existing %s: %v", id, err)
}
afterRevision, err := fixture.CurrentRevision(ctx, id)
if err != nil {
t.Fatalf("reading current_revision for %s: %v", id, err)
}
afterCount, err := fixture.VersionRowCount(ctx, id)
if err != nil {
t.Fatalf("counting version rows for %s: %v", id, err)
}
if afterCount != beforeCount {
t.Errorf("version row count for %s went from %d to %d across an update-shaped mutation with the "+
"flag off, want unchanged: turning versioned history off stops minting for every record, "+
"including one that already participates", id, beforeCount, afterCount)
}
if afterRevision != beforeRevision {
t.Errorf("current_revision for %s went from %d to %d across the same update with the flag off, "+
"want unchanged", id, beforeRevision, afterRevision)
}
}
// RunParticipationGenerationWispPromotionBeginsHistory pins that promoting a
// wisp onto the issues plane is CREATE-shaped in design §16.2b's sense. (This
// is wisp promotion, PromoteFromEphemeral: not R2.3's promotion of a legacy

View file

@ -0,0 +1,356 @@
package conformance
import (
"context"
"testing"
"time"
)
// This file holds the contract for R7.1 (gastownhall/beads#6136, design doc
// gastownhall/beads#5898 revision 9): the as-of read — the "versioned
// reads" half of Phase 3's title, authored here from scratch, since no
// fixture for it exists anywhere in this package to un-skip.
//
// R7.1, VERBATIM (design doc #5898 rev 9): "An as-of read is a named read
// whose selector is an instant. Given an instant T or a version address, a
// store returns one Bead's durable state as of that point — the latest
// version it holds that was accepted at or before T, with everything later
// excluded — under R7's record shape, marking the address it served, or
// refuses as gone or unknown with the reason (R8, R20). Like every history
// answer it is complete for the answering store's holdings and may change
// after a sync (TC3)."
//
// ADDRESS, RESTRICTION, AND CHANGEATTRIBUTION ARE DECLARED IN
// expected_revision_contract.go — see that file's package-level note on
// where this suite's shared vocabulary lives and why. This file reuses
// Restriction's five values as-is for the gone-or-unknown refusal outcome
// (R8): an as-of read never invents a sixth state, and never distinguishes
// "gone" from "unknown" any differently than R20 already does.
//
// EVERY HOOK ON THE FIXTURE BELOW IS INDEPENDENTLY NILABLE — see the
// package-level note in expected_revision_contract.go. Every case
// nil-checks every hook it uses and SKIPS BY NAME when one is missing. No
// backend implements as-of reads yet — the implementation is
// the child this suite is written ahead of.
//
// EXPLICIT NON-GOAL: MEMORY-PLANE CONSUMER POLICY IS NOT PART OF THIS
// PRIMITIVE. R7.1's own text is explicit that a closed-before-T boundary,
// sibling exclusion, and supersession exclusion "are Memory-plane policies
// a consumer layers on this primitive (#5877), not part of it." This suite
// does not implement or assert any of the three — a future reader who finds
// them absent should read that as this file honoring R7.1's own scope, not
// as an oversight. This is the read-side analog of the R16/R16.1 boundary
// risk already recorded in expected_revision_contract.go: do not conflate
// the primitive with policy layered on top of it.
//
// THIS SUITE ASSERTS LOCAL COMPLETENESS ONLY (TC3). Nothing below requires,
// or even checks, that two stores asked about the same lineage agree — R7.1
// itself says an as-of answer "may change after a sync," so two stores at
// different sync points are expected to answer differently, and neither is
// wrong. RunAsOfReadIsCompleteOnlyForTheAnsweringStoresHoldings is the one
// case that touches more than one store, and what it asserts is exactly
// this: each store answers strictly from its own holdings, never a
// sibling's — not that the two agree.
// AsOfSelector names the point R7.1 resolves against: either a wall-clock
// instant, or a specific version Address treated as the selector itself —
// "the read that names its own answer" (R7.1: "an instant T or a version
// address"). Exactly one of At/Version is populated in every case this file
// exercises; R7.1 does not speak to the shape where both or neither are
// set, so this suite does not either.
type AsOfSelector struct {
At *time.Time
Version *Address
}
// AsOfReadRefusal is R8's typed outcome for an as-of read that cannot be
// answered. Restriction is always one of the four Gone*/Unknown values,
// never RestrictionLive — a live answer is a served AsOfReadResult, not a
// refusal. Reason explains why (R8).
type AsOfReadRefusal struct {
Restriction Restriction
Reason string
}
// AsOfReadResult is the outcome of an as-of read (R7.1). Address/State and
// Refusal are mutually exclusive: read Address/State only when Refusal is
// nil.
type AsOfReadResult struct {
// Address is the version this read served, marking "the address it
// served" (R7.1). Populated only when Refusal is nil.
Address Address
// State is the served version's durable state under R7's record shape.
// Opaque to this suite: the fixture adapter translates a backend's real
// record shape into this map, and no case here asserts its field-level
// content — only that a served result carries an Address.
State map[string]any
// Refusal is populated instead of Address/State when the read cannot be
// answered (R8). Nil means the read was served.
Refusal *AsOfReadRefusal
}
// AsOfRead resolves storeID's answer to an as-of read against id's lineage,
// at selector (R7.1).
type AsOfRead func(ctx context.Context, storeID, id string, selector AsOfSelector) (AsOfReadResult, error)
// AsOfReadFixture supplies the capability under test for R7.1: a read whose
// selector is an instant or a version address, resolving to the latest
// version accepted at or before that point, or a typed refusal.
type AsOfReadFixture struct {
IssuePrefix string
// Resolve performs the as-of read under test (R7.1). A nil hook means
// this backend does not implement as-of reads yet, and every case in
// this file skips with that reason.
Resolve AsOfRead
// MintAt mints a fresh version for id under storeID, recorded as
// accepted at the given instant, and returns its Address. Cases use
// this to build a lineage with known accept-times to resolve an as-of
// read against. A nil hook means this backend has no way to mint a
// version at a controlled accept-time, and cases that need one skip
// with that reason.
MintAt func(ctx context.Context, storeID, id string, acceptedAt time.Time) (Address, error)
// MakeUnanswerable arranges for id to be unanswerable at storeID for
// the given Restriction (one of RestrictionGoneRetention/GoneErasure/
// GoneReorganization/Unknown) — independently of
// RetentionFixture/EpochFixture's own removal machinery, since R7.1's
// refusal is a sibling contract to R17/R20, not a dependent of them. A
// nil hook means this backend has no way to arrange this, and the case
// that needs it skips with that reason.
MakeUnanswerable func(ctx context.Context, storeID, id string, restriction Restriction) error
}
// RunAsOfReadSelectorAcceptsEitherAnInstantOrAVersionAddress pins R7.1's
// selector shape: an instant T and the version address that instant
// resolves to are two names for the same answer, and a store must accept
// either.
func RunAsOfReadSelectorAcceptsEitherAnInstantOrAVersionAddress(t *testing.T, ctx context.Context, fixture AsOfReadFixture) {
t.Helper()
if fixture.Resolve == nil {
t.Skip("this backend does not implement as-of reads (Resolve is nil)")
}
if fixture.MintAt == nil {
t.Skip("this backend has no way to mint a version at a controlled accept-time (MintAt is nil)")
}
store := asOfReadStore(fixture, "selector-kinds")
id := fixture.IssuePrefix + "-asof-selector"
t0 := time.Now().UTC().Add(-time.Hour)
asOfReadMint(t, ctx, fixture, store, id, t0)
t1 := t0.Add(time.Minute)
second := asOfReadMint(t, ctx, fixture, store, id, t1)
byInstant, err := fixture.Resolve(ctx, store, id, AsOfSelector{At: &t1})
if err != nil {
t.Fatalf("Resolve(selector=instant): %v", err)
}
if byInstant.Refusal != nil {
t.Fatalf("Resolve(selector=instant) = %+v, want a served result", byInstant)
}
byVersion, err := fixture.Resolve(ctx, store, id, AsOfSelector{Version: &second})
if err != nil {
t.Fatalf("Resolve(selector=version address): %v", err)
}
if byVersion.Refusal != nil {
t.Fatalf("Resolve(selector=version address) = %+v, want a served result", byVersion)
}
if byInstant.Address != second {
t.Errorf("Resolve(selector=instant matching a version's own accept-time).Address = %s, want %s", byInstant.Address, second)
}
if byVersion.Address != second {
t.Errorf("Resolve(selector=version address).Address = %s, want the same address named %s", byVersion.Address, second)
}
if byInstant.Address != byVersion.Address {
t.Errorf("an instant selector (served %s) and a version-address selector naming the same version (served %s) resolved to different addresses; R7.1 accepts either as a name for the same answer", byInstant.Address, byVersion.Address)
}
}
// RunAsOfReadReturnsTheLatestVersionAtOrBeforeTStrictlyExcludingLater pins
// R7.1's ordering promise: resolving at T returns the latest version
// accepted at or before T, and a version accepted after T is excluded even
// when its own instant is close by.
func RunAsOfReadReturnsTheLatestVersionAtOrBeforeTStrictlyExcludingLater(t *testing.T, ctx context.Context, fixture AsOfReadFixture) {
t.Helper()
if fixture.Resolve == nil {
t.Skip("this backend does not implement as-of reads (Resolve is nil)")
}
if fixture.MintAt == nil {
t.Skip("this backend has no way to mint a version at a controlled accept-time (MintAt is nil)")
}
store := asOfReadStore(fixture, "ordering")
id := fixture.IssuePrefix + "-asof-ordering"
t0 := time.Now().UTC().Add(-time.Hour)
asOfReadMint(t, ctx, fixture, store, id, t0)
t1 := t0.Add(time.Minute)
middle := asOfReadMint(t, ctx, fixture, store, id, t1)
t2 := t0.Add(2 * time.Minute)
asOfReadMint(t, ctx, fixture, store, id, t2)
atExactly, err := fixture.Resolve(ctx, store, id, AsOfSelector{At: &t1})
if err != nil {
t.Fatalf("Resolve(T=middle's own instant): %v", err)
}
if atExactly.Refusal != nil || atExactly.Address != middle {
t.Errorf("Resolve(T=middle's own instant) = %+v, want the version accepted exactly at T (%s), not a later one", atExactly, middle)
}
between := t1.Add(30 * time.Second)
betweenResult, err := fixture.Resolve(ctx, store, id, AsOfSelector{At: &between})
if err != nil {
t.Fatalf("Resolve(T strictly between two versions): %v", err)
}
if betweenResult.Refusal != nil || betweenResult.Address != middle {
t.Errorf("Resolve(T strictly between two versions) = %+v, want the latest version at-or-before T (%s); the version accepted after T must be strictly excluded", betweenResult, middle)
}
}
// RunAsOfReadReportsTheAddressItServed pins R7.1's "marking the address it
// served": a served result names the exact Address of the version it
// returned, not merely a truthy success.
func RunAsOfReadReportsTheAddressItServed(t *testing.T, ctx context.Context, fixture AsOfReadFixture) {
t.Helper()
if fixture.Resolve == nil {
t.Skip("this backend does not implement as-of reads (Resolve is nil)")
}
if fixture.MintAt == nil {
t.Skip("this backend has no way to mint a version at a controlled accept-time (MintAt is nil)")
}
store := asOfReadStore(fixture, "reports-address")
id := fixture.IssuePrefix + "-asof-reports-address"
at := time.Now().UTC()
address := asOfReadMint(t, ctx, fixture, store, id, at)
result, err := fixture.Resolve(ctx, store, id, AsOfSelector{At: &at})
if err != nil {
t.Fatalf("Resolve: %v", err)
}
if result.Refusal != nil {
t.Fatalf("Resolve = %+v, want a served result", result)
}
if result.Address == "" {
t.Fatal("Resolve returned an empty Address on a served result, want the address of the version it served (R7.1)")
}
if result.Address != address {
t.Errorf("Resolve(...).Address = %s, want the served version's own address %s", result.Address, address)
}
}
// RunAsOfReadRefusesAsGoneOrUnknownNeverSubstitutingAnotherVersion pins R8:
// a read that cannot be answered refuses as a typed Gone or Unknown outcome
// with a reason, and never silently returns a neighboring version, the
// nearest surviving version, or current state as a substitute — R8's own
// text names all three as non-answers.
func RunAsOfReadRefusesAsGoneOrUnknownNeverSubstitutingAnotherVersion(t *testing.T, ctx context.Context, fixture AsOfReadFixture) {
t.Helper()
if fixture.Resolve == nil {
t.Skip("this backend does not implement as-of reads (Resolve is nil)")
}
if fixture.MintAt == nil {
t.Skip("this backend has no way to mint a version at a controlled accept-time (MintAt is nil)")
}
if fixture.MakeUnanswerable == nil {
t.Skip("this backend has no way to make a lineage unanswerable (MakeUnanswerable is nil)")
}
for _, restriction := range []Restriction{
RestrictionGoneRetention,
RestrictionGoneErasure,
RestrictionGoneReorganization,
RestrictionUnknown,
} {
t.Run(restriction.String(), func(t *testing.T) {
store := asOfReadStore(fixture, "unanswerable-"+restriction.String())
id := fixture.IssuePrefix + "-asof-unanswerable-" + restriction.String()
at := time.Now().UTC()
address := asOfReadMint(t, ctx, fixture, store, id, at)
if err := fixture.MakeUnanswerable(ctx, store, id, restriction); err != nil {
t.Fatalf("MakeUnanswerable(%s, %s): %v", id, restriction, err)
}
result, err := fixture.Resolve(ctx, store, id, AsOfSelector{At: &at})
if err != nil {
t.Fatalf("Resolve after MakeUnanswerable(%s): %v", restriction, err)
}
if result.Refusal == nil {
t.Fatalf("Resolve after MakeUnanswerable(%s) = %+v, want a Refusal, not a served result (R8)", restriction, result)
}
if result.Refusal.Restriction != restriction {
t.Errorf("Refusal.Restriction = %s, want %s", result.Refusal.Restriction, restriction)
}
if result.Refusal.Reason == "" {
t.Error("Refusal.Reason is empty, want a reason (R8)")
}
if result.Address != "" {
t.Errorf("Resolve on a refusal returned Address = %s, want empty: R8 forbids silently substituting a neighboring version, the nearest surviving version, or current state (the pre-refusal address was %s)", result.Address, address)
}
})
}
}
// RunAsOfReadIsCompleteOnlyForTheAnsweringStoresHoldings pins R7.1's closing
// clause and TC3: an as-of answer "is complete for the answering store's
// holdings and may change after a sync." This case asserts NOTHING about
// agreement between two stores asked about the same lineage — proving that
// absence is the point, not a gap. It mints a lineage into exactly one of
// two stores and confirms each store answers strictly from its own
// holdings: the store that holds the lineage serves it, and the store that
// never received it answers Unknown (FR-06, reused from R20) rather than
// reaching across to a sibling store's knowledge, erroring, or answering
// Gone — which would claim knowledge of a lineage it never held.
func RunAsOfReadIsCompleteOnlyForTheAnsweringStoresHoldings(t *testing.T, ctx context.Context, fixture AsOfReadFixture) {
t.Helper()
if fixture.Resolve == nil {
t.Skip("this backend does not implement as-of reads (Resolve is nil)")
}
if fixture.MintAt == nil {
t.Skip("this backend has no way to mint a version at a controlled accept-time (MintAt is nil)")
}
holds := asOfReadStore(fixture, "tc3-holds-the-lineage")
neverSynced := asOfReadStore(fixture, "tc3-never-synced")
id := fixture.IssuePrefix + "-asof-tc3"
at := time.Now().UTC()
address := asOfReadMint(t, ctx, fixture, holds, id, at)
local, err := fixture.Resolve(ctx, holds, id, AsOfSelector{At: &at})
if err != nil {
t.Fatalf("Resolve on the store that holds the lineage: %v", err)
}
if local.Refusal != nil || local.Address != address {
t.Fatalf("Resolve on the store that holds the lineage = %+v, want it served from that store's own holdings (%s)", local, address)
}
remote, err := fixture.Resolve(ctx, neverSynced, id, AsOfSelector{At: &at})
if err != nil {
t.Fatalf("Resolve on a store that never received this lineage: %v", err)
}
if remote.Refusal == nil {
t.Fatalf("Resolve on a store that never received this lineage = %+v, want a Refusal: an as-of answer is complete for the answering store's own holdings, not a sibling's (TC3)", remote)
}
if remote.Refusal.Restriction != RestrictionUnknown {
t.Errorf("Refusal.Restriction on the never-synced store = %s, want RestrictionUnknown: no lineage knowledge is Unknown, not Gone (FR-06)", remote.Refusal.Restriction)
}
}
// --- fixture helpers -------------------------------------------------------
// asOfReadStore names a storeID namespaced by the fixture's IssuePrefix and
// tag, so cases that need more than one store (e.g. the TC3 local-
// completeness case) get independent ones.
func asOfReadStore(fixture AsOfReadFixture, tag string) string {
return fixture.IssuePrefix + "-asof-store-" + tag
}
// asOfReadMint mints a version for id on store at the given instant via
// fixture.MintAt, fataling the case if minting fails.
func asOfReadMint(t *testing.T, ctx context.Context, fixture AsOfReadFixture, store, id string, at time.Time) Address {
t.Helper()
address, err := fixture.MintAt(ctx, store, id, at)
if err != nil {
t.Fatalf("MintAt(%s, %s, %s): %v", store, id, at, err)
}
return address
}

View file

@ -375,6 +375,9 @@ go_library(
"version.go",
"version_proxied_server.go",
"version_tracking.go",
"versioned_history.go",
"versioned_history_switch.go",
"versions.go",
"where.go",
"wisp.go",
"wisp_proxied_server.go",
@ -463,6 +466,7 @@ go_library(
"//internal/utils",
"//internal/validation",
"//internal/versioncheck",
"//internal/versionedhistory",
"//internal/workapi",
"//internal/workspacegate",
"//internal/worktreeremove",
@ -1290,6 +1294,14 @@ go_test(
"version_embedded_test.go",
"version_test.go",
"version_tracking_test.go",
"versioned_history_construction_test.go",
"versioned_history_e2e_test.go",
"versioned_history_serve_e2e_test.go",
"versioned_history_switch_scan_embedded_test.go",
"versioned_history_switch_scan_proxied_integration_test.go",
"versioned_history_switch_test.go",
"versions_switch_embedded_test.go",
"versions_test.go",
"where_cgo_test.go",
"where_embedded_test.go",
"where_test.go",
@ -1319,6 +1331,7 @@ go_test(
":go_srcs",
":preflight_go_fixture",
"//:bd_test_files",
"//:go_srcs",
"//cmd/bd/doctor:go_srcs",
"//cmd/bd/doctor/fix:go_srcs",
"//internal/storage/embeddeddolt/cmd:go_srcs",

View file

@ -79,6 +79,9 @@ const (
trackSync = "proxied-parity S5 (bd sync)"
trackDegradation = "proxied-parity S6 (doctor, config show, degradations)"
trackLongTail = "proxied-parity S7 (long-tail policy pass)"
// Versioned history (gastownhall/beads#6132) is not a proxied-parity slice:
// its reads need a storage.VersionLister over the proxied uow provider.
trackVersionedHistory = "versioned history: VersionLister over the proxied uow provider (gastownhall/beads#6132)"
)
// capabilityRow is one command-path policy row. ArgSet is the sorted set of
@ -451,6 +454,16 @@ var proxyCapabilityRegistry = []capabilityRow{
// at the front door would leave those modes with no way to flush.
permitted("dolt commit").withHistory(HistoryProxySupported),
// --- versioned history ----------------------------------------------------
// `bd versions` is a pure read (issueops.ListVersionsInTx in one read
// transaction), so nothing about it is unsafe on a shared backend. It is
// refused only because no proxied route exists yet: it reaches the backend
// through the optional storage.VersionLister, which the dolt and embedded
// stores implement and the uow provider does not. Permitting it would open
// the proxied provider in the root pre-run and then fail untyped at
// errVersionsUnsupported, so it is refused here, before any side effect.
refusedPath("versions", "proxy.versions.unsupported", ProxyReasonUnimplemented, trackVersionedHistory),
// --- untyped refusals inside RunE ---------------------------------------
// The gate permits these paths and the command refuses itself with a bare
// string, so a JSON consumer gets no code and no mutates flag. They are

View file

@ -280,6 +280,12 @@ var configSetCmd = &cobra.Command{
if err != nil {
return HandleError("%v", err)
}
// Per-key validation that needs the store rather than the key alone: turning
// versioned history on refuses, writing nothing, while any issue holds a value a
// version could not record. The store is open here, on whichever route this is.
if err := checkVersionedHistoryCanBeEnabled(rootCtx, key, value); err != nil {
return HandleError("%v", err)
}
result, err := settings.SetSetting(rootCtx, issueops.SetSettingRequest{Key: key, Value: value})
if err != nil {
return HandleError("setting config: %v", err)
@ -1222,6 +1228,14 @@ Examples:
return HandleError("%v", err)
}
}
// The pre-enable check `bd config set` makes: turning versioned history
// on refuses while any issue holds a value a version could not record.
// This verb writes the same setting through a loop of its own, so it
// makes the check itself, here and before any pair is written: a refusal
// stores nothing from the batch.
if err := checkVersionedHistoryCanBeEnabled(rootCtx, p.key, p.value); err != nil {
return HandleError("%v", err)
}
}
var yamlPairs, gitPairs, dbPairs []kvPair
@ -1352,7 +1366,7 @@ var recognizedConfigPrefixes = []string{
"status.", "types.", "doctor.suppress.", "routing.", "sync.", "git.",
"directory.", "repos.", "external_projects.", "validation.",
"lint.", "hierarchy.", "ai.", "backup.", "federation.", "metrics.",
"agent.", "claim.", "storage-class.",
"agent.", "claim.", "storage-class.", "versioned-history.",
}
// validateStorageClassConfig validates a storage-class.<type> per-type

View file

@ -4,6 +4,8 @@ import (
"fmt"
"os"
"strings"
"github.com/steveyegge/beads/internal/versionedhistory"
)
// configSideEffect describes a hint or warning to show after a config change.
@ -65,6 +67,11 @@ func checkConfigSetSideEffects(key, value string) []configSideEffect {
Message: fmt.Sprintf("Git sync remote set to %q. Ensure this git remote exists.", value),
Command: fmt.Sprintf("git remote -v | grep %s", value),
})
case key == versionedHistorySettingKey && versionedhistory.ValueEnables(value):
effects = append(effects, configSideEffect{
Message: "Versioned history now records for this store. The setting replicates on 'bd dolt push' and 'bd dolt pull', so every clone that pulls it records too, and it is safe with a single writer only: keep one writer at a time per store (docs/reference/configuration.md#versioned-issue-history).",
})
}
return effects

View file

@ -2,6 +2,7 @@ package main
import (
"os"
"strings"
"testing"
)
@ -105,6 +106,34 @@ func TestCheckConfigSetSideEffects_UnknownKey(t *testing.T) {
}
}
// versioned-history.enabled is a row of the store's config table, which
// replicates on `bd dolt push` and `bd dolt pull`, and the feature is single
// writer only. `bd config set ... true` is the moment someone turns it on, so it
// is where that caveat belongs -- said once, at the command that has the effect.
func TestVersionedHistoryConfigSetHintsAboutReplicationAndSingleWriter(t *testing.T) {
for _, on := range []string{"true", "TRUE", " true ", "1", "t"} {
effects := checkConfigSetSideEffects(versionedHistorySettingKey, on)
if len(effects) != 1 {
t.Errorf("value %q turns recording on: expected 1 hint, got %d", on, len(effects))
continue
}
for _, want := range []string{"replicates", "single writer"} {
if !strings.Contains(strings.ToLower(effects[0].Message), want) {
t.Errorf("value %q: the hint does not mention %q: %s", on, want, effects[0].Message)
}
}
}
// Turning it off, or anything that does not turn it on, needs no caveat.
for _, off := range []string{"false", "0", "", "off", "nonsense"} {
if effects := checkConfigSetSideEffects(versionedHistorySettingKey, off); len(effects) != 0 {
t.Errorf("value %q does not turn recording on: expected no hint, got %d", off, len(effects))
}
}
if effects := checkConfigUnsetSideEffects(versionedHistorySettingKey); len(effects) != 0 {
t.Errorf("unsetting the key needs no hint, got %d", len(effects))
}
}
func TestCheckConfigUnsetSideEffects_FederationRemote(t *testing.T) {
effects := checkConfigUnsetSideEffects("federation.remote")
if len(effects) != 1 {

View file

@ -43,6 +43,7 @@ go_library(
"//internal/storage/issueops",
"//internal/types",
"//internal/utils",
"//internal/versionedhistory",
"@com_github_burntsushi_toml//:toml",
"@com_github_go_sql_driver_mysql//:mysql",
"@in_gopkg_yaml_v3//:yaml_v3",
@ -81,7 +82,11 @@ go_test(
"testmain_cgo_test.go",
"testmain_nocgo_test.go",
"validation_test.go",
"versioned_history_activation_test.go",
],
# versioned_history_activation_test.go parses store.go from its working
# directory, and a Bazel test only sees its declared runfiles.
data = ["store.go"],
embed = [":fix"],
deps = [
"//internal/configfile",

View file

@ -5,10 +5,11 @@ import (
"github.com/steveyegge/beads/internal/eventsjournal"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/versionedhistory"
)
// openBeadMutatingStore opens a repair handler's store WITH the workspace's
// events-journal activation applied.
// events-journal and versioned-history activation applied.
//
// Most of bd doctor inspects and repairs workspace state — schema cursors,
// metadata, remotes, fingerprints, git — and none of that belongs in a journal
@ -17,7 +18,10 @@ import (
// fresh-clone import paths CREATE them. Those are ordinary bead mutations, and
// a consumer whose mirror silently diverges because someone ran
// `bd doctor --fix` is exactly the failure the journal exists to prevent — the
// more so because a repair is unattended and nobody is watching the diff.
// more so because a repair is unattended and nobody is watching the diff. The
// same repairs are also ordinary issue mutations for version history, and an
// issue_versions trail with a silent gap where `bd doctor --fix` ran is the same
// failure one table over.
//
// The read-only and workspace-state handlers deliberately keep opening the
// store directly; they carry their exemption in the construction guard, with a
@ -27,7 +31,7 @@ import (
// is what a repair path legitimately does.
func openBeadMutatingStore(ctx context.Context, beadsDir string) (*dolt.DoltStore, error) {
store, err := dolt.NewFromConfig(ctx, beadsDir)
return activated(beadsDir, store, err)
return activated(ctx, beadsDir, store, err)
}
// openBeadMutatingStoreCreating is openBeadMutatingStore for the fresh-clone
@ -36,15 +40,23 @@ func openBeadMutatingStore(ctx context.Context, beadsDir string) (*dolt.DoltStor
// guard rather than failing on an absent database.
func openBeadMutatingStoreCreating(ctx context.Context, beadsDir string) (*dolt.DoltStore, error) {
store, err := dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{CreateIfMissing: true})
return activated(beadsDir, store, err)
return activated(ctx, beadsDir, store, err)
}
// activated applies the workspace's journal setting and closes the store if it
// cannot be honored. A failed open passes straight through, so the typed-nil
// store never reaches the activation.
func activated(beadsDir string, store *dolt.DoltStore, err error) (*dolt.DoltStore, error) {
// activated applies the workspace's journal setting and the store's own
// versioned-history setting, and closes the store if the journal cannot be
// honored. A failed open passes straight through, so the typed-nil store never
// reaches the activation.
//
// Versioned history cannot fail an open (a plumbing that cannot version simply
// records nothing), so it needs no error handling of its own; it runs after the
// journal so a store the journal refused is never activated. It is the shared
// internal/versionedhistory rule, not a copy: package main cannot be imported
// from here.
func activated(ctx context.Context, beadsDir string, store *dolt.DoltStore, err error) (*dolt.DoltStore, error) {
if _, err = eventsjournal.ActivateStore(beadsDir, store, err); err != nil {
return nil, err
}
_, _ = versionedhistory.ActivateStore(ctx, store, nil)
return store, nil
}

View file

@ -0,0 +1,87 @@
package fix
import (
"go/ast"
"go/parser"
"go/token"
"strconv"
"strings"
"testing"
)
const (
versionedHistoryPkg = "github.com/steveyegge/beads/internal/versionedhistory"
// package main cannot be imported at all; the guard below is that the
// activation this package applies lives in a package it CAN import, so the
// repair handlers apply the identical rule as the command surface rather than
// a copy of it.
beadMutatingStoreFile = "store.go"
)
// TestVersionedHistoryDoctorRepairOpenerUsesTheSharedActivation holds the one
// construction site the cmd/bd construction guard cannot see. bd doctor is exempted
// from that guard as a package (its CHECKS are read-only), so the repair opener --
// which opens the store the bead-mutating repairs (stale-closed cleanup, pollution
// cleanup, the fresh-clone imports) write through -- is held to the property here.
//
// A repair that deletes or creates issues is an ordinary mutation for version
// history: an issue_versions trail with a silent gap where `bd doctor --fix` ran is
// the same failure the routed-write bug produced, one command over, and the more
// dangerous for being unattended.
//
// The check is structural for the same reason the cmd/bd guard is: activation
// failing is invisible from inside the process. It requires the activation that
// `activated` applies to come from internal/versionedhistory -- the ONE
// implementation of the rule, which this package can import and package main cannot
// be.
func TestVersionedHistoryDoctorRepairOpenerUsesTheSharedActivation(t *testing.T) {
fset := token.NewFileSet()
file, err := parser.ParseFile(fset, beadMutatingStoreFile, nil, 0)
if err != nil {
t.Fatalf("parse %s: %v", beadMutatingStoreFile, err)
}
imports := map[string]string{}
for _, spec := range file.Imports {
path, err := strconv.Unquote(spec.Path.Value)
if err != nil {
t.Fatalf("unquote import %s: %v", spec.Path.Value, err)
}
name := path[strings.LastIndex(path, "/")+1:]
if spec.Name != nil {
name = spec.Name.Name
}
imports[name] = path
}
var activated *ast.FuncDecl
for _, decl := range file.Decls {
if fn, ok := decl.(*ast.FuncDecl); ok && fn.Name.Name == "activated" {
activated = fn
}
}
if activated == nil {
t.Fatalf("%s has no `activated` function: the repair opener's activation moved and this guard no longer looks at it", beadMutatingStoreFile)
}
called := false
ast.Inspect(activated, func(n ast.Node) bool {
call, ok := n.(*ast.CallExpr)
if !ok {
return true
}
sel, ok := call.Fun.(*ast.SelectorExpr)
if !ok {
return true
}
if ident, ok := sel.X.(*ast.Ident); ok && imports[ident.Name] == versionedHistoryPkg && sel.Sel.Name == "ActivateStore" {
called = true
}
return true
})
if !called {
t.Errorf("`activated` in %s never calls versionedhistory.ActivateStore: every repair that mutates issues through it "+
"mints NO issue_versions row while `bd doctor --fix` reports success. Apply the shared activation there; "+
"it is the same rule as the command surface and package main cannot be imported to reuse it.", beadMutatingStoreFile)
}
}

View file

@ -89,15 +89,21 @@ var qualifiedActivationCalls = map[string]map[string]bool{
// scannedPackages are the directories searched for construction sites: every
// package that builds a store or provider for the bd binary, plus the standalone
// embedded-Dolt utility so it is accounted for rather than merely unnoticed.
// Each maps to the prefix its sites are keyed under.
// embedded-Dolt utility and the Go SDK's own opens (the repository root), so they
// are accounted for rather than merely unnoticed. Each maps to the prefix its
// sites are keyed under.
var scannedPackages = map[string]string{
".": "",
"doctor": "doctor/",
"doctor/fix": "doctor/fix/",
"../../internal/storage/embeddeddolt/cmd": "embeddeddolt-cmd/",
"../..": "sdk/",
}
// sdkOpenExemptionReason is the one reason the Go SDK's five opens share. It has
// to be true of both per-store switches, because the exemption list is shared.
const sdkOpenExemptionReason = "SDK entry point (library surface, not the bd binary): applies neither per-store switch, the events journal's or versioned history's; the bd binary's factories do"
// constructionExemptions are construction sites that legitimately do NOT
// activate the events journal, each with a reason. Keyed by
// "<pkg>/<file>:<Recv.Func>" so the two build-tag twins of a factory are
@ -172,6 +178,17 @@ var constructionExemptions = map[string]string{
// A standalone developer utility binary, not bd. It has no workspace config
// to read and never runs as part of a bd command.
"embeddeddolt-cmd/main.go:main": "standalone embeddeddolt debug utility, not the bd binary; no workspace config and no bd command context",
// The Go SDK's own opens (the repository root's beads package). They are a
// library surface that embedders call directly, and they build stores without
// applying either per-store switch. They are declared here so that a new SDK
// open is noticed rather than missed. Making them apply the switches would
// change the library's behavior for every embedder, so it is a separate change.
"sdk/beads.go:Open": sdkOpenExemptionReason,
"sdk/beads.go:OpenFromConfig": sdkOpenExemptionReason,
"sdk/beads.go:OpenGated": sdkOpenExemptionReason,
"sdk/beads_cgo.go:OpenBestAvailableWith": sdkOpenExemptionReason,
"sdk/beads_nocgo.go:OpenBestAvailableWith": sdkOpenExemptionReason,
}
func TestEveryStoreConstructionActivatesTheEventsJournal(t *testing.T) {
@ -235,6 +252,9 @@ func exemptionFor(key string) (exemption, reason string, ok bool) {
type constructionSite struct {
constructors []string
activates bool
// activatesVersionedHistory is the same question for the versioned-history
// guard, which reuses this scan (see versioned_history_construction_test.go).
activatesVersionedHistory bool
}
// scanStoreConstructionSites parses each scanned package and returns one entry
@ -364,10 +384,16 @@ func inspectConstructionSite(node ast.Node, imports map[string]string) *construc
if qualifiedActivationCalls[path][fun.Sel.Name] {
site.activates = true
}
if qualifiedVersionedHistoryActivationCalls[path][fun.Sel.Name] {
site.activatesVersionedHistory = true
}
case *ast.Ident:
if activationCalls[fun.Name] {
site.activates = true
}
if versionedHistoryActivationCalls[fun.Name] {
site.activatesVersionedHistory = true
}
}
return true
})

View file

@ -25,8 +25,10 @@ import (
// workspace and then deletes them from the project. Those are ordinary bead
// mutations in another workspace, so they belong in that workspace's events
// journal if it has one enabled — and the setting is read from there, not from
// the workspace bd was launched in.
// the workspace bd was launched in. The same goes for its issue-version history,
// which the store's own settings row decides.
func openMigrationPlanningStore(ctx context.Context, planningBeadsDir string) (s storage.DoltStorage, err error) {
defer func() { s, err = activateVersionedHistoryStore(ctx, s, err) }()
defer func() { s, err = activateEventsJournalStore(planningBeadsDir, s, err) }()
return dolt.New(ctx, &dolt.Config{
Path: doltserver.ResolveDoltDir(planningBeadsDir),

View file

@ -23,6 +23,13 @@ import (
// storage spans measure pure DB time without hook-firing overhead. The policy
// sits directly beneath hooks so serve's one hook-layer peel retains it.
//
// Versioned-history activation is NOT applied here. It used to be, and this runs
// on the one store a command opens for its own workspace, so every store a
// routed write opens for another workspace missed it. It now happens in the
// factories that construct a store, on the raw store before anything can wrap it
// (see versioned_history.go) -- which is also why the decorators above, none of
// which forwards SetVersionedHistoryEnabled, cannot get in its way.
//
// Extracted from main.go's PersistentPreRunE so the chain composition is
// unit-testable — the bug this PR fixes was a missing WrapStorage call,
// and the regression class deserves test coverage.

View file

@ -56,6 +56,7 @@ func usesProxiedServer() bool {
// registered backend decides for itself what read-only means, and refusing to
// offer it the setting would be this factory guessing on its behalf.
func newRegisteredBackendStore(ctx context.Context, name, beadsDir string, readOnly bool) (s storage.DoltStorage, err error) {
defer func() { s, err = activateVersionedHistoryStore(ctx, s, err) }()
defer func() { s, err = activateEventsJournalStore(beadsDir, s, err) }()
backend, ok := backends.Lookup(name)
if !ok {
@ -68,6 +69,7 @@ func newRegisteredBackendStore(ctx context.Context, name, beadsDir string, readO
}
func newDoltStore(ctx context.Context, cfg *dolt.Config) (s storage.DoltStorage, err error) {
defer func() { s, err = activateVersionedHistoryStore(ctx, s, err) }()
defer func() { s, err = activateEventsJournalStore(cfg.BeadsDir, s, err) }()
if cfg.ProxiedServer {
return nil, errProxiedStoreUnrouted()
@ -176,6 +178,7 @@ func newExistingDoltStoreFromConfig(ctx context.Context, beadsDir string) (stora
// openDoltStoreFromConfig is the body of newDoltStoreFromConfig and
// newExistingDoltStoreFromConfig; requireExisting selects the latter.
func openDoltStoreFromConfig(ctx context.Context, beadsDir string, requireExisting bool) (s storage.DoltStorage, err error) {
defer func() { s, err = activateVersionedHistoryStore(ctx, s, err) }()
defer func() { s, err = activateEventsJournalStore(beadsDir, s, err) }()
cfg, err := configfile.Load(beadsDir)
if err != nil {

View file

@ -34,6 +34,7 @@ func usesProxiedServer() bool {
// exists here too so the root pre-run's registry arm has one activating
// construction path in both builds.
func newRegisteredBackendStore(ctx context.Context, name, beadsDir string, readOnly bool) (s storage.DoltStorage, err error) {
defer func() { s, err = activateVersionedHistoryStore(ctx, s, err) }()
defer func() { s, err = activateEventsJournalStore(beadsDir, s, err) }()
backend, ok := backends.Lookup(name)
if !ok {
@ -48,6 +49,7 @@ func newRegisteredBackendStore(ctx context.Context, name, beadsDir string, readO
// newDoltStore applies events-journal activation for the same reason its CGO
// twin does — see the note at the top of events_journal.go.
func newDoltStore(ctx context.Context, cfg *dolt.Config) (s storage.DoltStorage, err error) {
defer func() { s, err = activateVersionedHistoryStore(ctx, s, err) }()
defer func() { s, err = activateEventsJournalStore(cfg.BeadsDir, s, err) }()
if cfg.ProxiedServer {
return nil, errProxiedStoreUnrouted()
@ -65,6 +67,7 @@ func acquireEmbeddedLock(_ string, _ bool) (util.Unlocker, error) {
// newDoltStoreFromConfig creates a SQL-server-backed storage backend from config.
func newDoltStoreFromConfig(ctx context.Context, beadsDir string) (s storage.DoltStorage, err error) {
defer func() { s, err = activateVersionedHistoryStore(ctx, s, err) }()
defer func() { s, err = activateEventsJournalStore(beadsDir, s, err) }()
cfg, err := configfile.Load(beadsDir)
if err != nil {

View file

@ -463,6 +463,7 @@ func resolveServerModeUOWTopologyWithTransportResolver(ctx context.Context, bead
// the paths it resolves (root, log) are the same ones proxied mode uses because
// both modes root their server at the same directory.
func newExternalProxiedServerUOWProvider(ctx context.Context, beadsDir string, topology sqlServerUOWTopology, opts ...uow.ProviderOption) (p uow.UnitOfWorkProvider, err error) {
defer func() { p, err = activateVersionedHistoryProvider(ctx, p, err) }()
defer func() { p, err = activateEventsJournalProvider(ctx, beadsDir, p, err) }()
rootPath, err := resolveProxiedServerRootPath(beadsDir)
if err != nil {
@ -503,6 +504,7 @@ func newExternalProxiedServerUOWProvider(ctx context.Context, beadsDir string, t
}
func newManagedProxiedServerUOWProvider(ctx context.Context, beadsDir string, topology sqlServerUOWTopology, opts ...uow.ProviderOption) (p uow.UnitOfWorkProvider, err error) {
defer func() { p, err = activateVersionedHistoryProvider(ctx, p, err) }()
defer func() { p, err = activateEventsJournalProvider(ctx, beadsDir, p, err) }()
// Resolve and hardened-probe the external dolt binary before spawning
// it: an env/sidecar override that is explicitly named but broken

View file

@ -29,6 +29,12 @@ var versionCmd = &cobra.Command{
Short: "Print version information",
SilenceUsage: true,
SilenceErrors: true,
// Accept args only so the "did you mean bd versions" guard below can see
// them. `bd version` names bd's own build; `bd versions <id>` lists a
// bead's recorded versions. One character apart, unrelated meanings --
// without this a mistyped `bd version bd-123` silently prints the build
// and looks like the bead simply has no versions.
Args: cobra.ArbitraryArgs,
RunE: func(cmd *cobra.Command, args []string) error {
evt := metrics.NewCommandEvent("version")
defer func() {
@ -37,6 +43,12 @@ var versionCmd = &cobra.Command{
}
}()
if len(args) > 0 {
return HandleErrorRespectJSON(
"bd version prints bd's own version information and takes no arguments.\n"+
"Did you mean: bd versions %s", args[0])
}
commit := resolveCommitHash()
branch := resolveBranch()

View file

@ -0,0 +1,63 @@
package main
import (
"context"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/uow"
"github.com/steveyegge/beads/internal/versionedhistory"
)
// Versioned-history activation, applied in the SAME place events-journal
// activation is (see the note at the top of events_journal.go): the factories
// that construct a store or a unit-of-work provider -- store_factory.go,
// store_factory_nocgo.go, uow_factory.go, the personal-migration planning store,
// and bd doctor's repair handlers through the same shared package. Every
// plumbing bd opens goes through one of those, so a routed write cannot acquire a
// store that silently records no history.
//
// It did not start there. It was first applied in wireStorageDecorators, which
// the root pre-run calls on the ONE store a command opens for its own workspace.
// A routed update or close (routed.go), a routed create (`bd create --repo`) and
// the direct-mode open each build their OWN write-capable store through
// newDoltStoreFromConfig, so with the switch on they recorded nothing while the
// command reported success -- the "configured on, actually off" class this
// feature exists to prevent. TestEveryStoreConstructionActivatesVersionedHistory
// keeps it in the factories.
//
// Each store answers for itself. The switch is a row of THAT store's own config
// table (what `bd config set versioned-history.enabled true` writes), OR'd with
// the process-wide environment, which can only turn recording on -- so a write
// routed into rig B reads rig B's row, never the launching workspace's. Nothing
// here takes a beadsDir for that reason: the store already knows where it lives.
//
// The two defers in a factory are ordered on purpose. Deferred calls run
// last-in-first-out, and this one is registered ABOVE the events-journal
// activation, so the journal runs first. A journal activation that fails closes
// the store and returns (nil, err); this one then passes that through instead of
// reading a row out of a closed store.
//
// The policy itself lives in internal/versionedhistory so bd doctor's fix
// package, which cannot import package main, applies the identical rule.
// activateVersionedHistoryStore is versionedhistory.ActivateStore under the name
// the construction guard matches. Kept as a wrapper rather than called directly so
// cmd/bd has one spelling of the idiom and the guard has one name to look for,
// exactly as activateEventsJournalStore does for its feature.
func activateVersionedHistoryStore(ctx context.Context, s storage.DoltStorage, err error) (storage.DoltStorage, error) {
return versionedhistory.ActivateStore(ctx, s, err)
}
// activateVersionedHistoryProvider is the same for a unit-of-work provider -- bd's
// second write plumbing, with its own transactions and its own activation switch,
// which proxied-server mode and `bd serve` against a server-mode workspace write
// through instead of a DoltStorage.
//
// A provider has no DoltStorage to ask for a settings plane, so its row is read
// through a unit of work at construction (versionedhistory.ProviderSetting): one
// pooled connection, one SELECT, rolled back. The provider constructors have
// already opened the pool and run their schema setup by then, so the read starts
// no server and creates nothing.
func activateVersionedHistoryProvider(ctx context.Context, p uow.UnitOfWorkProvider, err error) (uow.UnitOfWorkProvider, error) {
return versionedhistory.ActivateProvider(ctx, p, err)
}

View file

@ -0,0 +1,322 @@
package main
import (
"fmt"
"go/ast"
"go/parser"
"go/token"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage/journalscan"
)
// The twin of TestEveryStoreConstructionActivatesTheEventsJournal, for the other
// per-store switch bd resolves when it opens a store: dual-write issue-version
// history.
//
// It exists for the same reason and has the same failure shape. Activation that
// is applied by whichever command happens to use a store, rather than by the
// factory that builds it, reaches only the stores those commands open. The first
// cut of this feature was wired in wireStorageDecorators, which the root pre-run
// calls on the ONE store a command opens for its own workspace. A routed update
// and close (routed.go), a routed create (`bd create --repo`) and the direct-mode
// open each build their OWN write-capable store through newDoltStoreFromConfig,
// ran with history off, and reported success -- leaving issue_versions with
// silent gaps in a workspace that had asked for it. Nothing in the process can
// tell: a missing version row looks exactly like a quiet one.
//
// The scan, the constructor set, the scanned packages and the exemption list are
// the events-journal guard's, shared rather than copied. A store that refuses
// writes, a store used only for a config read and a store that writes only
// workspace state are exempt from both for the same reason: there is no bead
// mutation for a journal row OR a version row to accompany, and one list means
// an exemption cannot be true of one feature and quietly forgotten for the other.
//
// Limits, stated rather than papered over. The check is syntactic and local, like
// its twin: a function that calls a store or provider constructor must call an
// activation helper in its OWN body. bd doctor is exempted as a package by the
// shared list, so the repair opener in doctor/fix/store.go is held to the
// property by its own test in that package
// (TestVersionedHistoryDoctorRepairOpenerUsesTheSharedActivation).
// versionedHistoryActivationCalls are the cmd/bd helpers that apply a store's own
// configured switch to the thing just constructed.
var versionedHistoryActivationCalls = map[string]bool{
"activateVersionedHistoryStore": true,
"activateVersionedHistoryProvider": true,
}
// qualifiedVersionedHistoryActivationCalls are the same, keyed by import path and
// function, for callers that cannot import package main.
//
// Apply is deliberately NOT here, unlike its events-journal twin. Apply binds a
// value somebody else resolved; it is ActivateStore/ActivateProvider that resolve
// the switch, so a caller that only Applies has decided the answer by hand.
var qualifiedVersionedHistoryActivationCalls = map[string]map[string]bool{
"github.com/steveyegge/beads/internal/versionedhistory": {
"ActivateStore": true,
"ActivateProvider": true,
},
}
// versionedHistoryConstructionViolations returns one message per non-exempt
// construction site that never calls a versioned-history activation helper. It
// is the guard's whole verdict, factored out so the mutation probe below asks the
// SAME question of a factory whose activation has been deleted.
func versionedHistoryConstructionViolations(sites map[string]*constructionSite) []string {
var out []string
for _, key := range sortedKeys(sites) {
site := sites[key]
if _, reason, ok := exemptionFor(key); ok {
if strings.TrimSpace(reason) == "" {
out = append(out, fmt.Sprintf("%s has an empty exemption reason", key))
}
continue
}
if !site.activatesVersionedHistory {
out = append(out, fmt.Sprintf("%s constructs a store or unit-of-work provider (%s) but never calls %v on it -- "+
"every mutation through it mints NO issue_versions row while the command reports success. "+
"Apply activation in this function (see newDoltStore for the idiom), or add it to "+
"constructionExemptions with a reason that is true of issue versions as well as the events journal.",
key, strings.Join(site.constructors, ", "), sortedKeys(versionedHistoryActivationCalls)))
}
}
return out
}
func TestEveryStoreConstructionActivatesVersionedHistory(t *testing.T) {
sites := scanStoreConstructionSites(t)
if len(sites) == 0 {
t.Fatal("found no store construction sites -- the constructor set or the scan changed and this guard is not actually running")
}
checked := 0
for key := range sites {
if _, _, exempt := exemptionFor(key); !exempt {
checked++
}
}
if checked == 0 {
t.Fatal("every construction site is exempt -- the guard is not actually checking anything")
}
for _, v := range versionedHistoryConstructionViolations(sites) {
t.Error(v)
}
}
// TestVersionedHistoryGuardSeesTheFactoriesEveryWriteUses pins that the scan
// really reaches the sites this feature was wrong about, in BOTH build-tag
// twins. A guard that quietly stops seeing a factory reports success while
// checking nothing, which is the worst way for one to fail.
//
// routed.go, create.go and direct_mode.go do not construct a store themselves;
// they call newDoltStoreFromConfig, so it is that factory the guard has to hold.
func TestVersionedHistoryGuardSeesTheFactoriesEveryWriteUses(t *testing.T) {
sites := scanStoreConstructionSites(t)
for _, key := range versionedHistoryFactoryKeys {
site, ok := sites[key]
if !ok {
t.Errorf("the construction scan no longer sees %s", key)
continue
}
if _, _, exempt := exemptionFor(key); exempt {
t.Errorf("%s is exempt from the guard, but it opens a write-capable plumbing", key)
continue
}
if !site.activatesVersionedHistory {
t.Errorf("%s does not activate versioned history", key)
}
}
}
// versionedHistoryFactoryKeys are the construction sites every routed, direct and
// served write goes through. Each is named so that a factory disappearing from
// the scan fails a test instead of shrinking the guard.
var versionedHistoryFactoryKeys = []string{
"store_factory.go:newDoltStore",
// Both routed-open wrappers (newDoltStoreFromConfig and
// newExistingDoltStoreFromConfig) delegate to this activating body.
"store_factory.go:openDoltStoreFromConfig",
"store_factory.go:newRegisteredBackendStore",
"store_factory_nocgo.go:newDoltStore",
"store_factory_nocgo.go:newDoltStoreFromConfig",
"store_factory_nocgo.go:newRegisteredBackendStore",
"migrate_personal.go:openMigrationPlanningStore",
"uow_factory.go:newExternalProxiedServerUOWProvider",
"uow_factory.go:newManagedProxiedServerUOWProvider",
}
// TestVersionedHistoryConstructionGuardFailsWhenAFactoryLosesItsActivation is the
// mutation probe. For each guarded factory it takes the factory's real source,
// deletes the versioned-history activation from THAT function alone, re-runs the
// scanner's own inspection on the result, and asks the guard's own verdict
// function whether it now objects.
//
// It answers a different question from the guard above. The guard says "every
// factory activates today". This says "the guard would notice if one stopped":
// a detector that matched too loosely (any function that merely mentions the
// helper's name, a substring in a comment, the wrong build-tag twin) would pass
// the guard forever and catch nothing. The probe also checks that the deletion
// removed the versioned-history activation ONLY, leaving the events-journal
// activation standing, so a probe that over-deleted cannot pass for the right
// reason.
func TestVersionedHistoryConstructionGuardFailsWhenAFactoryLosesItsActivation(t *testing.T) {
sites := scanStoreConstructionSites(t)
probed := 0
for _, key := range versionedHistoryFactoryKeys {
site, ok := sites[key]
if !ok {
t.Errorf("the construction scan no longer sees %s", key)
continue
}
fn, imports := parseConstructionSiteFunc(t, key)
before := inspectConstructionSite(fn, imports)
if before == nil || !before.activatesVersionedHistory {
t.Errorf("%s has no versioned-history activation to delete, so this probe cannot show that removing it is noticed", key)
continue
}
dropped := dropVersionedHistoryActivation(fn, imports)
if dropped == 0 {
t.Errorf("%s: the scanner sees an activation but the probe found no statement to delete -- the probe and the scanner disagree about what activation looks like", key)
continue
}
after := inspectConstructionSite(fn, imports)
if after == nil {
t.Errorf("%s: deleting the activation also deleted the construction itself, so the probe proved nothing; the factory must keep the open and its activation as separate statements", key)
continue
}
if after.activates != site.activates {
t.Errorf("%s: the probe changed the events-journal activation (%v -> %v); it must remove the versioned-history activation only", key, site.activates, after.activates)
}
if after.activatesVersionedHistory {
t.Errorf("%s: still reads as activating versioned history after its activation was deleted -- the detector is too loose", key)
continue
}
violations := versionedHistoryConstructionViolations(map[string]*constructionSite{key: after})
if len(violations) == 0 {
t.Errorf("%s: the guard raised no violation for a factory whose versioned-history activation was deleted", key)
continue
}
if !strings.Contains(violations[0], key) {
t.Errorf("%s: the violation does not name the factory: %q", key, violations[0])
}
probed++
}
if probed != len(versionedHistoryFactoryKeys) {
t.Errorf("probed %d of %d guarded factories", probed, len(versionedHistoryFactoryKeys))
}
}
// parseConstructionSiteFunc re-parses the source file a construction-site key
// names and returns the function declaration together with that file's import
// table. It parses afresh on every call because the probe mutates the tree.
func parseConstructionSiteFunc(t *testing.T, key string) (*ast.FuncDecl, map[string]string) {
t.Helper()
dir, file, name := "", "", ""
for candidatePrefix, candidateDir := range prefixToScannedDir() {
if strings.HasPrefix(key, candidatePrefix) && len(candidatePrefix) >= len(dir) {
rest := strings.TrimPrefix(key, candidatePrefix)
if before, after, ok := strings.Cut(rest, ":"); ok && !strings.Contains(before, "/") {
dir, file, name = candidateDir, before, after
}
}
}
if file == "" {
t.Fatalf("cannot locate the source of construction site %q", key)
}
fset := token.NewFileSet()
parsed, err := parser.ParseFile(fset, filepath.Join(dir, file), nil, 0)
if err != nil {
t.Fatalf("parse %s/%s: %v", dir, file, err)
}
imports := fileImports(t, parsed)
for _, decl := range parsed.Decls {
fn, ok := decl.(*ast.FuncDecl)
if !ok {
continue
}
got := fn.Name.Name
if fn.Recv != nil && len(fn.Recv.List) > 0 {
if recv := journalscan.ReceiverTypeName(fn.Recv.List[0].Type); recv != "" {
got = recv + "." + got
}
}
if got == name {
return fn, imports
}
}
t.Fatalf("construction site %q: no function %q in %s/%s", key, name, dir, file)
return nil, nil
}
// prefixToScannedDir inverts scannedPackages: the key prefix each package's sites
// carry, mapped back to the directory the scanner read them from.
func prefixToScannedDir() map[string]string {
out := make(map[string]string, len(scannedPackages))
for dir, prefix := range scannedPackages {
out[prefix] = dir
}
return out
}
// dropVersionedHistoryActivation deletes, in place and at any depth, every simple
// statement in fn that calls a versioned-history activation helper, and returns
// how many it removed. Compound statements are recursed into rather than removed,
// so the surrounding control flow (and any events-journal activation beside it)
// survives.
func dropVersionedHistoryActivation(fn *ast.FuncDecl, imports map[string]string) int {
dropped := 0
filter := func(list []ast.Stmt) []ast.Stmt {
out := make([]ast.Stmt, 0, len(list))
for _, st := range list {
switch st.(type) {
case *ast.DeferStmt, *ast.ExprStmt, *ast.AssignStmt, *ast.GoStmt:
if callsVersionedHistoryActivation(st, imports) {
dropped++
continue
}
}
out = append(out, st)
}
return out
}
ast.Inspect(fn, func(n ast.Node) bool {
switch b := n.(type) {
case *ast.BlockStmt:
b.List = filter(b.List)
case *ast.CaseClause:
b.Body = filter(b.Body)
case *ast.CommClause:
b.Body = filter(b.Body)
}
return true
})
return dropped
}
func callsVersionedHistoryActivation(node ast.Node, imports map[string]string) bool {
found := false
ast.Inspect(node, func(n ast.Node) bool {
call, ok := n.(*ast.CallExpr)
if !ok {
return true
}
switch fun := call.Fun.(type) {
case *ast.Ident:
if versionedHistoryActivationCalls[fun.Name] {
found = true
}
case *ast.SelectorExpr:
if ident, ok := fun.X.(*ast.Ident); ok {
if path, imported := imports[ident.Name]; imported && qualifiedVersionedHistoryActivationCalls[path][fun.Sel.Name] {
found = true
}
}
}
return !found
})
return found
}

View file

@ -0,0 +1,383 @@
//go:build cgo
package main
import (
"bytes"
"database/sql"
"errors"
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage/embeddeddolt"
)
// The end-to-end claim of versioned-history activation, against real embedded
// stores and the table it exists to fill: issue_versions.
//
// It is end-to-end on purpose, for the reason the events-journal E2Es are.
// Activation failing is INVISIBLE from inside the process -- the command
// succeeds, the write lands, every exit code is 0 -- and only a later count of
// version rows shows that nothing was recorded. This feature was wrong that way
// once already: the switch was read and applied where the root pre-run wraps the
// command's own store, which is the one store a routed update, a routed close and
// `bd create --repo` do NOT use. Each of those builds its own write-capable store
// for the target workspace, ran with history off, and reported success. A green
// unit suite was consistent with the feature doing nothing.
//
// The switch is a property of the STORE. `bd config set versioned-history.enabled
// true` writes a row of the workspace's own config table, and a store answers
// for itself: a write routed into rig B reads rig B's row, never the launching
// workspace's. The environment (and a hand-edited yaml value) is process-wide and
// can only turn recording ON; nothing but the row can turn a store off.
//
// Runs in the embedded-Dolt lane only (BEADS_TEST_EMBEDDED_DOLT=1), like every
// other test that builds and drives a real bd binary. The by-construction
// coverage that runs everywhere is the construction guard and the resolver's own
// tests.
// vhEnvVar is viper's spelling of versioned-history.enabled: the BD_ prefix, with
// dots and hyphens mapped to underscores.
const vhEnvVar = "BD_VERSIONED_HISTORY_ENABLED"
func vhRequireEmbeddedLane(t *testing.T) {
t.Helper()
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
}
// vhEnv is a subprocess environment in which nothing from the developer's own
// shell can turn the feature on or off: only what a step passes explicitly.
func vhEnv(dir string, extra ...string) []string {
env := envWithout(bdEnv(dir), vhEnvVar)
env = envWithout(env, "BD_EVENTS_JOURNAL")
return append(env, extra...)
}
// vhBD runs bd and returns stdout and stderr separately. It fails the test on a
// non-zero exit.
func vhBD(t *testing.T, bd, dir string, extraEnv []string, args ...string) (stdout, stderr string) {
t.Helper()
cmd := exec.Command(bd, args...)
cmd.Dir = dir
cmd.Env = vhEnv(dir, extraEnv...)
var out, errOut bytes.Buffer
cmd.Stdout, cmd.Stderr = &out, &errOut
if err := cmd.Run(); err != nil {
t.Fatalf("bd %s in %s: %v\nstdout:\n%s\nstderr:\n%s", strings.Join(args, " "), dir, err, out.String(), errOut.String())
}
return out.String(), errOut.String()
}
type vhWorkspace struct {
name string
dir string
beadsDir string
database string
}
func vhNewWorkspace(t *testing.T, bd, dir, prefix string) vhWorkspace {
t.Helper()
if err := os.MkdirAll(dir, 0o750); err != nil {
t.Fatal(err)
}
initGitRepoAt(t, dir)
runBDInit(t, bd, dir, "--prefix", prefix, "--skip-hooks", "--skip-agents")
return vhWorkspace{name: prefix, dir: dir, beadsDir: filepath.Join(dir, ".beads"), database: prefix}
}
// vhQuery runs one query against a workspace's embedded database. Callers must
// not have a bd process running against it: the embedded store is single-writer.
func vhQuery[T any](t *testing.T, w vhWorkspace, scan func(*sql.Row) (T, error), query string, args ...any) T {
t.Helper()
db, cleanup, err := embeddeddolt.OpenSQL(t.Context(), filepath.Join(w.beadsDir, "embeddeddolt"), w.database, "main")
if err != nil {
t.Fatalf("OpenSQL(%s): %v", w.database, err)
}
defer func() { _ = cleanup() }()
got, err := scan(db.QueryRowContext(t.Context(), query, args...))
if err != nil {
t.Fatalf("%s: %v", query, err)
}
return got
}
// vhVersions counts the issue_versions rows in one workspace's database.
func vhVersions(t *testing.T, w vhWorkspace) int {
t.Helper()
return vhQuery(t, w, func(r *sql.Row) (int, error) {
var n int
return n, r.Scan(&n)
}, "SELECT COUNT(*) FROM issue_versions")
}
// vhRow reads the switch's row out of one workspace's config table. present is
// false when there is no such row, which is the state of a workspace that never
// ran `bd config set`.
func vhRow(t *testing.T, w vhWorkspace) (value string, present bool) {
t.Helper()
type result struct {
value string
present bool
}
got := vhQuery(t, w, func(r *sql.Row) (result, error) {
var v string
err := r.Scan(&v)
if errors.Is(err, sql.ErrNoRows) {
return result{}, nil
}
return result{v, true}, err
}, "SELECT value FROM config WHERE `key` = ?", versionedHistorySettingKey)
return got.value, got.present
}
// TestVersionedHistoryConfigSetWritesTheStoreRow is the front door, and D5's
// regression pin for the plane #6661 chose. `bd config set` has to write the
// database row the stores read, and must not write config.yaml: the key is not a
// yaml-only key, and making it one would move the switch off the store and back
// to the per-process plane this feature was moved away from.
func TestVersionedHistoryConfigSetWritesTheStoreRow(t *testing.T) {
vhRequireEmbeddedLane(t)
bd := buildEmbeddedBD(t)
w := vhNewWorkspace(t, bd, filepath.Join(t.TempDir(), "ws"), "vhc")
if value, present := vhRow(t, w); present {
t.Fatalf("a fresh workspace already has a %s row (%q); the test's premise is wrong", versionedHistorySettingKey, value)
}
vhBD(t, bd, w.dir, nil, "config", "set", versionedHistorySettingKey, "true")
if value, present := vhRow(t, w); !present || value != "true" {
t.Errorf("config table holds (%q, present=%v) for %s after `bd config set ... true`, want (\"true\", true)", value, present, versionedHistorySettingKey)
}
for _, name := range []string{"config.yaml", "config.local.yaml"} {
raw, err := os.ReadFile(filepath.Join(w.beadsDir, name))
if err != nil {
continue
}
if strings.Contains(string(raw), "versioned-history") {
t.Errorf("`bd config set %s` wrote to %s; the switch is a store row, not a yaml key:\n%s", versionedHistorySettingKey, name, raw)
}
}
stdout, _ := vhBD(t, bd, w.dir, nil, "config", "get", versionedHistorySettingKey)
if !strings.Contains(stdout, "true") {
t.Errorf("`bd config get` does not read back the value `bd config set` wrote: %q", stdout)
}
vhBD(t, bd, w.dir, nil, "config", "set", versionedHistorySettingKey, "false")
if value, present := vhRow(t, w); !present || value != "false" {
t.Errorf("config table holds (%q, present=%v) after `bd config set ... false`, want (\"false\", true): the row is how a store is turned off", value, present)
}
}
// vhMatrix is the fixture for the routed-write matrix: a launching workspace
// (the "town") and two rigs it routes into by issue-ID prefix.
type vhMatrix struct {
bd string
town, rigA, rigB vhWorkspace
}
func (m vhMatrix) workspaces() []vhWorkspace { return []vhWorkspace{m.town, m.rigA, m.rigB} }
func (m vhMatrix) setRow(t *testing.T, w vhWorkspace, value string) {
t.Helper()
vhBD(t, m.bd, w.dir, nil, "config", "set", versionedHistorySettingKey, value)
}
// routedUpdate writes into a rig FROM THE TOWN, through the prefix route
// (routed.go: newDoltStoreFromConfig on the target's .beads).
func (m vhMatrix) routedUpdate(t *testing.T, id, title string, env ...string) {
t.Helper()
vhBD(t, m.bd, m.town.dir, env, "update", id, "--title", title)
}
// routedClose is the other prefix-routed write.
func (m vhMatrix) routedClose(t *testing.T, id string, env ...string) {
t.Helper()
vhBD(t, m.bd, m.town.dir, env, "close", id)
}
// routedCreate writes a new issue into a rig FROM THE TOWN, through --repo
// (create.go: newDoltStoreFromConfig on the target's .beads).
func (m vhMatrix) routedCreate(t *testing.T, target vhWorkspace, title string, env ...string) {
t.Helper()
vhBD(t, m.bd, m.town.dir, env, "create", "--silent", "--repo", target.dir, title)
}
func (m vhMatrix) create(t *testing.T, w vhWorkspace, title string) string {
t.Helper()
out, _ := vhBD(t, m.bd, w.dir, nil, "create", "--silent", title)
return strings.TrimSpace(out)
}
// expectDelta runs a write and asserts how many version rows EVERY workspace
// gained, so a write that lands in the wrong place fails as loudly as one that
// records nothing. want is keyed by workspace name; anything unlisted must gain
// none -- including the launching workspace, which never records a write that
// was routed into another one.
func (m vhMatrix) expectDelta(t *testing.T, step string, want map[string]int, write func()) {
t.Helper()
before := map[string]int{}
for _, w := range m.workspaces() {
before[w.name] = vhVersions(t, w)
}
write()
var counts []string
for _, w := range m.workspaces() {
after := vhVersions(t, w)
counts = append(counts, fmt.Sprintf("%s %d->%d", w.name, before[w.name], after))
if got := after - before[w.name]; got != want[w.name] {
t.Errorf("%s: %s gained %d issue_versions row(s), want %d (before %d, after %d)",
step, w.name, got, want[w.name], before[w.name], after)
}
}
// The measured counts, not just the verdict: with -v this is the
// before/after evidence for every routed write.
t.Logf("%s: issue_versions rows: %s", step, strings.Join(counts, ", "))
}
// newVHMatrix builds the town and its two rigs, with history off everywhere and
// a routes file mapping each rig's prefix to it.
func newVHMatrix(t *testing.T) vhMatrix {
t.Helper()
bd := buildEmbeddedBD(t)
root := t.TempDir()
m := vhMatrix{bd: bd}
m.town = vhNewWorkspace(t, bd, filepath.Join(root, "town"), "vht")
m.rigA = vhNewWorkspace(t, bd, filepath.Join(m.town.dir, "rig-a"), "vha")
m.rigB = vhNewWorkspace(t, bd, filepath.Join(m.town.dir, "rig-b"), "vhb")
routes := `{"prefix":"vha-","path":"rig-a"}` + "\n" + `{"prefix":"vhb-","path":"rig-b"}` + "\n"
if err := os.WriteFile(filepath.Join(m.town.beadsDir, "routes.jsonl"), []byte(routes), 0o644); err != nil {
t.Fatalf("write routes.jsonl: %v", err)
}
return m
}
// TestVersionedHistoryFollowsTheStoreItWritesInto is the routed-write matrix, with
// a count of issue_versions rows in every workspace after every write.
//
// D1: with the TARGET's row on and the launching workspace's row absent, a routed
// update, a routed close and `bd create --repo` each add exactly one version row
// to the target. At the commit this was built on, they add none: the store they
// open is never activated.
//
// D2: the reverse. The launching workspace's row on and the target's off (or
// absent), env unset: the routed write adds none. A store answers for itself, so
// the town's answer cannot leak into a store it opened for someone else.
func TestVersionedHistoryFollowsTheStoreItWritesInto(t *testing.T) {
vhRequireEmbeddedLane(t)
m := newVHMatrix(t)
// One issue in each rig, plus one to close, all created while history is off.
idA, idAClose, idB := m.create(t, m.rigA, "seed a"), m.create(t, m.rigA, "seed a close"), m.create(t, m.rigB, "seed b")
m.expectDelta(t, "control: history off everywhere, routed update", nil, func() { m.routedUpdate(t, idA, "control") })
t.Run("D1 target row on, launching workspace row absent", func(t *testing.T) {
m.setRow(t, m.rigA, "true")
if _, present := vhRow(t, m.town); present {
t.Fatal("the launching workspace has a row; this subtest's premise is that it has none")
}
// The rows the writes below expect a version for are created AFTER the setting
// is on, so they participate in history. The seeds above were created with it
// off, so they are legacy and design §16.2b's write fence skips an update-shaped
// write to them whole: that is pinned here, at the command level.
idAOn, idACloseOn := m.create(t, m.rigA, "seed a, created with history on"), m.create(t, m.rigA, "seed a close, created with history on")
m.expectDelta(t, "routed update of a seed created before history was enabled", nil, func() { m.routedUpdate(t, idA, "routed update a, legacy seed") })
m.expectDelta(t, "routed close of a seed created before history was enabled", nil, func() { m.routedClose(t, idAClose) })
m.expectDelta(t, "routed update into the enabling rig", map[string]int{"vha": 1}, func() { m.routedUpdate(t, idAOn, "routed update a") })
m.expectDelta(t, "routed close into the enabling rig", map[string]int{"vha": 1}, func() { m.routedClose(t, idACloseOn) })
m.expectDelta(t, "bd create --repo into the enabling rig", map[string]int{"vha": 1}, func() { m.routedCreate(t, m.rigA, "routed create a") })
// A second rig that never asked stays at zero while the first records.
m.expectDelta(t, "routed update into a rig that never enabled history", nil, func() { m.routedUpdate(t, idB, "routed update b") })
m.expectDelta(t, "bd create --repo into a rig that never enabled history", nil, func() { m.routedCreate(t, m.rigB, "routed create b") })
m.expectDelta(t, "direct write inside the enabling rig", map[string]int{"vha": 1}, func() {
vhBD(t, m.bd, m.rigA.dir, nil, "update", idAOn, "--title", "direct a")
})
})
t.Run("flipping it back is a plain config change", func(t *testing.T) {
m.setRow(t, m.rigA, "false")
m.expectDelta(t, "routed update after setting the rig's row back to false", nil, func() { m.routedUpdate(t, idA, "after flip back") })
m.setRow(t, m.rigA, "true")
// Created after the setting is on again, so it participates; idA is a legacy seed.
idAFlip := m.create(t, m.rigA, "seed a, created after enabling again")
m.expectDelta(t, "routed update after enabling again, with no restart of anything", map[string]int{"vha": 1}, func() {
m.routedUpdate(t, idAFlip, "after flip forward")
})
m.setRow(t, m.rigA, "false")
})
t.Run("D2 launching workspace row on, target row off", func(t *testing.T) {
m.setRow(t, m.town, "true")
// The routed stores the town opens belong to workspaces that did not ask
// (rig A says false outright, rig B says nothing) and must not inherit the
// town's answer.
m.expectDelta(t, "routed update into a rig whose own row says false", nil, func() { m.routedUpdate(t, idA, "leak check update") })
m.expectDelta(t, "bd create --repo into a rig whose own row says false", nil, func() { m.routedCreate(t, m.rigA, "leak check create") })
m.expectDelta(t, "routed update into a rig with no row at all", nil, func() { m.routedUpdate(t, idB, "leak check b") })
// The town's own store, in the town's own workspace, does record.
m.expectDelta(t, "the launching workspace's own write", map[string]int{"vht": 1}, func() {
m.create(t, m.town, "town's own issue")
})
m.setRow(t, m.town, "false")
})
}
// TestVersionedHistoryEnvIsProcessWideAndOnlyTurnsRecordingOn is D3. The
// environment applies to every store the process opens, routed targets included;
// it can turn recording on for a store that never asked, and it can never turn it
// off for a store whose row says on. Both planes are OR'd, never ranked: the
// hazard is a write that fails to record, never one that records when it needn't.
func TestVersionedHistoryEnvIsProcessWideAndOnlyTurnsRecordingOn(t *testing.T) {
vhRequireEmbeddedLane(t)
m := newVHMatrix(t)
idA, idB := m.create(t, m.rigA, "seed a"), m.create(t, m.rigB, "seed b")
on := []string{vhEnvVar + "=1"}
// The rows the writes below expect a version for are created AFTER the setting is on
// (here, the environment), so they participate in history. The seeds above were created
// with it off, so they are legacy and design §16.2b's write fence skips an update-shaped
// write to them whole: that is pinned here, at the command level.
createOn := func(w vhWorkspace, title string) string {
out, _ := vhBD(t, m.bd, w.dir, on, "create", "--silent", title)
return strings.TrimSpace(out)
}
idAOn, idBOn := createOn(m.rigA, "seed a, created under the env override"), createOn(m.rigB, "seed b, created under the env override")
m.expectDelta(t, "routed writes to seeds created before the env override", nil, func() {
m.routedUpdate(t, idA, "env legacy a", on...)
m.routedUpdate(t, idB, "env legacy b", on...)
})
// Every store this process opens records, whatever its own row says.
m.expectDelta(t, "routed writes into both rigs under the env override", map[string]int{"vha": 1, "vhb": 1}, func() {
m.routedUpdate(t, idAOn, "env a", on...)
m.routedUpdate(t, idBOn, "env b", on...)
})
m.expectDelta(t, "bd create --repo under the env override", map[string]int{"vhb": 1}, func() {
m.routedCreate(t, m.rigB, "env create b", on...)
})
// =0 is not "off". A store whose row says on keeps recording, and a store
// with no row stays quiet.
m.setRow(t, m.rigA, "true")
off := []string{vhEnvVar + "=0"}
m.expectDelta(t, "env=0 over a rig whose row enables history", map[string]int{"vha": 1}, func() {
m.routedUpdate(t, idAOn, "env off a", off...)
})
m.expectDelta(t, "env=0 over a rig with no row", nil, func() {
m.routedUpdate(t, idB, "env off b", off...)
})
// The only way off is the row.
m.setRow(t, m.rigA, "false")
m.expectDelta(t, "routed update after the row is set back to false", nil, func() {
m.routedUpdate(t, idA, "row off a")
})
}

View file

@ -0,0 +1,88 @@
//go:build cgo && unix
package main
import (
"context"
"database/sql"
"fmt"
"net/http"
"testing"
"time"
)
// K1, against a real server: the unit-of-work provider `bd serve` builds for a
// server-mode workspace.
//
// A provider has no storage.DoltStorage to ask for a settings plane, so its flag
// comes from viper OR its own database's row, read through a unit of work when
// the provider is constructed. The unit tests prove the read with fakes; what only
// a real server can prove is that the read WORKS at that moment -- a pooled
// connection, a database already selected, a config table already migrated -- and
// that a provider which silently fell back to the environment alone would have
// looked exactly the same from outside: the served mutation succeeds, the response
// is normal, and issue_versions is simply empty.
//
// Runs in the proxied-server lane only (BEADS_TEST_PROXIED_SERVER=1), like the
// events-journal twin, TestServeActivatesTheEventsJournal.
// serverVersionRows counts issue_versions rows in one database on the shared test
// Dolt container.
func serverVersionRows(t *testing.T, port int, database string) int {
t.Helper()
dsn := fmt.Sprintf("root:@tcp(127.0.0.1:%d)/%s?parseTime=true", port, database)
db, err := sql.Open("mysql", dsn)
if err != nil {
t.Fatalf("sql.Open %s: %v", dsn, err)
}
defer func() { _ = db.Close() }()
ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
defer cancel()
var n int
if err := db.QueryRowContext(ctx, "SELECT COUNT(*) FROM issue_versions").Scan(&n); err != nil {
t.Fatalf("count issue_versions in %s: %v", database, err)
}
return n
}
// serveOneMutation starts `bd serve` on a server-mode workspace, makes one HTTP
// mutation through the provider serve built, shuts serve down, and returns how many
// issue_versions rows that mutation added.
func serveOneMutation(t *testing.T, bd string, port int, p serverModeProject) int {
t.Helper()
before := serverVersionRows(t, port, p.database)
// Nothing from the developer's shell may switch the feature on for serve.
env := envWithout(p.env, vhEnvVar)
sp := startServe(t, bd, p.dir, env)
status, body := sp.postJSON(t, "/v0/beads/issues:batchCreate",
`{"actor":"tester","items":[{"title":"served mutation","issue_type":"task"}]}`)
if status != http.StatusOK {
t.Fatalf("POST /v0/beads/issues:batchCreate = %d: %v\nstderr:\n%s", status, body, sp.stderr.String())
}
sp.shutdown(t)
return serverVersionRows(t, port, p.database) - before
}
// TestProxiedServerVersionedHistoryServeActivatesTheProviderFromItsOwnRow: two server-mode
// workspaces on one server. The one whose OWN row says on records a served
// mutation; the one with no row does not, and does not inherit the other's answer.
// Neither is helped by the environment, which is unset.
func TestProxiedServerVersionedHistoryServeActivatesTheProviderFromItsOwnRow(t *testing.T) {
port := requireSharedProxiedServer(t)
t.Parallel()
bd := buildEmbeddedBD(t)
enabled := newServerModeProject(t, bd, "vhse")
quiet := newServerModeProject(t, bd, "vhsq")
enabled.run(t, bd, "config", "set", versionedHistorySettingKey, "true")
if got := serveOneMutation(t, bd, port, enabled); got != 1 {
t.Errorf("a served mutation into a workspace whose row says on added %d issue_versions row(s), want 1: "+
"the provider serve builds is not reading its own database's row", got)
}
if got := serveOneMutation(t, bd, port, quiet); got != 0 {
t.Errorf("a served mutation into a workspace with no row added %d issue_versions row(s), want 0", got)
}
}

View file

@ -0,0 +1,170 @@
package main
import (
"context"
"errors"
"fmt"
"strings"
"github.com/steveyegge/beads/internal/storage"
storageissueops "github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/versionedhistory"
"github.com/steveyegge/beads/issueops"
)
// The resolver for the versioned-history switch -- which planes it reads, why they
// are OR'd, how a store that cannot answer is handled -- lives in
// internal/versionedhistory, so that bd doctor's fix package (which cannot import
// package main) applies the same rule. This file keeps the two names the rest of
// cmd/bd uses.
// versionedHistorySettingKey is the one spelling of the switch, used for both the
// store-config read and the `bd config set` line the help text and the off-refusal
// tell people to run. They must not drift, so it is defined once, in the package
// that reads it.
const versionedHistorySettingKey = versionedhistory.ConfigKey
// versionedHistoryEnabled reports whether THIS STORE is recording versions: its
// own settings row, and nothing else. It is what `bd versions` calls, where the
// read is the point and no capability gate precedes it.
//
// It deliberately does not fold in the environment or config.yaml the way the
// rule for writers does. Those are process-wide and can only turn recording on
// for the writes this process makes; `bd versions` only reads, so they cannot
// make the store record anything. Letting them answer here made a store that
// never recorded read as one that was, and "No versions recorded" is the
// empty answer this command's three outcomes exist to prevent. What other
// clients of the store will do is what the store's row says.
func versionedHistoryEnabled(ctx context.Context, st storage.DoltStorage) bool {
return versionedhistory.StoreSetting(ctx, st)
}
// versionedHistoryRefusalListLimit is how many offending issues the refusal spells
// out. The count it leads with is always the whole number.
const versionedHistoryRefusalListLimit = 20
// checkVersionedHistoryCanBeEnabled is the check `bd config set
// versioned-history.enabled true` and `bd config set-many
// versioned-history.enabled=true` make before they write the setting, and it
// makes it for that value alone: any other key, and every value that does not
// turn recording on (`false` included), passes without reading a row.
//
// With history on, recording a version runs in the same transaction as the write,
// so a write that introduces a number outside the I-JSON exact-integer range, in
// metadata or in a gate's timeout, already fails atomically. A row that holds one
// BEFORE the switch is turned on -- written while history was off, or by a path
// that does not record -- would, if it participates in history, fail every later
// write to it. So the switch reads every issue the store would version, runs the
// check recording runs over each one (issueops.FindUnversionable: the whole
// issue, not its metadata alone), and refuses, writing nothing, while any is
// refused. It cannot see participation, so it checks legacy rows too: an
// over-approximation that can only refuse more.
//
// That check runs once, now. A writer that does not record (an older bd, bd sql, a
// pull from a clone that had history off) can add such a row at any time
// afterwards, even right after the switch is on. If the row participates in
// history, the first write to it then fails with the same refusal, and the same fix
// applies; a legacy row is skipped by the write fence and stays writable. Making
// the check and the write of the setting one transaction would narrow that window,
// not close it.
//
// It reads through the same role accessor `bd list` does, so the direct and the
// proxied route both answer, and with the request that means "everything": every
// status, pinned rows, every type, and both planes (the scan itself skips the rows
// recording never versions). Limit 0 with no MaxRows is an unbounded read: a store
// larger than a page must not be checked on a page. A read that fails refuses the
// switch too, because a check that could not run has not passed. The read is a
// brief one, without the large text columns or the labels, and loads no
// dependencies; that is sound because none of those can hold a number, which the
// tests in internal/storage/issueops pin.
//
// On the direct route it reads through the store the command has already opened:
// `config set` opens it through openWorkspaceConfig before it asks, and the
// command's pre-run has opened it for a `config set-many` that names a database
// key, before the batch is validated. The proxied route reads through its provider.
//
// The environment and config.yaml planes do not pass through these commands, so
// they are not checked here; for those, recording's own refusal at write time is
// the control.
func checkVersionedHistoryCanBeEnabled(ctx context.Context, key, value string) error {
if key != versionedHistorySettingKey || !versionedhistory.ValueEnables(value) {
return nil
}
reader, err := openIssueReader()
if err != nil {
return fmt.Errorf("cannot check the store's issues before turning versioned history on: %w", err)
}
unlimited := 0
page, err := reader.List(ctx, issueops.ListRequest{
AllFlag: true,
IncludeAllTypes: true,
Limit: &unlimited,
Brief: true,
SkipLabels: true,
SkipCounts: true,
})
if err != nil {
return fmt.Errorf("cannot check the store's issues before turning versioned history on: %w", err)
}
rows := make([]*types.Issue, 0, len(page.Items))
for _, item := range page.Items {
rows = append(rows, item.Issue)
}
if found := storageissueops.FindUnversionable(rows); len(found) > 0 {
return errors.New(unversionableIssueRefusal(found))
}
return nil
}
// unversionableIssueRefusal is the text of the refusal: how many issues, which
// (the first versionedHistoryRefusalListLimit), what is wrong with each and the
// field it is in, and the fix for each kind of field that is wrong. It says there
// is no override because there is none.
//
// The fix depends on the field. A number in metadata is replaced or removed with
// bd update, which works with history on or off, because a version is recorded
// from the state after the write. bd update cannot change a gate's timeout, so the
// gate is removed or its column is set with bd sql, while history is off; with
// history on, every write to that row, a close included, is refused if the row
// participates in history. bd sql needs a server-backed store, which the text says.
func unversionableIssueRefusal(found []storageissueops.UnversionableIssue) string {
noun, verb := "issues", "hold"
if len(found) == 1 {
noun, verb = "issue", "holds"
}
var b strings.Builder
fmt.Fprintf(&b, "cannot turn versioned history on: %d %s %s a value a version could not record.\n", len(found), noun, verb)
shown := found
if len(shown) > versionedHistoryRefusalListLimit {
shown = shown[:versionedHistoryRefusalListLimit]
}
for _, f := range shown {
fmt.Fprintf(&b, " %s %v\n", f.ID, f.Err)
}
if len(found) > len(shown) {
fmt.Fprintf(&b, " ... and %d more\n", len(found)-len(shown))
}
var inMetadata, inTimeout bool
for _, f := range found {
switch f.Field {
case "metadata", "":
inMetadata = true
case "timeout":
inTimeout = true
}
}
b.WriteString("With history on, a write to one of these issues that leaves its value in place would be refused if the issue participates in history: it was created while history was on, or it enters the issues plane while history is on (a wisp promoted or made persistent). This check cannot tell which issues participate, so it also lists legacy issues, created before history was on, whose writes would not be refused. Fix each one, then run this command again.\n")
if inMetadata {
b.WriteString("A number in metadata, one command per issue (this works with history on or off):\n")
b.WriteString(" bd update <id> --metadata '{\"<key>\": \"<value as a string>\"}' replace the value; a string keeps it exact\n")
b.WriteString(" bd update <id> --unset-metadata <key> or remove the key\n")
}
if inTimeout {
b.WriteString("A gate timeout is held as nanoseconds, and 9007199254740991 (about 104.25 days) is the most a version can record. bd update cannot change a gate's timeout. While history is off, remove the gate or set its timeout within that limit:\n")
b.WriteString(" bd delete <id> --force remove the gate; without --force bd only previews, and removing the gate also unblocks anything it was blocking\n")
b.WriteString(" bd sql \"UPDATE issues SET timeout_ns = <nanoseconds> WHERE id = '<id>'\" set the timeout; bd sql needs a server-backed store, not an embedded one\n")
}
b.WriteString("There is no override. This check runs once, now: if a writer that does not record (an older bd, bd sql, a pull from a clone that had history off) later puts such a value into an issue that participates in history, the next write to it fails with the same refusal, and the same fix applies.")
return b.String()
}

View file

@ -0,0 +1,436 @@
//go:build cgo
package main
import (
"encoding/json"
"errors"
"fmt"
"os"
"os/exec"
"path/filepath"
"regexp"
"sort"
"strings"
"testing"
"github.com/steveyegge/beads/internal/workapi"
)
// THE NAME IS LOAD-BEARING for the same reason TestEmbeddedVersionedHistorySwitchRoundTrip's is:
// .github/scripts/embedded-test-shard.sh selects the tests the embedded job runs by
// `grep -rh '^func TestEmbedded' cmd/bd/*_embedded_test.go`, so a test that keeps this prefix
// and this file suffix runs in the one job that sets BEADS_TEST_EMBEDDED_DOLT=1.
//
// TestEmbeddedVersionedHistorySwitchRefusesUnversionableMetadata drives the REAL
// `bd config set versioned-history.enabled true` against a real store that already holds rows
// a version could not be recorded for.
//
// With history on, recording a version runs in the same transaction as the write, so a write
// that introduces a number outside the I-JSON exact-integer range already fails atomically.
// What that cannot help is a row that holds such a number BEFORE the switch is turned on:
// written while history was off, or through a path that does not mint (bd sql, a pull from a
// clone that had history off). Once history is on, every later write to that row would fail
// if the row participates in history. The switch therefore checks first, with the same
// function the mint runs, and refuses to turn history on while any issue the mint would
// version holds a value it would refuse.
//
// What this pins, end to end and in a database of its own:
// - the refusal exits non-zero and prints the count, the ids and the remedy,
// - it names every issue the mint would version, whatever its status or type: a closed issue,
// a pinned one and a gate are all hidden from a default `bd list`, so a scan that read only
// what `bd list` shows would clear the switch over them,
// - it names only those: an ephemeral row and a no-history row holding the same value are
// never versioned, so they are not listed and do not block,
// - it writes NOTHING: the setting is still off afterwards,
// - turning history OFF never scans,
// - once the rows are fixed with the command the refusal names, the switch turns on.
func TestEmbeddedVersionedHistorySwitchRefusesUnversionableMetadata(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
// The environment can only turn recording on and would make a passing run prove nothing
// about the store's own setting, so clear it. No t.Parallel: t.Setenv is incompatible.
t.Setenv("BD_VERSIONED_HISTORY_ENABLED", "")
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "vsc")
const timestampInNanoseconds = `{"ts":1727000000000000000}`
const largeInteger = `{"n":9007199254740993}`
clean := bdCreateSilent(t, bd, dir, "clean", "--metadata", `{"ok":1,"fraction":0.1}`)
first := bdCreateSilent(t, bd, dir, "holds a nanosecond timestamp", "--metadata", timestampInNanoseconds)
second := bdCreateSilent(t, bd, dir, "holds an integer past 2^53", "--metadata", largeInteger)
wisp := bdCreateSilent(t, bd, dir, "ephemeral, never versioned", "--ephemeral", "--metadata", timestampInNanoseconds)
noHistory := bdCreateSilent(t, bd, dir, "no-history, never versioned", "--no-history", "--metadata", timestampInNanoseconds)
// Three more the mint versions that a default `bd list` does not show. The scan has to ask for
// every status and every type to see them.
closed := bdCreateSilent(t, bd, dir, "closed, still versioned", "--metadata", timestampInNanoseconds)
bdRunOK(t, bd, dir, "close", closed)
pinned := bdCreateSilent(t, bd, dir, "pinned, still versioned", "--metadata", largeInteger)
bdRunOK(t, bd, dir, "update", pinned, "--status", "pinned")
gate := bdCreateSilent(t, bd, dir, "a gate, still versioned", "--type", "gate", "--metadata", timestampInNanoseconds)
out, code := bdRunFailCode(t, bd, dir, "config", "set", "versioned-history.enabled", "true")
if code == 0 {
t.Fatalf("enabling versioned history over unrecordable rows exited 0; out=%s", out)
}
offenders := map[string]string{
"the open issue holding a timestamp": first,
"the open issue holding a large integer": second,
"the closed issue": closed,
"the pinned issue": pinned,
"the gate": gate,
}
for name, id := range offenders {
if !strings.Contains(out, id) {
t.Errorf("the refusal does not name %s (%s), which holds a value a version could not record:\n%s", name, id, out)
}
}
for name, id := range map[string]string{"the clean issue": clean, "the ephemeral issue": wisp, "the no-history issue": noHistory} {
if strings.Contains(out, id) {
t.Errorf("the refusal names %s (%s), which the mint would never version:\n%s", name, id, out)
}
}
if want := fmt.Sprintf("%d issues", len(offenders)); !strings.Contains(out, want) {
t.Errorf("the refusal does not give the count of offending issues (%d):\n%s", len(offenders), out)
}
for _, want := range []string{"bd update", "--metadata", "I-JSON"} {
if !strings.Contains(out, want) {
t.Errorf("the refusal does not contain %q, so it does not say what is wrong or how to fix it:\n%s", want, out)
}
}
// It refuses WITHOUT writing: the setting is still off.
if got := strings.TrimSpace(bdConfig(t, bd, dir, "get", "versioned-history.enabled")); strings.HasPrefix(got, "true") {
t.Fatalf("the refused `config set ... true` wrote the setting anyway: config get says %q", got)
}
// Turning it off never scans, so it works with offenders present and is how a
// store that is somehow already on gets out from under a poisoned row.
bdConfig(t, bd, dir, "set", "versioned-history.enabled", "false")
// The remedy the refusal names: one update per row, while history is off.
bdRunOK(t, bd, dir, "update", first, "--metadata", `{"ts":"1727000000000000000"}`)
bdRunOK(t, bd, dir, "update", second, "--unset-metadata", "n")
bdRunOK(t, bd, dir, "update", closed, "--metadata", `{"ts":"1727000000000000000"}`)
bdRunOK(t, bd, dir, "update", pinned, "--unset-metadata", "n")
bdRunOK(t, bd, dir, "update", gate, "--metadata", `{"ts":"1727000000000000000"}`)
bdConfig(t, bd, dir, "set", "versioned-history.enabled", "true")
if got := strings.TrimSpace(bdConfig(t, bd, dir, "get", "versioned-history.enabled")); !strings.HasPrefix(got, "true") {
t.Fatalf("after fixing every row the switch did not turn on: config get says %q", got)
}
}
// TestEmbeddedVersionedHistorySwitchScansEveryRowNotOnePage pins that the scan reads the whole
// store. A list read that sets no limit returns one page (workapi.DefaultListLimit rows), so a
// scan that stopped asking for everything would clear the switch over any offender past the first
// page and count only that page's worth in its refusal.
//
// The rows are imported in one process: creating a page and a half of issues one command at a
// time costs the better part of a minute in this job.
func TestEmbeddedVersionedHistorySwitchScansEveryRowNotOnePage(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Setenv("BD_VERSIONED_HISTORY_ENABLED", "")
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "vsp")
// More rows than one page, and more than the refusal lists, so both counts are exercised.
n := workapi.DefaultListLimit + 10
var rows strings.Builder
for i := 1; i <= n; i++ {
fmt.Fprintf(&rows, `{"title":"offender %03d","metadata":{"ts":1727000000000000000}}`+"\n", i)
}
file := filepath.Join(t.TempDir(), "offenders.jsonl")
if err := os.WriteFile(file, []byte(rows.String()), 0o600); err != nil {
t.Fatalf("writing the rows to import: %v", err)
}
bdRunOK(t, bd, dir, "import", file)
out, _ := bdRunFailCode(t, bd, dir, "config", "set", "versioned-history.enabled", "true")
if want := fmt.Sprintf("%d issues", n); !strings.Contains(out, want) {
t.Errorf("the refusal does not count all %d offending issues (a scan that read one page would say %d):\n%s", n, workapi.DefaultListLimit, out)
}
if want := fmt.Sprintf("... and %d more", n-versionedHistoryRefusalListLimit); !strings.Contains(out, want) {
t.Errorf("the refusal does not say %q after the first %d ids:\n%s", want, versionedHistoryRefusalListLimit, out)
}
}
// TestEmbeddedVersionedHistorySetManyRefusesUnversionableMetadata drives the REAL
// `bd config set-many versioned-history.enabled=true` against a store that holds a row a version
// could not be recorded for. set-many writes the same setting as `bd config set` through a
// validation loop of its own, and it once turned history on over such a row with no check at
// all: the next write to that row then failed.
//
// What this pins, end to end and in a database of its own:
// - the batch is refused: it exits non-zero and the refusal names the issue and the remedy,
// - it writes NOTHING, neither the setting nor the other pair in the same batch, because the
// check runs before any pair is written,
// - a batch that turns history OFF never scans,
// - once the row is fixed, the same batch turns history on and writes its other pair.
func TestEmbeddedVersionedHistorySetManyRefusesUnversionableMetadata(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Setenv("BD_VERSIONED_HISTORY_ENABLED", "")
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "vsm")
offender := bdCreateSilent(t, bd, dir, "holds a nanosecond timestamp", "--metadata", `{"ts":1727000000000000000}`)
// The other pair comes first, so a check made after the writes would already have stored it.
out, _ := bdRunFailCode(t, bd, dir, "config", "set-many", "vsm.marker=1", "versioned-history.enabled=true")
if !strings.Contains(out, offender) {
t.Errorf("the refusal does not name %s, which holds a value a version could not record:\n%s", offender, out)
}
for _, want := range []string{"1 issue", "bd update", "--metadata", "I-JSON"} {
if !strings.Contains(out, want) {
t.Errorf("the refusal does not contain %q, so it does not say what is wrong or how to fix it:\n%s", want, out)
}
}
// It refuses WITHOUT writing: the setting is still off and the other pair was not stored.
if got := strings.TrimSpace(bdConfig(t, bd, dir, "get", "versioned-history.enabled")); strings.HasPrefix(got, "true") {
t.Fatalf("the refused `config set-many ... versioned-history.enabled=true` wrote the setting anyway: config get says %q", got)
}
if got := strings.TrimSpace(bdConfig(t, bd, dir, "get", "vsm.marker")); got == "1" {
t.Fatalf("the refused batch stored its other pair anyway: config get vsm.marker says %q", got)
}
// Turning it off never scans, so a batch that does so works with the offender present.
bdConfig(t, bd, dir, "set-many", "versioned-history.enabled=false")
// The remedy the refusal names, then the same batch that was refused goes through.
bdRunOK(t, bd, dir, "update", offender, "--unset-metadata", "ts")
bdConfig(t, bd, dir, "set-many", "vsm.marker=1", "versioned-history.enabled=true")
if got := strings.TrimSpace(bdConfig(t, bd, dir, "get", "versioned-history.enabled")); !strings.HasPrefix(got, "true") {
t.Fatalf("after fixing the row the batch did not turn the switch on: config get says %q", got)
}
if got := strings.TrimSpace(bdConfig(t, bd, dir, "get", "vsm.marker")); got != "1" {
t.Fatalf("after fixing the row the batch did not store its other pair: config get vsm.marker says %q", got)
}
}
// gateIDFromCreateJSON reads the id out of `bd gate create --json` output, which may carry
// warnings ahead of the object.
func gateIDFromCreateJSON(t *testing.T, out string) string {
t.Helper()
start := strings.Index(out, "{")
if start < 0 {
t.Fatalf("no JSON object in `bd gate create --json` output:\n%s", out)
}
var created struct {
ID string `json:"id"`
}
if err := json.NewDecoder(strings.NewReader(out[start:])).Decode(&created); err != nil || created.ID == "" {
t.Fatalf("parsing `bd gate create --json` output: %v\n%s", err, out)
}
return created.ID
}
// createTimerGate creates a timer gate that blocks one issue, through the real command, so what
// reaches the store is what a person can write.
func createTimerGate(t *testing.T, bd, dir, blocks, timeout string) string {
t.Helper()
return gateIDFromCreateJSON(t, bdRunOK(t, bd, dir, "gate", "create", "--type=timer", "--blocks", blocks, "--timeout", timeout, "--json"))
}
// idsNamedIn returns the distinct issue ids with the given prefix that a command's output names.
func idsNamedIn(out, prefix string) map[string]bool {
ids := map[string]bool{}
for _, id := range regexp.MustCompile(regexp.QuoteMeta(prefix)+`-[0-9a-z]+`).FindAllString(out, -1) {
ids[id] = true
}
return ids
}
func sortedIDSet(set map[string]bool) []string {
ids := make([]string, 0, len(set))
for id := range set {
ids = append(ids, id)
}
sort.Strings(ids)
return ids
}
// writeRefusedWithHistoryOn reports whether an ordinary write to the issue is refused when the
// process records versions because its ENVIRONMENT says so. That plane does not pass through the
// pre-enable scan, which makes it the way to ask the mint itself what it would refuse.
func writeRefusedWithHistoryOn(t *testing.T, bd, dir, id string) bool {
t.Helper()
cmd := exec.Command(bd, "update", id, "--notes", "touched with history on")
cmd.Dir = dir
cmd.Env = append(bdEnv(dir), vhEnvVar+"=1")
out, err := cmd.CombinedOutput()
if err == nil {
return false
}
var exitErr *exec.ExitError
if !errors.As(err, &exitErr) {
t.Fatalf("bd update %s failed without an exit code: %v\n%s", id, err, out)
}
if !strings.Contains(string(out), "I-JSON") {
t.Fatalf("bd update %s failed, but not with the mint's refusal of a number outside the I-JSON range:\n%s", id, out)
}
return true
}
// createWithHistoryOn creates an issue in a process that records versions because its ENVIRONMENT
// says so, which makes the row participate in history from its first write. A row created while
// history is off does not participate: design §16.2b's write fence skips an update-shaped write to it.
func createWithHistoryOn(t *testing.T, bd, dir string, args ...string) string {
t.Helper()
cmd := exec.Command(bd, append([]string{"create", "--silent"}, args...)...)
cmd.Dir = dir
cmd.Env = append(bdEnv(dir), vhEnvVar+"=1")
out, err := cmd.Output()
if err != nil {
var exitErr *exec.ExitError
if errors.As(err, &exitErr) {
t.Fatalf("bd create --silent %s with history on failed: %v\n%s", strings.Join(args, " "), err, exitErr.Stderr)
}
t.Fatalf("bd create --silent %s with history on failed: %v", strings.Join(args, " "), err)
}
return strings.TrimSpace(string(out))
}
// TestEmbeddedVersionedHistorySwitchRefusesAnUnrecordableGateTimeout drives the REAL
// `bd config set versioned-history.enabled true` against a store that holds gates whose timeout a
// version could not record.
//
// A gate's timeout is a time.Duration, which a version holds as a count of nanoseconds, so one past
// 2^53-1 ns (about 104.25 days) is a number outside the I-JSON exact-integer range. Nothing stops
// `bd gate create --timeout 2600h` while history is off, and once history is on every write to a
// participating gate, a close included, is refused. A scan that read only metadata cleared the
// switch over it.
//
// What this pins, end to end and in a database of its own:
// - the refusal names each gate past the range, open or closed, and the field the number was
// found in ("timeout"), and does not name a gate that is in range,
// - it offers the remedy for the field that is wrong: removing the gate, not a metadata edit, until
// an issue with a number in its metadata is there too,
// - it writes NOTHING: the setting is still off afterwards,
// - the scan names every offender, because it cannot see participation: a row written while
// history was off is a legacy row, which design §16.2b's write fence makes the mint skip, so
// with history on through the environment, a plane the scan does not guard, no write to one is
// refused. The scan can only refuse more than the mint does,
// - for a row that participates in history, the scan and the mint AGREE: the issue whose next
// write is refused is exactly the one the scan named,
// - once the remedies are applied, the switch turns on.
func TestEmbeddedVersionedHistorySwitchRefusesAnUnrecordableGateTimeout(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("embedded dolt integration tests are not enabled")
}
// The environment can only turn recording on and would make a passing run prove nothing
// about the store's own setting, so clear it. No t.Parallel: t.Setenv is incompatible.
t.Setenv(vhEnvVar, "")
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "vsg")
blocked := bdCreateSilent(t, bd, dir, "blocked by three gates")
clean := bdCreateSilent(t, bd, dir, "clean")
// History is off, so nothing refuses a gate whose timeout a version could not record.
overlong := createTimerGate(t, bd, dir, blocked, "2600h")
inRange := createTimerGate(t, bd, dir, blocked, "2500h")
closedOverlong := createTimerGate(t, bd, dir, blocked, "8760h")
bdRunOK(t, bd, dir, "gate", "resolve", closedOverlong)
out, code := bdRunFailCode(t, bd, dir, "config", "set", "versioned-history.enabled", "true")
if code == 0 {
t.Fatalf("enabling versioned history over a gate whose timeout is past the range exited 0; out=%s", out)
}
for name, id := range map[string]string{"the open gate past the range": overlong, "the closed gate past the range": closedOverlong} {
if !strings.Contains(out, id) {
t.Errorf("the refusal does not name %s (%s), whose timeout a version could not record:\n%s", name, id, out)
}
}
for name, id := range map[string]string{"the gate in range": inRange, "the issue the gates block": blocked, "the clean issue": clean} {
if strings.Contains(out, id) {
t.Errorf("the refusal names %s (%s), which the mint would record:\n%s", name, id, out)
}
}
for _, want := range []string{"2 issues", `"timeout"`, "I-JSON", "bd delete <id> --force", "only previews", "unblocks anything it was blocking"} {
if !strings.Contains(out, want) {
t.Errorf("the refusal does not contain %q, so it does not say what is wrong or how to fix it:\n%s", want, out)
}
}
if strings.Contains(out, "--unset-metadata") {
t.Errorf("the refusal offers a metadata edit although nothing holds a number in its metadata:\n%s", out)
}
if got := strings.TrimSpace(bdConfig(t, bd, dir, "get", "versioned-history.enabled")); strings.HasPrefix(got, "true") {
t.Fatalf("the refused `config set ... true` wrote the setting anyway: config get says %q", got)
}
// Add the other kind of offender. The refusal now has two fields to fix and offers a remedy for each.
holdsNumber := bdCreateSilent(t, bd, dir, "holds a nanosecond timestamp", "--metadata", `{"ts":1727000000000000000}`)
out, _ = bdRunFailCode(t, bd, dir, "config", "set", "versioned-history.enabled", "true")
for _, want := range []string{"3 issues", `"timeout"`, `"metadata"`, "bd delete <id> --force", "only previews", "unblocks anything it was blocking", "--unset-metadata"} {
if !strings.Contains(out, want) {
t.Errorf("the refusal over a gate and a metadata number does not contain %q:\n%s", want, out)
}
}
// The scan reads rows, not participation, so it names every row that holds a value the mint would
// refuse. Ask the mint, through a process that records because its environment says so (a plane the
// scan does not guard), what a write to each row does. Everything so far was written while history
// was off, so every row is a legacy row, and design §16.2b's write fence skips an update-shaped write
// to one before the refusal could run: none of these writes is refused, offenders included. That is
// the scan's deliberate over-approximation, in the safe direction: it can only refuse more than the
// mint does.
legacy := []string{blocked, clean, overlong, inRange, closedOverlong, holdsNumber}
for _, id := range legacy {
if writeRefusedWithHistoryOn(t, bd, dir, id) {
t.Errorf("the mint refused a write to %s, a row written while history was off: the write fence should have skipped it", id)
}
}
if got, want := strings.Join(sortedIDSet(idsNamedIn(out, "vsg")), ","), strings.Join(sortedIDSet(map[string]bool{overlong: true, closedOverlong: true, holdsNumber: true}), ","); got != want {
t.Errorf("the scan named %s, want exactly the offenders %s", got, want)
}
// A row participates in history when it was created while history was on. Create two that way, in
// range, then take one of them out of range while history is off, which nothing refuses. For a row
// that participates the scan and the mint agree: the offender is named and every write to it is
// refused, and the clean one is neither.
participatingClean := createWithHistoryOn(t, bd, dir, "participates, clean", "--metadata", `{"ts":1}`)
participating := createWithHistoryOn(t, bd, dir, "participates, then holds a nanosecond timestamp", "--metadata", `{"ts":1}`)
bdRunOK(t, bd, dir, "update", participating, "--metadata", `{"ts":1727000000000000000}`)
out, _ = bdRunFailCode(t, bd, dir, "config", "set", "versioned-history.enabled", "true")
named := idsNamedIn(out, "vsg")
namedParticipating := map[string]bool{}
refused := map[string]bool{}
for _, id := range []string{participatingClean, participating} {
if named[id] {
namedParticipating[id] = true
}
if writeRefusedWithHistoryOn(t, bd, dir, id) {
refused[id] = true
}
}
if got, want := strings.Join(sortedIDSet(namedParticipating), ","), strings.Join(sortedIDSet(refused), ","); got != want {
t.Errorf("of the rows that participate, the scan named %s but the mint refused a write to %s: they must be the same issues", got, want)
}
if got := strings.Join(sortedIDSet(refused), ","); got != participating {
t.Errorf("the mint refused a write to %v, want exactly %s", sortedIDSet(refused), participating)
}
if got, want := strings.Join(sortedIDSet(named), ","), strings.Join(sortedIDSet(map[string]bool{overlong: true, closedOverlong: true, holdsNumber: true, participating: true}), ","); got != want {
t.Errorf("the scan named %s, want the three offenders written while history was off and the participating one, %s", got, want)
}
// The remedies the refusal names, then the switch turns on.
bdRunOK(t, bd, dir, "delete", overlong, closedOverlong, "--force")
bdRunOK(t, bd, dir, "update", holdsNumber, "--unset-metadata", "ts")
bdRunOK(t, bd, dir, "update", participating, "--unset-metadata", "ts")
bdConfig(t, bd, dir, "set", "versioned-history.enabled", "true")
if got := strings.TrimSpace(bdConfig(t, bd, dir, "get", "versioned-history.enabled")); !strings.HasPrefix(got, "true") {
t.Fatalf("after applying the remedies the switch did not turn on: config get says %q", got)
}
}

View file

@ -0,0 +1,158 @@
//go:build cgo
package main
import (
"fmt"
"strings"
"testing"
)
// THE NAME IS LOAD-BEARING: .github/scripts/proxied-test-shard.sh finds the tests the proxied-server
// lane runs by the name prefix (TestProxiedServer, TestServerMode) across cmd/bd/*_test.go, and that
// lane is the only one that enables the proxied-server tests. A test that dropped the prefix would
// skip everywhere else and never run.
// proxiedWriteRefusedWithHistoryOn is writeRefusedWithHistoryOn on the proxied route: it asks
// whether an ordinary write to the issue is refused when the process records versions because its
// environment says so, a plane the pre-enable scan does not guard.
func proxiedWriteRefusedWithHistoryOn(t *testing.T, bd, dir, id string) bool {
t.Helper()
_, stderr, err := bdProxiedRunBuffersWithEnv(t, bd, dir, []string{vhEnvVar + "=1"}, "update", id, "--notes", "touched with history on")
if err == nil {
return false
}
if !strings.Contains(stderr, "I-JSON") {
t.Fatalf("bd update %s failed, but not with the mint's refusal of a number outside the I-JSON range:\n%s", id, stderr)
}
return true
}
// proxiedCreateWithHistoryOn is createWithHistoryOn on the proxied route: the row participates in
// history from its first write because the process records versions as its environment says so.
func proxiedCreateWithHistoryOn(t *testing.T, bd, dir string, args ...string) string {
t.Helper()
stdout, stderr, err := bdProxiedRunBuffersWithEnv(t, bd, dir, []string{vhEnvVar + "=1"}, append([]string{"create", "--silent"}, args...)...)
if err != nil {
t.Fatalf("bd create --silent %s with history on failed: %v\nstdout:\n%s\nstderr:\n%s", strings.Join(args, " "), err, stdout, stderr)
}
return strings.TrimSpace(stdout)
}
// TestProxiedServerVersionedHistorySwitchRefusesAnUnrecordableGateTimeout is the proxied-server twin
// of TestEmbeddedVersionedHistorySwitchRefusesAnUnrecordableGateTimeout: the same scan, read through
// the proxied route's own reader instead of the store the command opened.
//
// That is the point of running it. The scan reads a lite projection, and each route builds its own,
// so a route whose projection left out a gate's timeout would clear the switch over a participating
// gate the mint then refuses every write to. A timeout past 2^53-1 ns (about 104.25 days) must be
// refused here exactly as on the direct route.
//
// What this pins, against a real server:
// - the refusal names the gate past the range and the field ("timeout"), and not the gate in range,
// - it writes NOTHING: the setting is still off afterwards,
// - the scan names every offender, because it cannot see participation: a row written while
// history was off is a legacy row, which design §16.2b's write fence makes the mint skip, so
// with history on through the environment no write to one is refused. The scan can only refuse
// more than the mint does,
// - for a row that participates in history, the scan and the mint AGREE: the issue whose next
// write is refused with history on through the environment is exactly the one the scan named,
// - the remedies it names work on this route, `bd sql` for the timeout included (it is not
// available on an embedded store), and the switch then turns on.
func TestProxiedServerVersionedHistorySwitchRefusesAnUnrecordableGateTimeout(t *testing.T) {
requireSharedProxiedServer(t)
t.Parallel()
bd := buildEmbeddedBD(t)
p := newSharedProxiedProject(t, bd, "vsx")
blocked := bdProxiedCreate(t, bd, p.dir, "blocked by two gates")
clean := bdProxiedCreate(t, bd, p.dir, "clean")
createGate := func(timeout string) string {
t.Helper()
stdout, stderr, err := bdProxiedRunBuffers(t, bd, p.dir, "gate", "create", "--type=timer", "--blocks", blocked.ID, "--timeout", timeout, "--json")
if err != nil {
t.Fatalf("bd gate create --timeout %s failed: %v\nstdout:\n%s\nstderr:\n%s", timeout, err, stdout, stderr)
}
return gateIDFromCreateJSON(t, stdout)
}
// History is off, so nothing refuses a gate whose timeout a version could not record.
overlong := createGate("2600h")
inRange := createGate("2500h")
holdsNumber := bdProxiedCreate(t, bd, p.dir, "holds a nanosecond timestamp", "--metadata", `{"ts":1727000000000000000}`)
out := bdProxiedConfigFail(t, bd, p.dir, "set", versionedHistorySettingKey, "true")
for name, id := range map[string]string{"the gate past the range": overlong, "the issue holding a number in metadata": holdsNumber.ID} {
if !strings.Contains(out, id) {
t.Errorf("the refusal does not name %s (%s), which holds a value a version could not record:\n%s", name, id, out)
}
}
for name, id := range map[string]string{"the gate in range": inRange, "the issue the gates block": blocked.ID, "the clean issue": clean.ID} {
if strings.Contains(out, id) {
t.Errorf("the refusal names %s (%s), which the mint would record:\n%s", name, id, out)
}
}
for _, want := range []string{"2 issues", `"timeout"`, `"metadata"`, "I-JSON", "bd delete <id> --force", "only previews", "unblocks anything it was blocking", "bd sql", "--unset-metadata"} {
if !strings.Contains(out, want) {
t.Errorf("the refusal does not contain %q, so it does not say what is wrong or how to fix it:\n%s", want, out)
}
}
if got := strings.TrimSpace(bdProxiedConfig(t, bd, p.dir, "get", versionedHistorySettingKey)); strings.HasPrefix(got, "true") {
t.Fatalf("the refused `config set ... true` wrote the setting anyway: config get says %q", got)
}
// The scan reads rows, not participation, so it names every row that holds a value the mint would
// refuse. Ask the mint, through a process that records because its environment says so (a plane the
// scan does not guard), what a write to each row does. Everything so far was written while history
// was off, so every row is a legacy row, and design §16.2b's write fence skips an update-shaped write
// to one before the refusal could run: none of these writes is refused, offenders included. That is
// the scan's deliberate over-approximation, in the safe direction: it can only refuse more than the
// mint does.
legacy := []string{blocked.ID, clean.ID, overlong, inRange, holdsNumber.ID}
for _, id := range legacy {
if proxiedWriteRefusedWithHistoryOn(t, bd, p.dir, id) {
t.Errorf("the mint refused a write to %s, a row written while history was off: the write fence should have skipped it", id)
}
}
if got, want := strings.Join(sortedIDSet(idsNamedIn(out, "vsx")), ","), strings.Join(sortedIDSet(map[string]bool{overlong: true, holdsNumber.ID: true}), ","); got != want {
t.Errorf("the scan named %s, want exactly the offenders %s", got, want)
}
// A row participates in history when it was created while history was on. Create two that way, in
// range, then take one of them out of range while history is off, which nothing refuses. For a row
// that participates the scan and the mint agree: the offender is named and every write to it is
// refused, and the clean one is neither.
participatingClean := proxiedCreateWithHistoryOn(t, bd, p.dir, "participates, clean", "--metadata", `{"ts":1}`)
participating := proxiedCreateWithHistoryOn(t, bd, p.dir, "participates, then holds a nanosecond timestamp", "--metadata", `{"ts":1}`)
bdProxiedUpdate(t, bd, p.dir, participating, "--metadata", `{"ts":1727000000000000000}`)
out = bdProxiedConfigFail(t, bd, p.dir, "set", versionedHistorySettingKey, "true")
named := idsNamedIn(out, "vsx")
namedParticipating := map[string]bool{}
refused := map[string]bool{}
for _, id := range []string{participatingClean, participating} {
if named[id] {
namedParticipating[id] = true
}
if proxiedWriteRefusedWithHistoryOn(t, bd, p.dir, id) {
refused[id] = true
}
}
if got, want := strings.Join(sortedIDSet(namedParticipating), ","), strings.Join(sortedIDSet(refused), ","); got != want {
t.Errorf("of the rows that participate, the scan named %s but the mint refused a write to %s: they must be the same issues", got, want)
}
if got := strings.Join(sortedIDSet(refused), ","); got != participating {
t.Errorf("the mint refused a write to %v, want exactly %s", sortedIDSet(refused), participating)
}
if got, want := strings.Join(sortedIDSet(named), ","), strings.Join(sortedIDSet(map[string]bool{overlong: true, holdsNumber.ID: true, participating: true}), ","); got != want {
t.Errorf("the scan named %s, want the two offenders written while history was off and the participating one, %s", got, want)
}
// The remedies the refusal names, then the switch turns on.
bdProxiedSQL(t, bd, p.dir, fmt.Sprintf("UPDATE issues SET timeout_ns = 7200000000000 WHERE id = '%s'", overlong))
bdProxiedUpdate(t, bd, p.dir, holdsNumber.ID, "--unset-metadata", "ts")
bdProxiedUpdate(t, bd, p.dir, participating, "--unset-metadata", "ts")
bdProxiedConfig(t, bd, p.dir, "set", versionedHistorySettingKey, "true")
if got := strings.TrimSpace(bdProxiedConfig(t, bd, p.dir, "get", versionedHistorySettingKey)); !strings.HasPrefix(got, "true") {
t.Fatalf("after applying the remedies the switch did not turn on: config get says %q", got)
}
}

View file

@ -0,0 +1,97 @@
package main
import (
"context"
"testing"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/hooks"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/issueops"
)
// The resolver's own tests -- the table of ways a store can fail to answer, how the
// stored string is read back, the capability guard, the recover, and the raw-store
// ordering -- moved to internal/versionedhistory with the resolver, assertions
// unchanged, which is what shows the move preserved #6661's behavior. What stays
// here is the one thing that is cmd/bd's: how the decorator chain is wired.
// configProbeStore is a raw store at the bottom of a decorator chain whose
// settings plane answers however a case needs. It counts the reads so a test can
// prove it was actually asked -- or, here, that it was NOT.
//
// Every other method promotes from the embedded nil interface and panics if
// called, which is deliberate: nothing here should be calling them.
type configProbeStore struct {
storage.DoltStorage
cfg issueops.WorkspaceConfig
calls int
enabled bool
}
func (s *configProbeStore) WorkspaceConfig() (issueops.WorkspaceConfig, error) {
s.calls++
return s.cfg, nil
}
// SetVersionedHistoryEnabled makes this store a storage.VersionedHistoryConfigurer,
// which is what would earn it a store-plane read if wiring still did one.
func (s *configProbeStore) SetVersionedHistoryEnabled(enabled bool) { s.enabled = enabled }
// settingsPlane is a workspace settings plane with one canned answer.
type settingsPlane struct {
issueops.WorkspaceConfig
value string
}
func (p *settingsPlane) GetSetting(context.Context, issueops.GetSettingRequest) (issueops.SettingResult, error) {
return issueops.SettingResult{Key: versionedHistorySettingKey, Value: p.value}, nil
}
// TestWireStorageDecoratorsLeavesActivationToTheFactories pins the other half of
// moving activation to where a store is constructed.
//
// wireStorageDecorators used to be the one place the switch was read and applied,
// and it runs on the ONE store a command opens for its own workspace. Every store
// a routed update, a routed close or `bd create --repo` opens for ANOTHER
// workspace is built by newDoltStoreFromConfig and never passed through here, so
// it recorded nothing while the command reported success. Activation now happens
// in the factories, for every store they hand back; if wiring ALSO read the row it
// would read it twice per open, and would read as the place that activates -- the
// misreading that produced the defect.
//
// The count is the assertion that matters, not "it survived": the store here would
// answer true, and would be switched on, if wiring still consulted it.
func TestWireStorageDecoratorsLeavesActivationToTheFactories(t *testing.T) {
for _, tt := range []struct {
name string
env string
}{
{"the store's row says on", ""},
{"the environment says on", "1"},
} {
t.Run(tt.name, func(t *testing.T) {
clearTelemetryEnv(t)
t.Setenv("BD_VERSIONED_HISTORY_ENABLED", tt.env)
// config.GetBool answers false until viper is initialised, so without
// this the env subtest would pass whatever wiring did with the env.
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize(): %v", err)
}
t.Cleanup(func() { _ = config.Initialize() })
raw := &configProbeStore{cfg: &settingsPlane{value: "true"}}
chain := wireStorageDecorators(raw, hooks.NewRunner("/nonexistent"), false)
if chain == nil {
t.Fatal("wireStorageDecorators returned nil for a non-nil store")
}
if raw.calls != 0 {
t.Errorf("wireStorageDecorators read the store's settings plane %d time(s), want 0: activation belongs to the factory that constructed the store", raw.calls)
}
if raw.enabled {
t.Error("wireStorageDecorators switched versioned history on; only the factory that constructs a store may, at construction")
}
})
}
}

305
cmd/bd/versions.go Normal file
View file

@ -0,0 +1,305 @@
package main
import (
"context"
"errors"
"fmt"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/utils"
)
// errVersionedHistoryOff and errVersionsUnsupported are distinct on purpose.
//
// #5898's third goal is that a history answer has three shapes, not two:
// here it is, there is no such thing, and something prevented a complete
// answer. An empty list is a WRONG answer for both of these cases -- it reads
// as "this bead has no versions", which is a claim about the bead rather than
// about the store. Same principle get_issue.go:38-41 applies to a missing
// leases table: a wrong answer, not an empty one.
var (
errVersionedHistoryOff = errors.New("versioned history is not enabled on this store")
errVersionsUnsupported = errors.New("this storage backend cannot serve version history")
errNoSuchBead = errors.New("no such bead")
)
// versionsOutcome is what runVersions resolved, kept apart from the rendering
// so the four ways of having nothing to show stay four different answers.
//
// It is also the --json payload: one object for every answer that is not an
// error, so a script parses one shape whether or not anything was recorded.
// Versions is never nil on a success, so an empty list is [] and never null.
type versionsOutcome struct {
Versions []storage.IssueVersion `json:"versions"`
// Recording reports whether the store is recording versions RIGHT NOW.
// It is independent of whether Versions is empty: a store that recorded
// for a month and was then switched off still has versions, and saying
// otherwise would be a claim about the store made from a fact about this
// invocation's config.
Recording bool `json:"recording"`
}
var versionsCmd = &cobra.Command{
Use: "versions <id>",
GroupID: "views",
Short: "List the recorded versions of a bead",
Long: `List the versions recorded for a bead by versioned history.
Recording is off by default. Turn it on with:
bd config set versioned-history.enabled true
That writes the setting into the store, so every client of that store agrees
about whether a write is recorded, and it is the setting this command reports.
BD_VERSIONED_HISTORY_ENABLED=1 (or a value in config.yaml) also turns recording
on for the writes a process makes, but it says nothing about the store, and
this command only reads, so it does not consult them.
Either source turning it on is enough for a writer; neither can switch the
other off. The consequence worth knowing: once the store setting says on,
BD_VERSIONED_HISTORY_ENABLED=0 will not turn recording off for one run. Turn
it off where it was turned on:
bd config set versioned-history.enabled false
Only beads created while recording is on, or that enter the issues plane
while it is on (a wisp promoted or made persistent), are versioned. A bead
already on the issues plane when recording was turned on is legacy: editing
it records nothing (the write fence, design §16.2b), and nothing is
backfilled.
Turning recording off does not hide what was already recorded — this command
still lists it, and says that recording is currently off.
A caution while the feature is young: keep recording ON for every writer of a
shared store, or leave it off for all of them. A write from a client with
recording off advances nothing, and the next recorded write mints a version
that absorbs that unrecorded change under its own actor — the revisions stay
contiguous and the listing looks gapless when it is not.
Examples:
bd versions bd-123
bd versions bd-123 --json`,
Args: cobra.ExactArgs(1),
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
evt := metrics.NewCommandEvent("versions")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
issueID := args[0]
resolved := false
if full, err := utils.ResolvePartialID(rootCtx, store, issueID); err == nil {
issueID, resolved = full, true
} else if errors.Is(err, utils.ErrAmbiguousID) {
return HandleErrorRespectJSON("%v", err)
}
recording := versionedHistoryEnabled(rootCtx, store)
outcome, err := runVersions(rootCtx, store, issueID, recording, resolved)
switch {
case errors.Is(err, errNoSuchBead):
return HandleErrorRespectJSON(
"no bead %s in this store, and no versions recorded under that id.", issueID)
case errors.Is(err, errVersionedHistoryOff):
return HandleErrorRespectJSON(
"versioned history is not being recorded on this store, and nothing was recorded earlier.\n"+
"Turn it on with: bd config set %s true\n"+
"Only beads created, or brought onto the issues plane (a wisp promoted or made persistent), after that are versioned: beads already on it stay unversioned, and nothing is backfilled.",
versionedHistorySettingKey)
case errors.Is(err, errVersionsUnsupported):
return HandleErrorRespectJSON(
"this storage backend cannot serve version history (proxied, no-db and non-Dolt backends cannot).\n" +
"Run this against a Dolt-backed workspace.")
case err != nil:
return HandleErrorRespectJSON("failed to list versions: %v", err)
}
if jsonOutput {
return outputJSON(outcome)
}
printVersions(issueID, outcome)
return nil
},
}
// runVersions is the testable core. It separates four situations that all
// look like "nothing here" and each need a different response.
//
// It deliberately READS EVEN WHEN RECORDING IS OFF. An earlier version
// refused up front, which meant a store that recorded for a month and was
// then switched off reported "no versions are recorded" -- a claim about the
// store, derived from a fact about this invocation's config. storage
// .VersionLister's own doc already says the two are independent: holding the
// capability says the backend can READ versions and says nothing about
// whether recording is on. (bee-ghosttrack, #6661 review, finding 3.)
//
// resolved reports whether issueID named a bead the store knows. An
// unresolved id with no versions is "no such bead", not "none yet" -- falling
// through on an unresolved id is right, because a deleted bead can still have
// versions, but only until the answer turns out to be empty. (Same review,
// finding 4.)
func runVersions(ctx context.Context, backend any, issueID string, recording, resolved bool) (versionsOutcome, error) {
lister, ok := versionListerFor(backend)
if !ok {
return versionsOutcome{}, errVersionsUnsupported
}
versions, err := lister.ListVersions(ctx, issueID)
if err != nil {
return versionsOutcome{}, err
}
if len(versions) > 0 {
// Something was recorded. Whether recording is on right now changes
// the footnote, never whether these rows are shown.
return versionsOutcome{Versions: versions, Recording: recording}, nil
}
// Nothing to show. Which of the three reasons it is decides the message.
if !resolved {
return versionsOutcome{}, errNoSuchBead
}
if !recording {
return versionsOutcome{}, errVersionedHistoryOff
}
// An empty non-nil list: this is also the --json payload, where nil would
// print null.
return versionsOutcome{Versions: []storage.IssueVersion{}, Recording: true}, nil
}
// versionListerFor finds the VersionLister behind whatever cmd/bd is holding.
//
// The store in cmd/bd is the DECORATED chain (telemetry, externaldeps,
// hooks), and VersionLister is an optional capability rather than a method on
// DoltStorage, so none of those decorators forwards it -- asserting against
// the wrapper reports "unsupported" for a store that can serve versions
// perfectly well. storage.UnwrapStore's own doc names this case: peel before
// asserting optional interfaces.
//
// The direct assertion is tried FIRST so a test double, or any future
// decorator that genuinely implements the capability itself, wins over the
// concrete store underneath -- the same precedence cmd/bd/dolt.go uses.
func versionListerFor(backend any) (storage.VersionLister, bool) {
if lister, ok := backend.(storage.VersionLister); ok {
return lister, true
}
if ds, ok := backend.(storage.DoltStorage); ok {
if lister, ok := storage.UnwrapStore(ds).(storage.VersionLister); ok {
return lister, true
}
}
return nil, false
}
func printVersions(issueID string, outcome versionsOutcome) {
versions := outcome.Versions
if len(versions) == 0 {
// Recording is on (runVersions refuses otherwise) and the bead
// resolved. A bead created, or brought onto the issues plane, while
// recording is on always has its create-shaped version, so an empty
// list means this bead does not participate: it is legacy (on the
// issues plane before recording was on, or put there by a writer that
// was not recording), or it is no-history or a wisp.
// Under design §16.2b's write fence it will not gain versions by
// being edited, so this says why rather than "not yet".
fmt.Printf("\nNo versions recorded for %s.\n", issueID)
fmt.Println(ui.RenderMuted("Only beads created while recording is on, or that enter the issues plane while it is on (a wisp promoted or made persistent), are versioned. This one reached the issues plane before recording was turned on (or through a writer that was not recording), or it is a no-history bead or a wisp, so editing it records nothing. Nothing is backfilled."))
return
}
fmt.Printf("\nVersions of %s (%d)\n\n", issueID, len(versions))
fmt.Printf(" %-5s %-19s %-22s %s\n",
ui.RenderMuted("REV"), ui.RenderMuted("WHEN"), ui.RenderMuted("WHO"), ui.RenderMuted("ATTRIB"))
for _, v := range versions {
if v.Removed() {
// A removed version is a restriction, not a blank row: name which
// restriction applied and when, so it is never mistaken for an
// absence. #5898's four values are distinct answers.
fmt.Printf(" %-5d %s\n", v.Revision,
ui.RenderMuted(fmt.Sprintf("✗ gone · %s%s · %s",
restrictionLabel(v.RemovedRestriction),
reasonSuffix(v.RemovedReason),
v.RemovedAt.Format("2006-01-02 15:04"))))
continue
}
who := v.ChangeActor
if who == "" {
who = ui.RenderMuted("—")
}
fmt.Printf(" %-5d %-19s %-22s %s\n",
v.Revision,
v.ChangeAt.Format("2006-01-02 15:04"),
who,
attributionLabel(v.AttributionStatus))
if v.ChangeMessage != "" {
fmt.Printf(" %s\n", ui.RenderMuted(v.ChangeMessage))
}
}
fmt.Println()
if !outcome.Recording {
// The rows are real; recording is simply off now. Saying nothing here
// would let a stale listing read as current.
fmt.Println(ui.RenderWarn("Recording is currently OFF — this listing ends where it was switched off."))
fmt.Println(ui.RenderMuted(fmt.Sprintf("Turn it back on with: bd config set %s true", versionedHistorySettingKey)))
fmt.Println()
}
fmt.Println(ui.RenderMuted("REV is local to this store and is not a citable address: two clones can"))
fmt.Println(ui.RenderMuted("both hold revision 8 of the same bead. Portable version addresses arrive"))
fmt.Println(ui.RenderMuted("with the version_id change."))
}
// restrictionLabel renders #5898's removal vocabulary. "unknown" is NOT
// "gone": it means this store has no lineage knowledge, which the conformance
// suite pins separately (a never-synced store answers Unknown, not Gone).
//
// A string outside the vocabulary renders as unknown, because that is what the
// as-of read answers for it: the label never prints a stored value the read
// would not give.
func restrictionLabel(r string) string {
switch issueops.NormalizeRemovedRestriction(r) {
case issueops.AsOfRestrictionGoneRetention:
return "outside the retention window"
case issueops.AsOfRestrictionGoneErasure:
return "erased"
case issueops.AsOfRestrictionGoneReorganization:
return "voided by an epoch change"
default:
return "no lineage knowledge in this store"
}
}
func attributionLabel(s string) string {
switch s {
case "claimed":
return "claimed"
case "unknown":
return ui.RenderMuted("unknown")
case "":
return ui.RenderMuted("—")
default:
return s
}
}
func reasonSuffix(reason string) string {
if strings.TrimSpace(reason) == "" {
return ""
}
return " (" + reason + ")"
}
func init() {
rootCmd.AddCommand(versionsCmd)
}

View file

@ -0,0 +1,122 @@
//go:build cgo
package main
import (
"os"
"strings"
"testing"
)
// THE NAME IS LOAD-BEARING: it must keep the TestEmbedded prefix, because
// .github/scripts/embedded-test-shard.sh selects what runs with
// `grep -rh '^func TestEmbedded' cmd/bd/*_embedded_test.go` and validates each
// manifest entry against `^TestEmbedded[A-Za-z0-9_]+$`. As
// TestVersionedHistorySwitchRoundTrip_Embedded this test matched neither, so
// the only job that sets BEADS_TEST_EMBEDDED_DOLT=1 for cmd/bd never selected
// it, and the generic Test jobs run without that env so its own guard skipped
// it there. The one test that can see the two planes disagree therefore ran
// only on the author's machine. Renaming it is the whole fix -- a test absent
// from the manifest still gets a shard from the fallback distribution.
// (bee-ghosttrack, #6661 third review, blocking finding 2.)
//
// TestEmbeddedVersionedHistorySwitchRoundTrip drives the REAL
// `bd config set versioned-history.enabled true` through to a real
// `bd versions`, against a real store.
//
// This exists because the two ends disagreed and no unit test could see it.
// `bd config set` routes a key that is not yaml-only to the workspace
// DATABASE; the readers called config.GetBool, which is viper (yaml + env)
// only. So the command the help text and the off-refusal both named wrote one
// plane while the reader read the other: the user ran exactly what they were
// told, was told it worked, and recording stayed off. A fake-backed unit test
// cannot catch that, because the bug IS the difference between the two real
// planes. (bee-ghosttrack, #6661 review, finding 1: "a test that drives the
// real bd config set -> reader round trip would have caught this and would
// keep it caught.")
//
// The env var is explicitly cleared for the write and read below, so a
// passing run proves the STORE setting alone carried it.
func TestEmbeddedVersionedHistorySwitchRoundTrip(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
// No t.Parallel: t.Setenv below is incompatible with it, and clearing the
// env var is the whole point — a pass has to prove the STORE setting
// carried the switch on its own.
t.Setenv("BD_VERSIONED_HISTORY_ENABLED", "")
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "vsw")
created := bdRunOK(t, bd, dir, "create", "switch round trip")
id := extractFirstID(created, "vsw-")
if id == "" {
t.Fatalf("could not find a vsw- id in create output: %s", created)
}
// Off by default: a bead with no recorded versions must refuse, not
// report an empty history.
if out, code := bdRunFailCode(t, bd, dir, "versions", id); code == 0 {
t.Errorf("bd versions succeeded with recording off and nothing recorded; want a refusal. out=%s", out)
} else if !strings.Contains(out, "bd config set versioned-history.enabled true") {
t.Errorf("the refusal must name the command that actually turns it on; got: %s", out)
}
// The advertised command. If this writes a plane the reader does not
// consult, everything below fails.
bdConfig(t, bd, dir, "set", "versioned-history.enabled", "true")
// A bead that existed before the switch was turned on never participated in
// history (design §16.2b: the write fence skips a legacy record), so writing
// to it versions nothing. That is the fence, pinned at the command level.
legacyID := id
bdRunOK(t, bd, dir, "update", legacyID, "--title", "switch round trip, edited while legacy")
if legacy := bdRunOK(t, bd, dir, "versions", legacyID); !strings.Contains(legacy, "No versions recorded for "+legacyID) {
t.Errorf("a bead created before the switch was turned on gained a version from an ordinary write; the fence must skip it. out=%s", legacy)
}
// The round trip itself is asserted on a bead created AFTER the switch, which
// participates, so its writes are versioned.
created = bdRunOK(t, bd, dir, "create", "switch round trip, created with history on")
id = extractFirstID(created, "vsw-")
if id == "" {
t.Fatalf("could not find a vsw- id in create output: %s", created)
}
bdRunOK(t, bd, dir, "update", id, "--title", "switch round trip, edited")
out := bdRunOK(t, bd, dir, "versions", id)
if !strings.Contains(out, "Versions of "+id) {
t.Fatalf("no versions listed after enabling via bd config set — the write and read planes have diverged again. out=%s", out)
}
if strings.Contains(out, "Recording is currently OFF") {
t.Errorf("recording reported OFF immediately after bd config set enabled it: %s", out)
}
// Turning it back off must not hide what was already recorded: that is a
// claim about the store made from a fact about this invocation's config
// (same review, finding 3).
bdConfig(t, bd, dir, "set", "versioned-history.enabled", "false")
off := bdRunOK(t, bd, dir, "versions", id)
if !strings.Contains(off, "Versions of "+id) {
t.Errorf("recorded versions vanished when recording was switched off; they are still real. out=%s", off)
}
if !strings.Contains(off, "Recording is currently OFF") {
t.Errorf("a listing taken while recording is off must say so, or it reads as current: %s", off)
}
}
// extractFirstID pulls the first whitespace-delimited token carrying prefix
// out of command output.
func extractFirstID(out, prefix string) string {
for _, f := range strings.FieldsFunc(out, func(r rune) bool {
return r == ' ' || r == '\n' || r == '\t' || r == ':' || r == '\r'
}) {
if strings.HasPrefix(f, prefix) {
return strings.TrimRight(f, ".,")
}
}
return ""
}

419
cmd/bd/versions_test.go Normal file
View file

@ -0,0 +1,419 @@
package main
import (
"context"
"encoding/json"
"errors"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/issueops"
)
type fakeVersionLister struct {
storage.DoltStorage
called bool
versions []storage.IssueVersion
}
func (f *fakeVersionLister) ListVersions(_ context.Context, _ string) ([]storage.IssueVersion, error) {
f.called = true
return f.versions, nil
}
type notAVersionLister struct{ storage.DoltStorage }
// settingsVersionLister is a store with both halves `bd versions` reads: a
// settings plane whose row is canned, and a version history that is canned.
// The nil storage.DoltStorage underneath makes anything else the command
// touches panic, so a case cannot pass through a path it did not mean to
// exercise.
type settingsVersionLister struct {
fakeVersionLister
cfg issueops.WorkspaceConfig
}
func (s *settingsVersionLister) WorkspaceConfig() (issueops.WorkspaceConfig, error) {
return s.cfg, nil
}
// TestVersionsOffButRecordedStillLists is finding 3 from bee's #6661 review:
// a store that recorded for a month and was then switched off HAS versions,
// and refusing with "nothing is recorded" states a fact about this
// invocation's config as if it were a fact about the store.
func TestVersionsOffButRecordedStillLists(t *testing.T) {
backend := &fakeVersionLister{versions: []storage.IssueVersion{{Revision: 3}, {Revision: 2}}}
got, err := runVersions(context.Background(), backend, "bd-1", false, true)
if err != nil {
t.Fatalf("runVersions(recording=false, 2 rows) = %v, want the rows", err)
}
if len(got.Versions) != 2 {
t.Fatalf("got %d versions, want 2 — recorded history must survive the switch going off", len(got.Versions))
}
if got.Recording {
t.Error("Recording should be false so the caller can say the listing ends where recording stopped")
}
}
// TestVersionsOffAndEmptyRefusesWithRemedy is the empty arm of the pair above,
// and together they are the whole of finding 3: recording off decides the
// FOOTER, never whether to read. Off with rows recorded lists them; off with
// nothing recorded is the one case that refuses, and it refuses with the
// remedy rather than returning an empty list.
//
// That distinction is what #5898 exists to make. An empty list is a claim
// about the bead ("it has no versions"); the truth here is a claim about the
// store ("it never recorded any"). Returning the former for the latter is the
// wrong-answer-not-an-empty-one failure.
//
// This was TestVersionsRefusesWhenFlagOff, which asserted that the read was
// refused BEFORE the backend was consulted. Finding 3 removed that behaviour
// deliberately, so the assertion went with it -- but the fixture it had been
// asserting against stayed behind, built, unused and ending in `_ = backend`,
// under a name that still promised the old contract. Renamed to what it
// actually pins, and the dead fixture is gone.
// (bee-ghosttrack, #6661 third review, finding 3.)
func TestVersionsOffAndEmptyRefusesWithRemedy(t *testing.T) {
got, err := runVersions(context.Background(), &fakeVersionLister{}, "bd-1", false, true)
if !errors.Is(err, errVersionedHistoryOff) {
t.Fatalf("runVersions(recording=false, empty) error = %v, want errVersionedHistoryOff", err)
}
if len(got.Versions) != 0 {
t.Errorf("returned %d versions, want none", len(got.Versions))
}
}
// TestVersionsUnresolvedIDIsNotAnEmptyBead is finding 4: falling through on an
// unresolved id is right (a deleted bead can still have versions), but only
// until the answer is empty. Then it is "no such bead", not "none yet".
func TestVersionsUnresolvedIDIsNotAnEmptyBead(t *testing.T) {
_, err := runVersions(context.Background(), &fakeVersionLister{}, "nosuch-id", true, false)
if !errors.Is(err, errNoSuchBead) {
t.Fatalf("runVersions(resolved=false, empty) error = %v, want errNoSuchBead", err)
}
}
// TestVersionsRefusesUnsupportedBackend pins that "this backend cannot answer"
// is distinguishable from "there are no versions" -- the third shape of an
// answer, not a smaller success.
func TestVersionsRefusesUnsupportedBackend(t *testing.T) {
_, err := runVersions(context.Background(), &notAVersionLister{}, "bd-1", true, true)
if !errors.Is(err, errVersionsUnsupported) {
t.Fatalf("runVersions(unsupported backend) error = %v, want errVersionsUnsupported", err)
}
if errors.Is(err, errVersionedHistoryOff) {
t.Error("an unsupported backend must not be reported as the feature being off: different fixes")
}
}
// TestVersionsEmptyIsNotAnError pins the other side: a supported, enabled
// store with nothing recorded returns an empty list and no error. That is a
// truthful answer, and the command renders the no-backfill explanation.
func TestVersionsEmptyIsNotAnError(t *testing.T) {
got, err := runVersions(context.Background(), &fakeVersionLister{}, "bd-1", true, true)
if err != nil {
t.Fatalf("runVersions on an empty store = %v, want nil", err)
}
if len(got.Versions) != 0 {
t.Errorf("got %d versions, want 0", len(got.Versions))
}
}
// TestVersionsDecidesRecordingFromTheStoreNotTheProcessEnvironment is the
// reviewer's probe on #6661 (finding 2): BD_VERSIONED_HISTORY_ENABLED=1, the
// store's own setting unset, nothing recorded.
//
// `bd versions` only reads, so the variable cannot make the store record
// anything; it can only make THIS invocation claim that the store does. With
// the environment ORed in, a store that never recorded answered "No versions
// recorded for <id> yet" -- the empty list this command's three outcomes exist
// to prevent, because an empty list is a claim about the bead and the truth is
// a claim about the store. The variable still turns recording on for the writes
// of a process that has it; what this command reports is the store's own
// setting.
//
// The rows that already pass stay in the table on purpose. They are the other
// half of the claim: a store whose setting says on keeps answering "none yet",
// and the variable never switches that off.
func TestVersionsDecidesRecordingFromTheStoreNotTheProcessEnvironment(t *testing.T) {
for _, tt := range []struct {
name string
env string
row string
wantRefusal bool
}{
{"env on, row unset (the reviewer's probe)", "1", "", true},
{"env on, row false", "1", "false", true},
{"env off, row unset", "", "", true},
{"env on, row true", "1", "true", false},
{"env off, row true", "", "true", false},
{"env 0 does not switch off a row that says true", "0", "true", false},
} {
t.Run(tt.name, func(t *testing.T) {
// The variable has to be in place before viper is initialised, and
// viper has to be initialised at all: config.GetBool answers false
// until it is, which would make every env-on row pass whatever the
// code did with the variable.
t.Setenv("BD_VERSIONED_HISTORY_ENABLED", tt.env)
initConfigForTest(t)
st := &settingsVersionLister{cfg: &settingsPlane{value: tt.row}}
recording := versionedHistoryEnabled(context.Background(), st)
got, err := runVersions(context.Background(), st, "bd-1", recording, true)
if tt.wantRefusal {
if !errors.Is(err, errVersionedHistoryOff) {
t.Fatalf("env=%q store row=%q, nothing recorded: runVersions = (%+v, %v), want errVersionedHistoryOff: the process environment must not make a store that never recorded look like one that is recording", tt.env, tt.row, got, err)
}
return
}
if err != nil {
t.Fatalf("env=%q store row=%q, nothing recorded: runVersions error = %v, want an empty listing", tt.env, tt.row, err)
}
if !got.Recording {
t.Errorf("env=%q store row=%q: Recording = false, want true for a store whose own setting says on", tt.env, tt.row)
}
})
}
}
// TestVersionsHelpDoesNotOfferTheEnvironmentAsAReadSwitch is the other half of
// finding 2. The help text told people to run
// `BD_VERSIONED_HISTORY_ENABLED=1 bd versions <id>` "for one run". A read
// records nothing, so that line could only ever make the answer wrong; and
// once the command reports the store's own setting it does not work at all.
func TestVersionsHelpDoesNotOfferTheEnvironmentAsAReadSwitch(t *testing.T) {
if strings.Contains(versionsCmd.Long, "BD_VERSIONED_HISTORY_ENABLED=1 bd versions") {
t.Errorf("bd versions help still suggests BD_VERSIONED_HISTORY_ENABLED=1 bd versions <id>; a read cannot record anything, so the variable cannot make it answer for a store that never recorded.\nhelp:\n%s", versionsCmd.Long)
}
}
// TestVersionListerPeelsDecorators is the regression guard for the bug this
// command shipped with first: cmd/bd holds the DECORATED store, VersionLister
// is an optional capability none of the decorators forwards, and asserting
// against the wrapper reported "unsupported" for a store that could serve
// versions. The capability must be found through the decorator chain.
func TestVersionListerPeelsDecorators(t *testing.T) {
inner := &fakeVersionLister{versions: []storage.IssueVersion{{Revision: 7}}}
decorated := storage.NewHookFiringStore(inner, nil)
lister, ok := versionListerFor(decorated)
if !ok {
t.Fatal("versionListerFor could not see through the decorator chain")
}
got, err := lister.ListVersions(context.Background(), "bd-1")
if err != nil {
t.Fatalf("ListVersions through decorator = %v", err)
}
if len(got) != 1 || got[0].Revision != 7 {
t.Errorf("got %+v, want the inner store's revision 7", got)
}
}
// TestRestrictionLabelsAreDistinct pins that the four removal reasons render
// as four different sentences. Collapsing them into one "gone" would erase
// the distinction R10 requires, and in particular "unknown" (this store has
// no lineage knowledge) is NOT "gone" -- the conformance suite pins that a
// never-synced store answers Unknown rather than Gone.
func TestRestrictionLabelsAreDistinct(t *testing.T) {
seen := map[string]string{}
for _, r := range []string{"gone_retention", "gone_erasure", "gone_reorganization", "unknown"} {
label := restrictionLabel(r)
if label == "" {
t.Errorf("restrictionLabel(%q) is empty", r)
}
if prev, dup := seen[label]; dup {
t.Errorf("restrictionLabel(%q) and (%q) both render %q; they are different answers", r, prev, label)
}
seen[label] = r
}
if restrictionLabel("unknown") == restrictionLabel("gone_erasure") {
t.Error("unknown must not read as gone: no lineage knowledge is not erasure")
}
}
// TestRestrictionLabelAnswersAnythingOutsideTheVocabularyAsUnknown is finding 3 of the
// #6661 review, on the label's side. The as-of read answers a stored restriction outside
// the four-value vocabulary as unknown, and so is "live", which is never stored; the
// label printed such a string raw, so a listing could show "quarantined" for a version
// the as-of read calls unknown. It renders as unknown does.
func TestRestrictionLabelAnswersAnythingOutsideTheVocabularyAsUnknown(t *testing.T) {
want := restrictionLabel("unknown")
for _, r := range []string{"", "live", "gone-retention", "quarantined"} {
if got := restrictionLabel(r); got != want {
t.Errorf("restrictionLabel(%q) = %q, want %q (what unknown renders as): a value outside the vocabulary is not an answer", r, got, want)
}
}
}
// TestVersionsJSONDoesNotCollideWithIssueRevision pins that the versions
// payload does not emit a "revision" key.
//
// types.Issue already ships `json:"revision"` and it is the row-lock CAS
// token -- an unrelated value, and a STRING where this one is a number. One
// key carrying two meanings, in the place machines read, is the `bd version`
// collision again with worse consequences: a script that learned one shape
// gets the other and cannot tell. Raised by bee-ghosttrack's consumer read on
// #5898, who reported a couple of hundred script files parsing bd --json.
func TestVersionsJSONDoesNotCollideWithIssueRevision(t *testing.T) {
blob, err := json.Marshal(storage.IssueVersion{Revision: 7, IssueID: "bd-1"})
if err != nil {
t.Fatalf("marshal: %v", err)
}
var generic map[string]any
if err := json.Unmarshal(blob, &generic); err != nil {
t.Fatalf("unmarshal: %v", err)
}
if _, collides := generic["revision"]; collides {
t.Errorf(`IssueVersion emits a "revision" key; types.Issue already uses that key for the row-lock token. Got: %s`, blob)
}
got, ok := generic["local_revision"]
if !ok {
t.Fatalf(`IssueVersion has no "local_revision" key. Got: %s`, blob)
}
if n, isNum := got.(float64); !isNum || n != 7 {
t.Errorf("local_revision = %v, want 7", got)
}
}
// TestVersionsJSONDoesNotPublishChangeAgent pins that the versions payload
// carries no "change_agent" key, while change_actor and change_message stay.
//
// Provenance V2 (gastownhall/beads#7510) replaces the ad hoc agent field with
// an actor chain, so a "change_agent" key in `bd versions --json` would become
// a public contract for a field that is on its way out. The column (migration
// 0067) and IssueVersion.ChangeAgent are kept; only the JSON key is withheld.
// The value is set here so an omitempty-style regression, which would hide it
// only when empty, still fails.
func TestVersionsJSONDoesNotPublishChangeAgent(t *testing.T) {
blob, err := json.Marshal(storage.IssueVersion{
IssueID: "bd-1",
Revision: 3,
ChangeActor: "alice",
ChangeAgent: "some-agent",
ChangeMessage: "why it changed",
})
if err != nil {
t.Fatalf("marshal: %v", err)
}
var generic map[string]any
if err := json.Unmarshal(blob, &generic); err != nil {
t.Fatalf("unmarshal: %v", err)
}
if _, published := generic["change_agent"]; published {
t.Errorf(`IssueVersion emits a "change_agent" key; Provenance V2 replaces that field, so it must not become part of bd versions --json. Got: %s`, blob)
}
if got := generic["change_actor"]; got != "alice" {
t.Errorf(`change_actor = %v, want "alice". Got: %s`, got, blob)
}
if got := generic["change_message"]; got != "why it changed" {
t.Errorf(`change_message = %v, want "why it changed". Got: %s`, got, blob)
}
}
// TestVersionsJSONIsOneObjectWhetherOrNotAnythingWasRecorded is finding 4:
// `bd versions <id> --json` printed `null` for a store with nothing recorded
// yet (a nil slice through outputJSON) and never said whether recording was on,
// so a JSON consumer could tell neither "empty" from "no such list" nor a
// listing that ends where recording was switched off from one that is current.
//
// The shape is one object for every answer that is not an error:
// {"versions": [...], "recording": bool}, with [] for the empty list, never
// null. It goes through outputJSON, the way the command does, so the check sees
// what a script sees.
func TestVersionsJSONIsOneObjectWhetherOrNotAnythingWasRecorded(t *testing.T) {
t.Setenv("BD_JSON_ENVELOPE", "")
rows := []storage.IssueVersion{{Revision: 2, IssueID: "bd-1"}, {Revision: 1, IssueID: "bd-1"}}
for _, tt := range []struct {
name string
backend *fakeVersionLister
recording bool
wantVersions int
}{
{"nothing recorded yet", &fakeVersionLister{}, true, 0},
{"recorded, recording on", &fakeVersionLister{versions: rows}, true, 2},
{"recorded, recording since switched off", &fakeVersionLister{versions: rows}, false, 2},
} {
t.Run(tt.name, func(t *testing.T) {
got, err := runVersions(context.Background(), tt.backend, "bd-1", tt.recording, true)
if err != nil {
t.Fatalf("runVersions: %v", err)
}
out := captureStdout(t, func() error { return outputJSON(got) })
var payload map[string]json.RawMessage
if err := json.Unmarshal([]byte(out), &payload); err != nil {
t.Fatalf("--json output is not one JSON object: %v\n%s", err, out)
}
rawVersions, ok := payload["versions"]
if !ok {
t.Fatalf(`--json output has no "versions" key. Got: %s`, out)
}
var list []json.RawMessage
if err := json.Unmarshal(rawVersions, &list); err != nil {
t.Fatalf(`"versions" is not an array: %v. Got: %s`, err, out)
}
if list == nil {
t.Errorf(`"versions" is null, want [] for an empty list. Got: %s`, out)
}
if len(list) != tt.wantVersions {
t.Errorf(`"versions" has %d entries, want %d. Got: %s`, len(list), tt.wantVersions, out)
}
rawRecording, ok := payload["recording"]
if !ok {
t.Fatalf(`--json output has no "recording" key. Got: %s`, out)
}
var recording bool
if err := json.Unmarshal(rawRecording, &recording); err != nil {
t.Fatalf(`"recording" is not a boolean: %v. Got: %s`, err, out)
}
if recording != tt.recording {
t.Errorf(`"recording" = %v, want %v. Got: %s`, recording, tt.recording, out)
}
})
}
}
// TestVersionWithAnArgumentPointsAtVersions pins the guard on `bd version`.
//
// `bd version` prints bd's own build and `bd versions <id>` lists a bead's
// recorded versions: one character apart, unrelated meanings. Before the guard,
// a mistyped `bd version <id>` silently printed the build and exited 0, which
// reads as "this bead has no versions". It now exits 1 and names the command
// that was probably meant (#6661 review, finding 8). The guard is deliberate,
// and it is a change from the exit 0 it replaced, so both halves are pinned:
// the exit code and the hint, for the argument the user typed.
//
// The hint is matched as two fragments rather than one string so that spacing
// inside the message can change without losing the pin.
func TestVersionWithAnArgumentPointsAtVersions(t *testing.T) {
pinJSONOutput(t, false)
var err error
stderr := captureStderr(t, func() {
err = versionCmd.RunE(versionCmd, []string{"bd-123"})
})
code, isExitError := exitCodeFromError(err)
if !isExitError || code != 1 {
t.Fatalf("bd version bd-123 returned %v (exit error: %v, code: %d), want an exit error with code 1", err, isExitError, code)
}
for _, want := range []string{"Did you mean", "bd versions bd-123"} {
if !strings.Contains(stderr, want) {
t.Errorf("bd version bd-123 stderr is missing %q. Got: %q", want, stderr)
}
}
}

View file

@ -292,7 +292,7 @@ export BEADS_ACTOR="my-github-handle"
## Project-Level Settings (Database)
These are written to the Dolt database by `bd config set` and have no env var override. Common namespaces:
These are written to the Dolt database by `bd config set` and have no env var override, with one exception: `versioned-history.enabled` also honors `BD_VERSIONED_HISTORY_ENABLED` (see [Versioned Issue History](#versioned-issue-history)). Common namespaces:
| Namespace | Purpose |
|---|---|
@ -312,6 +312,7 @@ These are written to the Dolt database by `bd config set` and have no env var ov
| `min_hash_length`, `max_hash_length` | Adaptive ID bounds (defaults `3` and `8`) |
| `max_collision_prob` | Hash ID collision tolerance (default `0.25`) |
| `claim.pools` | Comma-separated pool aliases: placeholder assignees that any actor can take with `bd update <id> --claim` (see [below](#claim-pools)). Unset by default, which turns pool claiming off |
| `versioned-history.enabled` | `true` records a version row for every issue write to this store; off by default. Unlike the rest of this table it also honors an environment variable, which can only turn it on (see [below](#versioned-issue-history)) |
| `doctor.suppress.*` | Suppress specific `bd doctor` warnings by check slug (warnings only; errors always show) |
Issue prefix (`issue_prefix`) is **not** settable via `bd config set` — use `bd init --prefix`, `bd bootstrap`, or `bd rename-prefix`.
@ -402,6 +403,25 @@ Claiming reads this key from the database only. A `claim.pools` value in `config
- **`bd ready --claim`** takes only unassigned issues, so it skips pool-assigned ones even though `bd ready` lists them. Claim those by ID.
- **Lease expiry.** If the claimer's lease expires, `bd reclaim` sets the issue back to `open` with no assignee. It does not return the issue to the pool alias, so a dispatcher that wants it back in the pool has to reassign it.
### Versioned Issue History
While `versioned-history.enabled` is on, every accepted change to an issue that participates in history (one created while it is on, or that enters the issues plane while it is on: a wisp promoted or made persistent) stores a snapshot of it as a row of `issue_versions`, in the same transaction, and `bd versions <id>` lists them. It is off by default, and it does not backfill: an issue already on the issues plane when it was turned on is legacy, and editing it records nothing (the write fence, design §16.2b).
```bash
bd config set versioned-history.enabled true # turn it on
bd config set versioned-history.enabled false # turn it off
```
- **The switch belongs to the store.** It is a row of the database `config` table, so `bd config set` writes it there and not to `config.yaml`. Every store answers for itself: a write routed into another workspace (a prefix-routed `bd update` or `bd close`, or `bd create --repo`) reads the *target* store's row, never the row of the workspace you launched `bd` from.
- **It replicates.** The config table travels with `bd dolt push` and `bd dolt pull`, so enabling it on one clone turns it on for every clone that pulls.
- **Single writer only.** Keep one writer at a time per store, and never two disconnected clones recording. Two writers that each mint the same revision for an issue collide on merge, and the pull fails (`VersionedHistoryConfigurer` in `internal/storage/storage.go`, and [#6379](https://github.com/gastownhall/beads/issues/6379) item 4). Because the setting replicates, turning it on is a decision for the whole store, not for one clone.
- **Turning it on checks the store first.** `bd config set versioned-history.enabled true` reads every issue the store would version and refuses, writing nothing, while any holds a value a version could not record: a number outside the I-JSON exact-integer range (magnitude above 2^53-1, whatever its spelling, fractions and exponent forms included), in its metadata or in a gate's timeout. A timeout is held as nanoseconds, so a gate that waits longer than about 104.25 days (9007199254740991 ns) is refused. It prints how many issues, which ones (the first 20), what is wrong with each and which field it is in. With history on, a write that introduces such a value already fails at once and commits nothing, and so does a later write to a row that already holds one if that row participates in history (it was created, or entered the issues plane, while history was on); a legacy row, created before history was on, is skipped by the write fence and stays writable, but the check still names it, because it cannot see participation. The fix depends on the field. For a number in metadata, one command per issue, and it works with history on or off: `bd update <id> --metadata '{"<key>": "<value as a string>"}'` to replace the value, or `bd update <id> --unset-metadata <key>` to remove the key. `bd update` cannot change a gate's timeout, so while history is off, remove the gate with `bd delete <id> --force` (without `--force`, `bd delete` only previews, and removing the gate also unblocks anything it was blocking), or set the `timeout_ns` column of the `issues` table within the limit with `bd sql`, which needs a server-backed store and does not run on an embedded one. Then run the command again. **There is no override**: the check has no flag, and `bd config set versioned-history.enabled false` never runs it.
- **What that check does not cover.** It runs once, at the moment you turn the setting on. A writer that does not record versions (an older `bd`, `bd sql`, a pull from a clone that had history off) can add such a row at any time afterwards, including right after the switch is on, and, if that row participates in history, the first write to it then fails with the same refusal; the same fix applies. Checking and writing the setting in one transaction would narrow that window, not close it. Turning recording on through `BD_VERSIONED_HISTORY_ENABLED` or `config.yaml` does not go through the command at all, so nothing is checked ahead of time there; a write to such a row is refused when it happens. Duplicate keys in metadata are refused too, but Dolt's JSON column collapses them when it stores a document, so on a Dolt store neither the check nor a write can see one; that refusal is a defense for another backend that keeps them.
- **The environment can turn it on, never off.** `BD_VERSIONED_HISTORY_ENABLED=1`, or a hand-written `enabled: true` under `versioned-history:` in `config.yaml`, applies to every store the process opens, routed targets included. The environment and the row are OR'd, not ranked, so `BD_VERSIONED_HISTORY_ENABLED=0` does not turn off a store whose row says `true`. Turn it off where it was turned on: `bd config set versioned-history.enabled false`.
- **Server-backed modes read the same row.** Proxied-server mode, and `bd serve` against a server-mode workspace, write through a unit-of-work provider rather than a store. The provider reads the row from its own database when it is constructed, through a short read-only transaction that is rolled back, so `bd config set versioned-history.enabled true` covers those modes too. It does not fall back to the environment alone.
- **The Go SDK is not covered.** Writers built on the Go SDK (the `beads` package: `Open`, `OpenFromConfig`, `OpenGated`, `OpenBestAvailable`) do not apply the switch: a write they make to a store whose row says `true` records no version. The `bd` binary's store factories apply it, and the events journal's switch has the same boundary. Opening a store through the SDK and applying both switches is a separate change.
- **The value is read when a store is opened.** A long-lived process such as `bd serve` keeps the value it read at start until it is restarted, so after changing the setting, restart it.
## Sync and Federation
Beads syncs exclusively through Dolt remotes (`bd dolt push` / `bd dolt pull`) with cell-level merge. Use `bd export` for issue portability and `bd backup` for restorable database backups.
@ -498,6 +518,7 @@ Selected commonly-used variables:
| `BD_DOLT_AUTO_COMMIT` | Override `dolt.auto-commit` (`on`/`off`) |
| `BD_DOLT_AUTO_PUSH`, `BD_DOLT_AUTO_PUSH_INTERVAL`, `BD_DOLT_AUTO_PUSH_TIMEOUT` | Override auto-push settings |
| `BD_BACKUP_ENABLED`, `BD_BACKUP_INTERVAL`, `BD_BACKUP_GIT_REPO` | Override backup settings |
| `BD_VERSIONED_HISTORY_ENABLED` | Turn on `versioned-history.enabled` for every store the process opens. `1` turns recording on; `0` does not turn it off for a store whose row says `true` (see [Versioned Issue History](#versioned-issue-history)) |
| `BD_AGENT_PROFILE` | Override `agent.profile` |
| `BD_AI_MODEL` | Override AI model |
| `BD_FEDERATION_REMOTE`, `BD_FEDERATION_SOVEREIGNTY` | Override federation settings |

View file

@ -263,6 +263,18 @@ func Initialize() error {
// own deletion itself. Env: BD_EVENTS_JOURNAL_AUTO_PRUNE.
v.SetDefault("events-journal-auto-prune", true)
v.SetDefault("audit.enabled", false)
// versioned-history.enabled activates the dual-write issue-version history
// (issue_versions, issues.current_revision) that migrations 0067+ provision.
// Default OFF: with it off the writer short-circuits and a store is
// byte-identical to one built without the feature, which is the contract
// gastownhall/beads#6135 ships under. Env: BD_VERSIONED_HISTORY_ENABLED.
//
// The flag is single-writer-only until the version_id primary key lands
// (design section 16.3 steps 1-5): issue_versions.revision and
// issues.current_revision are per-store ordinals, so two disconnected
// clones can both mint revision 8 for the same issue. Do not enable it on
// a store that more than one writer mutates.
v.SetDefault("versioned-history.enabled", false)
v.SetDefault("no-db", false)
v.SetDefault("no-hooks", false)
v.SetDefault("db", "")

View file

@ -178,6 +178,9 @@ func TestServedParticipationGenerationFence(t *testing.T) {
t.Run("ProceedsForPromotedRecord", func(t *testing.T) {
conformance.RunParticipationGenerationProceedsForPromotedRecord(t, ctx, fixture)
})
t.Run("FlagOffSkipsUpdateOnParticipatingRecord", func(t *testing.T) {
conformance.RunParticipationGenerationFlagOffSkipsUpdateOnParticipatingRecord(t, ctx, fixture)
})
t.Run("FenceIgnoresSchemaSkewHatch", func(t *testing.T) {
conformance.RunParticipationGenerationFenceIgnoresSchemaSkewHatch(t, ctx, fixture)
})

View file

@ -65,6 +65,7 @@ go_library(
"storage.go",
"sync.go",
"version_control.go",
"version_lister.go",
"versioned.go",
"wake_defers.go",
],

View file

@ -92,7 +92,7 @@ func largeScenarios() []scenario {
// recorded from the code BEFORE the batch-create fast paths existed
// (ebe3b6bcb), so the check holds the current code — fast and per-row
// bodies alike, including changes the fast-path switch does not gate — to
// what that code stored, apart from two deliberate behavior changes since.
// what that code stored, apart from three deliberate behavior changes since.
//
// First, the create role defaults an empty created_by to the request's actor
// (issueops.PreparePublicCreateRequest), so apply.json's issues, wisps and
@ -107,6 +107,17 @@ func largeScenarios() []scenario {
// their seeded rows instead (stampParticipation), so their dependency adds,
// closes and reopens mint as they did before the fence, and their digests
// did not move.
//
// Third, the issues_updated_at digests of small, depadd, import458 and
// import458-reject-stale were re-recorded when the update-shaped version
// mint stopped moving updated_at. Its UPDATE of current_revision used to
// fire the column's ON UPDATE CURRENT_TIMESTAMP, so a row minted a second
// time read the wall clock and dropped out of the compared set. Such a row
// now keeps the timestamp it has with versioned history off: the seeded one
// for depadd's eq-db1 and eq-dl, whose dependency adds mint again, and the
// import source's for the in-batch duplicates eq-n2 (small) and eq-b3 and
// eq-b250 (both import458 scenarios). apply and waitsfor did not move: their
// re-minted rows take the wall clock from their other writes anyway.
const GoldenDirEnv = "CREATEBATCHEQUIV_GOLDEN_DIR"
// Run seeds fresh databases, applies each scenario's batch through the fast

View file

@ -33,8 +33,8 @@
"sha256": "27fb5cdc6779efe18023610f468f30f7f3c21c9b47fe2b2660b280ed132785d1"
},
"issues_updated_at": {
"rows": 13,
"sha256": "7119d0e3827b68a653156835b19fbae4b2b497aa17743ca2abce9ce387870831"
"rows": 15,
"sha256": "bf6295c3ca28217417b2e545df8d756b756f3cea3eb3d0284dadb97b7c8c5377"
},
"labels": {
"rows": 0,

View file

@ -33,8 +33,8 @@
"sha256": "039484a3e75d7cb2f0939177e2504fa514602d33a40112092978db6b2de7316d"
},
"issues_updated_at": {
"rows": 400,
"sha256": "7b83c4335f54068965727a7230e71ad966f75fe6d23170963a142ab1654768cc"
"rows": 402,
"sha256": "80b591ea31a9821b44f006c8dca6d5390923b1e6d55689e0d776fecbb7cdf44b"
},
"labels": {
"rows": 1165,

View file

@ -33,8 +33,8 @@
"sha256": "d4245c8b62b007795d9c7f293f30ac0f341ffc541cf50aa319a24c8cbed3505a"
},
"issues_updated_at": {
"rows": 401,
"sha256": "a256b57e6a67ca0717d1200b4ad867abc1ccff8f9b088bc6c331c18fa6915c7f"
"rows": 403,
"sha256": "de6dbabb1bdd928fe633356cf3199f6124f440168c9ef9d56d76eea9fff0df02"
},
"labels": {
"rows": 1166,

View file

@ -33,8 +33,8 @@
"sha256": "742c88693fbef407c0648e75ccd42618cb7722ffc6b62546b6a04d3b8dc28254"
},
"issues_updated_at": {
"rows": 41,
"sha256": "2b1590dbb503fb2a1dcc71f78261f593f3c9144c4530c80325428b21d5e2164d"
"rows": 42,
"sha256": "ea303585edc660d2e4ea6e982668fefe4f85efa8b43a6e3d8bcb65850a08b856"
},
"labels": {
"rows": 65,

View file

@ -289,6 +289,7 @@ go_test(
"merge_strategy_test.go",
"metadata_cas_contract_test.go",
"metadata_merge_test.go",
"metadata_number_fidelity_test.go",
"metadata_schema_test.go",
"metadata_validation_test.go",
"migration_0052_test.go",
@ -372,6 +373,7 @@ go_test(
"version_reconciler_contract_test.go",
"version_scope_completeness_test.go",
"version_staging_completeness_test.go",
"versioned_read_contract_test.go",
"versioned_test.go",
"wisp_custom_type_tx_test.go",
"wisp_delete_cascade_integration_test.go",

View file

@ -35,6 +35,9 @@ func TestParticipationGenerationFence(t *testing.T) {
t.Run("ProceedsForPromotedRecord", func(t *testing.T) {
conformance.RunParticipationGenerationProceedsForPromotedRecord(t, ctx, fixture)
})
t.Run("FlagOffSkipsUpdateOnParticipatingRecord", func(t *testing.T) {
conformance.RunParticipationGenerationFlagOffSkipsUpdateOnParticipatingRecord(t, ctx, fixture)
})
t.Run("WispPromotionBeginsHistory", func(t *testing.T) {
conformance.RunParticipationGenerationWispPromotionBeginsHistory(t, ctx, fixture)
})

View file

@ -0,0 +1,272 @@
package dolt
import (
"bytes"
"database/sql"
"encoding/json"
"errors"
"fmt"
"math/big"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
)
// metadataNumberCorpus is what TestVersionedHistoryKeepsNumbersTheStoreDistinguishesApart writes
// through the store. It groups literals that share one nearest binary64 (0.1 and its longer
// spellings, 1 and its spellings, pi at several precisions), because those are the literals a
// store could tell apart and RFC 8785 cannot, and it includes the values outside the I-JSON
// exact-integer range that the mint has to refuse. The embedded leg carries the same list in
// embeddeddolt/metadata_number_fidelity_test.go; keep the two in step.
var metadataNumberCorpus = []string{
"0.1", "0.10000000000000000555", "0.1000000000000000055511151231257827",
"1", "1.0", "1.00", "1e0", "10e-1",
"3.14159265358979323846", "3.141592653589793", "3.1415926535897932",
"0.3", "0.30000000000000004",
"0", "-0", "0.0", "1e-400",
"9007199254740991",
"9007199254740992", "9007199254740993", "9007199254740993.5", "9007199254740994",
"1727000000000000000", "1727000000000000123",
"1e300", "123456789012345678901234567890",
}
// metadataNumbersOutsideTheRange are the corpus literals no store normalization can bring back
// inside 2^53-1: each is refused at the mint, and the write it belonged to must not survive.
var metadataNumbersOutsideTheRange = map[string]bool{
"9007199254740992": true, "9007199254740993": true, "9007199254740993.5": true, "9007199254740994": true,
"1727000000000000000": true, "1727000000000000123": true,
"1e300": true, "123456789012345678901234567890": true,
}
// TestVersionedHistoryKeepsNumbersTheStoreDistinguishesApart pins the safety property the
// number-admission rule rests on, against the real store rather than against what one version
// of it is known to do.
//
// RFC 8785 turns every number into its nearest double, so two literals that differ by less than
// a double can share one canonical form. That is harmless only while the store cannot hold them
// apart: if it stores both as the same value they are the same state. The rule was argued from a
// measurement of one Dolt. A Dolt that started keeping exact decimals would silently reopen the
// collision, so this asserts the property instead of the measurement, in four phases:
//
// 1. History OFF. The store accepts every literal, including the ones outside the I-JSON range,
// and the table logs what it actually holds for each. This is how a row comes to hold such a
// number without the mint ever having seen it.
// 2. History ON, two kinds of row. (a) The rows phase 1 made never participated in history
// (participation_generation is NULL), so design §16.2b's write fence skips an update-shaped
// write to them whole, before the mint's admission gate: the write succeeds, mints nothing
// and leaves the stamp NULL. (b) A row that DOES participate (created with history on, so
// stamped) and then comes to hold such a number by a write that does not mint is refused on
// its next write, and the write changes nothing. This is the hazard the switch's pre-enable
// check exists for.
// 3. History ON, fresh rows. Each literal is written and read back, and no two literals that
// read back as DIFFERENT numbers may have been both admitted with the SAME canonical form.
// A literal the mint refuses must leave neither an issue row nor a version row, because the
// mint runs in the writer's own transaction.
//
// The logged table (written, held or read back, canonical or refused, with the Dolt version) is
// the record of what this Dolt does today.
func TestVersionedHistoryKeepsNumbersTheStoreDistinguishesApart(t *testing.T) {
store, storeCleanup := setupTestStore(t)
defer storeCleanup()
ctx, cancel := testContext(t)
defer cancel()
configurer, ok := any(store).(storage.VersionedHistoryConfigurer)
if !ok {
t.Fatalf("%T does not implement storage.VersionedHistoryConfigurer", store)
}
defer configurer.SetVersionedHistoryEnabled(false)
var doltVersion string
if err := store.db.QueryRowContext(ctx, `SELECT dolt_version()`).Scan(&doltVersion); err != nil {
doltVersion = "unknown (" + err.Error() + ")"
}
newIssue := func(id, lit string) *types.Issue {
return &types.Issue{
ID: id, Title: "n " + lit, IssueType: types.TypeTask, Status: types.StatusOpen,
Metadata: json.RawMessage(`{"n":` + lit + `}`),
}
}
// Phase 1: history off. What does the store hold for a number outside the range?
t.Logf("metadata number normalization, server leg, dolt %s", doltVersion)
configurer.SetVersionedHistoryEnabled(false)
var held, heldLiterals []string
for i, lit := range metadataNumberCorpus {
if !metadataNumbersOutsideTheRange[lit] {
continue
}
id := fmt.Sprintf("nfoff-%02d", i)
if err := store.CreateIssue(ctx, newIssue(id, lit), "actor"); err != nil {
t.Logf(" history off: %-34s the store refused it: %v", lit, err)
continue
}
issue, err := store.GetIssue(ctx, id)
if err != nil {
t.Fatalf("reading %s back: %v", id, err)
}
stored, _ := storedNumberAndCanonicalMetadata(t, issue.Metadata, nil)
t.Logf(" history off: %-34s held as %s", lit, stored)
held = append(held, id)
heldLiterals = append(heldLiterals, lit)
}
rowState := func(id string) (versions int, revision int64, generation sql.NullInt64) {
t.Helper()
if err := store.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?`, id).Scan(&versions); err != nil {
t.Fatalf("counting the version rows of %s: %v", id, err)
}
if err := store.db.QueryRowContext(ctx, `SELECT current_revision, participation_generation FROM issues WHERE id = ?`, id).Scan(&revision, &generation); err != nil {
t.Fatalf("reading the revision and participation of %s: %v", id, err)
}
return versions, revision, generation
}
// Phase 2a: history on, rows that never participated. Each was made with history off, so it is
// a legacy record (participation_generation NULL) and design §16.2b's write fence skips an
// update-shaped write to it whole, before the mint's admission gate: the write succeeds,
// nothing is versioned, nothing is refused and the stamp stays NULL, whatever the metadata holds.
configurer.SetVersionedHistoryEnabled(true)
for _, id := range held {
_, revisionBefore, _ := rowState(id)
if err := store.UpdateIssue(ctx, id, map[string]any{"title": "retitled"}, "actor"); err != nil {
t.Errorf("updating %s, a legacy row that holds a number outside the I-JSON range, = %v, want success: the fence skips a legacy record before the mint's admission gate", id, err)
continue
}
after, err := store.GetIssue(ctx, id)
if err != nil || after.Title != "retitled" {
t.Errorf("the update of legacy row %s did not land: title %q (err %v), want %q", id, after.Title, err, "retitled")
}
versions, revision, generation := rowState(id)
if versions != 0 || generation.Valid || revision != revisionBefore {
t.Errorf("the update of legacy row %s versioned or promoted it: version rows %d (want 0), participation_generation %v (want NULL), current_revision %d -> %d (want unchanged)",
id, versions, generation, revisionBefore, revision)
}
}
// Phase 2b: history on, rows that participate. Each is created with history on holding an
// in-range stand-in, so the real create-shaped mint stamps it; the stamp is read first, because
// that is what makes this case about participation. History is then switched off and the row's
// metadata replaced through the store, which is how a row comes to hold such a number without the
// mint having seen it, and switched on again. The next write is refused and changes nothing.
for k, lit := range heldLiterals {
id := fmt.Sprintf("nfpart-%02d", k)
configurer.SetVersionedHistoryEnabled(true)
if err := store.CreateIssue(ctx, newIssue(id, "1"), "actor"); err != nil {
t.Fatalf("creating the participating row %s with history on: %v", id, err)
}
if _, _, generation := rowState(id); !generation.Valid {
t.Fatalf("%s was created with history on but participation_generation is NULL: the control failed, so this case would not be about participation", id)
}
configurer.SetVersionedHistoryEnabled(false)
if err := store.UpdateIssue(ctx, id, map[string]any{"metadata": json.RawMessage(`{"n":` + lit + `}`)}, "actor"); err != nil {
t.Fatalf("replacing the metadata of %s with %s while history is off: %v", id, lit, err)
}
configurer.SetVersionedHistoryEnabled(true)
before, err := store.GetIssue(ctx, id)
if err != nil {
t.Fatalf("reading %s: %v", id, err)
}
versionsBefore, revisionBefore, generationBefore := rowState(id)
err = store.UpdateIssue(ctx, id, map[string]any{"title": "retitled"}, "actor")
if !errors.Is(err, issueops.ErrIntegerNotRepresentable) {
t.Errorf("updating %s, a participating row that holds %s, = %v, want ErrIntegerNotRepresentable", id, lit, err)
}
after, getErr := store.GetIssue(ctx, id)
versions, revision, generation := rowState(id)
if getErr != nil || after.Title != before.Title || versions != versionsBefore || revision != revisionBefore || generation != generationBefore {
t.Errorf("the refused update of %s left a trace: title %q -> %q, version rows %d -> %d, current_revision %d -> %d, participation_generation %v -> %v (err %v)",
id, before.Title, after.Title, versionsBefore, versions, revisionBefore, revision, generationBefore, generation, getErr)
}
}
// Phase 3: history on, fresh rows. The property.
configurer.SetVersionedHistoryEnabled(true)
type admittedLiteral struct{ written, storedAs, canonical string }
var admitted []admittedLiteral
for i, lit := range metadataNumberCorpus {
id := fmt.Sprintf("nfid-%02d", i)
err := store.CreateIssue(ctx, newIssue(id, lit), "actor")
if err != nil {
if !metadataNumbersOutsideTheRange[lit] {
t.Errorf("%s was refused although it is an ordinary number: %v", lit, err)
} else if !errors.Is(err, issueops.ErrIntegerNotRepresentable) {
t.Errorf("%s was refused with %v, want ErrIntegerNotRepresentable", lit, err)
}
if _, getErr := store.GetIssue(ctx, id); !errors.Is(getErr, storage.ErrNotFound) {
t.Errorf("%s was refused but its issue exists afterwards (GetIssue = %v): the refusal did not abort the write", lit, getErr)
}
var versions int
if scanErr := store.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?`, id).Scan(&versions); scanErr != nil || versions != 0 {
t.Errorf("%s was refused but left %d version rows (err %v)", lit, versions, scanErr)
}
t.Logf(" history on: %-34s refused", lit)
continue
}
if metadataNumbersOutsideTheRange[lit] {
t.Errorf("%s is outside the I-JSON exact-integer range and was written", lit)
}
issue, err := store.GetIssue(ctx, id)
if err != nil {
t.Fatalf("reading %s back: %v", id, err)
}
var durable []byte
if err := store.db.QueryRowContext(ctx,
`SELECT durable_state FROM issue_versions WHERE issue_id = ? ORDER BY revision DESC LIMIT 1`, id).Scan(&durable); err != nil {
t.Fatalf("reading the version of %s: %v", id, err)
}
stored, canonical := storedNumberAndCanonicalMetadata(t, issue.Metadata, durable)
t.Logf(" history on: %-34s read back as %-28s canonical metadata %s", lit, stored, canonical)
admitted = append(admitted, admittedLiteral{lit, stored, canonical})
}
if len(admitted) < 12 {
t.Fatalf("only %d of %d literals were admitted; the property is close to vacuous", len(admitted), len(metadataNumberCorpus))
}
first := map[string]admittedLiteral{}
for _, a := range admitted {
prior, seen := first[a.canonical]
if !seen {
first[a.canonical] = a
continue
}
if !sameNumber(prior.storedAs, a.storedAs) {
t.Errorf("literals %s and %s read back from the store as different numbers (%s and %s) but share the canonical form %s: "+
"two distinct stored states would carry one content token", prior.written, a.written, prior.storedAs, a.storedAs, a.canonical)
}
}
}
// storedNumberAndCanonicalMetadata returns the number the store handed back in the issue's
// metadata, and, when durable is given, the metadata member of the canonical bytes the mint
// stored for it.
func storedNumberAndCanonicalMetadata(t *testing.T, readBack json.RawMessage, durable []byte) (stored, canonical string) {
t.Helper()
var back struct {
N json.Number `json:"n"`
}
dec := json.NewDecoder(bytes.NewReader(readBack))
dec.UseNumber()
if err := dec.Decode(&back); err != nil {
t.Fatalf("decoding the metadata read back %s: %v", readBack, err)
}
if durable == nil {
return back.N.String(), ""
}
var version struct {
Metadata json.RawMessage `json:"metadata"`
}
if err := json.Unmarshal(durable, &version); err != nil {
t.Fatalf("decoding durable_state %s: %v", durable, err)
}
return back.N.String(), strings.TrimSpace(string(version.Metadata))
}
// sameNumber reports whether two JSON number literals denote the same value, compared exactly.
func sameNumber(a, b string) bool {
x, okA := new(big.Rat).SetString(a)
y, okB := new(big.Rat).SetString(b)
return okA && okB && x.Cmp(y) == 0
}

View file

@ -33,6 +33,24 @@ func (s *DoltStore) History(ctx context.Context, issueID string) ([]*storage.His
return result, err
}
// ListVersions implements storage.VersionLister over issue_versions.
//
// Plain withReadTx, not the long-timeout variant History needs: this reads an
// ordinary user table by its composite primary key prefix, not the
// dolt_history_issues scan whose cost History has to budget for.
func (s *DoltStore) ListVersions(ctx context.Context, issueID string) ([]storage.IssueVersion, error) {
var result []storage.IssueVersion
err := s.withReadTx(ctx, func(tx *sql.Tx) error {
var err error
result, err = issueops.ListVersionsInTx(ctx, tx, issueID)
if err != nil {
return wrapQueryError("list issue versions", err)
}
return nil
})
return result, err
}
// HistoricalIssueIDs reports which of ids appear in HEAD's committed history
// of the issues table. Implements storage.HistoryPresence.
//
@ -278,3 +296,9 @@ func isSafeCommitRef(s string) bool {
}
return true
}
// Compile-time proof that this leg serves versions. It lives here rather than
// in package storage because storage cannot import the legs. Dropping
// ListVersions is then a build failure rather than a silent demotion to
// "this backend cannot serve version history" at runtime.
var _ storage.VersionLister = (*DoltStore)(nil)

View file

@ -0,0 +1,337 @@
package dolt
import (
"context"
"crypto/rand"
"database/sql"
"encoding/hex"
"fmt"
"os"
"testing"
"time"
"github.com/steveyegge/beads/backend/conformance"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
)
// asOfReadHarness is this leg's Design D dispatch table (gastownhall/beads#5898
// revision 9, gastownhall/beads#6136): the conformance suite
// invents storeID values to select among N genuinely isolated stores, and
// isolating them is entirely this harness's job -- AsOfReadInTx itself is
// storeID-oblivious (see the package doc on
// internal/storage/issueops/asof_read.go). Each storeID gets its own fresh
// *DoltStore, built lazily on first use (buildAsOfReadStore) and torn down
// via t.Cleanup on the TestAsOfReadContract-level *testing.T. created tracks
// which (storeID, id) pairs already have a base issues row, since mintAt's
// second and later calls for the same pair must only add a historical
// issue_versions row, never a second base create.
//
// store() cannot use setupConcurrentTestStore. AsOfReadFixture's hook types
// (Resolve/MintAt/MakeUnanswerable) carry no *testing.T of their own, so a
// store built lazily inside a hook -- itself invoked from inside a t.Run
// subtest closure, sometimes nested two deep (the restriction-loop case
// below) -- has access only to whichever *testing.T this harness was
// constructed with: necessarily the OUTER TestAsOfReadContract's t, captured
// before any t.Run. setupConcurrentTestStore calls t.Skip/t.Fatalf
// internally, and calling FailNow/SkipNow on a *testing.T from a goroutine
// other than the one running that exact test -- which a t.Run subtest's
// closure always is, relative to the outer test -- panics with "subtest may
// have called FailNow on a parent test" (go's testing package requires
// FailNow/SkipNow to run only on the goroutine executing that specific
// test). buildAsOfReadStore below is a Fatalf/Skip-free twin of
// setupConcurrentTestStore's body for exactly this reason: its failures come
// back as a plain error, which flows through the calling hook's own
// (..., error) return to conformance.RunAsOfReadXXX, which correctly
// Fatalfs using the SUBTEST's own *testing.T on the SUBTEST's own goroutine.
// Dolt-availability skipping itself is handled once, up front in
// TestAsOfReadContract's own body via skipIfNoDolt(t) -- safe there because
// that runs before any t.Run, in the one goroutine that actually owns t.
type asOfReadHarness struct {
t *testing.T
stores map[string]*DoltStore
created map[[2]string]bool
}
func newAsOfReadHarness(t *testing.T) *asOfReadHarness {
return &asOfReadHarness{
t: t,
stores: map[string]*DoltStore{},
created: map[[2]string]bool{},
}
}
func (h *asOfReadHarness) store(ctx context.Context, storeID string) (*DoltStore, error) {
if s, ok := h.stores[storeID]; ok {
return s, nil
}
store, cleanup, err := buildAsOfReadStore(ctx)
if err != nil {
return nil, err
}
// t.Cleanup only appends to a mutex-guarded slice -- unlike Fatalf/Skip it
// never calls runtime.Goexit, so registering it on the outer h.t from
// inside a subtest's goroutine is safe. h.t's own cleanups run only after
// ALL of TestAsOfReadContract's t.Run calls have returned (none of them,
// nor their own nested t.Run calls, ever invoke t.Parallel), so every
// store this harness builds stays open for the whole test, matching
// created's own whole-test lifetime.
h.t.Cleanup(cleanup)
h.stores[storeID] = store
return store, nil
}
// buildAsOfReadStore constructs one fresh, isolated *DoltStore -- the same
// shape setupConcurrentTestStore builds (own temp dir, own database,
// MaxOpenConns=2, issue_prefix seeded), minus every t.Fatalf/t.Skip call.
// The issue_prefix seed is NOT optional here, even though
// DoltStore.CreateIssue's single-issue path sets SkipPrefixValidation
// unconditionally (matches its own documented legacy behavior): that only
// skips validating an explicit ID's OWN prefix against the configured one.
// A separate, unconditional precondition -- issueops/helpers.go's
// resolvePrefix, "issue_prefix config is missing", wrapped in
// storage.ErrNotInitialized (bd-166) -- fails every write, including ones
// under SkipPrefixValidation, when no issue_prefix is configured at all.
// Confirmed the hard way: the first version of this function omitted the
// SetConfig call on the strength of the SkipPrefixValidation reasoning
// alone, and every MintAt in a real run failed with exactly that
// ErrNotInitialized. See the asOfReadHarness doc comment for why this
// function cannot take a *testing.T and call Fatalf/Skip the way
// setupConcurrentTestStore does.
//
// It also departs from setupConcurrentTestStore in when it releases
// testSem: setupConcurrentTestStore's callers build at most a couple of
// stores and hold the slot for the whole test via t.Cleanup, but this
// harness can lazily build many stores across one TestAsOfReadContract run
// (up to nine, across every RunAsOfReadXXX case), all held open
// simultaneously until h.t's own cleanups run at the very end. Holding one
// slot per store for the whole test against testSem's cap of 2 would make
// the third store's construction block on a slot only some OTHER test's
// completion could free -- an outright hang when this test runs alone (e.g.
// -run TestAsOfReadContract), since nothing else would ever be running to
// free one. testSem exists to bound concurrent SETUP load on the shared
// container, and this harness's own setups are already serialized (no
// subtest here calls t.Parallel), so acquiring only around New() and
// releasing immediately after -- rather than for the store's whole open
// lifetime -- still honors that purpose without the hang.
func buildAsOfReadStore(ctx context.Context) (*DoltStore, func(), error) {
acquireTestSlot()
defer releaseTestSlot()
ctx, cancel := context.WithTimeout(ctx, testTimeout)
defer cancel()
tmpDir, err := os.MkdirTemp("", "dolt-asof-test-*")
if err != nil {
return nil, nil, fmt.Errorf("as-of read fixture: create temp dir: %w", err)
}
dbSuffix := make([]byte, 6)
if _, err := rand.Read(dbSuffix); err != nil {
os.RemoveAll(tmpDir)
return nil, nil, fmt.Errorf("as-of read fixture: generate db name: %w", err)
}
cfg := &Config{
Path: tmpDir,
CommitterName: "test",
CommitterEmail: "test@example.com",
Database: "testdb_asof_" + hex.EncodeToString(dbSuffix),
MaxOpenConns: 2, // matches setupConcurrentTestStore: avoid overwhelming the test container
CreateIfMissing: true,
}
store, err := New(ctx, cfg)
if err != nil {
os.RemoveAll(tmpDir)
return nil, nil, fmt.Errorf("as-of read fixture: create Dolt store: %w", err)
}
store.db.SetMaxIdleConns(0)
store.db.SetConnMaxIdleTime(time.Second)
if err := store.SetConfig(ctx, "issue_prefix", "asof"); err != nil {
store.Close()
os.RemoveAll(tmpDir)
return nil, nil, fmt.Errorf("as-of read fixture: set issue_prefix: %w", err)
}
cleanup := func() {
store.Close()
os.RemoveAll(tmpDir)
}
return store, cleanup, nil
}
// ensureCreated bare-creates id in storeID's store the first time it is
// asked for, giving RecordVersionAtInTx (called from mintAt) a base issues
// row to snapshot -- recordVersionAtInTx starts with GetIssueInTx, so it has
// nothing to read until this has run once.
func (h *asOfReadHarness) ensureCreated(ctx context.Context, storeID, id string) error {
key := [2]string{storeID, id}
if h.created[key] {
return nil
}
store, err := h.store(ctx, storeID)
if err != nil {
return err
}
issue := &types.Issue{
ID: id,
Title: "as-of read fixture issue",
Status: types.StatusOpen,
Priority: 3,
IssueType: types.TypeTask,
}
if err := store.CreateIssue(ctx, issue, "asof-read-fixture"); err != nil {
return fmt.Errorf("as-of read fixture: bare-create %s: %w", id, err)
}
h.created[key] = true
return nil
}
func (h *asOfReadHarness) resolve(ctx context.Context, storeID, id string, selector conformance.AsOfSelector) (conformance.AsOfReadResult, error) {
store, err := h.store(ctx, storeID)
if err != nil {
return conformance.AsOfReadResult{}, err
}
var result issueops.AsOfReadResult
err = store.withReadTx(ctx, func(tx *sql.Tx) error {
var err error
result, err = issueops.AsOfReadInTx(ctx, tx, storeID, id, toIssueopsSelector(selector))
return err
})
if err != nil {
return conformance.AsOfReadResult{}, err
}
return toConformanceResult(result), nil
}
// mintAt is the two-phase implementation MintAt's contract needs: phase one
// (ensureCreated) runs only once per (storeID, id); phase two
// (RecordVersionAtInTx) runs every call and always supplies the row mintAt
// reports the address of. RecordVersionAtInTx deliberately does not gate on
// versionedHistoryEnabled (this harness never turns that on for its stores),
// so it always mints, and reading MAX(revision) back inside the same
// transaction (read-your-writes) is how we learn which revision it picked --
// RecordVersionAtInTx itself reports no revision number.
func (h *asOfReadHarness) mintAt(ctx context.Context, storeID, id string, acceptedAt time.Time) (conformance.Address, error) {
if err := h.ensureCreated(ctx, storeID, id); err != nil {
return "", err
}
store, err := h.store(ctx, storeID)
if err != nil {
return "", err
}
var revision int64
err = store.withWriteTx(ctx, func(tx *sql.Tx) error {
if err := issueops.RecordVersionAtInTx(ctx, tx, id, "asof-read-fixture", acceptedAt); err != nil {
return err
}
return tx.QueryRowContext(ctx,
`SELECT MAX(revision) FROM issue_versions WHERE issue_id = ?`, id,
).Scan(&revision)
})
if err != nil {
return "", err
}
return conformance.Address(issueops.AsOfVersionAddress(id, revision)), nil
}
func (h *asOfReadHarness) makeUnanswerable(ctx context.Context, storeID, id string, restriction conformance.Restriction) error {
asOfRestriction, ok := conformanceToAsOfRestriction[restriction]
if !ok {
return fmt.Errorf("as-of read fixture: unmapped restriction %v", restriction)
}
store, err := h.store(ctx, storeID)
if err != nil {
return err
}
reason := fmt.Sprintf("as-of read fixture: made unanswerable as %s", restriction)
return store.withWriteTx(ctx, func(tx *sql.Tx) error {
return issueops.MarkLatestVersionRemovedInTx(ctx, tx, id, asOfRestriction, reason)
})
}
// conformanceToAsOfRestriction and its inverse are this leg's translation
// boundary between backend/conformance.Restriction (hyphenated String(),
// int-backed) and issueops.AsOfRestriction (underscored, string-backed --
// its values ARE the removed_restriction column's contents). issueops must
// stay conformance-oblivious and conformance must stay backend-oblivious
// (internal/storage/issueops/asof_read.go's package doc), so this mapping is
// deliberately duplicated per leg rather than shared centrally.
var conformanceToAsOfRestriction = map[conformance.Restriction]issueops.AsOfRestriction{
conformance.RestrictionLive: issueops.AsOfRestrictionLive,
conformance.RestrictionGoneRetention: issueops.AsOfRestrictionGoneRetention,
conformance.RestrictionGoneErasure: issueops.AsOfRestrictionGoneErasure,
conformance.RestrictionGoneReorganization: issueops.AsOfRestrictionGoneReorganization,
conformance.RestrictionUnknown: issueops.AsOfRestrictionUnknown,
}
var asOfRestrictionToConformance = map[issueops.AsOfRestriction]conformance.Restriction{
issueops.AsOfRestrictionLive: conformance.RestrictionLive,
issueops.AsOfRestrictionGoneRetention: conformance.RestrictionGoneRetention,
issueops.AsOfRestrictionGoneErasure: conformance.RestrictionGoneErasure,
issueops.AsOfRestrictionGoneReorganization: conformance.RestrictionGoneReorganization,
issueops.AsOfRestrictionUnknown: conformance.RestrictionUnknown,
}
func toIssueopsSelector(selector conformance.AsOfSelector) issueops.AsOfSelector {
out := issueops.AsOfSelector{At: selector.At}
if selector.Version != nil {
out.Address = string(*selector.Version)
}
return out
}
func toConformanceResult(result issueops.AsOfReadResult) conformance.AsOfReadResult {
if result.Refused {
return conformance.AsOfReadResult{
Refusal: &conformance.AsOfReadRefusal{
Restriction: asOfRestrictionToConformance[result.Restriction],
Reason: result.Reason,
},
}
}
return conformance.AsOfReadResult{
Address: conformance.Address(result.Address),
State: result.State,
}
}
// TestAsOfReadContract wires this leg into the R7.1 as-of-read contract
// (gastownhall/beads#5898 revision 9, gastownhall/beads#6136) with a real
// Resolve/MintAt/MakeUnanswerable backed by one isolated *DoltStore per
// storeID (asOfReadHarness).
func TestAsOfReadContract(t *testing.T) {
// Must run before any t.Run: skipIfNoDolt calls t.Skip/t.Fatalf
// internally, and this is the one place in this file where that is safe
// -- the outer test's own goroutine, before any subtest closure exists.
// See the asOfReadHarness doc comment for why no other call in this file
// may do the same.
skipIfNoDolt(t)
ctx := context.Background()
h := newAsOfReadHarness(t)
fixture := conformance.AsOfReadFixture{
IssuePrefix: "asof",
Resolve: h.resolve,
MintAt: h.mintAt,
MakeUnanswerable: h.makeUnanswerable,
}
t.Run("SelectorAcceptsEitherAnInstantOrAVersionAddress", func(t *testing.T) {
conformance.RunAsOfReadSelectorAcceptsEitherAnInstantOrAVersionAddress(t, ctx, fixture)
})
t.Run("ReturnsTheLatestVersionAtOrBeforeTStrictlyExcludingLater", func(t *testing.T) {
conformance.RunAsOfReadReturnsTheLatestVersionAtOrBeforeTStrictlyExcludingLater(t, ctx, fixture)
})
t.Run("ReportsTheAddressItServed", func(t *testing.T) {
conformance.RunAsOfReadReportsTheAddressItServed(t, ctx, fixture)
})
t.Run("RefusesAsGoneOrUnknownNeverSubstitutingAnotherVersion", func(t *testing.T) {
conformance.RunAsOfReadRefusesAsGoneOrUnknownNeverSubstitutingAnotherVersion(t, ctx, fixture)
})
t.Run("IsCompleteOnlyForTheAnsweringStoresHoldings", func(t *testing.T) {
conformance.RunAsOfReadIsCompleteOnlyForTheAnsweringStoresHoldings(t, ctx, fixture)
})
}

View file

@ -190,6 +190,7 @@ go_test(
"merge_blockers_test.go",
"merge_strategy_test.go",
"metadata_cas_contract_test.go",
"metadata_number_fidelity_test.go",
"migrate_consent_gate_test.go",
"migrate_dep_rekey_dedup_test.go",
"migrate_events_flip_test.go",
@ -242,6 +243,8 @@ go_test(
"update_mergeops_test.go",
"version_completeness_behaviour_test.go",
"version_reconciler_contract_test.go",
"version_subsecond_test.go",
"versioned_read_contract_test.go",
"workspace_config_contract_test.go",
],
embed = [":embeddeddolt"],

View file

@ -40,6 +40,9 @@ func TestParticipationGenerationFence(t *testing.T) {
t.Run("ProceedsForPromotedRecord", func(t *testing.T) {
conformance.RunParticipationGenerationProceedsForPromotedRecord(t, ctx, fixture)
})
t.Run("FlagOffSkipsUpdateOnParticipatingRecord", func(t *testing.T) {
conformance.RunParticipationGenerationFlagOffSkipsUpdateOnParticipatingRecord(t, ctx, fixture)
})
t.Run("FenceIgnoresSchemaSkewHatch", func(t *testing.T) {
conformance.RunParticipationGenerationFenceIgnoresSchemaSkewHatch(t, ctx, fixture)
})

View file

@ -0,0 +1,286 @@
//go:build cgo
package embeddeddolt_test
import (
"bytes"
"database/sql"
"encoding/json"
"errors"
"fmt"
"math/big"
"os"
"path/filepath"
"runtime"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
)
// metadataNumberCorpus is what TestVersionedHistoryKeepsNumbersTheStoreDistinguishesApart writes
// through the store. It groups literals that share one nearest binary64 (0.1 and its longer
// spellings, 1 and its spellings, pi at several precisions), because those are the literals a
// store could tell apart and RFC 8785 cannot, and it includes the values outside the I-JSON
// exact-integer range that the mint has to refuse. The server leg carries the same list in
// dolt/metadata_number_fidelity_test.go; keep the two in step.
var metadataNumberCorpus = []string{
"0.1", "0.10000000000000000555", "0.1000000000000000055511151231257827",
"1", "1.0", "1.00", "1e0", "10e-1",
"3.14159265358979323846", "3.141592653589793", "3.1415926535897932",
"0.3", "0.30000000000000004",
"0", "-0", "0.0", "1e-400",
"9007199254740991",
"9007199254740992", "9007199254740993", "9007199254740993.5", "9007199254740994",
"1727000000000000000", "1727000000000000123",
"1e300", "123456789012345678901234567890",
}
// metadataNumbersOutsideTheRange are the corpus literals no store normalization can bring back
// inside 2^53-1: each is refused at the mint, and the write it belonged to must not survive.
var metadataNumbersOutsideTheRange = map[string]bool{
"9007199254740992": true, "9007199254740993": true, "9007199254740993.5": true, "9007199254740994": true,
"1727000000000000000": true, "1727000000000000123": true,
"1e300": true, "123456789012345678901234567890": true,
}
// embeddedDoltVersion names the engine this leg runs. The embedded engine answers
// dolt_version() with the placeholder "SET_BY_INIT", and a test binary's build info lists no
// dependencies, so the version of the module it is built from is read from go.mod; both are
// logged. Where go.mod is not reachable the reported string stands alone.
func embeddedDoltVersion(reported string) string {
_, file, _, ok := runtime.Caller(0)
if !ok {
return reported
}
data, err := os.ReadFile(filepath.Join(filepath.Dir(file), "..", "..", "..", "go.mod"))
if err != nil {
return reported
}
for _, line := range strings.Split(string(data), "\n") {
if fields := strings.Fields(line); len(fields) >= 2 && fields[0] == "github.com/dolthub/dolt/go" {
return fields[1] + " (go.mod; dolt_version() reports " + reported + ")"
}
}
return reported
}
// TestVersionedHistoryKeepsNumbersTheStoreDistinguishesApart is the embedded leg of the safety
// property the number-admission rule rests on; the server leg's twin carries the full argument.
//
// In short: RFC 8785 turns every number into its nearest double, so two literals that differ by
// less than a double can share a canonical form, which is harmless only while the store cannot
// hold them apart. Whatever this Dolt does to numbers, it asserts in three phases that (1) with
// history OFF the store accepts a number outside the I-JSON range and the table logs what it
// holds, (2) with history ON a later write to such a row succeeds and mints nothing while the row
// never participated (design §16.2b's fence skips a legacy record whole, before the mint's
// admission gate), and is refused and changes nothing once the row participates, and
// (3) no two literals which read back as DIFFERENT numbers were both admitted with the SAME
// canonical form, and a literal the mint refuses leaves neither an issue row nor a version row.
func TestVersionedHistoryKeepsNumbersTheStoreDistinguishesApart(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "nf")
ctx := t.Context()
kit := newEmbeddedRoleFixtureKit(te, "nf")
configurer, ok := any(te.store).(storage.VersionedHistoryConfigurer)
if !ok {
t.Fatalf("%T does not implement storage.VersionedHistoryConfigurer", te.store)
}
var reported string
if err := kit.QueryScalar(ctx, `SELECT dolt_version()`, nil, &reported); err != nil {
reported = "unknown (" + err.Error() + ")"
}
newIssue := func(id, lit string) *types.Issue {
return &types.Issue{
ID: id, Title: "n " + lit, IssueType: types.TypeTask, Status: types.StatusOpen,
Metadata: json.RawMessage(`{"n":` + lit + `}`),
}
}
// Phase 1: history off. What does the store hold for a number outside the range?
t.Logf("metadata number normalization, embedded leg, dolt %s", embeddedDoltVersion(reported))
configurer.SetVersionedHistoryEnabled(false)
var held, heldLiterals []string
for i, lit := range metadataNumberCorpus {
if !metadataNumbersOutsideTheRange[lit] {
continue
}
id := fmt.Sprintf("nf-off-%02d", i)
if err := te.store.CreateIssue(ctx, newIssue(id, lit), "actor"); err != nil {
t.Logf(" history off: %-34s the store refused it: %v", lit, err)
continue
}
issue, err := te.store.GetIssue(ctx, id)
if err != nil {
t.Fatalf("reading %s back: %v", id, err)
}
stored, _ := storedNumberAndCanonicalMetadata(t, issue.Metadata, nil)
t.Logf(" history off: %-34s held as %s", lit, stored)
held = append(held, id)
heldLiterals = append(heldLiterals, lit)
}
rowState := func(id string) (versions int, revision int64, generation sql.NullInt64) {
t.Helper()
if err := kit.QueryScalar(ctx, `SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?`, []any{id}, &versions); err != nil {
t.Fatalf("counting the version rows of %s: %v", id, err)
}
if err := kit.QueryScalar(ctx, `SELECT current_revision FROM issues WHERE id = ?`, []any{id}, &revision); err != nil {
t.Fatalf("reading the revision of %s: %v", id, err)
}
if err := kit.QueryScalar(ctx, `SELECT participation_generation FROM issues WHERE id = ?`, []any{id}, &generation); err != nil {
t.Fatalf("reading the participation of %s: %v", id, err)
}
return versions, revision, generation
}
// Phase 2a: history on, rows that never participated. Each was made with history off, so it is
// a legacy record (participation_generation NULL) and design §16.2b's write fence skips an
// update-shaped write to it whole, before the mint's admission gate: the write succeeds,
// nothing is versioned, nothing is refused and the stamp stays NULL, whatever the metadata holds.
configurer.SetVersionedHistoryEnabled(true)
for _, id := range held {
_, revisionBefore, _ := rowState(id)
if err := te.store.UpdateIssue(ctx, id, map[string]any{"title": "retitled"}, "actor"); err != nil {
t.Errorf("updating %s, a legacy row that holds a number outside the I-JSON range, = %v, want success: the fence skips a legacy record before the mint's admission gate", id, err)
continue
}
after, err := te.store.GetIssue(ctx, id)
if err != nil || after.Title != "retitled" {
t.Errorf("the update of legacy row %s did not land: title %q (err %v), want %q", id, after.Title, err, "retitled")
}
versions, revision, generation := rowState(id)
if versions != 0 || generation.Valid || revision != revisionBefore {
t.Errorf("the update of legacy row %s versioned or promoted it: version rows %d (want 0), participation_generation %v (want NULL), current_revision %d -> %d (want unchanged)",
id, versions, generation, revisionBefore, revision)
}
}
// Phase 2b: history on, rows that participate. Each is created with history on holding an
// in-range stand-in, so the real create-shaped mint stamps it; the stamp is read first, because
// that is what makes this case about participation. History is then switched off and the row's
// metadata replaced through the store, which is how a row comes to hold such a number without the
// mint having seen it, and switched on again. The next write is refused and changes nothing.
for k, lit := range heldLiterals {
id := fmt.Sprintf("nf-part-%02d", k)
configurer.SetVersionedHistoryEnabled(true)
if err := te.store.CreateIssue(ctx, newIssue(id, "1"), "actor"); err != nil {
t.Fatalf("creating the participating row %s with history on: %v", id, err)
}
if _, _, generation := rowState(id); !generation.Valid {
t.Fatalf("%s was created with history on but participation_generation is NULL: the control failed, so this case would not be about participation", id)
}
configurer.SetVersionedHistoryEnabled(false)
if err := te.store.UpdateIssue(ctx, id, map[string]any{"metadata": json.RawMessage(`{"n":` + lit + `}`)}, "actor"); err != nil {
t.Fatalf("replacing the metadata of %s with %s while history is off: %v", id, lit, err)
}
configurer.SetVersionedHistoryEnabled(true)
before, err := te.store.GetIssue(ctx, id)
if err != nil {
t.Fatalf("reading %s: %v", id, err)
}
versionsBefore, revisionBefore, generationBefore := rowState(id)
err = te.store.UpdateIssue(ctx, id, map[string]any{"title": "retitled"}, "actor")
if !errors.Is(err, issueops.ErrIntegerNotRepresentable) {
t.Errorf("updating %s, a participating row that holds %s, = %v, want ErrIntegerNotRepresentable", id, lit, err)
}
after, getErr := te.store.GetIssue(ctx, id)
versions, revision, generation := rowState(id)
if getErr != nil || after.Title != before.Title || versions != versionsBefore || revision != revisionBefore || generation != generationBefore {
t.Errorf("the refused update of %s left a trace: title %q -> %q, version rows %d -> %d, current_revision %d -> %d, participation_generation %v -> %v (err %v)",
id, before.Title, after.Title, versionsBefore, versions, revisionBefore, revision, generationBefore, generation, getErr)
}
}
// Phase 3: history on, fresh rows. The property.
configurer.SetVersionedHistoryEnabled(true)
type admittedLiteral struct{ written, storedAs, canonical string }
var admitted []admittedLiteral
for i, lit := range metadataNumberCorpus {
id := fmt.Sprintf("nf-%02d", i)
err := te.store.CreateIssue(ctx, newIssue(id, lit), "actor")
if err != nil {
if !metadataNumbersOutsideTheRange[lit] {
t.Errorf("%s was refused although it is an ordinary number: %v", lit, err)
} else if !errors.Is(err, issueops.ErrIntegerNotRepresentable) {
t.Errorf("%s was refused with %v, want ErrIntegerNotRepresentable", lit, err)
}
if _, getErr := te.store.GetIssue(ctx, id); !errors.Is(getErr, storage.ErrNotFound) {
t.Errorf("%s was refused but its issue exists afterwards (GetIssue = %v): the refusal did not abort the write", lit, getErr)
}
var versions int
if scanErr := kit.QueryScalar(ctx, `SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?`, []any{id}, &versions); scanErr != nil || versions != 0 {
t.Errorf("%s was refused but left %d version rows (err %v)", lit, versions, scanErr)
}
t.Logf(" history on: %-34s refused", lit)
continue
}
if metadataNumbersOutsideTheRange[lit] {
t.Errorf("%s is outside the I-JSON exact-integer range and was written", lit)
}
issue, err := te.store.GetIssue(ctx, id)
if err != nil {
t.Fatalf("reading %s back: %v", id, err)
}
var durable []byte
if err := kit.QueryScalar(ctx,
`SELECT durable_state FROM issue_versions WHERE issue_id = ? ORDER BY revision DESC LIMIT 1`, []any{id}, &durable); err != nil {
t.Fatalf("reading the version of %s: %v", id, err)
}
stored, canonical := storedNumberAndCanonicalMetadata(t, issue.Metadata, durable)
t.Logf(" history on: %-34s read back as %-28s canonical metadata %s", lit, stored, canonical)
admitted = append(admitted, admittedLiteral{lit, stored, canonical})
}
if len(admitted) < 12 {
t.Fatalf("only %d of %d literals were admitted; the property is close to vacuous", len(admitted), len(metadataNumberCorpus))
}
first := map[string]admittedLiteral{}
for _, a := range admitted {
prior, seen := first[a.canonical]
if !seen {
first[a.canonical] = a
continue
}
if !sameNumber(prior.storedAs, a.storedAs) {
t.Errorf("literals %s and %s read back from the store as different numbers (%s and %s) but share the canonical form %s: "+
"two distinct stored states would carry one content token", prior.written, a.written, prior.storedAs, a.storedAs, a.canonical)
}
}
}
// storedNumberAndCanonicalMetadata returns the number the store handed back in the issue's
// metadata, and, when durable is given, the metadata member of the canonical bytes the mint
// stored for it.
func storedNumberAndCanonicalMetadata(t *testing.T, readBack json.RawMessage, durable []byte) (stored, canonical string) {
t.Helper()
var back struct {
N json.Number `json:"n"`
}
dec := json.NewDecoder(bytes.NewReader(readBack))
dec.UseNumber()
if err := dec.Decode(&back); err != nil {
t.Fatalf("decoding the metadata read back %s: %v", readBack, err)
}
if durable == nil {
return back.N.String(), ""
}
var version struct {
Metadata json.RawMessage `json:"metadata"`
}
if err := json.Unmarshal(durable, &version); err != nil {
t.Fatalf("decoding durable_state %s: %v", durable, err)
}
return back.N.String(), strings.TrimSpace(string(version.Metadata))
}
// sameNumber reports whether two JSON number literals denote the same value, compared exactly.
func sameNumber(a, b string) bool {
x, okA := new(big.Rat).SetString(a)
y, okB := new(big.Rat).SetString(b)
return okA && okB && x.Cmp(y) == 0
}

View file

@ -1165,6 +1165,17 @@ func (s *EmbeddedDoltStore) History(ctx context.Context, issueID string) ([]*sto
return result, err
}
// ListVersions implements storage.VersionLister over issue_versions.
func (s *EmbeddedDoltStore) ListVersions(ctx context.Context, issueID string) ([]storage.IssueVersion, error) {
var result []storage.IssueVersion
err := s.withConn(ctx, false, func(tx *sql.Tx) error {
var err error
result, err = issueops.ListVersionsInTx(ctx, tx, issueID)
return err
})
return result, err
}
func (s *EmbeddedDoltStore) AsOf(ctx context.Context, issueID string, ref string) (*types.Issue, error) {
var result *types.Issue
err := s.withConn(ctx, false, func(tx *sql.Tx) error {
@ -1529,3 +1540,8 @@ func (s *EmbeddedDoltStore) GetStaleIssues(ctx context.Context, filter types.Sta
})
return result, err
}
// Compile-time proof that this leg serves versions -- see the matching
// assertion in internal/storage/dolt/versioned.go for why it lives in the
// leg's own package.
var _ storage.VersionLister = (*EmbeddedDoltStore)(nil)

View file

@ -5,6 +5,7 @@ package embeddeddolt_test
import (
"encoding/json"
"testing"
"time"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
@ -218,6 +219,118 @@ func TestEmbeddedEveryAcceptedLifecycleMutationMintsOneVersion(t *testing.T) {
p.revisionMatchesRows(b)
}
// TestEmbeddedMintLeavesUpdatedAtWhereHistoryOffDoes pins that minting a
// version is not itself an edit. issues.updated_at carries ON UPDATE
// CURRENT_TIMESTAMP, so a mint whose own UPDATE left it unassigned would move
// it to the clock on every versioned write, including the label and
// dependency writes that never touch it with history off. bd import's
// stale-upsert check reads that column, so a moved updated_at would also turn
// the source's next real edit away as stale. Each scenario runs with history
// off first, as the control the history-on run must match.
func TestEmbeddedMintLeavesUpdatedAtWhereHistoryOffDoes(t *testing.T) {
skipUnlessEmbeddedDolt(t)
// Fixed instants well before any clock this runs under, so a mint that
// wrote the clock cannot pass for any of them.
aged := time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)
sourceEdit := time.Date(2025, 2, 1, 0, 0, 0, 0, time.UTC)
laterSourceEdit := time.Date(2025, 3, 1, 0, 0, 0, 0, time.UTC)
for _, history := range []struct {
name string
on bool
}{{"HistoryOff", false}, {"HistoryOn", true}} {
t.Run(history.name, func(t *testing.T) {
te := newTestEnv(t, "verts")
ctx := t.Context()
te.store.SetVersionedHistoryEnabled(history.on)
// With history on every step below must mint exactly one version,
// so a mint that never ran cannot pass for one that kept updated_at.
mints := 0
if history.on {
mints = 1
}
a, b := "verts-a", "verts-b"
for _, id := range []string{a, b} {
if err := te.store.CreateIssue(ctx, &types.Issue{
ID: id, Title: id, Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask,
}, "seed"); err != nil {
t.Fatalf("CreateIssue(%s): %v", id, err)
}
}
age := func() { te.exec(t, ctx, "UPDATE issues SET updated_at = ? WHERE id = ?", aged, a) }
versions := func() int {
t.Helper()
var n int
te.queryScalar(t, ctx, "SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?", []any{a}, &n)
return n
}
// check asserts a's updated_at and that the step minted as the
// history setting says, and returns the new version count.
check := func(step string, before int, want time.Time) int {
t.Helper()
var got time.Time
te.queryScalar(t, ctx, "SELECT updated_at FROM issues WHERE id = ?", []any{a}, &got)
if !got.UTC().Equal(want) {
t.Errorf("%s: updated_at for %s is %v, want %v", step, a, got.UTC(), want)
}
n := versions()
if n != before+mints {
t.Fatalf("%s: version rows for %s = %d, want %d", step, a, n, before+mints)
}
return n
}
// Label and dependency writes never assign updated_at themselves.
age()
n := versions()
if err := te.store.AddLabel(ctx, a, "l1", "actor"); err != nil {
t.Fatalf("AddLabel: %v", err)
}
n = check("add label", n, aged)
if err := te.store.RemoveLabel(ctx, a, "l1", "actor"); err != nil {
t.Fatalf("RemoveLabel: %v", err)
}
n = check("remove label", n, aged)
if err := te.store.AddDependency(ctx, &types.Dependency{IssueID: a, DependsOnID: b, Type: types.DepBlocks}, "actor"); err != nil {
t.Fatalf("AddDependency: %v", err)
}
n = check("add dependency", n, aged)
if err := te.store.RemoveDependency(ctx, a, b, "actor"); err != nil {
t.Fatalf("RemoveDependency: %v", err)
}
n = check("remove dependency", n, aged)
// bd import's options. The upsert stores the source's own
// updated_at, and the source's next edit is compared against it.
// Aged again so this half does not depend on the half above.
age()
var rejected []string
opts := storage.BatchCreateOptions{
RejectStaleUpserts: true,
SkipDependencyValidationErrors: true,
OnStaleRejected: func(id string) { rejected = append(rejected, id) },
}
importEdit := func(title string, at time.Time) {
t.Helper()
if err := te.store.CreateIssuesWithFullOptions(ctx, []*types.Issue{{
ID: a, Title: title, Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask,
CreatedAt: aged, UpdatedAt: at,
}}, "importer", opts); err != nil {
t.Fatalf("import %q: %v", title, err)
}
if len(rejected) != 0 {
t.Fatalf("import %q with source updated_at %v was rejected as stale (%v)", title, at, rejected)
}
}
importEdit("source edit", sourceEdit)
n = check("import", n, sourceEdit)
importEdit("later source edit", laterSourceEdit)
check("later import", n, laterSourceEdit)
})
}
}
// TestEmbeddedBatchCreateFirstVersionCarriesCreationTimeEdges pins the
// batch-create ordering fix: the one version minted at creation is minted
// AFTER PersistDependenciesWithOptionsResult, so it carries the outgoing edge

View file

@ -0,0 +1,99 @@
//go:build cgo
package embeddeddolt
import (
"context"
"database/sql"
"testing"
"time"
)
// TestRecordVersionKeepsSubSecondChangeAt pins the WRITER half of migration
// 0069's contract: a sub-second change_at must survive through
// RecordVersionAtInTx into the row and back.
//
// 0069 widened issue_versions.change_at to DATETIME(6) precisely so that two
// versions minted inside the same second stay distinguishable, because
// --at <instant> is the only PORTABLE selector the read surface offers while
// revision remains a per-store ordinal and no durable version address has
// shipped. The column's own half is pinned by
// TestMigration0069ChangeAtSurvivesSubSecondPrecisionThroughDoltCLI in
// internal/storage/schema. The writer's half was NOT pinned, and that is
// exactly how it got defeated: recordVersionAtInTx carried an
// `at.Truncate(time.Second)` — correct while the column was precision 0,
// where Dolt rounds half-up — which kept flooring every value after the
// widening landed. A store with both applied stored four versions minted in
// one second as the identical 15:40:38.000000.
//
// So this test asserts the two things a caller actually depends on: the
// microseconds are there, and same-second versions differ.
func TestRecordVersionKeepsSubSecondChangeAt(t *testing.T) {
skipUnlessEmbeddedDolt(t)
ctx := context.Background()
store, cleanup, err := buildAsOfReadStore(ctx)
if err != nil {
t.Fatalf("build store: %v", err)
}
t.Cleanup(cleanup)
h := newAsOfReadHarness(t)
h.stores["subsecond"] = store
const id = "vt-subsec"
// Two instants inside the SAME second, a quarter of a second apart. Under
// the old floor both landed on :07.000000; under a precision-0 column the
// second would additionally have rounded up to :08.
first := time.Date(2026, 9, 27, 11, 4, 7, 250000000, time.UTC)
second := time.Date(2026, 9, 27, 11, 4, 7, 750000000, time.UTC)
if _, err := h.mintAt(ctx, "subsecond", id, first); err != nil {
t.Fatalf("mint at %s: %v", first, err)
}
if _, err := h.mintAt(ctx, "subsecond", id, second); err != nil {
t.Fatalf("mint at %s: %v", second, err)
}
var stamps []time.Time
if err := store.withConn(ctx, false, func(tx *sql.Tx) error {
rows, err := tx.QueryContext(ctx,
`SELECT change_at FROM issue_versions WHERE issue_id = ? ORDER BY revision`, id)
if err != nil {
return err
}
defer func() { _ = rows.Close() }()
for rows.Next() {
var at time.Time
if err := rows.Scan(&at); err != nil {
return err
}
stamps = append(stamps, at)
}
return rows.Err()
}); err != nil {
t.Fatalf("read change_at back: %v", err)
}
if len(stamps) < 2 {
t.Fatalf("got %d version rows for %s, want at least 2", len(stamps), id)
}
// The harness mints a creation version too, so take the last two.
got := stamps[len(stamps)-2:]
for i, at := range got {
if at.Nanosecond() == 0 {
t.Errorf("change_at[%d] = %s has a zero fractional part; the sub-second component was dropped between the caller and the row. "+
"If recordVersionAtInTx floors `at` again, or the column reverts to DATETIME(0), --at can no longer separate versions minted in the same second.",
i, at.Format("15:04:05.000000"))
}
}
if got[0].Equal(got[1]) {
t.Errorf("two versions minted 500ms apart both stored %s — same-second versions must stay distinguishable by change_at, "+
"which is what migration 0069 widened the column for", got[0].Format("15:04:05.000000"))
}
if !got[1].After(got[0]) {
t.Errorf("change_at went backwards or sideways: %s then %s",
got[0].Format("15:04:05.000000"), got[1].Format("15:04:05.000000"))
}
}

View file

@ -0,0 +1,309 @@
//go:build cgo
package embeddeddolt
import (
"context"
"database/sql"
"fmt"
"os"
"path/filepath"
"testing"
"time"
"github.com/steveyegge/beads/backend/conformance"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
)
// asOfReadHarness is this leg's Design D dispatch table (gastownhall/beads#5898
// revision 9, gastownhall/beads#6136): the conformance suite
// invents storeID values to select among N genuinely isolated stores, and
// isolating them is entirely this harness's job -- AsOfReadInTx itself is
// storeID-oblivious (see the package doc on
// internal/storage/issueops/asof_read.go). Each storeID gets its own fresh
// *EmbeddedDoltStore, built lazily on first use (buildAsOfReadStore) and torn
// down via t.Cleanup on the TestAsOfReadContract-level *testing.T. created
// tracks which (storeID, id) pairs already have a base issues row, since
// mintAt's second and later calls for the same pair must only add a
// historical issue_versions row, never a second base create.
//
// store() cannot use a *testing.T-tied fixture helper (e.g.
// newPristineEmbeddedDoltFixture): AsOfReadFixture's hook types
// (Resolve/MintAt/MakeUnanswerable) carry no *testing.T of their own, so a
// store built lazily inside a hook -- itself invoked from inside a t.Run
// subtest closure, sometimes nested two deep (the restriction-loop case
// below) -- has access only to whichever *testing.T this harness was
// constructed with: necessarily the OUTER TestAsOfReadContract's t, captured
// before any t.Run. Calling FailNow/SkipNow (t.Fatalf/t.Skip) on a *testing.T
// from a goroutine other than the one running that exact test -- which a
// t.Run subtest's closure always is, relative to the outer test -- panics
// with "subtest may have called FailNow on a parent test" (go's testing
// package requires FailNow/SkipNow to run only on the goroutine executing
// that specific test). buildAsOfReadStore below is a Fatalf/Skip-free
// construction path for exactly this reason: its failures come back as a
// plain error, which flows through the calling hook's own (..., error)
// return to conformance.RunAsOfReadXXX, which correctly Fatalfs using the
// SUBTEST's own *testing.T on the SUBTEST's own goroutine. Embedded-Dolt
// availability skipping itself is handled once, up front in
// TestAsOfReadContract's own body via skipUnlessEmbeddedDolt(t) -- safe there
// because that runs before any t.Run, in the one goroutine that actually owns
// t. See internal/storage/dolt/versioned_read_contract_test.go for this
// leg's sibling, which this file mirrors as closely as the two backends'
// store-construction APIs allow.
type asOfReadHarness struct {
t *testing.T
stores map[string]*EmbeddedDoltStore
created map[[2]string]bool
}
func newAsOfReadHarness(t *testing.T) *asOfReadHarness {
return &asOfReadHarness{
t: t,
stores: map[string]*EmbeddedDoltStore{},
created: map[[2]string]bool{},
}
}
func (h *asOfReadHarness) store(ctx context.Context, storeID string) (*EmbeddedDoltStore, error) {
if s, ok := h.stores[storeID]; ok {
return s, nil
}
store, cleanup, err := buildAsOfReadStore(ctx)
if err != nil {
return nil, err
}
// t.Cleanup only appends to a mutex-guarded slice -- unlike Fatalf/Skip it
// never calls runtime.Goexit, so registering it on the outer h.t from
// inside a subtest's goroutine is safe. h.t's own cleanups run only after
// ALL of TestAsOfReadContract's t.Run calls have returned (none of them,
// nor their own nested t.Run calls, ever invoke t.Parallel), so every
// store this harness builds stays open for the whole test, matching
// created's own whole-test lifetime.
h.t.Cleanup(cleanup)
h.stores[storeID] = store
return store, nil
}
// buildAsOfReadStore constructs one fresh, isolated *EmbeddedDoltStore: its
// own temp directory (so its own on-disk database, with nothing shared
// between stores -- unlike the dolt leg's single testcontainers server, an
// embedded store's isolation is just its own directory, so a fixed database
// name is safe to reuse across every call), issue_prefix seeded. Minus every
// t.Fatalf/t.Skip call; see the asOfReadHarness doc comment for why no call
// in this file may make one outside TestAsOfReadContract's own body.
func buildAsOfReadStore(ctx context.Context) (*EmbeddedDoltStore, func(), error) {
tmpDir, err := os.MkdirTemp("", "embeddeddolt-asof-test-*")
if err != nil {
return nil, nil, fmt.Errorf("as-of read fixture: create temp dir: %w", err)
}
beadsDir := filepath.Join(tmpDir, ".beads")
store, err := Open(ctx, beadsDir, "asof", "main")
if err != nil {
os.RemoveAll(tmpDir)
return nil, nil, fmt.Errorf("as-of read fixture: open embedded Dolt store: %w", err)
}
if err := store.SetConfig(ctx, "issue_prefix", "asof"); err != nil {
store.Close()
os.RemoveAll(tmpDir)
return nil, nil, fmt.Errorf("as-of read fixture: set issue_prefix: %w", err)
}
cleanup := func() {
store.Close()
os.RemoveAll(tmpDir)
}
return store, cleanup, nil
}
// ensureCreated bare-creates id in storeID's store the first time it is
// asked for, giving RecordVersionAtInTx (called from mintAt) a base issues
// row to snapshot -- recordVersionAtInTx starts with GetIssueInTx, so it has
// nothing to read until this has run once.
func (h *asOfReadHarness) ensureCreated(ctx context.Context, storeID, id string) error {
key := [2]string{storeID, id}
if h.created[key] {
return nil
}
store, err := h.store(ctx, storeID)
if err != nil {
return err
}
issue := &types.Issue{
ID: id,
Title: "as-of read fixture issue",
Status: types.StatusOpen,
Priority: 3,
IssueType: types.TypeTask,
}
if err := store.CreateIssue(ctx, issue, "asof-read-fixture"); err != nil {
return fmt.Errorf("as-of read fixture: bare-create %s: %w", id, err)
}
h.created[key] = true
return nil
}
func (h *asOfReadHarness) resolve(ctx context.Context, storeID, id string, selector conformance.AsOfSelector) (conformance.AsOfReadResult, error) {
store, err := h.store(ctx, storeID)
if err != nil {
return conformance.AsOfReadResult{}, err
}
var result issueops.AsOfReadResult
err = store.withConn(ctx, false, func(tx *sql.Tx) error {
var err error
result, err = issueops.AsOfReadInTx(ctx, tx, storeID, id, toIssueopsSelector(selector))
return err
})
if err != nil {
return conformance.AsOfReadResult{}, err
}
return toConformanceResult(result), nil
}
// mintAt is the two-phase implementation MintAt's contract needs: phase one
// (ensureCreated) runs only once per (storeID, id); phase two
// (RecordVersionAtInTx) runs every call and always supplies the row mintAt
// reports the address of. RecordVersionAtInTx deliberately does not gate on
// versionedHistoryEnabled (this harness never turns that on for its stores),
// so it always mints, and reading MAX(revision) back inside the same
// transaction (read-your-writes) is how we learn which revision it picked --
// RecordVersionAtInTx itself reports no revision number.
func (h *asOfReadHarness) mintAt(ctx context.Context, storeID, id string, acceptedAt time.Time) (conformance.Address, error) {
if err := h.ensureCreated(ctx, storeID, id); err != nil {
return "", err
}
store, err := h.store(ctx, storeID)
if err != nil {
return "", err
}
var revision int64
err = store.withConn(ctx, true, func(tx *sql.Tx) error {
if err := issueops.RecordVersionAtInTx(ctx, tx, id, "asof-read-fixture", acceptedAt); err != nil {
return err
}
return tx.QueryRowContext(ctx,
`SELECT MAX(revision) FROM issue_versions WHERE issue_id = ?`, id,
).Scan(&revision)
})
if err != nil {
return "", err
}
return conformance.Address(issueops.AsOfVersionAddress(id, revision)), nil
}
func (h *asOfReadHarness) makeUnanswerable(ctx context.Context, storeID, id string, restriction conformance.Restriction) error {
asOfRestriction, ok := conformanceToAsOfRestriction[restriction]
if !ok {
return fmt.Errorf("as-of read fixture: unmapped restriction %v", restriction)
}
store, err := h.store(ctx, storeID)
if err != nil {
return err
}
reason := fmt.Sprintf("as-of read fixture: made unanswerable as %s", restriction)
return store.withConn(ctx, true, func(tx *sql.Tx) error {
return issueops.MarkLatestVersionRemovedInTx(ctx, tx, id, asOfRestriction, reason)
})
}
// conformanceToAsOfRestriction and its inverse are this leg's translation
// boundary between backend/conformance.Restriction (hyphenated String(),
// int-backed) and issueops.AsOfRestriction (underscored, string-backed --
// its values ARE the removed_restriction column's contents). issueops must
// stay conformance-oblivious and conformance must stay backend-oblivious
// (internal/storage/issueops/asof_read.go's package doc), so this mapping is
// deliberately duplicated per leg rather than shared centrally.
var conformanceToAsOfRestriction = map[conformance.Restriction]issueops.AsOfRestriction{
conformance.RestrictionLive: issueops.AsOfRestrictionLive,
conformance.RestrictionGoneRetention: issueops.AsOfRestrictionGoneRetention,
conformance.RestrictionGoneErasure: issueops.AsOfRestrictionGoneErasure,
conformance.RestrictionGoneReorganization: issueops.AsOfRestrictionGoneReorganization,
conformance.RestrictionUnknown: issueops.AsOfRestrictionUnknown,
}
var asOfRestrictionToConformance = map[issueops.AsOfRestriction]conformance.Restriction{
issueops.AsOfRestrictionLive: conformance.RestrictionLive,
issueops.AsOfRestrictionGoneRetention: conformance.RestrictionGoneRetention,
issueops.AsOfRestrictionGoneErasure: conformance.RestrictionGoneErasure,
issueops.AsOfRestrictionGoneReorganization: conformance.RestrictionGoneReorganization,
issueops.AsOfRestrictionUnknown: conformance.RestrictionUnknown,
}
func toIssueopsSelector(selector conformance.AsOfSelector) issueops.AsOfSelector {
out := issueops.AsOfSelector{At: selector.At}
if selector.Version != nil {
out.Address = string(*selector.Version)
}
return out
}
func toConformanceResult(result issueops.AsOfReadResult) conformance.AsOfReadResult {
if result.Refused {
return conformance.AsOfReadResult{
Refusal: &conformance.AsOfReadRefusal{
Restriction: asOfRestrictionToConformance[result.Restriction],
Reason: result.Reason,
},
}
}
return conformance.AsOfReadResult{
Address: conformance.Address(result.Address),
State: result.State,
}
}
// skipUnlessEmbeddedDolt is this file's own copy of the embeddeddolt_test
// package's helper of the same name (create_issue_test.go): that one is
// unexported and lives in the external test package, unreachable from here.
// This harness must live in-package (see the asOfReadHarness doc comment for
// why: raw DBTX access requires the unexported withConn), so it carries its
// own copy rather than importing across the package/package_test boundary.
// Reads the same BEADS_TEST_EMBEDDED_DOLT env var so `go test
// ./internal/storage/embeddeddolt/...` gates uniformly regardless of which
// half of the package a given test file lives in.
func skipUnlessEmbeddedDolt(t *testing.T) {
t.Helper()
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt tests")
}
}
// TestAsOfReadContract wires this leg into the R7.1 as-of-read contract
// (gastownhall/beads#5898 revision 9, gastownhall/beads#6136) with a real
// Resolve/MintAt/MakeUnanswerable backed by one isolated *EmbeddedDoltStore
// per storeID (asOfReadHarness).
func TestAsOfReadContract(t *testing.T) {
// Must run before any t.Run: skipUnlessEmbeddedDolt calls t.Skip
// internally, and this is the one place in this file where that is safe
// -- the outer test's own goroutine, before any subtest closure exists.
// See the asOfReadHarness doc comment for why no other call in this file
// may do the same.
skipUnlessEmbeddedDolt(t)
ctx := context.Background()
h := newAsOfReadHarness(t)
fixture := conformance.AsOfReadFixture{
IssuePrefix: "asof",
Resolve: h.resolve,
MintAt: h.mintAt,
MakeUnanswerable: h.makeUnanswerable,
}
t.Run("SelectorAcceptsEitherAnInstantOrAVersionAddress", func(t *testing.T) {
conformance.RunAsOfReadSelectorAcceptsEitherAnInstantOrAVersionAddress(t, ctx, fixture)
})
t.Run("ReturnsTheLatestVersionAtOrBeforeTStrictlyExcludingLater", func(t *testing.T) {
conformance.RunAsOfReadReturnsTheLatestVersionAtOrBeforeTStrictlyExcludingLater(t, ctx, fixture)
})
t.Run("ReportsTheAddressItServed", func(t *testing.T) {
conformance.RunAsOfReadReportsTheAddressItServed(t, ctx, fixture)
})
t.Run("RefusesAsGoneOrUnknownNeverSubstitutingAnotherVersion", func(t *testing.T) {
conformance.RunAsOfReadRefusesAsGoneOrUnknownNeverSubstitutingAnotherVersion(t, ctx, fixture)
})
t.Run("IsCompleteOnlyForTheAnsweringStoresHoldings", func(t *testing.T) {
conformance.RunAsOfReadIsCompleteOnlyForTheAnsweringStoresHoldings(t, ctx, fixture)
})
}

View file

@ -5,6 +5,7 @@ go_library(
srcs = [
"aggregate.go",
"as_of.go",
"asof_read.go",
"batch_apply.go",
"batchget.go",
"batching.go",
@ -100,6 +101,8 @@ go_library(
"version.go",
"version_commit.go",
"version_history.go",
"version_history_scan.go",
"version_list.go",
"wake_defers.go",
"wisp_filter_convert.go",
"wisp_routing.go",
@ -134,6 +137,7 @@ go_test(
"aggregate_authorize_notes_test.go",
"aggregate_authorize_transfer_test.go",
"as_of_test.go",
"asof_read_test.go",
"batch_apply_test.go",
"batchget_test.go",
"batching_test.go",
@ -200,6 +204,9 @@ go_test(
"update_validation_test.go",
"version_completeness_test.go",
"version_history_durable_state_test.go",
"version_history_integer_admission_test.go",
"version_history_number_admission_test.go",
"version_history_preenable_scan_test.go",
"version_history_test.go",
"wisp_routing_test.go",
],

View file

@ -0,0 +1,286 @@
package issueops
import (
"context"
"database/sql"
"encoding/json"
"errors"
"fmt"
"strconv"
"strings"
"time"
)
// This file implements R7.1 as-of read (gastownhall/beads#5898 revision 9,
// gastownhall/beads#6136; conformance suite: backend/conformance/
// versioned_read_contract.go): given an instant T or a version address, it
// returns one issue's durable state as of that point -- the latest version
// accepted at or before T, with everything later excluded -- marking the
// address it served, or refuses as gone or unknown with the reason (R8,
// R20). It reads issue_versions rows minted by RecordVersionInTx /
// RecordVersionAtInTx (version_history.go); it adds no writer of its own for
// the mutation path.
//
// NOT part of this primitive (R7.1's own text): memory-plane consumer
// policy -- closed-before-T boundary, sibling exclusion, supersession
// exclusion (gastownhall/beads#5877). Those are layered on top by a
// consumer, not implemented here.
//
// ALL THREE LEGS SHARE THIS BODY, the same way CompareAndSetMetadataKeyInTx,
// R16's CompareAndSetVersionInTx, and R20's epoch_cas.go do: 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/Restriction vocabulary -- this file knows
// nothing about the conformance package (same package-boundary precedent as
// epoch_cas.go's EpochRestriction).
//
// removed_at / removed_reason (migration 0067, virgin and unused before this
// slice) plus removed_restriction (migration 0071, added by this slice) are
// the durable "this version row was removed" marker AsOfReadInTx reads.
// R7.1 only READS them here; a future R17 (not yet implemented on this
// branch) will be the production WRITER, via real hold/remove/erase
// primitives -- no collision, since this file never writes them outside the
// test-support seam below.
//
// STOREID IS ACCEPTED BUT NOT A FILTER, the same way CurrentEpochInTx
// accepts one: issue_versions has no store_id column, and a store's rows are
// already exactly the rows in that store's own database (one logical store
// per database, matching production reality). The parameter exists only so
// this function's signature matches AsOfReadFixture.Resolve's hook shape,
// which the conformance suite's own ad-hoc dispatch string requires (Design
// D: the suite invents storeID values to select among N genuinely isolated
// per-leg test stores; the leg fixture, not this function, does that
// isolation).
// AsOfRestriction is this file's own local answer vocabulary for R7.1's
// refusal path -- deliberately not backend/conformance.Restriction (see the
// package-boundary note above). Unlike R20's EpochRestriction (int-backed:
// R20 never persists a restriction, it recomputes GoneReorganization at read
// time from an epoch comparison), this type is STRING-backed: it is written
// directly into issue_versions.removed_restriction and read back with a
// plain cast, no separate parse/format step needed. AsOfRestrictionLive
// exists only for API symmetry with EpochRestriction's shape -- it is never
// persisted (Live is the absence of a value, removed_at IS NULL, not a
// stored one) and AsOfReadInTx never returns it.
type AsOfRestriction string
const (
AsOfRestrictionLive AsOfRestriction = "live"
AsOfRestrictionGoneRetention AsOfRestriction = "gone_retention"
AsOfRestrictionGoneErasure AsOfRestriction = "gone_erasure"
AsOfRestrictionGoneReorganization AsOfRestriction = "gone_reorganization"
AsOfRestrictionUnknown AsOfRestriction = "unknown"
)
// NormalizeRemovedRestriction is the one place a stored removed_restriction
// becomes an answer. The column is a free VARCHAR written by whatever produced
// the row, so only the values this file's vocabulary names are handed back.
// NULL, "", "live" (never persisted: Live is the absence of removed_at) and
// any other string say nothing about why the row was removed, and are reported
// as unknown rather than passed on as if they were an answer.
//
// Everything that says why a removed version is gone goes through it -- the
// as-of read, the version listing and the label bd versions prints -- so they
// cannot answer differently for the same row. It does not decide whether the
// row was removed; that is removed_at, which a caller reads first.
func NormalizeRemovedRestriction(stored string) AsOfRestriction {
restriction := AsOfRestriction(stored)
switch restriction {
case AsOfRestrictionGoneRetention, AsOfRestrictionGoneErasure,
AsOfRestrictionGoneReorganization, AsOfRestrictionUnknown:
return restriction
default:
return AsOfRestrictionUnknown
}
}
// AsOfSelector selects a point in an issue's version history to read: either
// a literal instant (At) or a previously-served version address (Address) --
// exactly one populated, mirroring the duality
// backend/conformance.AsOfSelector exposes to its own callers. This file
// owns its own copy rather than importing conformance's type (see the
// package-boundary note above).
type AsOfSelector struct {
At *time.Time
Address string
}
// AsOfReadResult is AsOfReadInTx's answer. State and Address are populated
// only on a served (non-refused) result; Restriction and Reason only on a
// refused one.
type AsOfReadResult struct {
Address string
State map[string]any
Refused bool
Restriction AsOfRestriction
Reason string
}
// AsOfVersionAddress is the address AsOfReadInTx serves for a resolved
// revision: a deterministic token over (issueID, revision). storeID is not
// part of the token -- a version address is meaningful only against its own
// issueID's rows, and Resolve is always called with issueID already known
// as its own separate parameter (matching the conformance fixture's own hook
// shape) -- but issueID is embedded anyway for readability/debuggability,
// per the design's stated rationale.
//
// Exported so each leg's AsOfReadFixture.MintAt can build the exact same
// token its own RecordVersionAtInTx write will resolve against, without
// duplicating the "asof:%s:%d" format in three separate packages.
func AsOfVersionAddress(issueID string, revision int64) string {
return fmt.Sprintf("asof:%s:%d", issueID, revision)
}
// parseAsOfVersionAddress reverses AsOfVersionAddress. ok is false for any
// address not shaped like one this file mints, INCLUDING one whose embedded
// issueID does not match the issueID the caller separately supplied -- a
// version address for a different issue is never valid in that caller's
// context.
func parseAsOfVersionAddress(address, issueID string) (revision int64, ok bool) {
parts := strings.SplitN(address, ":", 3)
if len(parts) != 3 || parts[0] != "asof" || parts[1] != issueID {
return 0, false
}
rev, err := strconv.ParseInt(parts[2], 10, 64)
if err != nil {
return 0, false
}
return rev, true
}
// resolveAsOfRevisionInTx resolves selector to the one issue_versions
// revision it names, for issueID: the version-address branch parses the
// revision straight out of the token, the instant branch is
//
// SELECT revision FROM issue_versions
// WHERE issue_id = ? AND change_at <= ?
// ORDER BY change_at DESC, revision DESC LIMIT 1
//
// -- the latest version accepted at or before T, with everything later
// strictly excluded (R7.1's own wording); revision DESC is a deterministic
// tie-break for two versions minted in the same instant. found is false
// when no row resolves either way -- the address named nothing this store
// holds, or no version of issueID existed yet at T -- which the caller
// reports as Unknown, never substituting a neighboring version (R8).
func resolveAsOfRevisionInTx(ctx context.Context, tx DBTX, issueID string, selector AsOfSelector) (revision int64, found bool, err error) {
if selector.Address != "" {
rev, ok := parseAsOfVersionAddress(selector.Address, issueID)
if !ok {
return 0, false, nil
}
var exists int
err := tx.QueryRowContext(ctx,
`SELECT 1 FROM issue_versions WHERE issue_id = ? AND revision = ?`, issueID, rev,
).Scan(&exists)
if errors.Is(err, sql.ErrNoRows) {
return 0, false, nil
}
if err != nil {
return 0, false, fmt.Errorf("as-of read: resolve address for %s: %w", issueID, err)
}
return rev, true, nil
}
if selector.At == nil {
return 0, false, fmt.Errorf("as-of read: selector for %s has neither an instant nor a version address", issueID)
}
var rev int64
err = tx.QueryRowContext(ctx,
`SELECT revision FROM issue_versions WHERE issue_id = ? AND change_at <= ? ORDER BY change_at DESC, revision DESC LIMIT 1`,
issueID, *selector.At,
).Scan(&rev)
if errors.Is(err, sql.ErrNoRows) {
return 0, false, nil
}
if err != nil {
return 0, false, fmt.Errorf("as-of read: resolve instant for %s: %w", issueID, err)
}
return rev, true, nil
}
// AsOfReadInTx answers R7.1's as-of read for issueID under selector: it
// resolves selector to one issue_versions row (resolveAsOfRevisionInTx),
// then reports that SAME row's own removed_at/removed_reason/
// removed_restriction. Asking as-of an earlier T than when a later removal
// happened is therefore not a refusal -- the earlier row itself was never
// marked removed, only whichever row a later MarkLatestVersionRemovedInTx
// call touched was.
//
// storeID is accepted only for signature parity (see the package doc above);
// it plays no role in resolution or scoping.
func AsOfReadInTx(ctx context.Context, tx DBTX, storeID, issueID string, selector AsOfSelector) (AsOfReadResult, error) {
_ = storeID
revision, found, err := resolveAsOfRevisionInTx(ctx, tx, issueID, selector)
if err != nil {
return AsOfReadResult{}, err
}
if !found {
return AsOfReadResult{
Refused: true,
Restriction: AsOfRestrictionUnknown,
Reason: fmt.Sprintf("no version of %s found at or before the requested point", issueID),
}, nil
}
var durableState []byte
var removedAt sql.NullTime
var removedReason sql.NullString
var removedRestriction sql.NullString
err = tx.QueryRowContext(ctx,
`SELECT durable_state, removed_at, removed_reason, removed_restriction
FROM issue_versions WHERE issue_id = ? AND revision = ?`,
issueID, revision,
).Scan(&durableState, &removedAt, &removedReason, &removedRestriction)
if errors.Is(err, sql.ErrNoRows) {
return AsOfReadResult{
Refused: true,
Restriction: AsOfRestrictionUnknown,
Reason: fmt.Sprintf("no version of %s found at or before the requested point", issueID),
}, nil
}
if err != nil {
return AsOfReadResult{}, fmt.Errorf("as-of read: load revision %d for %s: %w", revision, issueID, err)
}
if removedAt.Valid {
return AsOfReadResult{
Refused: true,
Restriction: NormalizeRemovedRestriction(removedRestriction.String),
Reason: removedReason.String,
}, nil
}
state := map[string]any{}
if len(durableState) > 0 {
if err := json.Unmarshal(durableState, &state); err != nil {
return AsOfReadResult{}, fmt.Errorf("as-of read: unmarshal durable state for %s revision %d: %w", issueID, revision, err)
}
}
return AsOfReadResult{Address: AsOfVersionAddress(issueID, revision), State: state}, nil
}
// MarkLatestVersionRemovedInTx is a test-support seam for R7.1's
// MakeUnanswerable fixture hook: it marks issueID's LATEST version row (by
// revision, not by time) as removed under restriction, independent of
// R17/R20's real (not yet implemented) hold/remove/erase primitives.
// "Latest" is correct for every AsOfReadContract case: each mints exactly
// one version before calling this, so the latest row and the row under test
// always coincide. Production code never calls this; only per-leg
// AsOfReadFixture.MakeUnanswerable implementations do.
func MarkLatestVersionRemovedInTx(ctx context.Context, tx DBTX, issueID string, restriction AsOfRestriction, reason string) error {
var revision int64
if err := tx.QueryRowContext(ctx,
`SELECT revision FROM issue_versions WHERE issue_id = ? ORDER BY revision DESC LIMIT 1`, issueID,
).Scan(&revision); err != nil {
return fmt.Errorf("as-of read: find latest version for %s: %w", issueID, err)
}
if _, err := tx.ExecContext(ctx,
`UPDATE issue_versions SET removed_at = ?, removed_reason = ?, removed_restriction = ? WHERE issue_id = ? AND revision = ?`,
time.Now().UTC(), reason, string(restriction), issueID, revision,
); err != nil {
return fmt.Errorf("as-of read: mark version removed for %s: %w", issueID, err)
}
return nil
}

View file

@ -0,0 +1,173 @@
package issueops
import (
"context"
"fmt"
"regexp"
"testing"
"time"
"github.com/DATA-DOG/go-sqlmock"
)
// TestAsOfReadMapsAnyStoredRestrictionOutsideTheVocabularyToUnknown is finding
// 5 of the #6661 review. removed_restriction is a free VARCHAR(30) written by
// whatever produced the row, and AsOfReadInTx handed it back as an
// AsOfRestriction by a plain cast. The type's doc says the answer is one of four
// values and that AsOfRestrictionLive is never returned (Live is the absence of
// removed_at, not a stored value), yet "live" and any other string passed
// straight through, so a caller switching on the result saw a value the
// vocabulary does not contain and could not tell it from an answer.
//
// A stored value outside the four says nothing about why the row was removed,
// so it is reported as unknown: this store cannot say. The hyphenated spelling
// is in the table because it is what the migration header used to tell a writer
// to store.
func TestAsOfReadMapsAnyStoredRestrictionOutsideTheVocabularyToUnknown(t *testing.T) {
const (
issueID = "bd-1"
revision = int64(3)
reason = "retention window elapsed"
)
removedAt := time.Date(2026, 9, 2, 0, 0, 0, 0, time.UTC)
for _, tt := range []struct {
name string
stored any // the removed_restriction column; nil is SQL NULL
want AsOfRestriction
}{
{"retention", "gone_retention", AsOfRestrictionGoneRetention},
{"erasure", "gone_erasure", AsOfRestrictionGoneErasure},
{"reorganization", "gone_reorganization", AsOfRestrictionGoneReorganization},
{"unknown", "unknown", AsOfRestrictionUnknown},
{"empty string", "", AsOfRestrictionUnknown},
{"NULL", nil, AsOfRestrictionUnknown},
{"live is never a stored answer", "live", AsOfRestrictionUnknown},
{"hyphenated spelling of a real value", "gone-retention", AsOfRestrictionUnknown},
{"arbitrary text", "quarantined", AsOfRestrictionUnknown},
} {
t.Run(tt.name, func(t *testing.T) {
_, mock, tx := beginMockTx(t)
mock.ExpectQuery(regexp.QuoteMeta(`SELECT 1 FROM issue_versions WHERE issue_id = ? AND revision = ?`)).
WithArgs(issueID, revision).
WillReturnRows(sqlmock.NewRows([]string{"1"}).AddRow(1))
mock.ExpectQuery(`SELECT durable_state, removed_at, removed_reason, removed_restriction\s+FROM issue_versions`).
WithArgs(issueID, revision).
WillReturnRows(sqlmock.NewRows([]string{"durable_state", "removed_at", "removed_reason", "removed_restriction"}).
AddRow([]byte("{}"), removedAt, reason, tt.stored))
got, err := AsOfReadInTx(context.Background(), tx, "store", issueID,
AsOfSelector{Address: AsOfVersionAddress(issueID, revision)})
if err != nil {
t.Fatalf("AsOfReadInTx: %v", err)
}
if !got.Refused {
t.Fatalf("a version row with removed_at set must be refused, got %+v", got)
}
if got.Restriction != tt.want {
t.Errorf("stored removed_restriction %#v: Restriction = %q, want %q", tt.stored, got.Restriction, tt.want)
}
if got.Reason != reason {
t.Errorf("Reason = %q, want %q: the stored reason must survive the restriction being normalised", got.Reason, reason)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet SQL expectations: %v", err)
}
})
}
}
// TestListVersionsAgreesWithTheAsOfReadOnWhyAVersionWasRemoved is finding 3 of the
// #6661 review. AsOfReadInTx puts a stored removed_restriction through the four-value
// vocabulary: anything outside it, a NULL or empty column included, is unknown. The
// listing returned the column as stored, for every row, so bd versions and its JSON
// could name a restriction the as-of read never gives ("live", "quarantined", a
// hyphenated spelling), say nothing for a removed version the as-of read calls
// unknown, and attach a restriction to a version that was never removed. Both reads
// must answer the same question the same way: a removed version's restriction is one
// of the vocabulary's values, and a version that is not removed carries none.
//
// The as-of read is the oracle, run on the same stored value, so the two cannot drift
// apart again whichever one is changed.
func TestListVersionsAgreesWithTheAsOfReadOnWhyAVersionWasRemoved(t *testing.T) {
const (
issueID = "bd-1"
revision = int64(3)
reason = "retention window elapsed"
)
changeAt := time.Date(2026, 9, 1, 12, 0, 0, 0, time.UTC)
removedAt := time.Date(2026, 9, 2, 0, 0, 0, 0, time.UTC)
for _, tt := range []struct {
name string
stored any // the removed_restriction column; nil is SQL NULL
}{
{"retention", "gone_retention"},
{"erasure", "gone_erasure"},
{"reorganization", "gone_reorganization"},
{"unknown", "unknown"},
{"empty string", ""},
{"NULL", nil},
{"live is never a stored answer", "live"},
{"hyphenated spelling of a real value", "gone-retention"},
{"arbitrary text", "quarantined"},
} {
for _, removed := range []bool{true, false} {
t.Run(fmt.Sprintf("%s/removed=%t", tt.name, removed), func(t *testing.T) {
// The listing selects COALESCE(removed_restriction, ''), so NULL reaches it as "".
listed, _ := tt.stored.(string)
var removedAtValue any // nil is SQL NULL: a version that was never removed
var storedReason string
if removed {
removedAtValue = removedAt
storedReason = reason
}
_, mock, tx := beginMockTx(t)
mock.ExpectQuery(`FROM issue_versions\s+WHERE issue_id = \?\s+ORDER BY revision DESC`).
WithArgs(issueID).
WillReturnRows(sqlmock.NewRows([]string{
"issue_id", "revision", "epoch", "change_actor", "change_agent", "change_message",
"change_at", "attribution_status", "removed_at", "removed_reason", "removed_restriction", "state_bytes",
}).AddRow(issueID, revision, int64(1), "", "", "", changeAt, "", removedAtValue, storedReason, listed, int64(0)))
mock.ExpectQuery(regexp.QuoteMeta(`SELECT 1 FROM issue_versions WHERE issue_id = ? AND revision = ?`)).
WithArgs(issueID, revision).
WillReturnRows(sqlmock.NewRows([]string{"1"}).AddRow(1))
mock.ExpectQuery(`SELECT durable_state, removed_at, removed_reason, removed_restriction\s+FROM issue_versions`).
WithArgs(issueID, revision).
WillReturnRows(sqlmock.NewRows([]string{"durable_state", "removed_at", "removed_reason", "removed_restriction"}).
AddRow([]byte("{}"), removedAtValue, storedReason, tt.stored))
versions, err := ListVersionsInTx(context.Background(), tx, issueID)
if err != nil {
t.Fatalf("ListVersionsInTx: %v", err)
}
asOf, err := AsOfReadInTx(context.Background(), tx, "store", issueID,
AsOfSelector{Address: AsOfVersionAddress(issueID, revision)})
if err != nil {
t.Fatalf("AsOfReadInTx: %v", err)
}
if len(versions) != 1 {
t.Fatalf("ListVersionsInTx returned %d versions, want 1", len(versions))
}
got := versions[0].RemovedRestriction
if removed {
if !asOf.Refused {
t.Fatalf("the as-of read of a removed version must be refused, got %+v", asOf)
}
if got != string(asOf.Restriction) {
t.Errorf("stored removed_restriction %#v: the listing says %q, the as-of read says %q; they must agree", tt.stored, got, asOf.Restriction)
}
return
}
if asOf.Refused {
t.Fatalf("the as-of read of a version that was not removed must be served, got %+v", asOf)
}
if got != "" {
t.Errorf("stored removed_restriction %#v on a version that was not removed: the listing says %q, want no restriction", tt.stored, got)
}
})
}
}
}

View file

@ -203,17 +203,32 @@ var beadDMLExemptions = map[string]string{
// equivalents used by the uow leg — version_completeness_test.go pins the
// set) immediately after those callers already invoke RecordEventInTx, so the
// mutation itself is already journaled by the time RecordVersionInTx runs.
// Its own UPDATE issues SET current_revision = ? only advances a
// denormalized pointer to match the snapshot row it just inserted into
// issue_versions (not a bead table, so it can't anchor the exemption on
// its own) — bookkeeping for an already-journaled mutation, not a second
// mutation that needs its own emit.
// Its own UPDATE issues SET current_revision = ?, updated_at = updated_at
// only advances a denormalized pointer to match the snapshot row it just
// inserted into issue_versions (not a bead table, so it can't anchor the
// exemption on its own), leaving updated_at where the mutation put it —
// bookkeeping for an already-journaled mutation, not a second mutation
// that needs its own emit.
"RecordVersionInTx": "advances the denormalized current_revision pointer to match a snapshot just inserted into issue_versions (not a bead table); called from the same entry points that already journal the mutation via RecordEventInTx, so this is bookkeeping for an already-journaled mutation, not a second one",
// RecordVersionForCreateInTx is RecordVersionInTx's create-shaped sibling
// (design §16.2b write-fence, be-h89oq): same entry points, same
// already-journaled-by-the-caller bookkeeping, plus stamping
// participation_generation on the row it just inserted into issue_versions.
"RecordVersionForCreateInTx": "advances the denormalized current_revision pointer and stamps participation_generation to match a snapshot just inserted into issue_versions (not a bead table); called from the same create entry points that already journal the mutation via RecordEventInTx, so this is bookkeeping for an already-journaled mutation, not a second one",
// RecordVersionAtInTx (R7.1 as-of read, gastownhall/beads#5898 rev 9,
// gastownhall/beads#6136) is RecordVersionInTx's test-support
// twin: it shares RecordVersionInTx's body (recordVersionAtInTx) but skips
// the versionedHistoryEnabled gate and takes an explicit historical
// timestamp, so an as-of-read conformance fixture can mint a version row
// dated in the past. It has no production caller and is not part of any
// mutationEntryPoints flow — only per-leg AsOfReadFixture.MintAt
// implementations call it, always directly, never from inside a journaled
// mutation. There is no separate bead mutation here for it to double-journal:
// the same "UPDATE issues SET current_revision only advances a pointer to
// a issue_versions snapshot, not a bead table" reasoning as RecordVersionInTx
// applies verbatim.
"RecordVersionAtInTx": "test-support twin of RecordVersionInTx (R7.1 as-of read); mints a historical-timestamped snapshot directly for conformance fixtures, with no production caller and no mutation of its own to journal — its UPDATE issues SET current_revision only advances a pointer to the issue_versions row it just inserted (not a bead table)",
}
// journalExemptMutations are mutation paths that deliberately do NOT journal

View file

@ -141,28 +141,32 @@ var funcNameExemptions = map[string]string{
// ExpectedVersion CAS reject a row it should still recognize.
"resolveOneConflictRow": "whole-row `theirs` adoption: the adopted row_lock already vouches for the (identical) adopted content",
// recordVersionInTx (version_history.go) is the private seam both public
// entry points — RecordVersionInTx (update-shaped) and
// recordVersionAtInTx (version_history.go) is the shared body behind all
// three public entry points: RecordVersionInTx (update-shaped),
// RecordVersionForCreateInTx (create-shaped, design §16.2b's write fence,
// be-h89oq) — delegate to; the three UPDATE issues statements this guard
// would otherwise flag live here, not in either public wrapper, so the
// exemption is keyed to this name. It runs immediately after the mutation
// it is snapshotting — create.go/update.go's own writes, or domain/db's
// Insert/Update — and those callers have already minted a fresh row_lock
// in that same INSERT/UPDATE, in the same transaction. Every UPDATE
// issues statement recordVersionInTx issues writes only bookkeeping
// columns: the update-shaped and create-shaped UPDATE issues SET
// current_revision = ... statements advance the denormalized pointer to
// the issue_versions row just inserted (the create-shaped one also stamps
// participation_generation in the same statement), and the no-history
// stamp sets participation_generation alone on a create-shaped row it does
// not version. None touches row_lock at all (not even to carry the
// existing value forward) because reminting here would bump the token a
// second time within one transaction, invalidating the RowVersion/CAS
// be-h89oq) and the R7.1 test-support twin RecordVersionAtInTx
// (gastownhall/beads#5898 rev 9, gastownhall/beads#6136).
// The three UPDATE issues statements this guard would otherwise flag live
// here, not in any public wrapper, so the exemption is keyed to this name.
// The two production entry points' callers run it immediately after the
// mutation it is snapshotting — create.go/update.go's own writes, or
// domain/db's Insert/Update — and those callers have already minted a
// fresh row_lock in that same INSERT/UPDATE, in the same transaction.
// RecordVersionAtInTx's fixture-only callers likewise run it only after a
// bare-create has already minted the row's row_lock, never as a row's
// first write. Every UPDATE issues statement this function issues writes
// only bookkeeping columns: the update-shaped and create-shaped UPDATE
// issues SET current_revision = ... statements advance the denormalized
// pointer to the issue_versions row just inserted (the create-shaped one
// also stamps participation_generation in the same statement), and the
// no-history stamp sets participation_generation alone on a create-shaped
// row it does not version. None touches row_lock at all (not even to carry
// the existing value forward) because reminting here would bump the token
// a second time within one transaction, invalidating the RowVersion/CAS
// value the primary mutation's own caller already captured and could
// cause a legitimate subsequent CAS check to fail as a spurious lost
// update.
"recordVersionInTx": "runs after the primary mutation already minted a fresh row_lock in the same transaction; reminting here would double-bump the token and invalidate the RowVersion/CAS value already returned to that mutation's caller — covers all three of its UPDATE issues statements (the update-shaped and create-shaped current_revision advances and the no-history participation_generation stamp), since both public entry points delegate to this one private seam",
"recordVersionAtInTx": "runs after the primary mutation (or, for RecordVersionAtInTx's fixture-only callers, a bare-create) already minted a fresh row_lock in the same transaction; reminting here would double-bump the token and invalidate the RowVersion/CAS value already returned to that mutation's caller — covers all three of its UPDATE issues statements (the update-shaped and create-shaped current_revision advances and the no-history participation_generation stamp), since all three public entry points delegate to this one shared body",
}
// TestAllIssueRowWritesStampRowLock is the load-bearing completeness guard for

View file

@ -359,6 +359,62 @@ func sortedShapeKeys(m map[string]string) []string {
return keys
}
// versionTestSupportMints sit outside the shape split above, explicitly: they
// are neither create-shaped, dual-shape nor update-shaped. They are not
// mutation entry points (versionedEntryPoints) but the seam's test-support
// twin, exempt in versionExemptions, and they reach the shared body directly
// rather than through either entry. Each must reach neither
// RecordVersionForCreateInTx nor RecordVersionInTx: the unfenced mint
// (mintUnfenced) never stamps participation_generation, so a conformance
// fixture's controlled-timestamp mint cannot promote a legacy row, and it is
// not gated or fenced, so routing it through the update-shaped entry would
// silently stop the as-of fixtures from minting history-off rows.
var versionTestSupportMints = map[string]string{
"RecordVersionAtInTx": "R7.1 as-of read fixtures' controlled-timestamp mint (mintUnfenced): no gate, no fence, no stamp",
}
// TestTestSupportMintsStayOutsideTheShapeSplit pins versionTestSupportMints.
func TestTestSupportMintsStayOutsideTheShapeSplit(t *testing.T) {
fns, createShaped, updateShaped := versionShapedMints(t)
shapeListed := map[string]string{}
for _, entry := range versionedEntryPoints {
shapeListed[entry] = "versionedEntryPoints"
}
for _, entry := range versionCreateShapedEntryPoints {
shapeListed[entry] = "versionCreateShapedEntryPoints"
}
for _, site := range versionCreateShapedMintSites {
shapeListed[site] = "versionCreateShapedMintSites"
}
for entry := range versionDualShapeEntryPoints {
shapeListed[entry] = "versionDualShapeEntryPoints"
}
for site := range versionDualShapeMintSites {
shapeListed[site] = "versionDualShapeMintSites"
}
for _, name := range sortedShapeKeys(versionTestSupportMints) {
if versionTestSupportMints[name] == "" {
t.Errorf("%s has an empty test-support reason", name)
}
if _, defined := fns[name]; !defined {
t.Errorf("test-support mint %q not found in issueops — was it renamed? update versionTestSupportMints", name)
continue
}
if list, listed := shapeListed[name]; listed {
t.Errorf("test-support mint %q is listed in %s; it is the seam's twin, not a mutation entry point or mint site, and stays outside the shape split", name, list)
}
if createShaped[name] {
t.Errorf("test-support mint %q reaches RecordVersionForCreateInTx, so a fixture's mint can stamp participation_generation and promote a legacy record (R2.3)", name)
}
if updateShaped[name] {
t.Errorf("test-support mint %q reaches RecordVersionInTx, whose gate and fence would stop an as-of fixture from minting a history-off row", name)
}
if _, exempt := versionExemptions[name]; !exempt {
t.Errorf("test-support mint %q is not in versionExemptions; it is the seam's twin, not a mutation entry point", name)
}
}
}
// versionExemptions are exported functions the DML detector flags as writing a
// work-bead table but which legitimately do NOT mint a version for the row
// they write, each with a reason. The staleness check fails if any stops being
@ -433,6 +489,15 @@ var versionExemptions = map[string]string{
// bookkeeping half of the mint, not a mutation that needs its own.
"RecordVersionInTx": "the seam itself; advances current_revision to match the row it just inserted",
"RecordVersionForCreateInTx": "the seam's create-shaped sibling; stamps participation_generation and advances current_revision to match the row it just inserted",
// RecordVersionAtInTx (R7.1 as-of read, gastownhall/beads#5898 rev 9,
// gastownhall/beads#6136) shares RecordVersionInTx's body
// (recordVersionAtInTx) but deliberately does not call RecordVersionInTx
// itself — it exists precisely to bypass RecordVersionInTx's
// versionedHistoryEnabled gate, so an as-of-read conformance fixture can
// mint a version dated in the past. It is the seam too, by the same
// reasoning as RecordVersionInTx's own entry above.
"RecordVersionAtInTx": "test-support twin of RecordVersionInTx, sharing its body; the seam itself, not a caller of it — advances current_revision to match the row it just inserted",
}
// versionNeverMints pins the deliberate NOT-versioned rulings from the other

View file

@ -1,15 +1,21 @@
package issueops
import (
"bytes"
"context"
"database/sql"
"encoding/json"
"errors"
"fmt"
"io"
"math"
"strconv"
"sync"
"time"
"github.com/gowebpki/jcs"
"github.com/steveyegge/beads/internal/types"
)
// Dual-write issue-version history records every accepted issue mutation as a
@ -81,6 +87,53 @@ import (
// costs no extra round-trip. Tracked as gastownhall/beads#6379 alongside
// item 4.
// THE MINT'S REFUSAL IS AN INTEGRITY BACKSTOP, NOT AN ADMISSION POLICY, AND IT
// BINDS THE ROWS THAT PARTICIPATE IN HISTORY.
// canonicalDurableState refuses what it cannot record faithfully -- a number
// outside the I-JSON exact-integer range, wherever in the issue it sits (in
// metadata, or in a gate's timeout, which is written as nanoseconds), and
// duplicate keys -- and it does so inside the mutating transaction, so with
// history on a write that introduces such a value to a row that participates
// fails atomically and commits nothing: refusing at the mint IS refusing the
// write, for every store-mediated write to such a row. That is what keeps a
// version's content token meaning what it says. It is not a rule about what an
// issue may hold, which stays open while history is off, and that is the case to
// plan for: a row that participates in history (participation_generation is set),
// written while history was off or by a path that does not mint (such as bd sql,
// an older bd or a pull from a clone that had history off), that already holds
// such a value would fail every later write to it once history is on. `bd config
// set versioned-history.enabled true` therefore checks the store first, with the
// check the mint runs (CheckIssueVersionable, over every issue the mint would
// version), and refuses, writing nothing, while any of them holds a value it would
// refuse.
//
// A row that does not participate is outside all of this. Design §16.2b makes an
// update-shaped write to a legacy record (participation_generation NULL) a skip,
// not a refusal: the fence returns before the snapshot is canonicalized, so no
// version is minted and the gate never runs. Such a write succeeds whatever the
// row's metadata holds, exactly as it would with history off, because no version
// row, and so no content token, comes of it. A create-shaped mint never meets a
// legacy row (its call site has just inserted the row), so it runs the gate
// whenever it mints; a new row flagged no-history is stamped but not minted, so
// nothing is canonicalized for it. The switch's check cannot see participation,
// so it checks legacy rows too: an over-approximation that can only refuse more.
//
// That check ran once, at that moment. Nothing keeps a writer that does not mint
// from adding such a row afterwards, even right after the switch is on; if the
// row participates, the first write to it then fails with the same refusal, and
// the same fix applies. Making the check and the write of the setting one
// transaction would narrow that window, not close it. Turning history on through
// the environment or config.yaml does not pass through that command at all; for
// those planes this refusal is the control on the rows that participate, and
// finding the rows ahead of time is a bd doctor check (gastownhall/beads#6379
// item 3).
//
// Duplicate keys are the exception to "the case to plan for". A Dolt JSON column
// collapses duplicate keys when it stores a document, so on a Dolt store neither
// the mint nor the scan can ever see one, and the refusal is a defense for a
// backend registered through backends.Lookup that keeps them. It is worth
// checking again whenever Dolt is upgraded.
var versionedHistoryTransactions sync.Map // map[DBTX]bool; entries live for one transaction
// ScopeVersionedHistoryTransaction associates versioned-history activation
@ -179,11 +232,18 @@ func attributionStatusForActor(actor string) string {
// (1.0 is 1, 1e300 is 1e+300), only the escapes RFC 8785 requires -- so the
// same issue state always yields the same bytes, whatever encoding/json's
// formatting happens to be. Numbers are canonicalized as IEEE-754 doubles
// (RFC 8785 section 3.2.2.3), so an integer past 2^53 is rounded here, once,
// by the writer, before anything hashes it: the stored bytes and the hashed
// bytes are the same bytes. types.Issue carries no such magnitudes (its
// integers are ordinals and priorities), but the rule is stated so nobody
// expects int64 fidelity from the token.
// (RFC 8785 section 3.2.2.3), so canonicalization alone would round a number
// past 2^53 here, once, by the writer, before anything hashes it; the admission
// gate (refuseUnrepresentableIntegers) refuses such a number instead, so the
// stored bytes and the hashed bytes are the same bytes and nothing is rounded
// silently. Two fields of types.Issue can reach that magnitude: Metadata, and
// Timeout, a time.Duration that encoding/json writes as a count of nanoseconds,
// so a gate timeout above 2^53-1 ns (about 104.25 days) is refused. Its other
// integers are priorities, ordinals and counts held in 32-bit columns.
//
// A refusal names the top-level field it was found in (nameRefusedField). The
// success path reads the document once; the field is located only after a
// refusal.
//
// Two properties worth stating because a hand-rolled canonicalizer would get
// them wrong. First, jcs.Transform normalizes away encoding/json's HTML
@ -191,18 +251,95 @@ func attributionStatusForActor(actor string) string {
// Go's escaping policy. Second, a snapshot that cannot be canonicalized
// deliberately FAILS the mutation: types.Issue.Metadata is a json.RawMessage
// passed through verbatim, RFC 8785 rejects duplicate keys, and this seam
// returns the error to its caller, which aborts the transaction. An issue
// whose metadata column already holds duplicate keys (reachable through bd
// sql or a hand-written JSONL import) therefore mutates fine with the flag
// off and becomes unmutatable with it on. Fail-closed is the policy for now
// -- bytes that could canonicalize two ways would not be a content token --
// and whether to normalize such metadata first, or to find such rows with
// returns the error to its caller, which aborts the transaction. A backend that
// keeps duplicate keys in a metadata document would therefore let an issue
// mutate with the flag off and make it unmutatable with it on, if it participates
// in history; a legacy row stays writable, because the fence skips it before this
// function runs. Dolt does not keep them (see the note above), so on a Dolt
// store this refusal is never reached. Fail-closed is the policy for a backend
// that does -- bytes that could canonicalize two ways would not be a content
// token -- and whether to normalize such metadata first, or to find such rows with
// bd doctor, is gastownhall/beads#6379 (item 3).
func canonicalDurableState(issue any) ([]byte, error) {
marshaled, err := json.Marshal(issue)
if err != nil {
return nil, err
}
if err := refuseUnrepresentableIntegers(marshaled); err != nil {
return nil, nameRefusedField(marshaled, err)
}
canonical, err := jcsCanonicalize(marshaled)
if err != nil {
return nil, nameRefusedField(marshaled, err)
}
return canonical, nil
}
// refusedFieldError is a refusal from canonicalDurableState that has been traced
// to the top-level field of the issue it was found in. It unwraps to the refusal
// itself, so errors.Is(err, ErrIntegerNotRepresentable) still answers.
type refusedFieldError struct {
field string
err error
}
func (e *refusedFieldError) Error() string { return fmt.Sprintf("%v (field %q)", e.err, e.field) }
func (e *refusedFieldError) Unwrap() error { return e.err }
// nameRefusedField finds the top-level field of marshaled, one issue as a JSON
// object, that the two checks canonicalDurableState runs refuse on their own, and
// returns err naming it. It runs only after a refusal, so what a successful
// canonicalization costs does not change. A document it cannot attribute, one
// that is not an object or in which no single field is refused alone, comes back
// unchanged.
func nameRefusedField(marshaled []byte, err error) error {
dec := json.NewDecoder(bytes.NewReader(marshaled))
if open, derr := dec.Token(); derr != nil || open != json.Delim('{') {
return err
}
for dec.More() {
keyToken, derr := dec.Token()
key, isString := keyToken.(string)
if derr != nil || !isString {
return err
}
var value json.RawMessage
if derr := dec.Decode(&value); derr != nil {
return err
}
if refuseUnrepresentableIntegers(value) != nil {
return &refusedFieldError{field: key, err: err}
}
if _, jerr := jcsCanonicalize(value); jerr != nil {
return &refusedFieldError{field: key, err: err}
}
}
return err
}
// jcsCanonicalize is canonicalDurableState's RFC 8785 (JCS) step alone, below
// the admission gate rather than behind it.
//
// IT MUST EXIST SEPARATELY because refuseUnrepresentableIntegers and RFC 8785
// disagree on purpose, not by oversight: RFC 8785 section 3.2.2.3 canonicalizes
// ANY number as a double, whatever its magnitude, while the admission gate
// refuses any number whose nearest double is past 2^53-1 outright (see
// refuseUnrepresentableIntegers's doc comment on why that rule has no
// notation carve-out). One of the RFC 8785 vectors this store pins conformance
// against, testdata/jcs/input/values.json, both ships from the spec's own
// reference suite AND contains 1E30 -- a value the gate refuses and RFC 8785
// requires canonicalizing to 1e+30. Routing that vector through
// canonicalDurableState would force a choice between weakening spec-conformance
// coverage and putting a magnitude exception in the gate, and neither is
// right: the gate's refusal is a policy decision about what this store admits,
// not a claim about what JCS can canonicalize. jcsCanonicalize lets a caller
// ask the second question without the first, so TestCanonicalDurableStateIsJCS
// can hold the RFC 8785 vectors to the spec's own bytes -- including
// values.json -- while refuseUnrepresentableIntegers's refusal of the same
// magnitude is pinned separately, in the admission tests
// (version_history_integer_admission_test.go), where it belongs.
func jcsCanonicalize(marshaled []byte) ([]byte, error) {
canonical, err := jcs.Transform(marshaled)
if err != nil {
return nil, fmt.Errorf("canonicalize (RFC 8785): %w", err)
@ -210,6 +347,129 @@ func canonicalDurableState(issue any) ([]byte, error) {
return canonical, nil
}
// ErrIntegerNotRepresentable is the refusal for a JSON number outside the I-JSON
// exact-integer range: one whose nearest binary64 has magnitude above 2^53-1, or
// that overflows binary64.
//
// The name is historical. It began as the refusal for an integer literal binary64
// cannot hold exactly, and it now also covers a literal spelled as a fraction whose
// nearest double lies at or beyond 2^53, which RFC 8785 would round to an integer
// just the same. It is kept rather than renamed so that nothing matching it with
// errors.Is has to change.
var ErrIntegerNotRepresentable = errors.New("number is outside the I-JSON exact-integer range (magnitude above 2^53-1)")
// maxExactJSONInteger is 2^53-1, the largest magnitude in the I-JSON
// interoperable integer range (RFC 7493 section 2.2), and BDP's admission law
// (gastownhall/bdp#21) makes a literal past it invalid rather than merely lossy.
// binary64 does represent 2^53 exactly, but 2^53 and 2^53+1 round to the same
// double, so from 2^53 up a literal can no longer be told from its neighbor.
const maxExactJSONInteger = 1<<53 - 1
// refuseUnrepresentableIntegers rejects marshaled if any JSON number literal in
// it is outside the I-JSON exact-integer range: the binary64 nearest to the
// literal has magnitude above 2^53-1, or the literal overflows binary64. Which of
// JSON's number forms spells the value -- bare integer, decimal or exponential --
// does not matter.
//
// WHY REFUSE RATHER THAN ROUND. jcs.Transform canonicalizes numbers as
// IEEE-754 doubles (RFC 8785 section 3.2.2.3), so 9007199254740993 becomes
// 9007199254740992 on the way in. That is not a formatting difference, it is
// a DIFFERENT VALUE, and it collapses two distinct issue states onto one
// durable_state and therefore one content token -- the token can no longer
// tell them apart, and a reader comparing tokens concludes the second write
// was a no-op. Rounding is silent; refusing is not.
//
// This seam is the admission gate, one layer above RecordVersionInTx, which
// is where BDP puts it: an authority adapting an existing store "MUST map or
// refuse values outside this contract before it serves them as BDP
// Resources" (gastownhall/bdp#20 section 5.1).
//
// THE NEAREST DOUBLE, NOT THE LITERAL'S SPELLING. Each literal is classified
// with strconv.ParseFloat, which returns the correctly rounded binary64 in time
// linear in the length of the literal, and that is exactly the value RFC 8785
// canonicalizes the literal to. So "the nearest double is past the range" and
// "canonicalization would move this literal past the range" are one question,
// and the gate is closed under its own canonicalization: whatever it admits
// canonicalizes to a form it also admits. A rule keyed to integer VALUES was
// not: 9007199254740991.5 is not an integer, so it was admitted, yet it rounds
// to 2^53 and its canonical bytes were then refused. Here 9007199254740993,
// 9007199254740993.0 and 9.007199254740993e15 are refused alike, and so is
// 9007199254740993.5, whose nearest double is 2^53+2. An overflow
// (strconv.ErrRange) is a refusal, not a syntax error; a magnitude too small for
// binary64 rounds to zero and is admitted.
//
// NOTHING IS BUILT PER EXPONENT. ParseFloat never constructs the number, so a
// literal such as 1e1000000 is an overflow refused in the time it takes to read
// it, not a million-digit integer built first and then compared. The gate runs
// inside the writer's transaction, so a classifier whose cost grew with an
// exponent would be a way to hold that transaction open with a few
// exponent-heavy metadata values.
//
// SCOPE. Ordinary fractions are admitted: 0.1 is canonicalized to its nearest
// double, which is how the store holds it. Whether two literals that share a
// nearest double can be told apart inside the store is a property of the store,
// not of this gate, and it is the one thing a Dolt upgrade could change: the
// store-level tests on each leg assert that no two literals the store reads back
// as different numbers are both admitted with one canonical form, and log what
// each Dolt does to a number, rather than assuming it. An integer past 2^53 is
// refused whatever the store does to it: a store may keep it exactly, where RFC
// 8785 would round it, and a store that already rounds it hands the gate an
// integer-valued double, which the rule refuses just the same. A JSON null is a
// token, not a number: only json.Number tokens are classified. Of types.Issue's
// own fields only Metadata (a json.RawMessage passed through verbatim) and
// Timeout (a time.Duration, written as nanoseconds) can reach this bound; its
// other integers are priorities, ordinals and counts held in 32-bit columns.
func refuseUnrepresentableIntegers(marshaled []byte) error {
dec := json.NewDecoder(bytes.NewReader(marshaled))
dec.UseNumber()
for {
tok, err := dec.Token()
if err == io.EOF {
return nil
}
if err != nil {
return fmt.Errorf("scan for unrepresentable integers: %w", err)
}
num, ok := tok.(json.Number)
if !ok {
continue
}
lit := num.String()
f, err := strconv.ParseFloat(lit, 64)
if err != nil && !errors.Is(err, strconv.ErrRange) {
return fmt.Errorf("scan for unrepresentable integers: invalid JSON number literal %q: %w", lit, err)
}
if math.IsInf(f, 0) || math.Abs(f) > maxExactJSONInteger {
return fmt.Errorf("%w: %s", ErrIntegerNotRepresentable, lit)
}
}
}
// CheckIssueVersionable reports whether issue could be minted into a version's
// durable_state. It is canonicalDurableState's own refusal -- the admission gate,
// then RFC 8785 canonicalization, over the whole marshaled issue -- so it refuses
// a number outside the I-JSON exact-integer range (ErrIntegerNotRepresentable)
// wherever in the issue it sits, in metadata or in a gate's timeout, and it also
// refuses duplicate keys, which RFC 8785 cannot canonicalize. The refusal names
// the top-level field it found the value in.
//
// It exists so that the check made when versioned history is switched on and
// the check the mint makes cannot disagree: FindUnversionable runs this over
// every issue the mint would version, and a store that passes it cannot then
// refuse the first write to a row it cleared. It is the one such check. A check
// over only part of an issue, its metadata say, can pass what the mint refuses (a
// gate's timeout can be past the range while its metadata is fine), so none may
// be exported beside it.
//
// The issue it is handed need not be the one the mint sees. The scan reads a
// lite projection, with no heavy text columns, no labels and no dependencies,
// and that is sound only because none of what it leaves out can hold a number.
// The tests in version_history_preenable_scan_test.go pin that.
func CheckIssueVersionable(issue *types.Issue) error {
_, err := canonicalDurableState(issue)
return err
}
// RecordVersionInTx mints one issue_versions row for issueID and advances
// issues.current_revision to match, as of tx (read-your-writes within the
// same transaction). A no-op when versioned history is disabled for tx, or
@ -239,8 +499,15 @@ func canonicalDurableState(issue any) ([]byte, error) {
// for a create-shaped mutation instead: a brand-new row has no legacy state
// to preserve, so that entry point stamps the column rather than checking
// it.
//
// The skip is whole: nothing about a legacy record is read, canonicalized or
// admitted, so such a write is neither versioned nor refused (design §16.2b: a
// skip, not a refusal).
func RecordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string) error {
return recordVersionInTx(ctx, tx, issueID, actor, false)
if !versionedHistoryEnabled(tx) {
return nil
}
return recordVersionAtInTx(ctx, tx, issueID, actor, time.Now().UTC(), mintUpdate)
}
// RecordVersionForCreateInTx is RecordVersionInTx's create-shaped sibling
@ -261,48 +528,135 @@ func RecordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string) erro
// a wisp is never versioned (FR-8). That covers an ordinary wisp create and
// an unflagged wisps-table row (import's "wisp_plane" marker) alike.
func RecordVersionForCreateInTx(ctx context.Context, tx DBTX, issueID, actor string) error {
return recordVersionInTx(ctx, tx, issueID, actor, true)
}
func recordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string, isCreate bool) error {
if !versionedHistoryEnabled(tx) {
return nil
}
return recordVersionAtInTx(ctx, tx, issueID, actor, time.Now().UTC(), mintCreate)
}
// RecordVersionAtInTx is RecordVersionInTx's test-support twin: it mints a
// version row at a caller-chosen change_at instead of time.Now(), and --
// deliberately -- does not gate on versionedHistoryEnabled at all, since its
// whole purpose is controlled-timestamp minting for conformance fixtures
// (R7.1's AsOfReadFixture.MintAt, backend/conformance/versioned_read_contract.go)
// regardless of a store's activation state. Production code never calls
// this; only per-leg as-of-read fixtures do, so their bare issue-create step
// can stay history-off (no unwanted real-time row) while still minting the
// exact versions a test needs at the instants it needs them.
//
// It bypasses design §16.2b's write fence exactly as it bypasses the gate:
// it ignores participation_generation and never stamps it, so it mints for
// a legacy row and a participating row alike and leaves the column as it
// found it. The fence and the stamp belong to the production entry points
// above, never to a fixture's controlled-timestamp mint. The plane rule is
// not the fence, and it does apply: a row the wisps table holds, or one
// flagged Ephemeral or NoHistory, mints nothing here either.
func RecordVersionAtInTx(ctx context.Context, tx DBTX, issueID, actor string, at time.Time) error {
return recordVersionAtInTx(ctx, tx, issueID, actor, at, mintUnfenced)
}
// versionMintKind says how recordVersionAtInTx treats design §16.2b's write
// fence, the one thing RecordVersionInTx, RecordVersionForCreateInTx and
// RecordVersionAtInTx do not share.
type versionMintKind int
const (
// mintUpdate is an update-shaped mutation (RecordVersionInTx): the fence
// applies, and a record whose participation_generation is NULL mints nothing.
mintUpdate versionMintKind = iota
// mintCreate is a create-shaped mutation (RecordVersionForCreateInTx): a
// brand-new row has no legacy state to preserve, so the fence does not
// apply and the mint stamps participation_generation instead.
mintCreate
// mintUnfenced is RecordVersionAtInTx's test-support mint: no fence and no
// stamp, exactly as it behaved before the fence existed. Like the other
// two, it mints nothing for a row that is not on the issues plane.
mintUnfenced
)
// recordVersionAtInTx is RecordVersionInTx, RecordVersionForCreateInTx and
// RecordVersionAtInTx's shared body, taking at where the callers differ:
// time.Now().UTC() for the production gate-checked paths, a caller-chosen
// instant for test minting; and kind, which says whether design §16.2b's
// write fence applies (mintUpdate), the mint stamps participation_generation
// (mintCreate) or neither (mintUnfenced). The no-op rules documented on
// RecordVersionInTx above (wisps) apply here too, since this is that
// function's entire mechanism minus the gate.
func recordVersionAtInTx(ctx context.Context, tx DBTX, issueID, actor string, at time.Time, kind versionMintKind) error {
// change_at is DATETIME(6) as of migration 0069, and this function
// deliberately does NOT floor `at` to the second.
//
// It used to. While 0067's plain DATETIME (precision 0) was in force that
// floor was load-bearing: Dolt's datetime(0) does not truncate sub-second
// input, it ROUNDS half-up, so a change_at of 13:32:04.77 stored as
// 13:32:05 -- strictly LATER than the instant it recorded. That breaks
// AsOfReadInTx's "latest version accepted at or before T"
// (resolveAsOfRevisionInTx, asof_read.go) for any T between the true
// instant and the rounded-up one. Flooring first left nothing to round.
//
// 0069 widened change_at and removed_at to DATETIME(6). That moves the
// rounding below the microsecond rather than removing it: GMS still rounds
// DATETIME(6) input to the microsecond (.1234567 is stored as .123457).
// The remainder is harmless to that lookup (resolveAsOfRevisionInTx),
// because the instant it compares against is rounded the same way, so a
// stored value still compares equal to the instant it was minted at. What the widening does
// make is the floor actively harmful: it threw away the microseconds the
// widening exists to keep. Two versions minted in the same second
// collapsed onto one stored value and became indistinguishable
// by change_at -- which defeats --at, the only PORTABLE selector the read
// surface offers while revision stays a local ordinal and no durable
// version address has shipped. Measured before this change on a store
// carrying both: four versions minted in one second all read back
// 15:40:38.000000.
//
// So the column's precision is now relied on rather than worked around.
// Pinned by TestRecordVersionKeepsSubSecondChangeAt below; the column's
// own half of the contract is pinned by
// TestMigration0069ChangeAtSurvivesSubSecondPrecisionThroughDoltCLI in
// internal/storage/schema. MarkLatestVersionRemovedInTx (asof_read.go)
// needs no matching change -- it already passes time.Now().UTC() straight
// through, so removed_at was never floored.
issue, err := GetIssueInTx(ctx, tx, issueID)
if err != nil {
return fmt.Errorf("versioned history: snapshot %s: %w", issueID, err)
}
// A flagged row (Ephemeral || NoHistory) is never versioned, so an
// update-shaped call has nothing to do. A create-shaped one may still
// have to declare participation; see the IsWisp branch below.
if IsWisp(issue) && !isCreate {
// update-shaped call, or the test-support mint, has nothing to do. A
// create-shaped one may still have to declare participation; see the
// IsWisp branch below.
if IsWisp(issue) && kind != mintCreate {
return nil
}
// design §16.2b write fence. Read straight off the row rather than
// through types.Issue: participation_generation is dual-write
// bookkeeping, not part of the issue's own content model, so it stays
// out of the durable_state snapshot canonicalDurableState marshals
// below. isCreate skips the check entirely (a brand-new row has no
// legacy state to preserve, and this same function stamps the column
// itself further down); an update-shaped call against a NULL (legacy)
// value returns here, before either half of this seam's write runs.
// BD_IGNORE_SCHEMA_SKEW (internal/storage/schema/schema.go) has no
// bearing on this check: it downgrades CheckForwardDrift's
// migration-cursor refusal, a different plane than this column's real
// per-row data.
//
// THE TABLE THAT HOLDS THE ROW decides its plane, not its flags. IsWisp
// reads Ephemeral || NoHistory, and a wisps-table row can carry neither:
// bd mol squash clears a wisp root's flag in place, and import's
// "wisp_plane" marker routes an unflagged row to wisps. Such a row passes
// IsWisp, but there is no issues row for it, so this read finds nothing.
// No issues row means nothing to version (FR-8), for an update- or a
// create-shaped call alike: mint nothing and let the mutation proceed,
// rather than abort it on sql.ErrNoRows. GetIssueInTx resolved the
// snapshot above, so the row exists; ErrNoRows here can only mean it is
// in the wisps table.
// create-shaped call alike, and for the test-support mint too, since this
// is the plane rule and not the fence: mint nothing and let the mutation
// proceed, rather than abort it on sql.ErrNoRows. GetIssueInTx resolved
// the snapshot above, so the row exists; ErrNoRows here can only mean it
// is in the wisps table.
//
// The same read is design §16.2b's write fence. participation_generation
// is read straight off the row rather than through types.Issue: it is
// dual-write bookkeeping, not part of the issue's own content model, so it
// stays out of the durable_state snapshot canonicalDurableState marshals
// below. Only an update-shaped call (mintUpdate) acts on its value: a
// brand-new row (mintCreate) has no legacy state to preserve, and this
// same function stamps the column itself further down; the test-support
// mint (mintUnfenced) ignores it. An update-shaped call against a NULL
// (legacy) value returns here, before either half of this seam's write
// runs. The fence runs before the admission gate (canonicalDurableState)
// on purpose, so a legacy record is skipped whole: nothing about it is
// canonicalized, admitted or refused.
// BD_IGNORE_SCHEMA_SKEW (internal/storage/schema/schema.go) has no
// bearing on this check: it downgrades CheckForwardDrift's
// migration-cursor refusal, a different plane than this column's real
// per-row data.
var participationGeneration sql.NullInt64
if err := tx.QueryRowContext(ctx,
"SELECT participation_generation FROM issues WHERE id = ?", issueID,
@ -337,7 +691,7 @@ func recordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string, isCr
}
return nil
}
if !isCreate && !participationGeneration.Valid {
if kind == mintUpdate && !participationGeneration.Valid {
return nil
}
@ -389,12 +743,12 @@ func recordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string, isCr
`INSERT INTO issue_versions
(issue_id, revision, epoch, durable_state, change_actor, change_agent, change_message, change_at, attribution_status)
VALUES (?, ?, ?, ?, ?, NULL, NULL, ?, ?)`,
issueID, newRevision, epoch, durableState, actor, time.Now().UTC(), attributionStatusForActor(actor),
issueID, newRevision, epoch, durableState, actor, at, attributionStatusForActor(actor),
); err != nil {
return fmt.Errorf("versioned history: insert version row for %s: %w", issueID, err)
}
if isCreate {
if kind == mintCreate {
// Stamps participation_generation in the same statement that advances
// current_revision — design §16.2b's "positive declaration sourced
// from store_epoch.epoch," minted here from the epoch already read
@ -410,8 +764,16 @@ func recordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string, isCr
}
return nil
}
// The same updated_at rule for every update-shaped mint. Advancing
// current_revision is bookkeeping, not an edit, but on its own it fires
// the ON UPDATE CURRENT_TIMESTAMP clause, so a label or dependency write
// that never touches updated_at would move it to the wall clock only
// while history is on, and an import's stale-upsert check would then
// reject the source's next edit. History on must leave updated_at
// exactly where history off does (the same reason #4298 and
// blocked_state.go's mark/unmark templates assign it to itself).
if _, err := tx.ExecContext(ctx,
"UPDATE issues SET current_revision = ? WHERE id = ?", newRevision, issueID,
"UPDATE issues SET current_revision = ?, updated_at = updated_at WHERE id = ?", newRevision, issueID,
); err != nil {
return fmt.Errorf("versioned history: advance current_revision for %s: %w", issueID, err)
}

View file

@ -38,22 +38,63 @@ import (
// be the JCS form or the token would depend on which marshaler ran first.
// Every case is also checked to be a fixed point of canonicalization, and a
// duplicate-key input is refused rather than silently resolved.
//
// THE OFFICIAL VECTORS RUN BELOW THE ADMISSION GATE, through jcsCanonicalize
// rather than canonicalDurableState, and this is deliberate, not an
// inconsistency: testdata/jcs/input/values.json -- from the spec's own
// reference suite, not a case authored for this repo -- contains 1E30, an
// integer-valued literal past 2^53-1 that refuseUnrepresentableIntegers now
// refuses outright (see version_history.go's refuseUnrepresentableIntegers
// and jcsCanonicalize doc comments). RFC 8785 conformance is a claim about
// the canonicalizer, not about this store's admission policy, so weakening
// or dropping that vector to fit the gate would be the wrong trade; the gate
// refusing the same magnitude is pinned on its own terms in
// version_history_integer_admission_test.go. The two local cases below carry
// no such conflict and keep exercising the full gated seam, which is the
// more faithful check for them since production traffic never bypasses the
// gate.
func TestCanonicalDurableStateIsJCS(t *testing.T) {
t.Parallel()
cases := append(jcsTestVectors(t),
jcsCase{
for _, tc := range jcsTestVectors(t) {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
marshaled, err := json.Marshal(tc.state)
if err != nil {
t.Fatalf("json.Marshal: %v", err)
}
got, err := jcsCanonicalize(marshaled)
if err != nil {
t.Fatalf("jcsCanonicalize: %v", err)
}
if !bytes.Equal(got, tc.want) {
t.Fatalf("jcsCanonicalize =\n %s\nwant\n %s", got, tc.want)
}
// canonical(canonical(x)) == canonical(x): the stored bytes are
// a fixed point, so re-canonicalizing what was read back can
// never change the token.
again, err := jcsCanonicalize(got)
if err != nil {
t.Fatalf("jcsCanonicalize over its own output: %v", err)
}
if !bytes.Equal(again, got) {
t.Fatalf("canonical form is not a fixed point:\n %s\n %s", got, again)
}
})
}
for _, tc := range []jcsCase{
{
name: "unicode and astral keys sort by UTF-16 code units",
state: json.RawMessage(`{"b":1,"a":2,"é":3,"A":4,"😀":5}`),
want: []byte(`{"A":4,"a":2,"b":1,"é":3,"😀":5}`),
},
jcsCase{
{
name: "html escapes are normalized away",
state: map[string]any{"s": `<a>&"'</a>`},
want: []byte(`{"s":"<a>&\"'</a>"}`),
},
)
for _, tc := range cases {
} {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
got, err := canonicalDurableState(tc.state)
@ -118,9 +159,23 @@ func TestCanonicalDurableStateIsJCS(t *testing.T) {
"id": "bd-1",
"priority": json.Number("1.0"),
"metadata": map[string]any{
"weight": json.Number("1.50"),
"huge": json.Number("1E300"),
"ordinal": json.Number("9007199254740993"), // 2^53 + 1
"weight": json.Number("1.50"),
// 1E-300, not 1E300: this test is about number FORM
// canonicalization (ES6 exponential notation), not the admission
// gate. 1E300 denotes an INTEGER value (10^300) past what
// binary64 holds exactly, so refuseUnrepresentableIntegers now
// refuses it -- see version_history_integer_admission_test.go.
// 1E-300 exercises the same exponential FORM without being an
// integer at all, so it stays in scope for this test.
"huge": json.Number("1E-300"),
// 2^53-1, the largest integer binary64 holds exactly. This was
// 2^53+1 until the admission gate began refusing literals that
// binary64 cannot hold: JCS would round such a literal to a
// DIFFERENT VALUE, collapsing two distinct states onto one
// durable_state. That case now lives in
// version_history_integer_admission_test.go, which asserts the
// refusal; this test stays about number FORM canonicalization.
"ordinal": json.Number("9007199254740991"),
"tags": []any{json.Number("2.0"), "b", nil},
},
"raw": json.RawMessage(`{ "z" : 10.0e0 , "a" : true }`),
@ -132,9 +187,10 @@ func TestCanonicalDurableStateIsJCS(t *testing.T) {
}
// RFC 8785: keys sorted, no whitespace, numbers in ES6 Number::toString
// form (1.0 -> 1, 1.50 -> 1.5, 1E300 -> 1e+300, 2^53+1 -> the double it
// rounds to, 10.0e0 -> 10).
want := []byte(`{"id":"bd-1","metadata":{"huge":1e+300,"ordinal":9007199254740992,"tags":[2,"b",null],"weight":1.5},"priority":1,"raw":{"a":true,"z":10}}`)
// form (1.0 -> 1, 1.50 -> 1.5, 1E-300 -> 1e-300, 10.0e0 -> 10). An
// integer-valued literal past 2^53-1, any spelling, never reaches JCS now
// -- the admission gate refuses it first.
want := []byte(`{"id":"bd-1","metadata":{"huge":1e-300,"ordinal":9007199254740991,"tags":[2,"b",null],"weight":1.5},"priority":1,"raw":{"a":true,"z":10}}`)
if !bytes.Equal(got, want) {
t.Fatalf("canonicalDurableState =\n %s\nwant\n %s", got, want)
}
@ -148,7 +204,7 @@ func TestCanonicalDurableStateIsJCS(t *testing.T) {
if bytes.Equal(plain, got) {
t.Fatalf("plain json.Marshal already equals the canonical form (%s); this test no longer proves canonicalization matters", plain)
}
for _, nonCanonical := range []string{"1.0", "1.50", "1E300", "9007199254740993", "10.0e0"} {
for _, nonCanonical := range []string{"1.0", "1.50", "1E-300", "10.0e0"} {
if !bytes.Contains(plain, []byte(nonCanonical)) {
t.Errorf("plain marshal lost the non-canonical form %q, so the fixture no longer exercises it: %s", nonCanonical, plain)
}

View file

@ -0,0 +1,186 @@
package issueops
import (
"encoding/json"
"errors"
"testing"
"github.com/steveyegge/beads/internal/types"
)
func issueWithMetadata(meta string) types.Issue {
return types.Issue{ID: "be-1", Title: "t", Metadata: json.RawMessage(meta)}
}
// A metadata integer past 2^53 used to be ROUNDED by jcs.Transform, which
// collapsed two distinct issue states onto one durable_state and therefore
// one content token. It must be refused instead, so the loss is loud.
func TestCanonicalDurableStateRefusesIntegerPastBinary64(t *testing.T) {
_, err := canonicalDurableState(issueWithMetadata(`{"n":9007199254740993}`))
if err == nil {
t.Fatal("canonicalDurableState(metadata 9007199254740993) = nil error, want a refusal")
}
if !errors.Is(err, ErrIntegerNotRepresentable) {
t.Fatalf("error = %v, want ErrIntegerNotRepresentable", err)
}
}
// The defect this admission gate exists to prevent, stated directly: two
// DISTINCT states must never render to the same bytes.
func TestCanonicalDurableStateNeverCollapsesTwoDistinctStates(t *testing.T) {
// Before the admission gate, BOTH of these canonicalized, and both to
// the same bytes: 2^53+1 rounded down onto 2^53. One content token for
// two live states. Now the unrepresentable side is refused, so the pair
// can never be confused for one another.
a, errA := canonicalDurableState(issueWithMetadata(`{"n":9007199254740993}`))
b, errB := canonicalDurableState(issueWithMetadata(`{"n":9007199254740991}`))
if errA == nil && errB == nil && string(a) == string(b) {
t.Fatalf("two distinct states produced identical durable_state %s", a)
}
if errA == nil {
t.Fatalf("the unrepresentable state canonicalized instead of being refused: %s", a)
}
if errB != nil {
t.Fatalf("the representable state was refused: %v", errB)
}
}
// The bound itself, both sides of it, bare-integer spelling.
func TestCanonicalDurableStateIntegerBoundary(t *testing.T) {
for _, tc := range []struct {
name string
meta string
refused bool
}{
{"2^53-1 accepted", `{"n":9007199254740991}`, false},
{"2^53 refused", `{"n":9007199254740992}`, true},
{"2^53+1 refused", `{"n":9007199254740993}`, true},
{"negative past bound refused", `{"n":-9007199254740993}`, true},
{"beyond int64 refused", `{"n":18446744073709551616}`, true},
} {
t.Run(tc.name, func(t *testing.T) {
_, err := canonicalDurableState(issueWithMetadata(tc.meta))
if tc.refused && err == nil {
t.Fatalf("%s: nil error, want refusal", tc.meta)
}
if !tc.refused && err != nil {
t.Fatalf("%s: %v, want acceptance", tc.meta, err)
}
})
}
}
// Ordinary fractions must keep working: they are not exactly representable
// either, but ES6 shortest-round-trip returns them to the same binary64
// value, so they neither round to a different value nor collide.
//
// 1e300 is deliberately NOT in this list: it is a mathematical integer
// (10^300) whose magnitude vastly exceeds 2^53-1, so it is refused like any
// other unrepresentable integer, regardless of spelling. See
// TestCanonicalDurableStateRefusesHugeExponentInteger below.
func TestCanonicalDurableStateStillAcceptsOrdinaryDecimals(t *testing.T) {
for _, meta := range []string{`{"n":0.1}`, `{"n":1.0}`, `{"n":-2.5}`, `{"n":0}`} {
if _, err := canonicalDurableState(issueWithMetadata(meta)); err != nil {
t.Fatalf("canonicalDurableState(%s) = %v, want acceptance", meta, err)
}
}
}
// 1e300 denotes the integer 10^300 at a magnitude vastly past 2^53-1, and
// is subject to the same collision defect this gate
// exists to close -- binary64 spacing near 10^300 is roughly 2^248, so a wide
// range of distinct large integers near 10^300 collapse onto that one
// double, same failure mode as the 2^53 boundary, larger window. The
// spec for this predicate is "value not form, any spelling, no exceptions"
// (see version_history.go's refuseUnrepresentableIntegers doc comment),
// applied literally that refuses 1e300 -- but two pre-gate tests assumed it
// stayed accepted, one of which lived right here until this admission gate
// (see version_history_durable_state_test.go's "huge" fixture, moved off
// 1E300 for the same reason).
//
// RESOLVED: REFUSE 1e300. The rule applies
// literally, with no notation carve-out -- admitting a spelling this large
// while refusing 9007199254740993 would be indefensible, since the collision
// window near 10^300 (binary64 spacing ~2^248) is vastly larger than the one
// at the 2^53 boundary this gate was built to close. This is final, not
// provisional.
func TestCanonicalDurableStateRefusesHugeExponentInteger(t *testing.T) {
_, err := canonicalDurableState(issueWithMetadata(`{"n":1e300}`))
if err == nil {
t.Fatal("canonicalDurableState(metadata 1e300) = nil error, want a refusal")
}
if !errors.Is(err, ErrIntegerNotRepresentable) {
t.Fatalf("error = %v, want ErrIntegerNotRepresentable", err)
}
}
// THE GAP QA FOUND IN THE FIRST CUT OF THIS GATE. The first patch's
// refuseUnrepresentableIntegers skipped any literal containing '.', 'e', or
// 'E' outright, reasoning that non-integer literals round-trip losslessly
// through ES6 shortest-round-trip. That reasoning covers genuinely
// fractional literals (0.1, 1.5) but not integer-VALUED literals written in
// decimal or exponential FORM: 9007199254740993.0, 9.007199254740993e15, and
// 90071992547409930e-1 all denote the same integer VALUE as the bare literal
// 9007199254740993, and all three walked straight past the first gate and
// canonicalized to the identical colliding target 9007199254740992 -- the
// exact defect class this gate exists to close, just reachable through
// spelling instead of magnitude.
//
// The predicate under test must inspect the VALUE (the binary64 nearest
// to the literal) rather than the literal's spelling, so it must
// refuse and accept the same values regardless of which of the three JSON
// number forms (integer, decimal, exponent) carries them. This is pinned
// here for the bound itself; ordinary small decimals are covered separately
// by TestCanonicalDurableStateStillAcceptsOrdinaryDecimals.
func TestCanonicalDurableStateIntegerBoundaryAllSpellings(t *testing.T) {
for _, tc := range []struct {
name string
lit string
refused bool
}{
// at the bound (2^53-1 = 9007199254740991): every spelling accepted.
{"at bound, bare", `9007199254740991`, false},
{"at bound, decimal", `9007199254740991.0`, false},
{"at bound, exponent", `9.007199254740991e15`, false},
// one past the bound (2^53+1 = 9007199254740993): every spelling
// refused. The decimal and exponent rows are the QA-found gap.
{"past bound, bare", `9007199254740993`, true},
{"past bound, decimal (THE GAP)", `9007199254740993.0`, true},
{"past bound, exponent (THE GAP)", `9.007199254740993e15`, true},
{"past bound, exponent negative-exp form (THE GAP)", `90071992547409930e-1`, true},
} {
t.Run(tc.name, func(t *testing.T) {
meta := `{"n":` + tc.lit + `}`
_, err := canonicalDurableState(issueWithMetadata(meta))
if tc.refused && err == nil {
t.Fatalf("metadata %s: nil error, want refusal", meta)
}
if !tc.refused && err != nil {
t.Fatalf("metadata %s: %v, want acceptance", meta, err)
}
if tc.refused && !errors.Is(err, ErrIntegerNotRepresentable) {
t.Fatalf("metadata %s: error = %v, want ErrIntegerNotRepresentable", meta, err)
}
})
}
}
// Same property as TestCanonicalDurableStateNeverCollapsesTwoDistinctStates,
// spelled in decimal form -- the exact QA-found gap stated as a distinctness
// property rather than a table row: two states differing only in a
// decimal-spelled metadata integer past 2^53 must never render to the same
// bytes.
func TestCanonicalDurableStateNeverCollapsesDecimalSpellingOfDistinctStates(t *testing.T) {
a, errA := canonicalDurableState(issueWithMetadata(`{"n":9007199254740993.0}`))
b, errB := canonicalDurableState(issueWithMetadata(`{"n":9007199254740991.0}`))
if errA == nil && errB == nil && string(a) == string(b) {
t.Fatalf("two distinct states produced identical durable_state %s", a)
}
if errA == nil {
t.Fatalf("the unrepresentable state (9007199254740993.0) canonicalized instead of being refused: %s", a)
}
if errB != nil {
t.Fatalf("the representable state (9007199254740991.0) was refused: %v", errB)
}
}

View file

@ -0,0 +1,298 @@
package issueops
import (
"errors"
"math"
"math/rand"
"runtime"
"strconv"
"strings"
"testing"
)
// admitNumber runs the admission gate over one JSON number literal in the
// position the mint meets it: an object member of an issue's metadata.
func admitNumber(lit string) error {
return refuseUnrepresentableIntegers([]byte(`{"n":` + lit + `}`))
}
// The admission rule, stated once for the tests below: a JSON number literal
// is admitted into a durable_state if and only if the binary64 nearest to it
// has magnitude at most 2^53-1, whatever the literal's spelling (integer,
// decimal or exponent), and a literal that overflows binary64 is refused.
// Ordinary fractions such as 0.1 stay admitted, and so do magnitudes too small
// for binary64, which round to zero.
// A fraction whose nearest double lies at or beyond 2^53 used to be admitted:
// the old rule looked only at literals that denote an integer VALUE, and
// 9007199254740993.5 is not one. jcs.Transform then rounds it to the integer
// 9007199254740994, so two distinct issue states shared one durable_state,
// which is exactly what the gate exists to prevent. Refusing must depend on
// where the nearest double falls, not on whether the literal looks integral.
func TestNumberAdmissionRefusesFractionsWhoseNearestDoubleIsPastTheBound(t *testing.T) {
for _, tc := range []struct {
lit string
refused bool
why string
}{
{"9007199254740993.5", true, "nearest double is 2^53+2"},
{"9007199254740994.5", true, "nearest double is 2^53+2"},
{"9007199254740991.5", true, "a tie between 2^53-1 and 2^53 that rounds to the even 2^53"},
{"9007199254740991.75", true, "nearest double is 2^53"},
{"-9007199254740993.5", true, "magnitude decides, not sign"},
{"9007199254740990.5", false, "a tie that rounds to the even 2^53-2, inside the range"},
{"9007199254740991.25", false, "nearest double is 2^53-1, inside the range"},
{"9007199254740991.0", false, "exactly 2^53-1"},
} {
t.Run(tc.lit, func(t *testing.T) {
err := admitNumber(tc.lit)
if tc.refused {
if !errors.Is(err, ErrIntegerNotRepresentable) {
t.Fatalf("admitNumber(%s) = %v, want ErrIntegerNotRepresentable (%s)", tc.lit, err, tc.why)
}
if _, mintErr := canonicalDurableState(issueWithMetadata(`{"n":` + tc.lit + `}`)); !errors.Is(mintErr, ErrIntegerNotRepresentable) {
t.Fatalf("canonicalDurableState(metadata %s) = %v, want ErrIntegerNotRepresentable", tc.lit, mintErr)
}
return
}
if err != nil {
t.Fatalf("admitNumber(%s) = %v, want acceptance (%s)", tc.lit, err, tc.why)
}
})
}
}
// numberAdmissionCorpus is every literal the closure property is checked
// over: the boundary cases the rule was written around, every spelling of the
// values on either side of 2^53, and pseudo-random doubles in three renderings.
// The seed is fixed so a failure names a literal that reproduces.
func numberAdmissionCorpus() []string {
corpus := []string{
"0", "-0", "0.0", "-0.0", "1", "1.0", "-2.5", "0.1", "3.14159265358979323846", "0.30000000000000004",
"5e-324", "4.9e-324", "2.2250738585072014e-308", "1e-7", "1e-400", "1e-100000000",
"9007199254740991", "9007199254740992", "9007199254740993", "9.007199254740991e15", "90071992547409930e-1",
"9007199254740993.5", "9007199254740994.5", "9007199254740991.5", "9007199254740990.5",
"1727000000000000000", "1727000000000000123", "1e21", "1e300", "1.7976931348623157e308",
"123456789012345678901234567890", "18446744073709551616",
}
// Every spelling of the integers and near-integers either side of the bound.
for delta := int64(-6); delta <= 6; delta++ {
base := strconv.FormatInt(int64(1)<<53+delta, 10)
for _, frac := range []string{"", ".0", ".25", ".5", ".75", ".999999"} {
corpus = append(corpus, base+frac, "-"+base+frac)
}
}
rng := rand.New(rand.NewSource(20260930))
for _, scale := range []float64{1, 1e3, 1e9, 1e15, 1e-9} {
for range 60 {
f := (rng.Float64()*2 - 1) * scale
corpus = append(corpus,
strconv.FormatFloat(f, 'g', -1, 64),
strconv.FormatFloat(f, 'e', 17, 64),
strconv.FormatFloat(f, 'f', -1, 64))
}
}
for range 200 {
f := math.Float64frombits(rng.Uint64())
if math.IsNaN(f) || math.IsInf(f, 0) {
continue
}
corpus = append(corpus, strconv.FormatFloat(f, 'g', -1, 64), strconv.FormatFloat(f, 'e', -1, 64))
}
return corpus
}
// The gate must be closed under its own canonicalization: whatever it admits
// canonicalizes to a form it also admits. Otherwise a value can pass at the
// door and become unmintable one step later, which is what 9007199254740991.5
// did (it rounds to 2^53, and the canonical bytes are then refused). Checked as
// a property over a corpus, not by example.
func TestNumberAdmissionIsClosedUnderCanonicalization(t *testing.T) {
admitted := 0
for _, lit := range numberAdmissionCorpus() {
doc := []byte(`{"n":` + lit + `}`)
if err := refuseUnrepresentableIntegers(doc); err != nil {
continue // refused literals are outside the property
}
admitted++
canonical, err := jcsCanonicalize(doc)
if err != nil {
t.Errorf("literal %s: jcsCanonicalize: %v", lit, err)
continue
}
if err := refuseUnrepresentableIntegers(canonical); err != nil {
t.Errorf("literal %s is admitted but its canonical form %s is refused: %v", lit, canonical, err)
}
}
if admitted < 100 {
t.Fatalf("only %d corpus literals were admitted; the property is close to vacuous", admitted)
}
}
// The classification must not depend on how large an exponent the literal
// spells. The old rule parsed every literal as an exact rational, so a huge
// exponent either cost a million-digit integer or fell outside what the
// parser accepts and came back as an invalid literal, a different class of
// error from the refusal it is. Overflow is a refusal; a magnitude too small
// for binary64 is admitted.
func TestNumberAdmissionClassifiesByMagnitudeWhateverTheExponent(t *testing.T) {
for _, tc := range []struct {
lit string
refused bool
}{
{"1e100000000", true},
{"1e1000000", true},
{"1e309", true},
{"-1e400", true},
{"1.7976931348623159e308", true},
{"1e-100000000", false},
{"1e-400", false},
{"-1e-400", false},
{"5e-324", false},
} {
t.Run(tc.lit, func(t *testing.T) {
err := admitNumber(tc.lit)
switch {
case tc.refused && !errors.Is(err, ErrIntegerNotRepresentable):
t.Fatalf("admitNumber(%s) = %v, want ErrIntegerNotRepresentable", tc.lit, err)
case !tc.refused && err != nil:
t.Fatalf("admitNumber(%s) = %v, want acceptance", tc.lit, err)
}
})
}
}
// The gate allocates nothing proportional to an exponent. Measured as an
// allocation count and never as wall time, so a loaded machine cannot flake it,
// and it is what distinguishes a classifier that builds a million-digit integer
// from one that does not.
//
// The count is exact only without the race detector. Under it sync.Pool drops
// one Put in four at random (sync/pool.go), and the refusal builds its error with
// fmt.Errorf, whose printer comes from a pool, so a call now and then allocates a
// printer the pool would have supplied: a literal that costs 22 allocations reads
// 23, or 24, on a run where a printer was dropped, and comparing two
// independently averaged samples with a strict > is a coin flip. That noise only
// ever ADDS allocations, so the fewest allocations over many single-call samples
// is the count without it, and it is the same on every run. The comparison stays
// strict, with no margin to tune, and it loses no sensitivity: a classifier that
// builds per-exponent state does so on every call, so it raises the fewest too.
func TestNumberAdmissionAllocationsDoNotGrowWithTheExponent(t *testing.T) {
// The chance that every one of these samples is noisy is under one in 10^19.
const samples = 32
fewest := func(lit string) float64 {
doc := []byte(`{"n":` + lit + `}`)
least := math.Inf(1)
for range samples {
least = math.Min(least, testing.AllocsPerRun(1, func() { _ = refuseUnrepresentableIntegers(doc) }))
}
return least
}
baseline := fewest("1e400")
for _, lit := range []string{"1e1000000", "1e100000000", "-1e1000000"} {
if got := fewest(lit); got > baseline {
t.Errorf("%s allocates %v times per call against %v for 1e400: allocation grows with the exponent", lit, got, baseline)
}
}
}
// TestNumberAdmissionBytesDoNotGrowWithTheExponent is the count bound's twin, and finding 6
// of the #6661 review. The count bound passes a classifier that builds the number it is
// asked about: one big-integer allocation is one allocation whether it holds 400 bits or a
// hundred million. What grows with the exponent is then the size of the allocation, so this
// bounds bytes: the fewest bytes one call allocates for a literal with a huge exponent is
// no more than for a small one, plus a margin and a few bytes for each byte of literal (a
// refusal names the literal in its message).
//
// The fewest over many single-call samples, as in the count bound and for the same reason:
// whatever else allocates while a sample runs only ever ADDS bytes, so the minimum is the
// cost of the call itself. TotalAlloc is read before and after each call, with GOMAXPROCS
// pinned to one for the measurement as testing.AllocsPerRun does, so a background
// goroutine does not add to a sample.
func TestNumberAdmissionBytesDoNotGrowWithTheExponent(t *testing.T) {
const (
samples = 32
smallLiteral = "1e400"
// What the bound allows beyond the small literal's bytes: a margin, and a few
// bytes for each byte a longer literal adds to the refusal's message.
slackBytes = 1024
perLitByte = 16
)
defer runtime.GOMAXPROCS(runtime.GOMAXPROCS(1))
fewest := func(lit string) uint64 {
doc := []byte(`{"n":` + lit + `}`)
least := uint64(math.MaxUint64)
var before, after runtime.MemStats
for range samples {
runtime.ReadMemStats(&before)
_ = refuseUnrepresentableIntegers(doc)
runtime.ReadMemStats(&after)
least = min(least, after.TotalAlloc-before.TotalAlloc)
}
return least
}
baseline := fewest(smallLiteral)
for _, lit := range []string{"1e1000000", "1e100000000", "-1e1000000"} {
limit := baseline + slackBytes + perLitByte*uint64(max(len(lit)-len(smallLiteral), 0))
if got := fewest(lit); got > limit {
t.Errorf("%s allocates %d bytes per call against %d for %s (limit %d): bytes grow with the exponent", lit, got, baseline, smallLiteral, limit)
}
}
}
// The sentinel names the range it enforces. Its old wording said a literal
// was not exactly representable, which no longer describes what is refused:
// 9007199254740993.5 is a fraction, and the rule is about magnitude. The
// identifier keeps its historical name so nothing that matches it with
// errors.Is has to change; the text is what a person reads.
func TestIntegerNotRepresentableTextNamesTheIJSONRange(t *testing.T) {
const want = "number is outside the I-JSON exact-integer range (magnitude above 2^53-1)"
got := ErrIntegerNotRepresentable.Error()
if got != want {
t.Fatalf("ErrIntegerNotRepresentable.Error() = %q, want %q", got, want)
}
if !strings.Contains(got, "I-JSON") {
t.Errorf("sentinel text %q does not name I-JSON", got)
}
if strings.Contains(got, "cannot represent") {
t.Errorf("sentinel text %q still uses the old wording", got)
}
err := admitNumber("9007199254740993")
if err == nil || err.Error() != want+": 9007199254740993" {
t.Fatalf("refusal text = %v, want the sentinel followed by the offending literal", err)
}
}
// Nothing the store already accepted becomes admitted or refused differently.
// Dolt does not hand a literal back the way it was written: an integer up to
// int64 is stored exactly and every other number is stored as a double, so what
// the mint sees is the right-hand column. Each row pins the verdict on that
// column, which is what production meets. The verdicts are the ones the rule
// had before it changed, so this stays green through the change and fails only
// if the new rule moves one.
func TestNumberAdmissionKeepsTheVerdictOnEveryLiteralAsTheStoreReturnsIt(t *testing.T) {
for _, tc := range []struct {
written string
returned string // what a Dolt JSON column hands back for it
refused bool
}{
{"9007199254740993", "9007199254740993", true},
{"1727000000000000123", "1727000000000000123", true},
{"9007199254740993.5", "9007199254740994", true},
{"1.0", "1", false},
{"0.1", "0.1", false},
{"3.14159265358979323846", "3.141592653589793", false},
{"1e300", "1" + strings.Repeat("0", 300), true},
{"123456789012345678901234567890", "123456789012345680000000000000", true},
} {
t.Run(tc.written, func(t *testing.T) {
err := admitNumber(tc.returned)
if tc.refused && !errors.Is(err, ErrIntegerNotRepresentable) {
t.Fatalf("admitNumber(%s), the store's rendering of %s = %v, want a refusal", tc.returned, tc.written, err)
}
if !tc.refused && err != nil {
t.Fatalf("admitNumber(%s), the store's rendering of %s = %v, want acceptance", tc.returned, tc.written, err)
}
})
}
}

View file

@ -0,0 +1,680 @@
package issueops
import (
"context"
"database/sql/driver"
"encoding/json"
"errors"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"reflect"
"regexp"
"sort"
"strings"
"testing"
"time"
"github.com/DATA-DOG/go-sqlmock"
"github.com/steveyegge/beads/internal/storage/sqlbuild"
"github.com/steveyegge/beads/internal/types"
)
// With versioned history on, the mint runs in the same transaction as the
// mutation that reaches it, so refusing at the mint IS refusing the write: a
// number outside the I-JSON range aborts the writer's own transaction and
// nothing it did is committed. The mint reads the whole issue, so the number
// can be in any field that holds one: in metadata, or in a gate's timeout,
// which encoding/json writes as a count of nanoseconds. The mint's reads run
// first and its two writes, the version row and the current_revision advance,
// come last, so a refusal must arrive after the reads and before either write.
//
// The mock scripts exactly the reads. It expects no INSERT into issue_versions
// and no UPDATE of issues.current_revision, so a mint that wrote before it
// refused would make the mock fail the call with an unexpected-statement error
// instead of the refusal asserted here. The caller's own rollback closes the
// transaction, as every store does when the mint returns an error.
//
// The refusal names the top-level field the number was found in, as well as the
// literal, so a person who reads it knows which part of the issue to fix.
func TestRecordVersionInTxRefusesANumberOutsideTheRangeAndWritesNothing(t *testing.T) {
for _, tc := range []struct {
name string
column string
value driver.Value
literal string
field string
}{
{"a number in metadata", "metadata", `{"ts":1727000000000000000}`, "1727000000000000000", "metadata"},
{"a gate timeout past 2^53-1 nanoseconds", "timeout_ns", int64(2600 * time.Hour), "9360000000000000", "timeout"},
} {
t.Run(tc.name, func(t *testing.T) {
const id = "bd-9"
_, mock, tx := beginMockTx(t)
defer ScopeVersionedHistoryTransaction(tx, true)()
values := issueRowValues(id, "carries an out-of-range number")
for i, col := range issueColumns() {
if col == tc.column {
values[i] = tc.value
}
}
mock.ExpectQuery(regexp.QuoteMeta("SELECT " + IssueSelectColumns + " FROM issues " + sqlbuild.LeaseJoin("issues") + " WHERE id = ?")).
WithArgs(id).
WillReturnRows(issueRows().AddRow(values...))
mock.ExpectQuery(regexp.QuoteMeta("SELECT label FROM labels WHERE issue_id = ? ORDER BY label")).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"label"}))
// design §16.2b's write fence reads participation_generation right after the
// snapshot. A non-NULL value is a participating row, so the mint goes on to the
// refusal this test pins; a NULL one would be a legacy row and mint nothing.
mock.ExpectQuery(regexp.QuoteMeta("SELECT participation_generation FROM issues WHERE id = ?")).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"participation_generation"}).AddRow(1))
mock.ExpectQuery(regexp.QuoteMeta("SELECT 1 FROM wisps LIMIT 1")).
WillReturnRows(sqlmock.NewRows([]string{"1"}))
mock.ExpectQuery(`FROM dependencies WHERE issue_id IN`).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"issue_id", "depends_on_id", "type", "created_at", "created_by", "metadata", "thread_id"}))
mock.ExpectQuery(regexp.QuoteMeta("SELECT epoch FROM store_epoch WHERE id = 1")).
WillReturnRows(sqlmock.NewRows([]string{"epoch"}).AddRow(1))
mock.ExpectQuery(regexp.QuoteMeta("SELECT COALESCE(MAX(revision), 0) + 1 FROM issue_versions WHERE issue_id = ?")).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"next"}).AddRow(1))
mock.ExpectRollback()
err := RecordVersionInTx(context.Background(), tx, id, "actor")
if !errors.Is(err, ErrIntegerNotRepresentable) {
t.Fatalf("RecordVersionInTx = %v, want ErrIntegerNotRepresentable", err)
}
if !strings.Contains(err.Error(), id) {
t.Errorf("refusal %q does not name the issue %s", err, id)
}
if !strings.Contains(err.Error(), tc.literal) {
t.Errorf("refusal %q does not name the offending literal %s", err, tc.literal)
}
if !strings.Contains(err.Error(), fmt.Sprintf("%q", tc.field)) {
t.Errorf("refusal %q does not name the field %q the number was found in", err, tc.field)
}
if rbErr := tx.Rollback(); rbErr != nil {
t.Fatalf("rolling back the writer's transaction: %v", rbErr)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("the mint read or wrote something other than the scripted reads: %v", err)
}
})
}
}
// A legacy row (participation_generation NULL) holding the same out-of-range number is outside
// the mint's refusal: design §16.2b's write fence returns right after the snapshot, so the
// admission gate never runs and RecordVersionInTx returns nil.
//
// The mock scripts the snapshot, the labels and the fence's read returning NULL, and nothing after
// it. A mint that read the dependencies, the epoch or a revision, or wrote, before it decided to
// skip would fail the call with an unexpected-statement error instead of returning nil, so this is
// the cheapest pin of the fence's order against the gate.
func TestRecordVersionInTxSkipsALegacyRowBeforeTheAdmissionGate(t *testing.T) {
const id = "bd-9"
_, mock, tx := beginMockTx(t)
defer ScopeVersionedHistoryTransaction(tx, true)()
values := issueRowValues(id, "a legacy row that carries an out-of-range number")
for i, col := range issueColumns() {
if col == "metadata" {
values[i] = `{"ts":1727000000000000000}`
}
}
mock.ExpectQuery(regexp.QuoteMeta("SELECT " + IssueSelectColumns + " FROM issues " + sqlbuild.LeaseJoin("issues") + " WHERE id = ?")).
WithArgs(id).
WillReturnRows(issueRows().AddRow(values...))
mock.ExpectQuery(regexp.QuoteMeta("SELECT label FROM labels WHERE issue_id = ? ORDER BY label")).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"label"}))
mock.ExpectQuery(regexp.QuoteMeta("SELECT participation_generation FROM issues WHERE id = ?")).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"participation_generation"}).AddRow(nil))
mock.ExpectRollback()
if err := RecordVersionInTx(context.Background(), tx, id, "actor"); err != nil {
t.Fatalf("RecordVersionInTx on a legacy row = %v, want nil: the fence skips it before the admission gate", err)
}
if rbErr := tx.Rollback(); rbErr != nil {
t.Fatalf("rolling back the writer's transaction: %v", rbErr)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("the mint read or wrote something after the fence skipped the row: %v", err)
}
}
// TestRecordVersionAtInTxKeepsThePlaneRuleButNotTheFence pins what the
// test-support mint (RecordVersionAtInTx, mintUnfenced) does on the paths #6943
// gave the shared body.
//
// - A row the wisps table holds, flags clear: the plane rule is not the fence,
// so the unfenced mint honours it like the other two kinds. The issues-table
// read finds nothing and the mint returns nil having written nothing, where
// before it would have inserted a version row no issues row points at.
// - An issues-table row flagged NoHistory: never versioned, and the unfenced
// mint never declares participation, so it returns right after the snapshot,
// without reading or stamping participation_generation.
// - A legacy row (participation_generation NULL), flags clear: the fence does
// not apply, so it mints, and the closing UPDATE advances current_revision
// alone, with no stamp.
//
// The mock scripts each sequence exactly, so an extra read or any write fails
// the call with an unexpected-statement error.
func TestRecordVersionAtInTxKeepsThePlaneRuleButNotTheFence(t *testing.T) {
const id = "bd-7"
at := time.Date(2026, 9, 1, 12, 0, 0, 0, time.UTC)
issuesSnapshot := regexp.QuoteMeta("SELECT " + IssueSelectColumns + " FROM issues " + sqlbuild.LeaseJoin("issues") + " WHERE id = ?")
participation := regexp.QuoteMeta("SELECT participation_generation FROM issues WHERE id = ?")
t.Run("a row the wisps table holds mints nothing", func(t *testing.T) {
_, mock, tx := beginMockTx(t)
mock.ExpectQuery(issuesSnapshot).WithArgs(id).WillReturnRows(issueRows())
mock.ExpectQuery(regexp.QuoteMeta("SELECT " + IssueSelectColumns + " FROM wisps " + sqlbuild.LeaseJoin("wisps") + " WHERE id = ?")).
WithArgs(id).
WillReturnRows(issueRows().AddRow(issueRowValues(id, "a squashed wisp root, flags clear")...))
mock.ExpectQuery(regexp.QuoteMeta("SELECT label FROM wisp_labels WHERE issue_id = ? ORDER BY label")).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"label"}))
mock.ExpectQuery(participation).WithArgs(id).WillReturnRows(sqlmock.NewRows([]string{"participation_generation"}))
mock.ExpectRollback()
if err := RecordVersionAtInTx(context.Background(), tx, id, "actor", at); err != nil {
t.Fatalf("RecordVersionAtInTx on a wisps-table row = %v, want nil", err)
}
if err := tx.Rollback(); err != nil {
t.Fatalf("rollback: %v", err)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("the unfenced mint did something after finding no issues row: %v", err)
}
})
t.Run("an issues row flagged no-history is neither minted nor stamped", func(t *testing.T) {
_, mock, tx := beginMockTx(t)
values := issueRowValues(id, "no-history, on the issues plane")
for i, col := range issueColumns() {
if col == "no_history" {
values[i] = int64(1)
}
}
mock.ExpectQuery(issuesSnapshot).WithArgs(id).WillReturnRows(issueRows().AddRow(values...))
mock.ExpectQuery(regexp.QuoteMeta("SELECT label FROM labels WHERE issue_id = ? ORDER BY label")).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"label"}))
mock.ExpectRollback()
if err := RecordVersionAtInTx(context.Background(), tx, id, "actor", at); err != nil {
t.Fatalf("RecordVersionAtInTx on a no-history row = %v, want nil", err)
}
if err := tx.Rollback(); err != nil {
t.Fatalf("rollback: %v", err)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("the unfenced mint read or wrote something for a no-history row: %v", err)
}
})
t.Run("a legacy row is minted and left unstamped", func(t *testing.T) {
_, mock, tx := beginMockTx(t)
mock.ExpectQuery(issuesSnapshot).WithArgs(id).
WillReturnRows(issueRows().AddRow(issueRowValues(id, "legacy, history was off when it was made")...))
mock.ExpectQuery(regexp.QuoteMeta("SELECT label FROM labels WHERE issue_id = ? ORDER BY label")).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"label"}))
mock.ExpectQuery(participation).WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"participation_generation"}).AddRow(nil))
mock.ExpectQuery(regexp.QuoteMeta("SELECT 1 FROM wisps LIMIT 1")).
WillReturnRows(sqlmock.NewRows([]string{"1"}))
mock.ExpectQuery(`FROM dependencies WHERE issue_id IN`).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"issue_id", "depends_on_id", "type", "created_at", "created_by", "metadata", "thread_id"}))
mock.ExpectQuery(regexp.QuoteMeta("SELECT epoch FROM store_epoch WHERE id = 1")).
WillReturnRows(sqlmock.NewRows([]string{"epoch"}).AddRow(1))
mock.ExpectQuery(regexp.QuoteMeta("SELECT COALESCE(MAX(revision), 0) + 1 FROM issue_versions WHERE issue_id = ?")).
WithArgs(id).
WillReturnRows(sqlmock.NewRows([]string{"next"}).AddRow(1))
mock.ExpectExec(`INSERT INTO issue_versions`).
WithArgs(id, int64(1), 1, sqlmock.AnyArg(), "actor", at, sqlmock.AnyArg()).
WillReturnResult(sqlmock.NewResult(0, 1))
mock.ExpectExec(regexp.QuoteMeta("UPDATE issues SET current_revision = ?, updated_at = updated_at WHERE id = ?")).
WithArgs(int64(1), id).
WillReturnResult(sqlmock.NewResult(0, 1))
mock.ExpectRollback()
if err := RecordVersionAtInTx(context.Background(), tx, id, "actor", at); err != nil {
t.Fatalf("RecordVersionAtInTx on a legacy row = %v, want nil", err)
}
if err := tx.Rollback(); err != nil {
t.Fatalf("rollback: %v", err)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("the unfenced mint did not mint a legacy row exactly once, unstamped: %v", err)
}
})
}
// refusalClass names what an admission verdict is, so two functions can be
// compared for agreement without depending on their exact wording.
func refusalClass(err error) string {
switch {
case err == nil:
return "admitted"
case errors.Is(err, ErrIntegerNotRepresentable):
return "number outside the I-JSON range"
case strings.Contains(err.Error(), "Duplicate key"):
return "duplicate key"
default:
return "other refusal"
}
}
func issueWithTimeout(timeout time.Duration) types.Issue {
return types.Issue{ID: "be-1", Title: "t", IssueType: types.TypeGate, Timeout: timeout}
}
// The check the pre-enable scan runs and the check the mint runs must never
// disagree, or a store could pass the scan, be switched on, and then refuse the
// first write to the row the scan cleared. So the check is the mint's own two
// steps behind one exported name, and this pins that they agree on every shape
// of issue.
//
// The domain is the WHOLE issue, because that is what the mint canonicalizes and
// what the scan hands the check. Metadata covers a number past the range, a
// fraction rounding past it, duplicate keys at the top level and nested,
// ordinary values, null, empty and an empty object, and text that is not JSON at
// all. The other field that can reach the range is a gate's timeout, a
// time.Duration that encoding/json writes as nanoseconds: 2^53-1 ns is about
// 104.25 days, so 2500h is admitted and 2600h is not.
func TestCheckIssueVersionableAgreesWithTheMint(t *testing.T) {
const maxExact = 1<<53 - 1 // 9007199254740991 ns, the last whole nanosecond count in range
for _, tc := range []struct {
name string
issue types.Issue
want string
}{
{"number past the range", issueWithMetadata(`{"ts":1727000000000000000}`), "number outside the I-JSON range"},
{"fraction rounding past the range", issueWithMetadata(`{"n":9007199254740993.5}`), "number outside the I-JSON range"},
{"overflowing exponent", issueWithMetadata(`{"n":1e400}`), "number outside the I-JSON range"},
{"number nested in an array", issueWithMetadata(`{"a":[1,{"b":-9007199254740993}]}`), "number outside the I-JSON range"},
{"duplicate key", issueWithMetadata(`{"k":1,"k":2}`), "duplicate key"},
{"nested duplicate key", issueWithMetadata(`{"a":{"k":1,"k":2}}`), "duplicate key"},
{"ordinary values", issueWithMetadata(`{"a":1,"b":[0.1,2,"x"],"c":{"d":null}}`), "admitted"},
{"number at the bound", issueWithMetadata(`{"n":9007199254740991}`), "admitted"},
{"tiny magnitude", issueWithMetadata(`{"n":1e-400}`), "admitted"},
{"null", issueWithMetadata(`null`), "admitted"},
{"empty object", issueWithMetadata(`{}`), "admitted"},
{"empty", issueWithMetadata(``), "admitted"},
{"text that is not JSON", issueWithMetadata(`{"a":`), "other refusal"},
{"no timeout", issueWithTimeout(0), "admitted"},
{"timeout 2500h", issueWithTimeout(2500 * time.Hour), "admitted"},
{"timeout 2600h", issueWithTimeout(2600 * time.Hour), "number outside the I-JSON range"},
{"timeout 8760h", issueWithTimeout(8760 * time.Hour), "number outside the I-JSON range"},
{"negative timeout -2600h", issueWithTimeout(-2600 * time.Hour), "number outside the I-JSON range"},
{"timeout of exactly 2^53-1 ns", issueWithTimeout(time.Duration(maxExact)), "admitted"},
{"timeout of exactly 2^53 ns", issueWithTimeout(time.Duration(maxExact + 1)), "number outside the I-JSON range"},
{"timeout in range beside ordinary metadata", func() types.Issue {
issue := issueWithTimeout(time.Hour)
issue.Metadata = json.RawMessage(`{"ok":1}`)
return issue
}(), "admitted"},
} {
t.Run(tc.name, func(t *testing.T) {
check := CheckIssueVersionable(&tc.issue)
_, mint := canonicalDurableState(tc.issue)
if got := refusalClass(check); got != tc.want {
t.Errorf("CheckIssueVersionable = %v (%s), want %s", check, got, tc.want)
}
if got := refusalClass(mint); got != tc.want {
t.Errorf("canonicalDurableState = %v (%s), want %s", mint, got, tc.want)
}
if refusalClass(check) != refusalClass(mint) {
t.Errorf("the pre-enable check and the mint disagree: check %v, mint %v", check, mint)
}
})
}
}
// The scan runs the check over every issue the mint would version and skips
// the ones it would not, by the mint's own rule (IsWisp): ephemeral rows and
// no-history rows are never versioned, so a poisoned value in one can never
// abort a write and is not an obstacle to switching history on. The scan
// reports what it found in the order it was given, names each offender with
// the refusal the mint would return and the field it was found in, and finds
// nothing in a clean store.
//
// A gate whose timeout is over 105 days is the case that motivated checking the
// whole issue: its timeout is past 2^53-1 ns, so, if it participates in history,
// the mint refuses every write to it, and a scan that looked only at metadata
// cleared the switch over it.
func TestFindUnversionableFindsWhatTheMintWouldRefuse(t *testing.T) {
oversize := json.RawMessage(`{"ts":1727000000000000000}`)
overlong := 105 * 24 * time.Hour
issues := []*types.Issue{
{ID: "bd-1", Metadata: oversize},
{ID: "bd-2", Metadata: json.RawMessage(`{"k":1,"k":2}`)},
{ID: "bd-3", Metadata: json.RawMessage(`{"ok":1}`)},
{ID: "bd-4", Ephemeral: true, Metadata: oversize},
{ID: "bd-5", NoHistory: true, Metadata: oversize},
{ID: "bd-6"},
{ID: "bd-7", Metadata: json.RawMessage(`{"n":9007199254740993.5}`)},
{ID: "bd-8", Ephemeral: true, WispPlaneOverride: boolPtr(false), Metadata: oversize},
{ID: "bd-9", WispPlaneOverride: boolPtr(true), Metadata: oversize},
{ID: "bd-10", IssueType: types.TypeGate, Timeout: overlong},
{ID: "bd-11", IssueType: types.TypeGate, Timeout: 2500 * time.Hour},
{ID: "bd-12", IssueType: types.TypeGate, Ephemeral: true, Timeout: overlong},
{ID: "bd-13", IssueType: types.TypeGate, Timeout: -overlong},
}
got := FindUnversionable(issues)
want := []struct {
id string
class string
field string
}{
{"bd-1", "number outside the I-JSON range", "metadata"},
{"bd-2", "duplicate key", "metadata"},
{"bd-7", "number outside the I-JSON range", "metadata"},
// The override decides which plane the mint routes an issue to, and the
// scan follows it: bd-8 is versioned despite Ephemeral, bd-9 is not.
{"bd-8", "number outside the I-JSON range", "metadata"},
{"bd-10", "number outside the I-JSON range", "timeout"},
{"bd-13", "number outside the I-JSON range", "timeout"},
}
if len(got) != len(want) {
t.Fatalf("FindUnversionable found %d issues %v, want %d", len(got), unversionableIDs(got), len(want))
}
for i, w := range want {
if got[i].ID != w.id {
t.Fatalf("offender %d is %s, want %s (order of the input); got %v", i, got[i].ID, w.id, unversionableIDs(got))
}
if class := refusalClass(got[i].Err); class != w.class {
t.Errorf("%s: refusal class %q (%v), want %q", w.id, class, got[i].Err, w.class)
}
if got[i].Field != w.field {
t.Errorf("%s: field %q, want %q", w.id, got[i].Field, w.field)
}
if !strings.Contains(got[i].Err.Error(), fmt.Sprintf("%q", w.field)) {
t.Errorf("%s: refusal %q does not name the field %q", w.id, got[i].Err, w.field)
}
}
clean := []*types.Issue{
{ID: "bd-1", Metadata: json.RawMessage(`{"ok":1,"f":0.1}`)},
{ID: "bd-2"},
{ID: "bd-3", Metadata: json.RawMessage(`null`)},
{ID: "bd-4", Ephemeral: true, Metadata: oversize},
{ID: "bd-5", IssueType: types.TypeGate, Timeout: 2500 * time.Hour},
{ID: "bd-6", IssueType: types.TypeGate, Ephemeral: true, Timeout: overlong},
}
if found := FindUnversionable(clean); len(found) != 0 {
t.Fatalf("a store with nothing the mint would refuse reported %v", unversionableIDs(found))
}
if found := FindUnversionable(nil); len(found) != 0 {
t.Fatalf("no issues reported %v", unversionableIDs(found))
}
}
func unversionableIDs(found []UnversionableIssue) []string {
ids := make([]string, 0, len(found))
for _, f := range found {
ids = append(ids, f.ID)
}
return ids
}
// The scan does not hand the check the issue the mint sees. It reads a lite
// projection (the heavy text columns are left out, labels are not loaded) and
// never loads dependencies, which the mint adds before it canonicalizes. That is
// sound only while everything the scan leaves out is free of numbers: a number in
// a field the scan never loads is one it can never refuse and the mint will. The
// next three tests are how that stays true. They fail, with the way out, the day
// a field is added that breaks it.
// fieldByJSONName finds the exported field of the struct type typ that
// encoding/json writes under name.
func fieldByJSONName(typ reflect.Type, name string) (reflect.StructField, bool) {
for i := 0; i < typ.NumField(); i++ {
f := typ.Field(i)
if !f.IsExported() {
continue
}
tag := f.Tag.Get("json")
if tag == "-" {
continue
}
jsonName := strings.Split(tag, ",")[0]
if jsonName == "" {
jsonName = f.Name
}
if jsonName == name {
return f, true
}
}
return reflect.StructField{}, false
}
// heavyColumnProblems maps each column to its field of the issue type and reports
// every one that is missing or that can hold a number. A string or a slice of
// strings cannot: encoding/json writes both without a JSON number in them.
func heavyColumnProblems(columns []string, issue reflect.Type) []string {
var problems []string
for _, col := range columns {
f, ok := fieldByJSONName(issue, col)
if !ok {
problems = append(problems, fmt.Sprintf("column %q has no %s field written under that name: map it, then say whether it can hold a number", col, issue))
continue
}
numberFree := f.Type.Kind() == reflect.String ||
(f.Type.Kind() == reflect.Slice && f.Type.Elem().Kind() == reflect.String)
if !numberFree {
problems = append(problems, fmt.Sprintf("column %q is %s.%s (%s), which can hold a number the scan never reads but the mint refuses: load it in the scan or classify it lite", col, issue, f.Name, f.Type))
}
}
return problems
}
// TestTheScanProjectionOmitsOnlyNumberFreeFields pins that every column the
// scan's lite projection leaves out (HeavyDropList) is a string or a list of
// strings on the issue.
func TestTheScanProjectionOmitsOnlyNumberFreeFields(t *testing.T) {
if problems := heavyColumnProblems(HeavyDropList, reflect.TypeOf(types.Issue{})); len(problems) > 0 {
t.Fatalf("the scan's projection leaves out a column that can hold a number:\n %s", strings.Join(problems, "\n "))
}
}
// The guard above would pass vacuously if it never found anything to refuse, so
// it is run once against columns that must be refused: numbers, metadata (a
// verbatim JSON document), a column that maps to nothing, and the columns that
// really are number-free.
func TestTheHeavyColumnGuardRefusesWhatCanHoldANumber(t *testing.T) {
issue := reflect.TypeOf(types.Issue{})
for _, col := range []string{"priority", "estimated_minutes", "timeout", "metadata", "created_at_unix"} {
if problems := heavyColumnProblems([]string{col}, issue); len(problems) != 1 {
t.Errorf("column %q: got %d problems %v, want exactly one", col, len(problems), problems)
}
}
for _, col := range []string{"description", "design", "acceptance_criteria", "notes", "waiters", "payload"} {
if problems := heavyColumnProblems([]string{col}, issue); len(problems) != 0 {
t.Errorf("column %q is number-free but was refused: %v", col, problems)
}
}
problems := heavyColumnProblems([]string{"priority"}, issue)
if len(problems) == 1 && !strings.Contains(problems[0], "load it in the scan or classify it lite") {
t.Errorf("the refusal %q does not say how to resolve it", problems[0])
}
}
var (
timeType = reflect.TypeOf(time.Time{})
rawMessageType = reflect.TypeOf(json.RawMessage(nil))
)
// numberBearingPaths walks typ the way encoding/json does and returns the path of
// everything that can write a JSON number or a value this walk cannot see into:
// an integer, unsigned integer or float (a time.Duration is an int64), a
// json.RawMessage, an interface, a map. It recurses through slices, arrays,
// pointers and structs, skips what json:"-" leaves out and the unexported fields,
// and treats a time.Time as the string it is written as.
func numberBearingPaths(typ reflect.Type, path string, onPath map[reflect.Type]bool) []string {
switch typ {
case timeType:
return nil
case rawMessageType:
return []string{path + " is a json.RawMessage, passed through verbatim"}
}
switch typ.Kind() {
case reflect.Bool, reflect.String:
return nil
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr,
reflect.Float32, reflect.Float64:
return []string{fmt.Sprintf("%s is a %s", path, typ)}
case reflect.Interface, reflect.Map:
return []string{fmt.Sprintf("%s is a %s", path, typ.Kind())}
case reflect.Pointer, reflect.Slice, reflect.Array:
return numberBearingPaths(typ.Elem(), path, onPath)
case reflect.Struct:
if onPath[typ] {
return nil
}
onPath[typ] = true
defer delete(onPath, typ)
var found []string
for i := 0; i < typ.NumField(); i++ {
f := typ.Field(i)
if !f.IsExported() || f.Tag.Get("json") == "-" {
continue
}
found = append(found, numberBearingPaths(f.Type, path+"."+f.Name, onPath)...)
}
return found
default:
return []string{fmt.Sprintf("%s is a %s, which this walk cannot classify", path, typ.Kind())}
}
}
// TestWhatTheMintAddsAndTheScanDoesNotLoadCarriesNoNumber covers the other half
// of what the scan leaves out. The mint adds the issue's dependencies before it
// canonicalizes, and the scan reads without labels, so a number anywhere in a
// Dependency, a Comment, a BondRef or a label would be refused by the mint and
// invisible to the scan. None carries one today; a field that could (a Weight
// int on Dependency) fails here, and the person who adds it decides whether the
// scan has to load it.
func TestWhatTheMintAddsAndTheScanDoesNotLoadCarriesNoNumber(t *testing.T) {
for _, tc := range []struct {
name string
typ reflect.Type
}{
{"types.Dependency", reflect.TypeOf(types.Dependency{})},
{"types.Comment", reflect.TypeOf(types.Comment{})},
{"types.BondRef", reflect.TypeOf(types.BondRef{})},
{"a label", reflect.TypeOf("")},
{"the labels of an issue", reflect.TypeOf([]string(nil))},
} {
t.Run(tc.name, func(t *testing.T) {
if found := numberBearingPaths(tc.typ, tc.name, map[reflect.Type]bool{}); len(found) > 0 {
t.Fatalf("a field the mint writes and the scan does not load can hold a number:\n %s", strings.Join(found, "\n "))
}
})
}
}
// The walk is run against shapes it must flag and shapes it must not, for the
// same reason as the guard above.
func TestTheNumberFreeWalkFlagsEveryNumberBearingShape(t *testing.T) {
type weighted struct {
Weight int `json:"weight"`
}
type unsigned struct{ N uint32 }
type scored struct{ Score float64 }
type waiting struct{ Wait time.Duration }
type verbatim struct{ Blob json.RawMessage }
type anything struct{ Value any }
type keyed struct{ Extra map[string]string }
type nested struct{ Deps []*weighted }
type tagged struct {
Name string `json:"name"`
Tags []string `json:"tags"`
At time.Time `json:"at"`
Skipped int `json:"-"`
_ int
}
type recursive struct{ Next *recursive }
for name, typ := range map[string]reflect.Type{
"an int": reflect.TypeOf(weighted{}),
"an unsigned integer": reflect.TypeOf(unsigned{}),
"a float": reflect.TypeOf(scored{}),
"a time.Duration": reflect.TypeOf(waiting{}),
"a json.RawMessage": reflect.TypeOf(verbatim{}),
"an interface": reflect.TypeOf(anything{}),
"a map": reflect.TypeOf(keyed{}),
"an int behind slice+pointer": reflect.TypeOf(nested{}),
} {
if found := numberBearingPaths(typ, "x", map[reflect.Type]bool{}); len(found) == 0 {
t.Errorf("%s was not flagged", name)
}
}
for name, typ := range map[string]reflect.Type{
"strings, a time, a skipped int and an unexported int": reflect.TypeOf(tagged{}),
"a type that contains itself": reflect.TypeOf(recursive{}),
} {
if found := numberBearingPaths(typ, "x", map[reflect.Type]bool{}); len(found) != 0 {
t.Errorf("%s was flagged: %v", name, found)
}
}
}
// There is ONE check, CheckIssueVersionable, and the scan and the mint both go
// through it. A check over a part of the issue, the metadata alone as there once
// was, can pass what the mint refuses, and an exported one invites reuse by the
// next caller (a doctor check, say) that then inherits the gap. So no exported
// function in the package may be named for versionability beside the check and
// the scan that calls it.
func TestNoExportedCheckOverASubPartOfTheIssueExistsBesideCheckIssueVersionable(t *testing.T) {
fset := token.NewFileSet()
pkgs, err := parser.ParseDir(fset, ".", func(fi fs.FileInfo) bool {
return !strings.HasSuffix(fi.Name(), "_test.go")
}, parser.SkipObjectResolution)
if err != nil {
t.Fatalf("parse issueops package: %v", err)
}
allowed := map[string]bool{"CheckIssueVersionable": true, "FindUnversionable": true}
seen := map[string]bool{}
var stray []string
for _, pkg := range pkgs {
for _, file := range pkg.Files {
for _, decl := range file.Decls {
fn, ok := decl.(*ast.FuncDecl)
if !ok || fn.Recv != nil || !fn.Name.IsExported() {
continue
}
if !strings.Contains(strings.ToLower(fn.Name.Name), "versionable") {
continue
}
seen[fn.Name.Name] = true
if !allowed[fn.Name.Name] {
stray = append(stray, fmt.Sprintf("%s (%s)", fn.Name.Name, fset.Position(fn.Pos())))
}
}
}
}
sort.Strings(stray)
if len(stray) > 0 {
t.Errorf("an exported check over part of the issue exists beside CheckIssueVersionable: %s", strings.Join(stray, ", "))
}
for name := range allowed {
if !seen[name] {
t.Errorf("%s was not found: this guard no longer sees the check it protects", name)
}
}
}

View file

@ -0,0 +1,53 @@
package issueops
import (
"errors"
"github.com/steveyegge/beads/internal/types"
)
// UnversionableIssue names one issue that RecordVersionInTx would refuse to
// version, and the refusal it would return. Field is the top-level field of the
// issue the refusal was found in ("metadata", "timeout"), empty when the refusal
// does not name one.
type UnversionableIssue struct {
ID string
Field string
Err error
}
// FindUnversionable runs CheckIssueVersionable over every issue in issues that
// the mint would version and returns the ones it refuses, in the order they were
// given. It is the core of the check made when versioned history is switched on:
// with history on, a write that introduces a value the mint refuses aborts in its
// own transaction, but a row that already holds one -- written while history was
// off, or by a path that does not mint -- would, if it participates in history,
// fail every later write to it. The check is over the whole issue, as the mint's
// is, and not over its metadata alone: a gate's timeout past 2^53-1 nanoseconds is
// refused too.
//
// It skips the rows the mint never versions by IsWisp: ephemeral and no-history
// rows are never versioned, so a value they hold can never abort a write. It
// cannot skip legacy rows, because participation is not on types.Issue, so on a
// store with the write fence (design §16.2b) it is a deliberate
// over-approximation: the mint skips a legacy row whatever it holds, and this
// still refuses over it, which is the safe direction because it can only refuse
// more. It does no I/O; the caller loads the rows, which is what lets one
// function serve the direct store and the proxied route.
func FindUnversionable(issues []*types.Issue) []UnversionableIssue {
var found []UnversionableIssue
for _, issue := range issues {
if issue == nil || IsWisp(issue) {
continue
}
if err := CheckIssueVersionable(issue); err != nil {
var named *refusedFieldError
field := ""
if errors.As(err, &named) {
field = named.field
}
found = append(found, UnversionableIssue{ID: issue.ID, Field: field, Err: err})
}
}
return found
}

View file

@ -0,0 +1,77 @@
package issueops
import (
"context"
"database/sql"
"fmt"
"github.com/steveyegge/beads/internal/storage"
)
// ListVersionsInTx returns every retained version of issueID, newest first.
//
// No subquery wrapper here, deliberately: HistoryInTx wraps its select
// because dolt_history_issues is a Dolt SYSTEM table and the planner's
// max1Row optimization mis-assumes WHERE id=? yields one row. issue_versions
// is an ordinary user table with a composite (issue_id, revision) primary
// key, so that optimization does not apply and the wrapper would only cost a
// materialization.
//
// An issue with no versions returns an empty slice and no error -- that is a
// truthful "nothing retained here", and it is the CALLER's job to distinguish
// it from "the feature is off" and from "no such issue", which it cannot do
// from this result alone.
//
// A removed version's RemovedRestriction is one of the as-of read's four values:
// whatever else the column holds, a NULL or empty one included, is reported as
// unknown, exactly as AsOfReadInTx reports it. A version that was not removed
// carries none.
func ListVersionsInTx(ctx context.Context, tx DBTX, issueID string) ([]storage.IssueVersion, error) {
rows, err := tx.QueryContext(ctx, `
SELECT
issue_id, revision, epoch,
COALESCE(change_actor, '') AS change_actor,
COALESCE(change_agent, '') AS change_agent,
COALESCE(change_message, '') AS change_message,
change_at,
COALESCE(attribution_status, '') AS attribution_status,
removed_at,
COALESCE(removed_reason, '') AS removed_reason,
COALESCE(removed_restriction, '') AS removed_restriction,
COALESCE(LENGTH(durable_state), 0) AS state_bytes
FROM issue_versions
WHERE issue_id = ?
ORDER BY revision DESC
`, issueID)
if err != nil {
return nil, fmt.Errorf("failed to list issue versions: %w", err)
}
defer func() { _ = rows.Close() }()
var out []storage.IssueVersion
for rows.Next() {
var v storage.IssueVersion
var removedAt sql.NullTime
if err := rows.Scan(
&v.IssueID, &v.Revision, &v.Epoch,
&v.ChangeActor, &v.ChangeAgent, &v.ChangeMessage, &v.ChangeAt,
&v.AttributionStatus,
&removedAt, &v.RemovedReason, &v.RemovedRestriction,
&v.StateBytes,
); err != nil {
return nil, fmt.Errorf("failed to scan issue version: %w", err)
}
if removedAt.Valid {
t := removedAt.Time
v.RemovedAt = &t
v.RemovedRestriction = string(NormalizeRemovedRestriction(v.RemovedRestriction))
} else {
v.RemovedRestriction = ""
}
out = append(out, v)
}
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("failed to read issue versions: %w", err)
}
return out, nil
}

View file

@ -33,6 +33,30 @@ var neverSatisfiedTags = map[string]bool{"ignore": true, "never": true}
const importerOneAccessorWaiverReason = "Importer has one accessor (uow.ImporterSource); " +
"the store legs run bd import through the raw seam and implement no Importer role"
// asOfReadNoHTTPWireWaiverReason covers the five R7.1 as-of read contracts
// (backend/conformance/versioned_read_contract.go). Unlike the
// participation-generation cases, which run on this leg because their subject
// is a create or an update the client can send
// (internal/httpclient/served_participation_generation_test.go), the subject
// here is the read itself, AsOfReadFixture.Resolve, and it has no form on the
// wire:
// - R7.1's read is issueops.AsOfReadInTx. No publicops role reaches it and no
// wire operation serves it, so there is nothing for the client to call.
// - The wire carries neither selector (an instant, or a previously served
// version address) nor the gone/unknown refusal the read answers with.
// - The client's only point-in-time read, storage.DoltStorage.AsOf, is a
// Dolt commit-ref read, not R7.1, and it is on the client's unsupported
// allowlist (D8: v0 publishes no history surface).
//
// Binding Resolve to the reference store behind the served env would run the
// cases green, but as a property of that store, never of the client; the store
// legs already pin it. The waiver stands until the wire publishes an as-of
// read.
const asOfReadNoHTTPWireWaiverReason = "the read under test has no form on the http wire: R7.1's as-of read " +
"(issueops.AsOfReadInTx) is reached by no publicops role and no wire operation, the wire carries neither an " +
"instant/version-address selector nor a gone/unknown refusal, and the client's only point-in-time read, " +
"DoltStorage.AsOf, is a Dolt commit-ref read on its unsupported allowlist (D8)"
// The waivers of the three legs registered here. Each is registered beside its
// leg rather than written into one literal, so a leg registered elsewhere
// brings its waivers the same way; see unwiredContractEntrypoints.
@ -57,6 +81,12 @@ func init() {
"RunIssueOperationsCreateParentChildRecomputesWaitsForClosure": stagingWaiverReason,
})
registerContractLegWaivers("http", map[string]string{
"RunAsOfReadIsCompleteOnlyForTheAnsweringStoresHoldings": asOfReadNoHTTPWireWaiverReason,
"RunAsOfReadRefusesAsGoneOrUnknownNeverSubstitutingAnotherVersion": asOfReadNoHTTPWireWaiverReason,
"RunAsOfReadReportsTheAddressItServed": asOfReadNoHTTPWireWaiverReason,
"RunAsOfReadReturnsTheLatestVersionAtOrBeforeTStrictlyExcludingLater": asOfReadNoHTTPWireWaiverReason,
"RunAsOfReadSelectorAcceptsEitherAnInstantOrAVersionAddress": asOfReadNoHTTPWireWaiverReason,
"RunCycleDetectorIncludeTracksFindsTheMoleculeRootShape": cycleTracksWireGapWaiverReason,
"RunCycleDetectorIncludeTracksIgnoresAPureTracksLoop": cycleTracksWireGapWaiverReason,
"RunCycleDetectorIncludeTracksWalksEachEdgeInItsStoredDirection": cycleTracksWireGapWaiverReason,

View file

@ -120,6 +120,7 @@ go_library(
"migrations/0069_widen_issue_versions_datetime_precision.up.sql",
"migrations/ignored/0028_add_wisps_participation_generation.up.sql",
"migrations/0070_add_participation_generation.up.sql",
"migrations/0071_add_removed_restriction.up.sql",
],
importpath = "github.com/steveyegge/beads/internal/storage/schema",
visibility = ["//:__subpackages__"],
@ -154,6 +155,7 @@ go_test(
"migration_0068_add_attribution_status_test.go",
"migration_0069_datetime_precision_test.go",
"migration_0070_add_participation_generation_test.go",
"migration_0071_add_removed_restriction_test.go",
"migration_body_drain_test.go",
"migration_freeze_test.go",
"migration_watchdog_test.go",
@ -169,6 +171,7 @@ go_test(
deps = [
"//internal/debug",
"//internal/storage/depid",
"//internal/storage/issueops",
"//internal/storage/rowid",
"//internal/testutil",
"@com_github_data_dog_go_sqlmock//:go-sqlmock",

View file

@ -168,6 +168,15 @@ func cliCompatibleMigrationSQL(name, sqlText string) string {
// substitute ALTERs wisps directly, the same as 0067's, so it
// belongs on cliSubstituteAssumesWispTables too.
return cliMigration0070AddParticipationGeneration
case "0071_add_removed_restriction.up.sql":
// Direct DDL for the same reason as 0067/0068: the source migration's
// PREPARE guard (an INFORMATION_SCHEMA probe) is what makes the raw
// .up.sql idempotent when replayed onto an already-migrated store,
// and the 2.2.x CLI no-ops a prepared ADD COLUMN. issue_versions is
// always present here -- 0067 runs earlier in the same fresh-bundle
// series -- and never carries removed_restriction yet, so the column
// always needs adding on a fresh bundle.
return cliMigration0071AddRemovedRestriction
default:
return sqlText
}
@ -318,6 +327,12 @@ ALTER TABLE issue_versions MODIFY COLUMN removed_at DATETIME(6);`
const cliMigration0070AddParticipationGeneration = `ALTER TABLE issues ADD COLUMN participation_generation BIGINT NULL;
ALTER TABLE wisps ADD COLUMN participation_generation BIGINT NULL;`
// cliMigration0071AddRemovedRestriction is 0071 with its one guarded PREPARE
// block replaced by the direct ALTER it would run on a fresh database.
// issue_versions is created earlier in the same series by 0067 and never
// carries removed_restriction yet, so the column always needs adding here.
const cliMigration0071AddRemovedRestriction = `ALTER TABLE issue_versions ADD COLUMN removed_restriction VARCHAR(30);`
const cliMigration0041SplitDependenciesTarget = `DELETE FROM dolt_nonlocal_tables;
CALL DOLT_COMMIT('-Am', 'disable nonlocal tables for fk migrations');
SET FOREIGN_KEY_CHECKS = 0;

View file

@ -39,6 +39,12 @@ const migration0069Down = "0069_widen_issue_versions_datetime_precision.down.sql
const migration0069ChangeAtDatetimeGuard = "@issue_versions_change_at_needs_widen"
const migration0069RemovedAtDatetimeGuard = "@issue_versions_removed_at_needs_widen"
// TestLatestVersionIncludesMigration0069 (pinning LatestVersion() == 69) is
// superseded by TestLatestVersionIncludesMigration0070
// (migration_0070_add_participation_generation_test.go) now that 0070 claims the
// next free slot; only one such pin lives at a time, matching how this
// test itself already superseded 0068's own version.
// TestMigration0069WidensChangeAtAndRemovedAtPrecision is the pure-Go,
// DB-independent half of the pin, mirroring
// TestMigration0068AddsAttributionStatus's shape: it checks the frozen

View file

@ -33,20 +33,11 @@ import (
const migration0070Up = "0070_add_participation_generation.up.sql"
const migration0070Down = "0070_add_participation_generation.down.sql"
// TestLatestVersionIncludesMigration0070 pins the real next free slot this
// migration claims, superseding 0069's own version of this test
// (LatestVersion() moved from 69 to 70 the moment this migration file was
// added). Deliberately a hardcoded literal for the same reason 0067's,
// 0068's, and 0069's were: LatestVersion() drifting to 70 for the wrong
// reason (an unrelated migration landing first) should still be caught by
// this test failing to explain why 70 is participation_generation-shaped,
// which the CLI test below checks.
func TestLatestVersionIncludesMigration0070(t *testing.T) {
const want = 70
if got := LatestVersion(); got != want {
t.Fatalf("LatestVersion() = %d, want %d (issues/wisps participation_generation migration slot claimed by be-h89oq)", got, want)
}
}
// TestLatestVersionIncludesMigration0070 (pinning LatestVersion() == 70) is
// superseded by TestLatestVersionIncludesMigration0071
// (migration_0071_add_removed_restriction_test.go) now that 0071 claims the
// next free slot; only one such pin lives at a time, matching how this
// test itself already superseded 0069's own version.
// TestMigration0070AddsParticipationGeneration is the pure-Go, DB-independent
// half of the pin, mirroring TestMigration0069WidensChangeAtAndRemovedAtPrecision's

View file

@ -0,0 +1,171 @@
package schema
import (
"os"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/testutil"
)
// R7.1 as-of read (gastownhall/beads#5898 revision 9, gastownhall/beads#6136)
// adds one nullable column: issue_versions gains
// removed_restriction VARCHAR(30). issue_versions already carries removed_at
// and removed_reason (migration 0067), virgin and unused until this slice;
// AsOfReadInTx (internal/storage/issueops/asof_read.go) reads all three as
// the durable "this version row was removed" marker. removed_restriction
// carries the categorical restriction removed_at's presence alone cannot:
// gone_retention / gone_erasure / gone_reorganization / unknown, never
// live -- live is the absence of a value, not a stored one.
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)
}
}
// TestMigration0071AddsRemovedRestriction is a pure-Go, DB-independent check
// of the frozen migration bytes themselves — it runs even where no `dolt`
// binary is available.
//
// It pins the same guarded-PREPARE shape 0067/0068 use and for the same
// reason: the guard is what makes a raw replay of this file onto an
// already-migrated store a no-op, and Dolt accepts no unprepared conditional
// ADD COLUMN. The cost is the same pre-2.3 CLI hazard those migrations carry,
// so this migration needs the same direct-DDL override in
// cliCompatibleMigrationSQL, policed by the same two guard tests
// (TestBundleMigrationsWithPreparedALTERAreOverriddenOrJustified and
// TestAllMigrationsSQLUsesDirectDDLForKnownCLIIncompatibilities).
func TestMigration0071AddsRemovedRestriction(t *testing.T) {
upSQL, err := MigrationSQL(migration0071Up)
if err != nil {
t.Fatalf("MigrationSQL(%s) error = %v, want the migration file to exist", migration0071Up, err)
}
for _, want := range []string{
"ALTER TABLE issue_versions ADD COLUMN removed_restriction VARCHAR(30)",
"COLUMN_NAME = 'removed_restriction'",
"@issue_versions_rr_needs_add",
} {
if !strings.Contains(upSQL, want) {
t.Errorf("0071 up migration missing %q\nfull SQL:\n%s", want, upSQL)
}
}
if !strings.Contains(strings.ToUpper(upSQL), "PREPARE STMT FROM @SQL") {
t.Error("0071 up migration must keep its guarded PREPARE block — it is what makes a raw .up.sql replay onto an already-migrated store a no-op, and Dolt accepts no unprepared conditional ADD COLUMN. Unwrapping it also invalidates cliMigration0071AddRemovedRestriction.")
}
// The bundle override is what keeps the PREPARE above off the pre-2.3
// CLI path. Assert it directly rather than trusting the two schema_test
// assertions to stay pointed at this migration.
const wantDirectDDL = "ALTER TABLE issue_versions ADD COLUMN removed_restriction VARCHAR(30);"
if !strings.Contains(cliCompatibleMigrationSQL(migration0071Up, upSQL), wantDirectDDL) {
t.Errorf("0071's CLI bundle substitute missing direct DDL %q", wantDirectDDL)
}
if cliSubstituteAssumesWispTables(migration0071Up) {
t.Error("0071's CLI substitute touches only issue_versions, which has no wisps-side counterpart table — it must not be listed in cliSubstituteAssumesWispTables")
}
// down.sql files are not part of the embedded FS (only migrations/*.up.sql
// is //go:embed'd — see mainSource.files), so unlike the up side above,
// this reads straight from disk by package-relative path, matching
// TestMigration0067AddsVersionedBeadsSchema's / TestMigration0068AddsAttributionStatus's
// precedent.
downBytes, err := os.ReadFile("migrations/" + migration0071Down)
if err != nil {
t.Fatalf("read %s: %v, want the migration file to exist", migration0071Down, err)
}
downSQL := string(downBytes)
for _, want := range []string{
"ALTER TABLE issue_versions DROP COLUMN removed_restriction",
"COLUMN_NAME = 'removed_restriction'",
} {
if !strings.Contains(downSQL, want) {
t.Errorf("0071 down migration missing %q\nfull SQL:\n%s", want, downSQL)
}
}
// Only migrations/*.up.sql is embedded into the CLI fresh bundle
// (mainSource.files), so the pre-2.3 prepared-DDL hazard never reaches a
// down migration and the guard is free — 0060's/0067's/0068's downs are
// the precedent.
if !strings.Contains(strings.ToUpper(downSQL), "PREPARE STMT FROM @SQL") {
t.Error("0071 down migration must guard its DROP COLUMN the way the up migration guards its ADD COLUMN, so a partially-applied or already-rolled-back workspace rolls back safely")
}
}
// TestMigration0071HeaderSpellsTheVocabularyTheCodeStores pins the header's
// vocabulary to the constants that store, read and label the column (finding 6
// of the #6661 review). The header is the one place a writer learns which
// strings to store, and a writer follows it literally: it said gone-retention,
// the code compares gone_retention, so a row written from the header was not
// recognised and rendered without a label. Deriving the expected spellings
// from the constants keeps the two from drifting apart again.
//
// Pure Go, like TestMigration0071AddsRemovedRestriction: it reads the frozen
// bytes and needs no `dolt` binary.
func TestMigration0071HeaderSpellsTheVocabularyTheCodeStores(t *testing.T) {
upSQL, err := MigrationSQL(migration0071Up)
if err != nil {
t.Fatalf("MigrationSQL(%s) error = %v, want the migration file to exist", migration0071Up, err)
}
for _, stored := range []issueops.AsOfRestriction{
issueops.AsOfRestrictionGoneRetention,
issueops.AsOfRestrictionGoneErasure,
issueops.AsOfRestrictionGoneReorganization,
issueops.AsOfRestrictionUnknown,
} {
if !strings.Contains(upSQL, string(stored)) {
t.Errorf("0071 header never spells the stored value %q", stored)
}
if hyphenated := strings.ReplaceAll(string(stored), "_", "-"); hyphenated != string(stored) && strings.Contains(upSQL, hyphenated) {
t.Errorf("0071 header spells %q as %q; the code stores and compares the underscore spelling, so a writer following the header stores a value that renders unlabeled", stored, hyphenated)
}
}
}
// TestMigration0071AddsRemovedRestrictionThroughDoltCLI applies the full
// migration bundle through a real `dolt` binary (skipped without one — see
// testutil.RequireDoltBinary) and checks the shape acceptance criteria a
// pure-Go SQL-text check cannot: actual column type/nullability as Dolt
// reports it, and that the column stays NULL for a row that never sets it
// (Live is the absence of a value) while round-tripping any of the four
// restriction strings a row does set it to.
func TestMigration0071AddsRemovedRestrictionThroughDoltCLI(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, "issue_versions", "removed_restriction", "varchar(30)", "YES")
requireDoltNoRows(t, dir, "SELECT issue_id FROM issue_versions", "issue_versions")
runDoltSQL(t, dir, `INSERT INTO issue_versions (issue_id, revision, epoch, change_at, attribution_status) VALUES ('iv-1', 1, 1, '2026-09-01 00:00:00', 'claimed')`)
// issue_id rides along as a non-NULL anchor column: queryDoltCSV trims the
// whole `dolt sql -r csv` output before parsing, and a row whose ONLY
// selected column is NULL renders as a bare blank line, which
// strings.TrimSpace swallows when it's the trailing line -- silently
// turning "one row, NULL value" into "zero rows" and passing the wrong
// assertion for the wrong reason. Selecting issue_id alongside keeps the
// row's CSV line non-blank so it survives the trim.
rows := queryDoltCSV(t, dir, `SELECT issue_id, removed_restriction FROM issue_versions WHERE issue_id = 'iv-1'`)
if len(rows) != 1 || rows[0]["removed_restriction"] != "" {
t.Fatalf("removed_restriction for a row that never set it = %v, want NULL/empty (Live is the absence of a value)", rows)
}
runDoltSQL(t, dir, `INSERT INTO issue_versions (issue_id, revision, epoch, change_at, attribution_status, removed_at, removed_reason, removed_restriction) VALUES ('iv-2', 1, 1, '2026-09-01 00:00:00', 'claimed', '2026-09-02 00:00:00', 'retention window elapsed', 'gone_retention')`)
rows = queryDoltCSV(t, dir, `SELECT issue_id, removed_restriction FROM issue_versions WHERE issue_id = 'iv-2'`)
if len(rows) != 1 || rows[0]["removed_restriction"] != "gone_retention" {
t.Fatalf("removed_restriction round-trip failed post-migration: %v", rows)
}
}

View file

@ -0,0 +1,16 @@
-- Reverse of 0071: drop issue_versions.removed_restriction.
--
-- Guarded on INFORMATION_SCHEMA the same way 0067/0068's downs are, so a
-- partially-applied or already-rolled-back workspace rolls back safely.
-- Only migrations/*.up.sql is embedded into the CLI fresh bundle, so the
-- PREPARE hazard (cli_prepared_ddl.go) never reaches this file.
SET @issue_versions_rr_has = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'issue_versions'
AND COLUMN_NAME = 'removed_restriction'
);
SET @sql = IF(@issue_versions_rr_has > 0,
'ALTER TABLE issue_versions DROP COLUMN removed_restriction',
'SELECT 1');
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;

View file

@ -0,0 +1,49 @@
-- Migration 0071: R7.1 as-of read (gastownhall/beads#5898 revision 9,
-- gastownhall/beads#6136); conformance suite: backend/conformance/
-- versioned_read_contract.go.
--
-- issue_versions already carries removed_at DATETIME and removed_reason
-- VARCHAR(255) (migration 0067), virgin and unused until now: R7.1's
-- AsOfReadInTx (internal/storage/issueops/asof_read.go) reads them as the
-- durable "this version row was removed" marker on the resolved row, and
-- refuses a served answer whenever removed_at is set (R8: never silently
-- substitute a neighboring/surviving/current version).
--
-- removed_restriction VARCHAR(30) is the one column this migration adds: the
-- categorical restriction (gone_retention / gone_erasure /
-- gone_reorganization / unknown) that removed_at's presence alone cannot
-- carry. Nullable and NULL for every existing row -- Live is the absence of
-- a value, never a stored one -- and populated only alongside removed_at,
-- never independently. 30 chars comfortably fits the longest local
-- constant (internal/storage/issueops/asof_read.go's AsOfRestriction,
-- "gone_reorganization", 19 bytes) with headroom, matching change_agent's
-- own no-tight-fit precedent elsewhere in this table.
--
-- Forward-compatible with R17 (not yet implemented on this branch): R17's
-- eventual real hold/remove/erase primitives will be the production WRITER
-- of these three columns; R7.1 only reads them here. No future collision --
-- this migration only adds the one column R17 will also need, it does not
-- claim the writing role.
--
-- Guarded the same way 0067/0068 guard their ADD COLUMNs (see 0067's header
-- for the full explanation): no MariaDB-only IF NOT EXISTS on Dolt 2.2.3's
-- ADD COLUMN, so an INFORMATION_SCHEMA probe + PREPARE is the only
-- replay-safe shape. Needs a CLI-bundle direct-DDL override
-- (cliMigration0071AddRemovedRestriction in cli_migrations.go), the same
-- dolthub/dolt#11345 escape hatch 0067/0068 use, guarded by
-- TestBundleMigrationsWithPreparedALTERAreOverriddenOrJustified.
--
-- No wisps twin: issue_versions has no wisps-side counterpart table (design
-- section 16.3), so cliSubstituteAssumesWispTables does not apply here
-- either, matching 0068.
SET @issue_versions_rr_needs_add = (
SELECT IF(COUNT(*) = 0, 1, 0)
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'issue_versions'
AND COLUMN_NAME = 'removed_restriction'
);
SET @sql = IF(@issue_versions_rr_needs_add = 1,
'ALTER TABLE issue_versions ADD COLUMN removed_restriction VARCHAR(30)',
'SELECT 1');
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;

View file

@ -1974,6 +1974,9 @@ func TestAllMigrationsSQLUsesDirectDDLForKnownCLIIncompatibilities(t *testing.T)
// 0070: two-plane prepared ADD COLUMN, same shape as 0067.
"ALTER TABLE issues ADD COLUMN participation_generation BIGINT NULL;",
"ALTER TABLE wisps ADD COLUMN participation_generation BIGINT NULL;",
// 0071: single-plane prepared ADD COLUMN, same shape as 0068's
// attribution_status (no wisps twin -- issue_versions has none).
"ALTER TABLE issue_versions ADD COLUMN removed_restriction VARCHAR(30);",
} {
if !strings.Contains(got, want) {
t.Fatalf("AllMigrationsSQL missing direct CLI DDL %q", want)
@ -2010,6 +2013,9 @@ func TestAllMigrationsSQLUsesDirectDDLForKnownCLIIncompatibilities(t *testing.T)
// 0070 guards both planes' ALTERs the same way, mirroring 0067's pair.
"@issues_pg_needs_add",
"@wisps_pg_needs_add",
// 0071 guards its ALTER the same way; only its source text carries
// this probe.
"@issue_versions_rr_needs_add",
} {
if strings.Contains(got, forbidden) {
t.Fatalf("AllMigrationsSQL contains source prepared-DDL guard %q", forbidden)

View file

@ -175,6 +175,7 @@ go_test(
"version_reconcile_boot_test.go",
"version_reconcile_integration_test.go",
"version_reconciler_contract_test.go",
"versioned_read_contract_test.go",
"workspace_config_contract_test.go",
],
data = [

View file

@ -33,6 +33,9 @@ func TestParticipationGenerationFence(t *testing.T) {
t.Run("ProceedsForPromotedRecord", func(t *testing.T) {
conformance.RunParticipationGenerationProceedsForPromotedRecord(t, ctx, fixture)
})
t.Run("FlagOffSkipsUpdateOnParticipatingRecord", func(t *testing.T) {
conformance.RunParticipationGenerationFlagOffSkipsUpdateOnParticipatingRecord(t, ctx, fixture)
})
t.Run("FenceIgnoresSchemaSkewHatch", func(t *testing.T) {
conformance.RunParticipationGenerationFenceIgnoresSchemaSkewHatch(t, ctx, fixture)
})

View file

@ -0,0 +1,404 @@
package uow
import (
"context"
"crypto/rand"
"encoding/hex"
"fmt"
"os/exec"
"path/filepath"
"testing"
"time"
"github.com/stretchr/testify/require"
"github.com/steveyegge/beads/backend/conformance"
"github.com/steveyegge/beads/internal/storage/dbproxy/proxy"
"github.com/steveyegge/beads/internal/storage/domain"
storageissueops "github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/testutil"
"github.com/steveyegge/beads/internal/types"
)
// asOfReadHarness is this leg's Design D dispatch table (gastownhall/beads#5898
// revision 9, gastownhall/beads#6136): the conformance suite
// invents storeID values to select among N genuinely isolated stores, and
// isolating them is entirely this harness's job -- AsOfReadInTx itself is
// storeID-oblivious (see the package doc on
// internal/storage/issueops/asof_read.go). Each storeID gets its own fresh
// UnitOfWorkProvider, built lazily on first use (provider) and torn down via
// t.Cleanup on the TestAsOfReadContract-level *testing.T. created tracks
// which (storeID, id) pairs already have a base issues row, since mintAt's
// second and later calls for the same pair must only add a historical
// issue_versions row, never a second base create.
//
// UNLIKE the dolt leg's buildAsOfReadStore (one shared testcontainer, N
// randomly-named databases) or the embeddeddolt leg's buildAsOfReadStore (N
// fully independent on-disk databases, isolation free), this leg spawns one
// real dolt sql-server SUBPROCESS per NewDoltServerUOWProvider call unless
// that call adopts an already-running one. Booting N subprocesses -- one per
// storeID, up to seven across a full TestAsOfReadContract run -- would be
// needlessly heavy, so this harness follows the same "one shared server, many
// databases" shape the dolt leg uses: TestAsOfReadContract does the ONE
// heavyweight, Fatal-permitted setup (dolt/bd binaries, HOME, port,
// storeRootDir, server config, log path) once in its own body, before any
// t.Run, and hands the resulting coordinates to newAsOfReadHarness. provider()
// then calls NewDoltServerUOWProvider -- a pure, Fatal-free function -- against
// those SAME coordinates with a fresh, randomly-named database per storeID.
// proxy.GetCreateDatabaseProxyServerEndpoint's adoption semantics (given the
// same rootDir, a later call dials the already-running server instead of
// spawning a duplicate, regardless of which database name it carries -- see
// TestNewDoltServerUOWProvider_ConcurrentInstantiation) mean only ONE server
// process is ever spawned, no matter how many storeIDs a case invents.
//
// storeID itself is used ONLY as a map key into h.providers here -- never as
// the database name. The conformance suite's storeID strings are built from
// free-form tags (asOfReadStore in backend/conformance/
// versioned_read_contract.go: fixture.IssuePrefix + "-asof-store-" + tag,
// where tag can itself embed a Restriction's hyphenated String()), so they are
// not assumed to be safe SQL/Dolt identifiers. Generating an independent
// random per-store database name (asOfReadDatabaseName, matching the dolt
// leg's own dbSuffix approach) sidesteps that question entirely rather than
// sanitizing storeID.
//
// provider() cannot use newTestUOWProvider or newUOWRoleFixtureProvider.
// AsOfReadFixture's hook types (Resolve/MintAt/MakeUnanswerable) carry no
// *testing.T of their own, so a provider built lazily inside a hook -- itself
// invoked from inside a t.Run subtest closure, sometimes nested two deep (the
// restriction-loop case) -- has access only to whichever *testing.T this
// harness was constructed with: necessarily the OUTER TestAsOfReadContract's
// t, captured before any t.Run. Both of those helpers call testify's
// require.NoError / t.Fatalf internally, and calling FailNow/SkipNow on a
// *testing.T from a goroutine other than the one running that exact test --
// which a t.Run subtest's closure always is, relative to the outer test --
// panics with "subtest may have called FailNow on a parent test" (go's
// testing package requires FailNow/SkipNow to run only on the goroutine
// executing that specific test). provider() is a Fatalf/Skip-free path for
// exactly this reason: its failures come back as a plain error, which flows
// through the calling hook's own (..., error) return to
// conformance.RunAsOfReadXXX, which correctly Fatalfs using the SUBTEST's own
// *testing.T on the SUBTEST's own goroutine. Also unlike
// newUOWRoleFixtureProvider (one provider for a whole role suite, matching
// roleFixtureKit's frozen shape), this harness needs N independently-isolated
// providers -- roleFixtureKit is deliberately not reused here; see this
// file's own note by conformanceToAsOfRestriction on why issueops must stay
// conformance-oblivious, the same boundary that keeps this harness's own
// mapping from living centrally.
//
// See internal/storage/dolt/versioned_read_contract_test.go and
// internal/storage/embeddeddolt/versioned_read_contract_test.go for this
// leg's siblings, which this file mirrors as closely as the three backends'
// construction APIs allow.
type asOfReadHarness struct {
t *testing.T
storeRootDir string
doltBin string
cfgPath string
logPath string
providers map[string]UnitOfWorkProvider
created map[[2]string]bool
}
func newAsOfReadHarness(t *testing.T, storeRootDir, doltBin, cfgPath, logPath string) *asOfReadHarness {
return &asOfReadHarness{
t: t,
storeRootDir: storeRootDir,
doltBin: doltBin,
cfgPath: cfgPath,
logPath: logPath,
providers: map[string]UnitOfWorkProvider{},
created: map[[2]string]bool{},
}
}
// provider returns storeID's UnitOfWorkProvider, building it on first use
// against a fresh, randomly-named database on the shared server. See the
// asOfReadHarness doc comment for why this function -- and everything it
// calls -- must never call *testing.T's Fatalf/Skip.
func (h *asOfReadHarness) provider(ctx context.Context, storeID string) (UnitOfWorkProvider, error) {
if p, ok := h.providers[storeID]; ok {
return p, nil
}
database, err := asOfReadDatabaseName()
if err != nil {
return nil, err
}
provider, err := NewDoltServerUOWProvider(
ctx,
h.storeRootDir,
database,
h.logPath,
h.cfgPath,
proxy.BackendLocalServer,
"root",
"",
h.doltBin,
0,
0,
false,
"",
)
if err != nil {
return nil, fmt.Errorf("as-of read fixture: new provider for store %q (database %q): %w", storeID, database, err)
}
// t.Cleanup only appends to a mutex-guarded slice -- unlike Fatalf/Skip it
// never calls runtime.Goexit, so registering it on the outer h.t from
// inside a subtest's goroutine is safe. h.t's own cleanups run only after
// ALL of TestAsOfReadContract's t.Run calls have returned (none of them,
// nor their own nested t.Run calls, ever invoke t.Parallel), so every
// provider this harness builds stays open for the whole test. These
// per-provider Close cleanups are registered AFTER (so, per t.Cleanup's
// LIFO order, run BEFORE) TestAsOfReadContract's own shared
// verifiedShutdownCleanup (proxy.Shutdown) cleanup, so every provider is
// closed while the server they share is still up.
h.t.Cleanup(func() { _ = provider.Close(context.Background()) })
if err := RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) {
return "bd: set issue prefix", uw.ConfigUseCase().SetConfig(ctx, "issue_prefix", "asof")
}); err != nil {
return nil, fmt.Errorf("as-of read fixture: set issue_prefix for store %q: %w", storeID, err)
}
h.providers[storeID] = provider
return provider, nil
}
// asOfReadDatabaseName mints a fresh, unique database name, independent of
// any storeID's own content -- see the asOfReadHarness doc comment for why
// storeID itself is never used as one.
func asOfReadDatabaseName() (string, error) {
suffix := make([]byte, 6)
if _, err := rand.Read(suffix); err != nil {
return "", fmt.Errorf("as-of read fixture: generate db name: %w", err)
}
return "asof_" + hex.EncodeToString(suffix), nil
}
// ensureCreated bare-creates id in storeID's store the first time it is
// asked for, giving RecordVersionAtInTx (called from mintAt) a base issues
// row to snapshot -- recordVersionAtInTx starts with GetIssueInTx, so it has
// nothing to read until this has run once. This goes through the real
// IssueUseCase, the same production entry point batch_creator.go and
// issue_operations.go use, unlike resolve/mintAt/makeUnanswerable below,
// which reach the shared issueops body directly (see the package doc on
// internal/storage/issueops/asof_read.go: "ALL THREE LEGS SHARE THIS BODY").
func (h *asOfReadHarness) ensureCreated(ctx context.Context, storeID, id string) error {
key := [2]string{storeID, id}
if h.created[key] {
return nil
}
provider, err := h.provider(ctx, storeID)
if err != nil {
return err
}
issue := &types.Issue{
ID: id,
Title: "as-of read fixture issue",
Status: types.StatusOpen,
Priority: 3,
IssueType: types.TypeTask,
}
err = RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) {
params := domain.CreateIssueParams{
Issue: issue,
ExplicitID: issue.ID,
CreateOnly: true,
}
_, err := uw.IssueUseCase().CreateIssue(ctx, params, "asof-read-fixture")
return "as-of read fixture: bare-create " + issue.ID, err
})
if err != nil {
return fmt.Errorf("as-of read fixture: bare-create %s: %w", id, err)
}
h.created[key] = true
return nil
}
func (h *asOfReadHarness) resolve(ctx context.Context, storeID, id string, selector conformance.AsOfSelector) (conformance.AsOfReadResult, error) {
provider, err := h.provider(ctx, storeID)
if err != nil {
return conformance.AsOfReadResult{}, err
}
result, err := RunTxRead(ctx, provider, func(ctx context.Context, uw UnitOfWork) (storageissueops.AsOfReadResult, error) {
runner, err := importStatementRunner(uw)
if err != nil {
return storageissueops.AsOfReadResult{}, err
}
return storageissueops.AsOfReadInTx(ctx, runner, storeID, id, toIssueopsSelector(selector))
})
if err != nil {
return conformance.AsOfReadResult{}, err
}
return toConformanceResult(result), nil
}
// mintAt is the two-phase implementation MintAt's contract needs: phase one
// (ensureCreated) runs only once per (storeID, id); phase two
// (RecordVersionAtInTx) runs every call and always supplies the row mintAt
// reports the address of. RecordVersionAtInTx deliberately does not gate on
// versionedHistoryEnabled (this harness never turns that on for its stores),
// so it always mints, and reading MAX(revision) back inside the same
// transaction (read-your-writes) is how we learn which revision it picked --
// RecordVersionAtInTx itself reports no revision number.
//
// The commit message returned to RunTxResult is deliberately non-empty: an
// empty commitMsg makes RunTxResultWithin skip calling uw.Commit entirely
// (tx.go), so the write would never persist past this attempt's implicit
// rollback -- exactly the RunTxEphemeral hazard its own doc comment warns
// against for versioned tables.
func (h *asOfReadHarness) mintAt(ctx context.Context, storeID, id string, acceptedAt time.Time) (conformance.Address, error) {
if err := h.ensureCreated(ctx, storeID, id); err != nil {
return "", err
}
provider, err := h.provider(ctx, storeID)
if err != nil {
return "", err
}
revision, err := RunTxResult(ctx, provider, func(ctx context.Context, uw UnitOfWork) (int64, string, error) {
runner, err := importStatementRunner(uw)
if err != nil {
return 0, "", err
}
if err := storageissueops.RecordVersionAtInTx(ctx, runner, id, "asof-read-fixture", acceptedAt); err != nil {
return 0, "", err
}
var rev int64
if err := runner.QueryRowContext(ctx,
`SELECT MAX(revision) FROM issue_versions WHERE issue_id = ?`, id,
).Scan(&rev); err != nil {
return 0, "", err
}
return rev, "as-of read fixture: mint version for " + id, nil
})
if err != nil {
return "", err
}
return conformance.Address(storageissueops.AsOfVersionAddress(id, revision)), nil
}
func (h *asOfReadHarness) makeUnanswerable(ctx context.Context, storeID, id string, restriction conformance.Restriction) error {
asOfRestriction, ok := conformanceToAsOfRestriction[restriction]
if !ok {
return fmt.Errorf("as-of read fixture: unmapped restriction %v", restriction)
}
provider, err := h.provider(ctx, storeID)
if err != nil {
return err
}
reason := fmt.Sprintf("as-of read fixture: made unanswerable as %s", restriction)
return RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) {
runner, err := importStatementRunner(uw)
if err != nil {
return "", err
}
if err := storageissueops.MarkLatestVersionRemovedInTx(ctx, runner, id, asOfRestriction, reason); err != nil {
return "", err
}
return "as-of read fixture: mark " + id + " removed", nil
})
}
// conformanceToAsOfRestriction and its inverse are this leg's translation
// boundary between backend/conformance.Restriction (hyphenated String(),
// int-backed) and issueops.AsOfRestriction (underscored, string-backed --
// its values ARE the removed_restriction column's contents). issueops must
// stay conformance-oblivious and conformance must stay backend-oblivious
// (internal/storage/issueops/asof_read.go's package doc), so this mapping is
// deliberately duplicated per leg rather than shared centrally.
var conformanceToAsOfRestriction = map[conformance.Restriction]storageissueops.AsOfRestriction{
conformance.RestrictionLive: storageissueops.AsOfRestrictionLive,
conformance.RestrictionGoneRetention: storageissueops.AsOfRestrictionGoneRetention,
conformance.RestrictionGoneErasure: storageissueops.AsOfRestrictionGoneErasure,
conformance.RestrictionGoneReorganization: storageissueops.AsOfRestrictionGoneReorganization,
conformance.RestrictionUnknown: storageissueops.AsOfRestrictionUnknown,
}
var asOfRestrictionToConformance = map[storageissueops.AsOfRestriction]conformance.Restriction{
storageissueops.AsOfRestrictionLive: conformance.RestrictionLive,
storageissueops.AsOfRestrictionGoneRetention: conformance.RestrictionGoneRetention,
storageissueops.AsOfRestrictionGoneErasure: conformance.RestrictionGoneErasure,
storageissueops.AsOfRestrictionGoneReorganization: conformance.RestrictionGoneReorganization,
storageissueops.AsOfRestrictionUnknown: conformance.RestrictionUnknown,
}
func toIssueopsSelector(selector conformance.AsOfSelector) storageissueops.AsOfSelector {
out := storageissueops.AsOfSelector{At: selector.At}
if selector.Version != nil {
out.Address = string(*selector.Version)
}
return out
}
func toConformanceResult(result storageissueops.AsOfReadResult) conformance.AsOfReadResult {
if result.Refused {
return conformance.AsOfReadResult{
Refusal: &conformance.AsOfReadRefusal{
Restriction: asOfRestrictionToConformance[result.Restriction],
Reason: result.Reason,
},
}
}
return conformance.AsOfReadResult{
Address: conformance.Address(result.Address),
State: result.State,
}
}
// TestAsOfReadContract wires this leg into the R7.1 as-of-read contract
// (gastownhall/beads#5898 revision 9, gastownhall/beads#6136) with a real
// Resolve/MintAt/MakeUnanswerable backed by one isolated UnitOfWorkProvider
// per storeID (asOfReadHarness).
func TestAsOfReadContract(t *testing.T) {
// Everything through logPath below is the same one-time, Fatal-permitted
// setup newTestUOWProvider does, run here directly instead of through
// that helper: newTestUOWProvider both sets up AND builds one provider
// bound to a fixed "beads" database, but this harness needs the setup
// coordinates kept separate so provider() can build N providers, one per
// storeID, lazily from inside subtest closures. See the asOfReadHarness
// doc comment for why provider() must stay Fatalf/Skip-free, which is
// exactly why this block -- the one place in this file where Fatalf/Skip
// is safe -- must run here, before any t.Run.
testutil.RequireDoltBinary(t)
bin, err := exec.LookPath("dolt")
require.NoError(t, err)
bdBin := buildBDBinary(t)
prev := proxy.ResolveExecutable
proxy.ResolveExecutable = func() (string, error) { return bdBin, nil }
t.Cleanup(func() { proxy.ResolveExecutable = prev })
t.Setenv("HOME", t.TempDir())
port, err := proxy.PickFreePort()
require.NoError(t, err)
storeRootDir := t.TempDir()
shutdownOnInterrupt(t, storeRootDir)
verifiedShutdownCleanup(t, storeRootDir)
cfgPath := writeServerConfig(t, port)
logPath := filepath.Join(t.TempDir(), "server.log")
ctx := context.Background()
h := newAsOfReadHarness(t, storeRootDir, bin, cfgPath, logPath)
fixture := conformance.AsOfReadFixture{
IssuePrefix: "asof",
Resolve: h.resolve,
MintAt: h.mintAt,
MakeUnanswerable: h.makeUnanswerable,
}
t.Run("SelectorAcceptsEitherAnInstantOrAVersionAddress", func(t *testing.T) {
conformance.RunAsOfReadSelectorAcceptsEitherAnInstantOrAVersionAddress(t, ctx, fixture)
})
t.Run("ReturnsTheLatestVersionAtOrBeforeTStrictlyExcludingLater", func(t *testing.T) {
conformance.RunAsOfReadReturnsTheLatestVersionAtOrBeforeTStrictlyExcludingLater(t, ctx, fixture)
})
t.Run("ReportsTheAddressItServed", func(t *testing.T) {
conformance.RunAsOfReadReportsTheAddressItServed(t, ctx, fixture)
})
t.Run("RefusesAsGoneOrUnknownNeverSubstitutingAnotherVersion", func(t *testing.T) {
conformance.RunAsOfReadRefusesAsGoneOrUnknownNeverSubstitutingAnotherVersion(t, ctx, fixture)
})
t.Run("IsCompleteOnlyForTheAnsweringStoresHoldings", func(t *testing.T) {
conformance.RunAsOfReadIsCompleteOnlyForTheAnsweringStoresHoldings(t, ctx, fixture)
})
}

View file

@ -0,0 +1,76 @@
package storage
import (
"context"
"time"
)
// IssueVersion is one accepted, immutable durable state of one issue, as
// issue_versions records it.
//
// Revision is a PER-STORE ORDINAL, not a portable address: two disconnected
// clones can both hold revision 8 for the same issue (migration 0067's own
// header says so, and the flag is single-writer-only until the version_id
// primary key lands). Callers must not present it as a citable address.
//
// Its JSON key is "local_revision", NOT "revision", for two reasons that
// compound. types.Issue already ships `json:"revision"` (types.go:1206) and
// that is the row-lock CAS token, an unrelated thing -- and it is a STRING
// there while this is an int64, so a script that learned one shape breaks on
// the other. The name also carries the non-citability with the value, where a
// machine reader sees it, instead of only in a footer no script parses. It
// needs no rename when version_id lands beside it. (bee-ghosttrack, #5898
// consumer read, 2026-09-20.)
//
// ChangeAgent is read from issue_versions.change_agent (migration 0067) but
// is deliberately NOT part of the JSON shape, which is what `bd versions
// --json` prints. Provenance V2 (gastownhall/beads#7510) replaces the ad hoc
// agent field with an actor chain, so publishing it now would make a public
// contract out of a field that is on its way out. The column and the field
// stay; only the JSON key is withheld.
//
// It lives here rather than in issueops for the same reason HistoryEntry
// does: issueops imports storage, so the shared row type has to sit on this
// side of that edge.
type IssueVersion struct {
IssueID string `json:"issue_id"`
Revision int64 `json:"local_revision"`
Epoch int64 `json:"epoch"`
ChangeActor string `json:"change_actor"`
ChangeAgent string `json:"-"`
ChangeMessage string `json:"change_message"`
ChangeAt time.Time `json:"change_at"`
AttributionStatus string `json:"attribution_status"`
RemovedAt *time.Time `json:"removed_at"`
RemovedReason string `json:"removed_reason"`
RemovedRestriction string `json:"removed_restriction"`
StateBytes int64 `json:"state_bytes"`
}
// Removed reports whether this version is no longer served -- retention,
// erasure or an epoch reorganization removed it. A removed version keeps its
// row (so the gap is legible) but its durable state is gone, and callers must
// render it as a restriction rather than as an empty version.
func (v IssueVersion) Removed() bool { return v.RemovedAt != nil }
// VersionLister is implemented by backends that can serve an issue's
// versioned history from the issue_versions table (migration 0067+).
//
// This is a narrow capability rather than a method on Storage on purpose: a
// backend that has no issue_versions table -- a proxied client, a no-db
// workspace, a non-Dolt backend -- should not be forced to implement it, and
// a caller that asserts for it learns the truth instead of receiving a stub
// that answers "no versions" for a store that simply cannot know. Same
// reasoning as ExternalRefHistoryQuerier in history_viewer.go.
//
// Holding this capability says the backend can READ versions. It says nothing
// about whether version recording is switched on -- that is
// VersionedHistoryConfigurer, and a store can legitimately implement both
// while the feature is off, in which case ListVersions truthfully returns
// nothing.
type VersionLister interface {
// ListVersions returns every retained version of issueID, newest first.
// An empty result means no retained versions, never "unsupported" --
// unsupported is the failed type assertion.
ListVersions(ctx context.Context, issueID string) ([]IssueVersion, error)
}

View file

@ -0,0 +1,92 @@
load("@rules_go//go:def.bzl", "go_library", "go_test")
go_library(
name = "versionedhistory",
srcs = ["activation.go"],
importpath = "github.com/steveyegge/beads/internal/versionedhistory",
visibility = ["//:__subpackages__"],
deps = [
"//internal/config",
"//internal/debug",
"//internal/storage",
"//internal/storage/uow",
"//issueops",
],
)
go_test(
name = "versionedhistory_test",
srcs = ["activation_test.go"],
embed = [":versionedhistory"],
deps = [
"//internal/config",
"//internal/debug",
"//internal/storage",
"//internal/storage/domain",
"//internal/storage/externaldeps",
"//internal/storage/uow",
"//internal/telemetry",
"//issueops",
],
)
# --- begin repo_files (managed by tools/bazel/go_srcs.py; run `make bazel-sync`) ---
filegroup(
name = "repo_doc_files",
srcs = glob(
[
"**/*.md",
"**/*.mdx",
],
allow_empty = True,
exclude = ["**/node_modules/**"],
),
visibility = ["//:__subpackages__"],
)
filegroup(
name = "repo_go_srcs",
srcs = glob(
["**/*.go"],
allow_empty = True,
exclude = [
"**/*_test.go",
"**/node_modules/**",
],
),
visibility = ["//:__subpackages__"],
)
filegroup(
name = "repo_go_test_srcs",
srcs = glob(
["**/*_test.go"],
allow_empty = True,
exclude = ["**/node_modules/**"],
),
visibility = ["//:__subpackages__"],
)
filegroup(
name = "repo_other_files",
srcs = glob(
["**"],
exclude = [
"**/*.db",
"**/*.exe",
"**/*.go",
"**/*.md",
"**/*.mdx",
"**/*.out",
"**/*.prof",
"**/*.pyc",
"**/*.test",
"**/__pycache__/**",
"**/node_modules/**",
],
),
visibility = ["//:__subpackages__"],
)
# --- end repo_files ---

View file

@ -0,0 +1,350 @@
// Package versionedhistory decides whether dual-write issue-version history is on
// for one store or unit-of-work provider, and applies that decision where the
// thing is constructed.
//
// It is a package rather than helpers inside cmd/bd for the same reason as
// internal/eventsjournal: bd doctor's repair handlers live in their own package
// and cannot import package main, and a repair that mutates issues needs exactly
// the same rule as the command surface. There is ONE implementation of that rule,
// here.
//
// THE SWITCH IS A PROPERTY OF THE STORE. `bd config set versioned-history.enabled
// true` writes a row of the workspace's own config table, and a store answers for
// itself: a write routed into rig B reads rig B's row, never the launching
// workspace's. The environment (BD_VERSIONED_HISTORY_ENABLED) and a hand-edited
// config.yaml value are read through viper, are process-wide, and can only turn
// recording ON for every store the process opens; nothing but the row turns a
// store off. The two are OR'd rather than ranked, deliberately: the hazard is a
// write that fails to record, never one that records when it needn't, so either
// plane saying yes is enough and neither can silently switch the other off.
//
// Activation is applied by the FACTORIES that construct a store or provider
// (ActivateStore, ActivateProvider), never by the commands that use one. Applying
// it at the root pre-run reached only the store a command opens for its own
// workspace, and missed every store a routed update, a routed close, `bd create
// --repo` or the direct-mode open builds for another one -- which then recorded no
// history while the command reported success. See
// cmd/bd/versioned_history_construction_test.go for the structural guard.
package versionedhistory
import (
"context"
"fmt"
"os"
"strconv"
"strings"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/uow"
"github.com/steveyegge/beads/issueops"
)
// ConfigKey is the one spelling of the switch, used for the store-config read
// below and for the `bd config set` line the help text and the off-refusal tell
// people to run. They must not drift.
const ConfigKey = "versioned-history.enabled"
// Enabled reports whether version recording is on for this store, reading BOTH
// planes bd stores configuration in.
//
// This exists because the two disagreed. `bd config set versioned-history.enabled
// true` -- the command the help text and the off-refusal both name -- writes the
// workspace DATABASE, because the key is not a yaml-only key (config.IsYamlOnlyKey,
// and "versioned-history." is not among the prefixes at yaml_config.go).
// config.GetBool reads viper, which is yaml and env only. So the advertised command
// wrote one plane and the reader read the other: the user ran exactly what they
// were told, was told it worked, and the feature stayed off. Configured on,
// actually off -- the GH#536 class, and the precise failure this command was added
// to end. (bee-ghosttrack, #6661 review, finding 1.)
//
// The store plane is authoritative in the sense that matters: it makes the switch
// a property of the STORE rather than of whoever is calling, so two clients of one
// dolt sql-server agree about whether a write records a version. That closes the
// silent-holes case in the same review's finding 2 -- a client with recording off
// advances nothing, and the next enabled write mints a version that absorbs the
// unrecorded change under its own actor, producing contiguous revisions and a
// gapless-LOOKING history that is not one.
//
// The two are OR'd rather than ranked, deliberately. The hazard is a write that
// fails to record, never one that records when it needn't, so either plane saying
// yes is enough and neither can silently switch the other off. That keeps
// BD_VERSIONED_HISTORY_ENABLED=1 working for a one-off run without letting an unset
// (or =0) env var countermand a store that is recording.
//
// A store that cannot answer is not an error: proxied and no-db workspaces have no
// settings plane to read. Those fall back to viper alone rather than failing the
// command, because a store-config read is not worth breaking every bd invocation
// over.
//
// Nothing in production calls Enabled today. `bd versions` reports StoreSetting
// alone, because it only reads: the process-wide planes cannot make a store
// record, so they cannot speak for it. Activation uses EnabledForStore. Enabled
// stays, with its tests, as the ungated form of the combined rule.
func Enabled(ctx context.Context, st storage.DoltStorage) bool {
if config.GetBool(ConfigKey) {
// Already on via env or yaml; skip the store read entirely. This is also
// what keeps the common path cheap when someone is driving the feature from
// the environment.
return true
}
return StoreSetting(ctx, st)
}
// StoreSetting reads the switch from the store's own settings plane, answering
// false for every reason a read can fail to produce a true.
//
// "EVERY reason" INCLUDES A PANIC, and that is the whole point of the defer below
// rather than an oversight to tidy away. The factories call this on every store
// they hand back, before anything has established that the store at the bottom of
// the chain can answer a config question at all -- so a store that cannot is not a
// hypothetical, it is a store that takes the process down. The shape that found
// it: a test double embedding a nil storage.DoltStorage, whose promoted
// WorkspaceConfig SIGSEGVs on call. The blast radius of letting that through is not
// one command; it is every bd invocation against any store whose settings plane is
// absent or half-built, for a read whose answer only ever decides whether to record
// versions. (bee-ghosttrack, #6661 second review.)
//
// A CAPABILITY ASSERTION ON WorkspaceConfig CANNOT REPLACE THIS, because
// WorkspaceConfig is declared on storage.DoltStorage itself
// (internal/storage/storage.go): every store satisfies an
// interface{ WorkspaceConfig() ... } assertion, including the one that panics when
// the method is actually called. That assertion would pass and the panic would
// happen anyway.
//
// AN ASSERTION ON storage.VersionedHistoryConfigurer IS DIFFERENT, and it is the
// primary guard now -- see EnabledForStore below. SetVersionedHistoryEnabled is NOT
// part of DoltStorage, so a store that embeds a nil DoltStorage does not promote it
// and does not satisfy that interface. (bee-ghosttrack, #6661 third review.)
//
// The recover stays anyway, because the guard does not cover every caller: `bd
// versions` calls StoreSetting directly, where the read is the point and no
// capability gate precedes it, and because a store that DOES implement the
// capability can still have a half-built settings plane. Guard first, recover as
// the backstop.
//
// A typed nil needs no separate guard for the same reason it needs no reflection:
// if its WorkspaceConfig panics, the recover answers false; if it returns (nil, nil)
// instead, the cfg == nil check answers false. Both arms are already here.
//
// The answer when the store cannot be read is false -- recording off, which is what
// the feature ships as. That is a real tradeoff and not a free one: a store that IS
// recording, whose settings read panics, is read as not recording, and a write
// during that window advances nothing. It is still the right side to fail to,
// because the alternative is that bd does not run at all, and a store too broken to
// answer a settings query is not one that was successfully recording versions a
// moment ago.
//
// WHAT IS AND IS NOT DIAGNOSED. An absent row is "" with a nil error by contract
// (WorkspaceConfig.GetSetting) and is the normal state of every workspace that never
// ran `bd config set`: it stays silently off. A read that ERRORS is different -- the
// row may well be there -- and resolving it to off with nothing to say so is the
// "set but silently off" shape this feature exists to end. Those go to debug.Logf,
// not to stderr: this runs on every invocation, and a diagnostic on a path the user
// did not ask about would be noise on all of them.
func StoreSetting(ctx context.Context, st storage.DoltStorage) (enabled bool) {
if st == nil {
return false
}
defer func() {
if r := recover(); r != nil {
// Deliberately swallowed, not re-raised and not logged: this runs on
// every invocation and its answer is a default, so the honest report is
// the false below rather than noise on a path the user did not ask
// about. The named return makes that explicit.
//
// This is the opposite choice from the repo's other non-test recover
// (internal/storage/dolt/transaction.go), which rolls back and then
// re-panics, and the difference is not stylistic: there a caller must
// not proceed over a half-applied transaction, so the panic has to keep
// traveling. Here the caller can proceed perfectly well, because what it
// wanted was a boolean with a documented default.
enabled = false
}
}()
cfg, err := st.WorkspaceConfig()
if err != nil {
debug.Logf("versioned history: %s left off: no settings plane readable on %T: %v\n", ConfigKey, st, err)
return false
}
if cfg == nil {
return false
}
res, err := cfg.GetSetting(ctx, issueops.GetSettingRequest{Key: ConfigKey})
if err != nil {
debug.Logf("versioned history: %s left off: reading the setting from %T failed: %v\n", ConfigKey, st, err)
return false
}
return parseSettingBool(res.Value)
}
// parseSettingBool reads the stored string the way `bd config set` writes it.
// Unset is "" and a nil error by contract (WorkspaceConfig.GetSetting), which lands
// here as false -- the correct default for a flag that ships off.
func parseSettingBool(v string) bool {
b, err := strconv.ParseBool(strings.TrimSpace(v))
return err == nil && b
}
// ValueEnables reports whether a stored value of the switch turns recording on,
// reading it the way every reader of the row does. `bd config set` uses it to
// decide whether the value it was just given deserves the replication and
// single-writer caveat, so that answer cannot drift from what the stores do with
// the same string.
func ValueEnables(v string) bool { return parseSettingBool(v) }
// EnabledForStore answers the switch for a freshly constructed store, which is the
// caller that runs on EVERY store bd opens.
//
// It differs from Enabled in one deliberate way: it will not read the store's
// settings plane unless the store could actually act on the answer. Activation's
// whole use for the result is Apply, which needs a storage.VersionedHistoryConfigurer;
// a store that is not one cannot record versions however the question is answered,
// so the read is pure cost and, for a store whose settings plane is absent or
// half-built, pure risk. This is what took CI red at 32d4f966e: the read panicked at
// wiring time on a test double embedding a nil storage.DoltStorage, which is a panic
// in a path whose answer only ever decides whether to record versions.
//
// The ordering matters and is not interchangeable with Apply's own assertion. The
// viper plane is read FIRST and unconditionally, so a store that is
// set-but-unsupported still reaches Apply with enabled=true and still gets the
// warning it prints. Only the STORE-plane read is gated. The one case that loses its
// warning is a store whose own settings plane says true but which lacks the
// capability -- and `bd config set` could not have written that plane on such a
// store in the first place.
//
// (bee-ghosttrack, #6661 third review, blocking finding 1.)
func EnabledForStore(ctx context.Context, st storage.DoltStorage) bool {
if config.GetBool(ConfigKey) {
return true
}
if _, canRecord := st.(storage.VersionedHistoryConfigurer); !canRecord {
return false
}
return StoreSetting(ctx, st)
}
// ProviderSetting reads the switch from a unit-of-work provider's own database,
// answering false for every reason a read can fail to produce a true. It is the
// provider-path twin of StoreSetting: a provider has no storage.DoltStorage to ask
// for a settings plane, so the row is read the way the rest of the unit-of-work
// layer reads one -- through a unit of work's ConfigUseCase, as
// internal/storage/uow/issue_operations.go does for claim.pools.
//
// The read opens one unit of work, asks for one config row, and rolls it back: a
// pooled connection, START TRANSACTION, a SELECT, a ROLLBACK. It starts no server
// and creates no schema (the provider constructors have already opened the pool and
// run initSchema by the time this is called) and commits nothing. That is the whole
// cost of "each provider answers for its own database", and it is why this is read
// at construction, once, rather than falling back to viper alone: a provider that
// silently ignored the row would record nothing for a workspace that asked, while
// every command reported success.
//
// The same failure policy as StoreSetting applies, including the recover.
func ProviderSetting(ctx context.Context, p uow.UnitOfWorkProvider) (enabled bool) {
if p == nil {
return false
}
defer func() {
if r := recover(); r != nil {
enabled = false
}
}()
unit, err := p.NewUOW(ctx)
if err != nil {
debug.Logf("versioned history: %s left off: opening a unit of work on %T to read it failed: %v\n", ConfigKey, p, err)
return false
}
// Rolled back, never committed: this is a read.
defer unit.Close(ctx)
raw, err := unit.ConfigUseCase().GetConfig(ctx, ConfigKey)
if err != nil {
debug.Logf("versioned history: %s left off: reading the setting through %T failed: %v\n", ConfigKey, p, err)
return false
}
return parseSettingBool(raw)
}
// EnabledForProvider is EnabledForStore for a provider: viper first, then the
// capability check, then the provider's own row.
func EnabledForProvider(ctx context.Context, p uow.UnitOfWorkProvider) bool {
if config.GetBool(ConfigKey) {
return true
}
if _, canRecord := p.(storage.VersionedHistoryConfigurer); !canRecord {
return false
}
return ProviderSetting(ctx, p)
}
// ActivateStore applies a freshly opened store's own configured switch to it. It is
// written to be used as a deferred rewrite of a factory's named results:
//
// func newX(ctx context.Context, ...) (s storage.DoltStorage, err error) {
// defer func() { s, err = versionedhistory.ActivateStore(ctx, s, err) }()
// ... open and return ...
// }
//
// The shape is deliberate, and is internal/eventsjournal's. It keeps the open and
// its activation in ONE function body, so "constructs a store" and "activates
// history on it" are the same syntactic unit -- which is what lets the construction
// guard check the property structurally instead of chasing a call graph.
//
// The store is activated RAW: every factory hands back the concrete store, before
// any decorator wraps it. That ordering is load-bearing, because activation is a
// type assertion and none of the decorators (telemetry, externaldeps, hooks)
// forwards SetVersionedHistoryEnabled -- asserting against a wrapper would fail
// silently and leave history off while the config said it was on. It is pinned by
// TestApplyReachesOnlyTheRawStore.
//
// A failed open passes through untouched, so the typed-nil store never reaches the
// activation. A store that cannot version at all is returned as-is without its
// settings plane being read: there is nothing to activate, and the factories run for
// every command that opens a store.
func ActivateStore(ctx context.Context, s storage.DoltStorage, err error) (storage.DoltStorage, error) {
if err != nil || s == nil {
return s, err
}
Apply(s, EnabledForStore(ctx, s))
return s, nil
}
// ActivateProvider is ActivateStore for a unit-of-work provider -- bd's second write
// plumbing, with its own transactions and its own activation switch, which
// proxied-server mode and `bd serve` against a server-mode workspace write through
// instead of a DoltStorage.
func ActivateProvider(ctx context.Context, p uow.UnitOfWorkProvider, err error) (uow.UnitOfWorkProvider, error) {
if err != nil || p == nil {
return p, err
}
Apply(p, EnabledForProvider(ctx, p))
return p, nil
}
// Apply binds a resolved answer to one plumbing -- a store or a unit-of-work
// provider. Activation is per instance rather than process-global: a process can
// hold several plumbings at once (a routed create holds two), and enabling history
// on one must not enable it on the rest.
//
// It only ever turns recording ON. A false answer touches nothing, so flag-off is
// byte-identical to a build without the feature, which is the contract #6135 ships
// under.
//
// A plumbing that does not implement the capability is not an error: proxied and
// no-db backends legitimately do not. But it is not silently ignored either --
// asking for history and not getting it is exactly the case a user must be told
// about, so it warns.
func Apply(target any, enabled bool) {
if !enabled {
return
}
configurer, ok := target.(storage.VersionedHistoryConfigurer)
if !ok {
fmt.Fprintf(os.Stderr,
"warning: versioned-history.enabled is set, but this storage backend (%T) does not support version history; it stays off\n",
target)
return
}
configurer.SetVersionedHistoryEnabled(true)
}

View file

@ -0,0 +1,776 @@
package versionedhistory
import (
"context"
"errors"
"fmt"
"io"
"os"
"strings"
"testing"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/domain"
"github.com/steveyegge/beads/internal/storage/externaldeps"
"github.com/steveyegge/beads/internal/storage/uow"
"github.com/steveyegge/beads/internal/telemetry"
"github.com/steveyegge/beads/issueops"
)
// The resolver's tests. Most of them moved here from cmd/bd with the code they
// test, assertions unchanged: that is what shows the move preserved #6661's
// behavior. The rest are the new claims -- each store (and each provider) answers
// for itself, the environment is process-wide and can only turn recording on, and
// a read that errors is not the same as a row that is absent.
const envVar = "BD_VERSIONED_HISTORY_ENABLED"
// viperEnv sets the switch's environment variable and re-initialises viper, since
// config.GetBool answers false until viper is initialised and so would make every
// env-driven case below pass whatever the code did with the env.
func viperEnv(t *testing.T, value string) {
t.Helper()
t.Setenv(envVar, value)
// Nothing from the machine's own config may decide these cases.
t.Setenv("HOME", t.TempDir())
t.Setenv("XDG_CONFIG_HOME", t.TempDir())
t.Chdir(t.TempDir())
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize(): %v", err)
}
t.Cleanup(config.ResetForTesting)
}
// captureStderr runs fn with os.Stderr redirected and returns what it wrote. With
// verbose set, debug.Logf writes too.
func captureStderr(t *testing.T, verbose bool, fn func()) string {
t.Helper()
r, w, err := os.Pipe()
if err != nil {
t.Fatal(err)
}
orig := os.Stderr
os.Stderr = w
debug.SetVerbose(verbose)
func() {
defer func() {
debug.SetVerbose(false)
os.Stderr = orig
_ = w.Close()
}()
fn()
}()
out, err := io.ReadAll(r)
if err != nil {
t.Fatal(err)
}
return string(out)
}
// --- fakes -----------------------------------------------------------------
// settingsPlane is a workspace settings plane with one canned answer.
type settingsPlane struct {
issueops.WorkspaceConfig
value string
err error
panicMsg string
reads int
}
func (p *settingsPlane) GetSetting(_ context.Context, req issueops.GetSettingRequest) (issueops.SettingResult, error) {
p.reads++
if p.panicMsg != "" {
panic(p.panicMsg)
}
return issueops.SettingResult{Key: req.Key, Value: p.value}, p.err
}
// configProbeStore is a raw store at the bottom of a decorator chain whose
// settings plane behaves however a case needs: panicking, erroring, absent, or
// answering. It counts the reads so a test can prove it was actually asked, rather
// than passing because the switch short-circuited before reaching it.
//
// Every other method promotes from the embedded nil interface and panics if
// called, which is deliberate: nothing here should be calling them.
type configProbeStore struct {
storage.DoltStorage
cfg issueops.WorkspaceConfig
err error
panicMsg string
calls int
enabled bool
sets int
}
func (s *configProbeStore) WorkspaceConfig() (issueops.WorkspaceConfig, error) {
s.calls++
if s.panicMsg != "" {
panic(s.panicMsg)
}
return s.cfg, s.err
}
// SetVersionedHistoryEnabled makes this store a storage.VersionedHistoryConfigurer,
// which is what earns it the store-plane read at activation time. Without it this
// store would be skipped before WorkspaceConfig was ever called, and every
// calls-count assertion below would pass for the wrong reason.
func (s *configProbeStore) SetVersionedHistoryEnabled(enabled bool) {
s.enabled = enabled
s.sets++
}
// nonConfigurerStore is the shape the capability guard exists for, and it is not a
// hypothetical: it is cmd/bd's own fakeProbingDoltStore, which embeds a nil
// storage.DoltStorage and documents that only its own methods may be called.
// SetVersionedHistoryEnabled is not part of DoltStorage, so nothing promotes it and
// this type does not satisfy storage.VersionedHistoryConfigurer -- while
// WorkspaceConfig IS part of DoltStorage, so it promotes, type-checks, and SIGSEGVs
// on call.
type nonConfigurerStore struct {
storage.DoltStorage
calls int
}
func (s *nonConfigurerStore) WorkspaceConfig() (issueops.WorkspaceConfig, error) {
s.calls++
panic("WorkspaceConfig on a store with no settings plane")
}
// planeOnlyStore can answer a settings query but cannot record versions, which is
// what `bd versions` may be pointed at: the read is the point there.
type planeOnlyStore struct {
storage.DoltStorage
cfg issueops.WorkspaceConfig
calls int
}
func (s *planeOnlyStore) WorkspaceConfig() (issueops.WorkspaceConfig, error) {
s.calls++
return s.cfg, nil
}
// nilDerefStore reproduces the exact shape that broke CI: the method body touches
// the receiver, so a TYPED NIL of this type is non-nil as an interface and panics
// when called.
type nilDerefStore struct {
storage.DoltStorage
cfg issueops.WorkspaceConfig
}
func (s *nilDerefStore) WorkspaceConfig() (issueops.WorkspaceConfig, error) {
return s.cfg, nil
}
// configUseCaseProbe is a unit of work's config use case with one canned answer.
type configUseCaseProbe struct {
domain.ConfigUseCase
value string
err error
reads int
keys []string
}
func (c *configUseCaseProbe) GetConfig(_ context.Context, key string) (string, error) {
c.reads++
c.keys = append(c.keys, key)
return c.value, c.err
}
// unitProbe is a unit of work that records how it was finished: a settings read
// must be rolled back (Close), never committed.
type unitProbe struct {
uow.UnitOfWork
cfg *configUseCaseProbe
closed int
committed int
}
func (u *unitProbe) ConfigUseCase() domain.ConfigUseCase { return u.cfg }
func (u *unitProbe) Close(context.Context) { u.closed++ }
func (u *unitProbe) Commit(context.Context, string) error {
u.committed++
return nil
}
// providerProbe is a unit-of-work provider that is a VersionedHistoryConfigurer.
type providerProbe struct {
uow.UnitOfWorkProvider
unit *unitProbe
newErr error
panicMsg string
newCalls int
enabled bool
sets int
}
func (p *providerProbe) NewUOW(context.Context) (uow.UnitOfWork, error) {
p.newCalls++
if p.panicMsg != "" {
panic(p.panicMsg)
}
if p.newErr != nil {
return nil, p.newErr
}
return p.unit, nil
}
func (p *providerProbe) SetVersionedHistoryEnabled(enabled bool) {
p.enabled = enabled
p.sets++
}
func newProviderProbe(value string, err error) *providerProbe {
return &providerProbe{unit: &unitProbe{cfg: &configUseCaseProbe{value: value, err: err}}}
}
// nonConfigurerProvider cannot record versions: it does not implement the capability.
type nonConfigurerProvider struct {
uow.UnitOfWorkProvider
newCalls int
}
func (p *nonConfigurerProvider) NewUOW(context.Context) (uow.UnitOfWork, error) {
p.newCalls++
panic("NewUOW on a provider that cannot record versions")
}
// --- the resolver, moved from cmd/bd with its assertions unchanged ----------
// TestStoreSettingAnswersFalseForAStoreThatCannotAnswer pins the contract the
// function's own doc states, across every way a store can fail to produce a true
// -- including the two that are panics rather than errors, which is the pair that
// took the process down.
func TestStoreSettingAnswersFalseForAStoreThatCannotAnswer(t *testing.T) {
ctx := context.Background()
var typedNil *nilDerefStore
for _, tt := range []struct {
name string
store storage.DoltStorage
want bool
}{
{"nil store", nil, false},
{"typed nil store", typedNil, false},
{"WorkspaceConfig panics", &configProbeStore{panicMsg: "no settings plane on this store"}, false},
{"WorkspaceConfig errors", &configProbeStore{err: fmt.Errorf("server unreachable")}, false},
{"WorkspaceConfig returns no plane", &configProbeStore{}, false},
{"GetSetting panics", &configProbeStore{cfg: &settingsPlane{panicMsg: "settings table missing"}}, false},
{"GetSetting errors", &configProbeStore{cfg: &settingsPlane{err: fmt.Errorf("read failed")}}, false},
{"unset is off", &configProbeStore{cfg: &settingsPlane{value: ""}}, false},
{"stored false", &configProbeStore{cfg: &settingsPlane{value: "false"}}, false},
{"unparseable is off", &configProbeStore{cfg: &settingsPlane{value: "yes please"}}, false},
{"stored true", &configProbeStore{cfg: &settingsPlane{value: "true"}}, true},
{"stored 1", &configProbeStore{cfg: &settingsPlane{value: "1"}}, true},
{"stored true with whitespace", &configProbeStore{cfg: &settingsPlane{value: " true\n"}}, true},
} {
t.Run(tt.name, func(t *testing.T) {
// No recover here on purpose: a panic escaping the call under test
// must fail this test, not be absorbed by it.
if got := StoreSetting(ctx, tt.store); got != tt.want {
t.Errorf("StoreSetting = %v, want %v", got, tt.want)
}
})
}
}
// TestParseSettingBool pins how the stored string is read back. `bd config set`
// stores whatever the user typed, verbatim, so this is the whole translation
// between that and the boolean the factories activate on.
func TestParseSettingBool(t *testing.T) {
for _, tt := range []struct {
in string
want bool
}{
{"", false},
{"true", true},
{"TRUE", true},
{"True", true},
{"1", true},
{"t", true},
{" true ", true},
{"false", false},
{"0", false},
{"off", false},
{"on", false},
{"nonsense", false},
} {
t.Run(fmt.Sprintf("%q", tt.in), func(t *testing.T) {
if got := parseSettingBool(tt.in); got != tt.want {
t.Errorf("parseSettingBool(%q) = %v, want %v", tt.in, got, tt.want)
}
})
}
}
// TestEnabledForStoreSkipsTheStoreReadForANonConfigurer is the capability GUARD's
// test, and the regression test for the CI failure as it actually happened.
//
// The store read is only ever used to decide whether to call
// SetVersionedHistoryEnabled, so a store that cannot record versions has nothing to
// gain from being asked -- and, if its settings plane is absent or half-built,
// everything to lose. That is what took Test (macos-latest) and PR Core (wrapper
// timing) red at 32d4f966e, via cmd/bd's own fakeProbingDoltStore.
//
// The assertion that matters is calls == 0: not "it survived" (the recover would
// deliver that too, which is exactly how this regressed the first time) but "it was
// never asked".
func TestEnabledForStoreSkipsTheStoreReadForANonConfigurer(t *testing.T) {
raw := &nonConfigurerStore{}
if _, isConfigurer := storage.DoltStorage(raw).(storage.VersionedHistoryConfigurer); isConfigurer {
t.Fatal("nonConfigurerStore satisfies VersionedHistoryConfigurer; this test cannot exercise the guard it claims to")
}
if EnabledForStore(context.Background(), raw) {
t.Error("EnabledForStore = true for a store that cannot record versions")
}
if raw.calls != 0 {
t.Fatalf("WorkspaceConfig called %d times on a store that cannot record versions, want 0", raw.calls)
}
}
// TestEnabledForStoreReadsTheStoreWhenItCanRecord is the other half: the guard must
// not be so eager that it stops reading the plane that finding 1 existed to start
// reading. A store that CAN record still gets asked, and a stored true still turns
// recording on.
func TestEnabledForStoreReadsTheStoreWhenItCanRecord(t *testing.T) {
raw := &configProbeStore{cfg: &settingsPlane{value: "true"}}
if got := EnabledForStore(context.Background(), raw); !got {
t.Fatal("EnabledForStore = false for a configurer whose store plane says true")
}
if raw.calls != 1 {
t.Fatalf("store read %d times, want 1", raw.calls)
}
}
// TestEnabledReadsTheRowWithoutTheCapabilityGate: `bd versions` is the one caller
// where the read is the point, so it must ask a store that cannot record too.
func TestEnabledReadsTheRowWithoutTheCapabilityGate(t *testing.T) {
raw := &planeOnlyStore{cfg: &settingsPlane{value: "true"}}
if _, isConfigurer := storage.DoltStorage(raw).(storage.VersionedHistoryConfigurer); isConfigurer {
t.Fatal("planeOnlyStore satisfies VersionedHistoryConfigurer; this test cannot exercise what it claims to")
}
if !Enabled(context.Background(), raw) {
t.Error("Enabled = false for a store whose row says true")
}
if raw.calls != 1 {
t.Errorf("store read %d times, want 1", raw.calls)
}
}
// --- each store answers for itself; the environment only turns recording on --
// TestActivateStoreReadsTheStoresOwnRow is D1 at the unit level: two stores opened
// by one process each read ITS OWN row. The one whose row says on records; the one
// with no row does not, and does not inherit the other's answer.
func TestActivateStoreReadsTheStoresOwnRow(t *testing.T) {
ctx := context.Background()
on := &configProbeStore{cfg: &settingsPlane{value: "true"}}
absent := &configProbeStore{cfg: &settingsPlane{value: ""}}
off := &configProbeStore{cfg: &settingsPlane{value: "false"}}
for name, s := range map[string]*configProbeStore{"on": on, "absent": absent, "off": off} {
got, err := ActivateStore(ctx, s, nil)
if err != nil || got != storage.DoltStorage(s) {
t.Fatalf("%s: ActivateStore = (%v, %v), want the same store and no error", name, got, err)
}
}
if !on.enabled {
t.Error("the store whose row says true was not activated")
}
if absent.enabled || off.enabled {
t.Errorf("a store with no row (%v) or a false row (%v) was activated by another store's answer", absent.enabled, off.enabled)
}
}
// TestActivateStoreReadsTheRowExactlyOncePerOpen: with the factories activating,
// wireStorageDecorators no longer does, so each store is activated and its row read
// once per open -- not twice.
func TestActivateStoreReadsTheRowExactlyOncePerOpen(t *testing.T) {
plane := &settingsPlane{value: "true"}
raw := &configProbeStore{cfg: plane}
if _, err := ActivateStore(context.Background(), raw, nil); err != nil {
t.Fatal(err)
}
if raw.calls != 1 || plane.reads != 1 {
t.Errorf("settings plane fetched %d time(s) and row read %d time(s), want 1 and 1", raw.calls, plane.reads)
}
if raw.sets != 1 || !raw.enabled {
t.Errorf("SetVersionedHistoryEnabled called %d time(s), enabled=%v; want exactly one call turning it on", raw.sets, raw.enabled)
}
}
func TestActivateStorePassesAFailedOpenThrough(t *testing.T) {
openErr := errors.New("open failed")
got, err := ActivateStore(context.Background(), nil, openErr)
if got != nil || !errors.Is(err, openErr) {
t.Errorf("ActivateStore(nil, err) = (%v, %v), want (nil, the open error)", got, err)
}
// A store handed back alongside an error is not touched or read either.
raw := &configProbeStore{cfg: &settingsPlane{value: "true"}}
got, err = ActivateStore(context.Background(), raw, openErr)
if got != storage.DoltStorage(raw) || !errors.Is(err, openErr) {
t.Errorf("ActivateStore(store, err) = (%v, %v), want the store and the open error unchanged", got, err)
}
if raw.calls != 0 || raw.sets != 0 {
t.Errorf("a failed open still touched the store: %d settings reads, %d activations", raw.calls, raw.sets)
}
}
// TestActivateStoreSurvivesAStoreThatCannotAnswer is the regression test for the CI
// failure itself, at the layer that now owns it. This is the RECOVER's test: the
// store here IS a configurer, so the capability guard lets it through to the read,
// and only the recover keeps the panic from escaping.
func TestActivateStoreSurvivesAStoreThatCannotAnswer(t *testing.T) {
raw := &configProbeStore{panicMsg: "WorkspaceConfig on a store with no settings plane"}
got, err := ActivateStore(context.Background(), raw, nil)
if err != nil || got != storage.DoltStorage(raw) {
t.Fatalf("ActivateStore = (%v, %v), want the store back and no error", got, err)
}
if raw.calls != 1 {
t.Fatalf("WorkspaceConfig called %d times, want 1; this test is not exercising the read it claims to", raw.calls)
}
if raw.enabled {
t.Error("a store whose settings plane panicked was switched on")
}
}
func TestActivateStoreLeavesAStoreThatCannotRecordUntouched(t *testing.T) {
raw := &nonConfigurerStore{}
got, err := ActivateStore(context.Background(), raw, nil)
if err != nil || got != storage.DoltStorage(raw) {
t.Fatalf("ActivateStore = (%v, %v), want the store back and no error", got, err)
}
if raw.calls != 0 {
t.Errorf("a store that cannot record was asked for its settings plane %d time(s), want 0", raw.calls)
}
}
// TestEnvironmentIsProcessWideAndShortCircuitsTheRead is D3 for stores: viper says
// on, so every store the process opens is activated -- including one whose own row
// says nothing -- and the row is not even read.
func TestEnvironmentIsProcessWideAndShortCircuitsTheRead(t *testing.T) {
viperEnv(t, "1")
absent := &configProbeStore{cfg: &settingsPlane{value: ""}}
if _, err := ActivateStore(context.Background(), absent, nil); err != nil {
t.Fatal(err)
}
if !absent.enabled {
t.Error("the environment said on but a store with no row was not activated")
}
if absent.calls != 0 {
t.Errorf("the settings plane was read %d time(s) although the environment had already answered, want 0", absent.calls)
}
}
// TestEnvironmentZeroNeverSwitchesOffAStoreWhoseRowIsOn is D3's other half, and
// the rule that OR is never ranked: =0 is not "off". A store whose own row says on
// keeps recording, and a store with no row stays quiet. The only way off is the row.
func TestEnvironmentZeroNeverSwitchesOffAStoreWhoseRowIsOn(t *testing.T) {
viperEnv(t, "0")
ctx := context.Background()
on := &configProbeStore{cfg: &settingsPlane{value: "true"}}
absent := &configProbeStore{cfg: &settingsPlane{value: ""}}
for _, s := range []*configProbeStore{on, absent} {
if _, err := ActivateStore(ctx, s, nil); err != nil {
t.Fatal(err)
}
}
if !on.enabled {
t.Error("BD_VERSIONED_HISTORY_ENABLED=0 switched off a store whose own row says true")
}
if absent.enabled {
t.Error("BD_VERSIONED_HISTORY_ENABLED=0 switched ON a store with no row")
}
}
// --- D7: an error is not an absent row --------------------------------------
func TestAnAbsentRowIsSilentlyOffButAReadErrorIsDiagnosed(t *testing.T) {
ctx := context.Background()
t.Run("absent row: off, and nothing to say", func(t *testing.T) {
raw := &configProbeStore{cfg: &settingsPlane{value: ""}}
var got bool
out := captureStderr(t, true, func() { got = StoreSetting(ctx, raw) })
if got {
t.Error("an absent row resolved to on")
}
if out != "" {
t.Errorf("an absent row is the normal state of every workspace and must not be diagnosed, got: %q", out)
}
})
t.Run("GetSetting error: off, and diagnosed at debug level", func(t *testing.T) {
raw := &configProbeStore{cfg: &settingsPlane{err: errors.New("read failed: table config is locked")}}
var got bool
out := captureStderr(t, true, func() { got = StoreSetting(ctx, raw) })
if got {
t.Error("a failed row read resolved to on")
}
for _, want := range []string{ConfigKey, "table config is locked"} {
if !strings.Contains(out, want) {
t.Errorf("the diagnostic does not mention %q: %q", want, out)
}
}
})
t.Run("WorkspaceConfig error: off, and diagnosed at debug level", func(t *testing.T) {
raw := &configProbeStore{err: errors.New("server unreachable")}
var got bool
out := captureStderr(t, true, func() { got = StoreSetting(ctx, raw) })
if got {
t.Error("an unreadable settings plane resolved to on")
}
if !strings.Contains(out, "server unreachable") {
t.Errorf("the diagnostic does not carry the cause: %q", out)
}
})
t.Run("the diagnostic is debug-level, never unconditional stderr", func(t *testing.T) {
raw := &configProbeStore{cfg: &settingsPlane{err: errors.New("read failed")}}
out := captureStderr(t, false, func() { _ = StoreSetting(ctx, raw) })
if out != "" {
t.Errorf("this runs on every invocation and must be silent unless debugging, got: %q", out)
}
})
}
// --- Apply: the raw-store ordering, and the set-but-unsupported warning -----
// TestApplyReachesOnlyTheRawStore pins the ORDERING that activation depends on.
//
// The capability is reached by type assertion, and none of the decorators
// (telemetry, externaldeps, hooks) forwards SetVersionedHistoryEnabled. So applying
// the config after any wrap would assert against a wrapper, fail silently, and
// leave versioned history OFF while the operator's config said it was on -- a wrong
// answer rather than an empty one. That is why the factories, which hand back the
// concrete store before anything wraps it, are where activation lives.
//
// The second half of this test is the part that actually guards the ordering: it
// proves the wrapped chain does NOT satisfy the capability, so if a decorator ever
// starts forwarding, the constraint this test exists for has changed.
func TestApplyReachesOnlyTheRawStore(t *testing.T) {
raw := &configProbeStore{}
Apply(raw, true)
if !raw.enabled {
t.Error("Apply(raw, true) did not enable versioned history on the raw store")
}
wrap := func(s storage.DoltStorage) storage.DoltStorage {
return externaldeps.New(
telemetry.WrapStorage(s),
func(externaldeps.ProjectName) (string, bool) { return "", false },
func(context.Context, string) (storage.DoltStorage, error) { return nil, errors.New("unused") },
)
}
if _, ok := wrap(&configProbeStore{}).(storage.VersionedHistoryConfigurer); ok {
// Fatal, not Skip. A skip here returns BEFORE the assertion below -- the
// half that actually guards the ordering -- so the case would report
// "not applicable" while checking nothing.
t.Fatal("a decorator now forwards SetVersionedHistoryEnabled; the ordering constraint has changed and this test needs rewriting rather than silently passing")
}
behindWrap := &configProbeStore{}
captureStderr(t, false, func() { Apply(wrap(behindWrap), true) })
if behindWrap.enabled {
t.Error("the capability was somehow reached through the decorators; this test's premise is stale")
}
}
// TestApplyOffIsANoop pins that the disabled path touches nothing at all --
// flag-off must be byte-identical to a build without the feature, which is the
// contract #6135 ships under.
func TestApplyOffIsANoop(t *testing.T) {
raw := &configProbeStore{}
out := captureStderr(t, true, func() { Apply(raw, false) })
if raw.sets != 0 || raw.enabled {
t.Errorf("Apply(raw, false) called SetVersionedHistoryEnabled %d time(s), enabled=%v; flag-off must be a no-op", raw.sets, raw.enabled)
}
if out != "" {
t.Errorf("Apply(raw, false) wrote %q", out)
}
}
// TestApplyWarnsWhenTheBackendCannotRecord: asking for history and not getting it is
// exactly the case a user must be told about. The wording is #6661's, unchanged.
func TestApplyWarnsWhenTheBackendCannotRecord(t *testing.T) {
out := captureStderr(t, false, func() { Apply(&nonConfigurerStore{}, true) })
for _, want := range []string{
"warning: versioned-history.enabled is set, but this storage backend (",
"does not support version history; it stays off",
} {
if !strings.Contains(out, want) {
t.Errorf("the warning is missing %q: %q", want, out)
}
}
}
// TestConfigKeyIsNotYamlOnly is D5's pin at the unit level. versioned-history.* must
// NOT become a yaml-only key: `bd config set versioned-history.enabled true` keeps
// writing the database row exactly as #6661 wired it, and a yaml-only key would move
// the switch off the store.
func TestConfigKeyIsNotYamlOnly(t *testing.T) {
if ConfigKey != "versioned-history.enabled" {
t.Errorf("ConfigKey = %q; the key is documented, and read back by `bd versions`, under this exact spelling", ConfigKey)
}
if config.IsYamlOnlyKey(ConfigKey) {
t.Errorf("%s is a yaml-only key, so `bd config set` would write config.yaml and no store would ever read it", ConfigKey)
}
}
// --- K1: the provider path ---------------------------------------------------
// TestActivateProviderReadsItsOwnRow is K1's central claim. A unit-of-work provider
// has no storage.DoltStorage to ask, so its flag comes from viper OR its own row --
// read through a unit of work's ConfigUseCase -- and NOT from viper alone.
func TestActivateProviderReadsItsOwnRow(t *testing.T) {
p := newProviderProbe("true", nil)
got, err := ActivateProvider(context.Background(), p, nil)
if err != nil || got != uow.UnitOfWorkProvider(p) {
t.Fatalf("ActivateProvider = (%v, %v), want the provider back and no error", got, err)
}
if !p.enabled {
t.Fatal("a provider whose database row says true was not activated: the flag was resolved from viper alone")
}
if p.unit.cfg.reads != 1 || len(p.unit.cfg.keys) != 1 || p.unit.cfg.keys[0] != ConfigKey {
t.Errorf("config rows read = %v (%d read(s)), want exactly one read of %q", p.unit.cfg.keys, p.unit.cfg.reads, ConfigKey)
}
// A settings read is a read: rolled back, never committed.
if p.unit.closed != 1 || p.unit.committed != 0 {
t.Errorf("unit of work closed %d time(s) and committed %d time(s), want closed once and never committed", p.unit.closed, p.unit.committed)
}
}
func TestActivateProviderLeavesAnAbsentOrFalseRowOff(t *testing.T) {
for _, value := range []string{"", "false", "0", "on", "nonsense"} {
t.Run(fmt.Sprintf("%q", value), func(t *testing.T) {
p := newProviderProbe(value, nil)
captureStderr(t, true, func() { _, _ = ActivateProvider(context.Background(), p, nil) })
if p.enabled {
t.Errorf("a provider whose row is %q was activated", value)
}
if p.unit.closed != 1 {
t.Errorf("unit of work closed %d time(s), want 1", p.unit.closed)
}
})
}
t.Run("an absent row is silent", func(t *testing.T) {
p := newProviderProbe("", nil)
if out := captureStderr(t, true, func() { _, _ = ActivateProvider(context.Background(), p, nil) }); out != "" {
t.Errorf("an absent row must not be diagnosed, got %q", out)
}
})
}
// TestActivateProviderReadFailureIsOffAndDiagnosed is D7 for providers: an error is
// not an absent row. It resolves to off -- but not silently.
func TestActivateProviderReadFailureIsOffAndDiagnosed(t *testing.T) {
t.Run("GetConfig errors", func(t *testing.T) {
p := newProviderProbe("", errors.New("no such table: config"))
out := captureStderr(t, true, func() { _, _ = ActivateProvider(context.Background(), p, nil) })
if p.enabled {
t.Error("a failed row read activated the provider")
}
for _, want := range []string{ConfigKey, "no such table: config"} {
if !strings.Contains(out, want) {
t.Errorf("the diagnostic does not mention %q: %q", want, out)
}
}
if p.unit.closed != 1 {
t.Errorf("unit of work closed %d time(s) after a failed read, want 1", p.unit.closed)
}
})
t.Run("NewUOW errors", func(t *testing.T) {
p := &providerProbe{newErr: errors.New("connection refused")}
out := captureStderr(t, true, func() { _, _ = ActivateProvider(context.Background(), p, nil) })
if p.enabled {
t.Error("a provider that could not open a unit of work was activated")
}
if !strings.Contains(out, "connection refused") {
t.Errorf("the diagnostic does not carry the cause: %q", out)
}
})
t.Run("silent unless debugging", func(t *testing.T) {
p := newProviderProbe("", errors.New("no such table: config"))
if out := captureStderr(t, false, func() { _, _ = ActivateProvider(context.Background(), p, nil) }); out != "" {
t.Errorf("this runs on every invocation and must be silent unless debugging, got: %q", out)
}
})
}
func TestActivateProviderSurvivesAProviderThatPanics(t *testing.T) {
p := &providerProbe{panicMsg: "NewUOW on a half-built provider"}
got, err := ActivateProvider(context.Background(), p, nil)
if err != nil || got != uow.UnitOfWorkProvider(p) {
t.Fatalf("ActivateProvider = (%v, %v), want the provider back and no error", got, err)
}
if p.newCalls != 1 {
t.Fatalf("NewUOW called %d times, want 1; this test is not exercising the read it claims to", p.newCalls)
}
if p.enabled {
t.Error("a provider whose read panicked was activated")
}
}
func TestActivateProviderSkipsTheReadForANonConfigurer(t *testing.T) {
p := &nonConfigurerProvider{}
if _, ok := uow.UnitOfWorkProvider(p).(storage.VersionedHistoryConfigurer); ok {
t.Fatal("nonConfigurerProvider satisfies VersionedHistoryConfigurer; this test cannot exercise the guard it claims to")
}
got, err := ActivateProvider(context.Background(), p, nil)
if err != nil || got != uow.UnitOfWorkProvider(p) {
t.Fatalf("ActivateProvider = (%v, %v), want the provider back and no error", got, err)
}
if p.newCalls != 0 {
t.Errorf("a provider that cannot record was asked for a unit of work %d time(s), want 0", p.newCalls)
}
}
func TestActivateProviderPassesAFailedOpenThrough(t *testing.T) {
openErr := errors.New("open failed")
got, err := ActivateProvider(context.Background(), nil, openErr)
if got != nil || !errors.Is(err, openErr) {
t.Errorf("ActivateProvider(nil, err) = (%v, %v), want (nil, the open error)", got, err)
}
p := newProviderProbe("true", nil)
got, err = ActivateProvider(context.Background(), p, openErr)
if got != uow.UnitOfWorkProvider(p) || !errors.Is(err, openErr) {
t.Errorf("ActivateProvider(provider, err) = (%v, %v), want the provider and the open error unchanged", got, err)
}
if p.newCalls != 0 || p.sets != 0 {
t.Errorf("a failed open still touched the provider: %d unit(s) of work opened, %d activation(s)", p.newCalls, p.sets)
}
}
// TestProviderEnvironmentIsProcessWideAndOnlyTurnsRecordingOn is D3 for providers.
func TestProviderEnvironmentIsProcessWideAndOnlyTurnsRecordingOn(t *testing.T) {
t.Run("=1 activates without reading the row", func(t *testing.T) {
viperEnv(t, "1")
p := newProviderProbe("", nil)
if _, err := ActivateProvider(context.Background(), p, nil); err != nil {
t.Fatal(err)
}
if !p.enabled {
t.Error("the environment said on but the provider was not activated")
}
if p.newCalls != 0 {
t.Errorf("a unit of work was opened %d time(s) although the environment had already answered, want 0", p.newCalls)
}
})
t.Run("=0 never switches off a provider whose row is on", func(t *testing.T) {
viperEnv(t, "0")
p := newProviderProbe("true", nil)
if _, err := ActivateProvider(context.Background(), p, nil); err != nil {
t.Fatal(err)
}
if !p.enabled {
t.Error("BD_VERSIONED_HISTORY_ENABLED=0 switched off a provider whose own row says true")
}
})
}

View file

@ -290,6 +290,7 @@ release_cross_build(
"//internal/utils:utils",
"//internal/validation:validation",
"//internal/versioncheck:versioncheck",
"//internal/versionedhistory:versionedhistory",
"//internal/workapi/storecounter:storecounter",
"//internal/workapi/storequerier:storequerier",
"//internal/workapi/storereader:storereader",

View file

@ -69,6 +69,7 @@ import sys
# Packages whose own Go source a test scans.
PACKAGES = (
".", # //cmd/bd:bd_test (events-journal construction scan: the Go SDK opens)
"backend", # //backend:backend_test (public alias census)
"backend/conformance", # //backend/conformance, //internal/storage
"beadserrors", # role facade alias targets