diff --git a/.github/scripts/embedded-storage-test-shards.txt b/.github/scripts/embedded-storage-test-shards.txt index 8cc9f773e..089738a24 100644 --- a/.github/scripts/embedded-storage-test-shards.txt +++ b/.github/scripts/embedded-storage-test-shards.txt @@ -245,7 +245,6 @@ 40 11 TestWithPeerAuth_WarnsWhenStoredPeerSuppressesAmbientPasswordStored 40 12 TestCounterExcludeStatusAcceptsAWorkspaceCustomStatusWithoutIncludeInfra -40 12 TestReaderListExcludeStatusAcceptsAWorkspaceCustomStatus 40 12 TestEmbeddedClaimerAcceptsAConfiguredActiveStatusAndRefusesAConfiguredWipOne 40 12 TestEmbeddedClaimerRefusesAWispIDAsNotFound 40 12 TestEmbeddedDependencyEditorVersionsOnlyARealAddOrRemove @@ -254,6 +253,7 @@ 40 12 TestEmbeddedReadyClaimerAnswersTheQuestionReaderReadyLists 40 12 TestHistoryPresenceContract 40 12 TestLifecycleUpdateContract +40 12 TestReaderListExcludeStatusAcceptsAWorkspaceCustomStatus 40 13 TestEmbeddedDepRekeyConvergesRenameChain 40 13 TestEmbeddedDependencyEditorAppliesParentChildBeforeBlockingEdges @@ -311,6 +311,7 @@ 40 17 TestStatsReporterContract 40 17 TestVersionReconcilerContract +40 18 TestCreateBatchParticipationGeneration 40 18 TestEmbeddedBatchCloserIdempotentRecloseIsAPerItemSuccess 40 18 TestEmbeddedDependencyEditorMixedBatchWritesBothPlanes 40 18 TestEmbeddedIssueOperationsUpdateRawMetadataTakesTheFunnelsValueShapes @@ -330,6 +331,7 @@ 40 19 TestIgnoredCursorHealConvergesFromEveryCrashState 40 19 TestOpenAfterCloseCreatesNewStore 40 19 TestOpenReturnsCachedStore +40 19 TestParticipationGenerationFixtureKitIsWired 40 19 TestRemoteVerbsPresentStoredPeerCredentials 40 19 TestRenameLabelMintsOneVersionPerTouchedBead @@ -571,6 +573,7 @@ 40 39 TestEmbeddedMigrateRepairedDependenciesIDColumnCommitsAtomicallyWithVersion53_4690 40 39 TestEmbeddedReaderListSkipCountsDropsTheCardinalitiesAndNothingElse 40 39 TestEmbeddedRelationsResolvesAWispAnchor +40 39 TestParticipationGenerationFence 40 39 TestPreviewStoreRefusesLocalMetadataWrite 40 39 TestReclaimRefusesForeignReplicaLease 40 39 TestWorkspaceConfigContract diff --git a/VERSIONED-BEADS-WRITE-PATHS.md b/VERSIONED-BEADS-WRITE-PATHS.md index 887816aad..bed384ade 100644 --- a/VERSIONED-BEADS-WRITE-PATHS.md +++ b/VERSIONED-BEADS-WRITE-PATHS.md @@ -19,7 +19,7 @@ Row numbers are the historical table's. Line numbers in this table are against t | # | Path | Version seam at this head | Disposition | Mechanism | |---|---|---|---|---| -| 13 | any of rows 1-8 whose target row is a wisp **or a promoted no-history bead** | no | NO-OP | `RecordVersionInTx` returns on `IsWisp`, which is `Ephemeral \|\| NoHistory` (helpers.go:36-41): wisps per FR-8, and a promoted no-history bead — a durable issues-plane row with `NoHistory=true` — because no-history means no history. Wording only; the code did not change. | +| 13 | any of rows 1-8 whose target row is a wisp **or a promoted no-history bead** | no | NO-OP (a flagged issues-table create is stamped, not versioned) | The table that holds the row decides its plane, not its flags. A row in the wisps table mints and stamps nothing, whatever its flags say (FR-8). An update-shaped call on a flagged wisp returns on `IsWisp`, which is `Ephemeral \|\| NoHistory` (helpers.go:36-41). Every other wisps-table row is excluded by the seam's read of `participation_generation` from the issues table, which finds no row and returns: a flagged wisp's create-shaped call, and an unflagged row (bd mol squash's in-place flag clear, import's `wisp_plane` marker), which passes `IsWisp`. An issues-table row carrying `NoHistory` (a promoted no-history bead, bd-r9uce) is never versioned while it says so, because no-history means no history: an update-shaped call returns on `IsWisp`. A create-shaped call on such a row, with the flag on, still stamps `participation_generation` and mints nothing, so the row is not legacy once `bd update --persistent` repairs the flag in place. | | 14 | dependencies.go:`addDependencyInTx` via `AddDependencyInTx` from the store verbs, `ApplyParentPatch`, `applyBatchRun.applyDepAdd` | yes | VERSIONED | mint moved into `addDependencyInTx` (`mintDependencyVersion`, dependencies.go:393), gated on the row insert rather than on `eventWritten`; the publicops editor's own mint call was removed so no leg double-mints | | 15 | domain/db/dependency.go:`dependencySQLRepositoryImpl.Insert` (uow `AddDependencies`, create-time edges) | yes | VERSIONED | seam at dependency.go:228 and :240 after the insert | | 16 | dependencies.go:`removeDependencyInTx` via `RemoveDependencyInTx` and domain/db/dependency.go:`Delete` | yes | VERSIONED | gated on the row delete; dependency.go:409 on the uow leg | diff --git a/backend/conformance/BUILD.bazel b/backend/conformance/BUILD.bazel index abf0ea1ed..545efa1aa 100644 --- a/backend/conformance/BUILD.bazel +++ b/backend/conformance/BUILD.bazel @@ -29,6 +29,7 @@ go_library( "deleter_contract.go", "dependency_editor_contract.go", "dualwrite_history_contract.go", + "dualwrite_participation_generation_contract.go", "edge_reader_contract.go", "expected_revision_contract.go", "graph_counter_contract.go", diff --git a/backend/conformance/dualwrite_history_contract.go b/backend/conformance/dualwrite_history_contract.go index 8bfb55c56..e94a15d01 100644 --- a/backend/conformance/dualwrite_history_contract.go +++ b/backend/conformance/dualwrite_history_contract.go @@ -71,11 +71,13 @@ import ( // - PARTICIPATION-GENERATION GATING (design §16.2b). Whether an // update-shaped mutation on a legacy (participation_generation IS NULL) // row is correctly skipped is Phase 2 behavior this bead also owns, but -// it depends on migration 0068's participation_generation column, which -// does not exist when this contract is first written (0068 lands last in -// this bead's build order, by the mayor's explicit sequencing). It gets -// its own dedicated cases once 0068 lands, beside this file rather than -// inside it. +// it depends on migration 0070's participation_generation column, which +// does not exist when this contract is first written (0070 lands last in +// this bead's build order, by the mayor's explicit sequencing — steps 4-5 +// of design §16.3 moved to their own migration slot when 0068 shipped as +// attribution_status-only, see that migration's header). It gets its own +// dedicated cases once 0070 lands, beside this file rather than inside +// it. // - CONCURRENT WRITERS. Every case here is one writer, one issue, one // mutation at a time — the same restriction journal_contract.go states // for the same reason: a single-threaded case cannot exercise what only diff --git a/backend/conformance/dualwrite_participation_generation_contract.go b/backend/conformance/dualwrite_participation_generation_contract.go new file mode 100644 index 000000000..e1e283380 --- /dev/null +++ b/backend/conformance/dualwrite_participation_generation_contract.go @@ -0,0 +1,585 @@ +package conformance + +import ( + "context" + "testing" +) + +// This file holds the write-fence cases dualwrite_history_contract.go's own +// "WHAT THIS CONTRACT DELIBERATELY DOES NOT PIN" section explicitly deferred: +// "PARTICIPATION-GENERATION GATING (design §16.2b)... It gets its own +// dedicated cases once 0070 lands, beside this file rather than inside it." +// Migration 0070 now carries participation_generation on both issues and +// wisps (design §16.3 steps 4-5, be-dt74u amendment, be-h89oq), so this is +// that file. +// +// Design §16.2b, verbatim substance: the flag-on writer does not increment +// current_revision or mint an issue_versions row for an UPDATE-shaped +// mutation against a record whose participation_generation is NULL — a skip, +// not a refusal (FR-2's zero-rows no-op shape). A CREATE-shaped mutation is +// different: a brand-new row has no prior legacy state to preserve, so if the +// flag is already on at creation time, the writer stamps +// participation_generation as part of the same insert that begins its +// history. A create with the flag off leaves the column NULL, indistinguishable +// from a true legacy row (FR-7's byte-identical requirement). +// +// WHY A SEPARATE FIXTURE RATHER THAN THREE MORE DualWriteFixture CLOSURES. +// DualWriteFixture's Mutate/MutateAsNoOp pair is deliberately flag-fixed-at- +// construction (see that file's SEEDING DISCIPLINE note and each leg's +// newXxxDualWriteFixture, which calls SetVersionedHistoryEnabled exactly +// once). The legacy-record case here is inherently "created while the flag +// was OFF, then mutated after the flag turns ON" — a fixture built once with +// one flag state cannot express that sequence, so SetFlag here is a toggle +// callable more than once per fixture, not a one-time constructor argument. +// +// THE FIXTURE'S CLOSURES ARE THE OBSERVABLE SURFACE, NOT THE SCHEMA — same +// discipline as DualWriteFixture: Mutate/MutateExisting drive CreateIssue and +// UpdateIssue (or their unit-of-work equivalents), never issue_versions or +// store_epoch directly. +// +// WHAT THIS CONTRACT DELIBERATELY DOES NOT PIN: +// - THE EXACT STAMPED VALUE. That a create-shaped mutation with the flag on +// stamps SOME non-NULL participation_generation is pinned here; that the +// value equals the current store_epoch.epoch is not — reaching +// store_epoch is the same one-column, two-of-three-legs-need-white-box- +// access problem dualwrite_history_contract.go's FR-6 note describes, and +// the same resolution applies: pinned per leg, dolt-only, alongside +// TestDualWriteStampsTheCurrentStoreEpochOnEachVersionRow. +// - wisps.participation_generation. FR-8 (carried by dualwrite_history_contract.go's +// exclusion list) applies here too: this fixture's Mutate front door is +// CreateIssue against the issues table, the wisp-arrival cases read only +// the issues row a wisp becomes, and no phase reads or writes the wisps +// column regardless. +type ParticipationGenerationFixture struct { + // IssuePrefix namespaces the id each case mints, the same discipline + // DualWriteFixture uses and for the same reason. + IssuePrefix string + // SetFlag toggles versioned history for every subsequent call through + // this fixture, and may be called more than once per case — unlike + // DualWriteFixture, whose flag is fixed at construction. + SetFlag func(ctx context.Context, enabled bool) error + // Mutate creates a new issue with the given id: a CREATE-shaped mutation + // in design §16.2b's sense. + Mutate func(ctx context.Context, id string) error + // MutateExisting applies a real (non-no-op) UPDATE-shaped mutation to an + // already-existing issue — a different value than Mutate gave it, so a + // vacuous no-op skip can never be mistaken for the fence. + MutateExisting func(ctx context.Context, id string) error + // CreateWisp creates a new wisp-plane (ephemeral) issue with the given + // id: the starting point for the two ways a record reaches the issues + // plane without being created there. A wisp is never versioned (FR-8) + // and never carries a participation declaration, in either flag state. + CreateWisp func(ctx context.Context, id string) error + // PromoteWisp promotes the wisp id onto the issues plane + // (PromoteFromEphemeral, or the unit-of-work leg's PromoteWisp). + PromoteWisp func(ctx context.Context, id string) error + // MovePersistent moves the wisp id onto the issues plane through a + // persistence-mode update (bd update --persistent). It is its own + // closure rather than a second spelling of PromoteWisp because it mints at + // a different site on every leg: the guarded update's one end-of-update + // mint on dolt and embeddeddolt, MoveIssuePersistenceInTx's own on uow. + // On an issues-plane row whose flags disagree with it (see + // CreateNoHistoryIssue) the same update repairs the flags in place, a + // same-plane normalize, rather than moving the row. + MovePersistent func(ctx context.Context, id string) error + // ClearWispFlag clears the wisp id's ephemeral flag IN PLACE: the untyped + // UpdateIssue of {"wisp": false} bd mol squash makes on a squashed root + // (UpdateWisp on the unit-of-work leg, the way its molecule writer routes + // it). The row stays in the wisps table, now carrying neither Ephemeral + // nor NoHistory. + ClearWispFlag func(ctx context.Context, id string) error + // SquashWispRoot closes the wisp id and then clears its flag as + // ClearWispFlag does, both in ONE transaction: the shape bd mol squash's + // root auto-close takes, where an error from either write aborts both. + SquashWispRoot func(ctx context.Context, id string) error + // CreateUnflaggedWisp creates id in the wisps table with neither + // Ephemeral nor NoHistory set: import's "wisp_plane" marker, which pins + // the plane whatever the flags say (WispPlaneOverride = &true, through + // the batch create import runs), or on the unit-of-work leg CreateWisp, + // which routes by the call rather than by the flags. + CreateUnflaggedWisp func(ctx context.Context, id string) error + // CreateNoHistoryIssue creates id in the ISSUES table carrying + // NoHistory=true: import's promoted-no-history shape (bd-r9uce), a + // durable row whose stray flag is preserved while WispPlaneOverride = + // &false pins its plane, through the batch create import runs; or on the + // unit-of-work leg CreateIssue, which routes by the call. + CreateNoHistoryIssue func(ctx context.Context, id string) error + // CurrentRevision reads issues.current_revision for id. + CurrentRevision func(ctx context.Context, id string) (int64, error) + // VersionRowCount reads how many issue_versions rows exist for id. + VersionRowCount func(ctx context.Context, id string) (int, error) + // ParticipationGeneration reads issues.participation_generation for id, + // returning nil for SQL NULL. + ParticipationGeneration func(ctx context.Context, id string) (*int64, error) + // InWispsTable reports whether the wisps table holds a row for id: the + // precondition the wisps-table cases check, so they cannot pass on a row + // that a step moved to the issues table. + InWispsTable func(ctx context.Context, id string) (bool, error) +} + +// RunParticipationGenerationCreateWithFlagOnStampsAValue pins design +// §16.2(a)/(b): a create-shaped mutation with the flag already on stamps a +// non-NULL participation_generation on the new row, as part of the same +// insert that begins its history — a brand-new row has no legacy state to +// preserve, so there is nothing to skip. +func RunParticipationGenerationCreateWithFlagOnStampsAValue(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 + "-create-stamps" + if err := fixture.Mutate(ctx, id); err != nil { + t.Fatalf("mutating %s: %v", id, err) + } + gen, err := fixture.ParticipationGeneration(ctx, id) + if err != nil { + t.Fatalf("reading participation_generation for %s: %v", id, err) + } + if gen == nil { + t.Errorf("participation_generation for %s is NULL immediately after a create-shaped mutation with "+ + "the flag on, want a stamped non-NULL value: design §16.2b requires the writer to declare "+ + "participation at insert time, since a brand-new row has no prior legacy state to preserve", id) + } +} + +// RunParticipationGenerationCreateWithFlagOffLeavesLegacyNull pins the other +// half of design §16.2(b): a create-shaped mutation with the flag off leaves +// participation_generation NULL, indistinguishable from a true legacy row — +// flag-off must stay byte-identical to pre-Phase-2 behavior (FR-7). +func RunParticipationGenerationCreateWithFlagOffLeavesLegacyNull(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) { + t.Helper() + if err := fixture.SetFlag(ctx, false); err != nil { + t.Fatalf("disabling versioned history: %v", err) + } + id := fixture.IssuePrefix + "-create-flag-off" + if err := fixture.Mutate(ctx, id); err != nil { + t.Fatalf("mutating %s: %v", id, err) + } + gen, err := fixture.ParticipationGeneration(ctx, id) + if err != nil { + t.Fatalf("reading participation_generation for %s: %v", id, err) + } + if gen != nil { + t.Errorf("participation_generation for %s = %d with the flag off at creation, want NULL: a "+ + "flag-off create must remain indistinguishable from a true legacy row (design §16.2b)", id, *gen) + } +} + +// RunParticipationGenerationSkipsUpdateOnLegacyRecord pins the write fence's +// central claim, design §16.2(b): the flag-on writer does not increment +// current_revision or mint an issue_versions row for an update-shaped +// mutation against a record whose participation_generation is NULL. The +// record must be a REAL legacy record — created while the flag was off, not +// merely one the fixture asserts is NULL — so this also re-confirms that +// precondition before trusting the rest of the case. +func RunParticipationGenerationSkipsUpdateOnLegacyRecord(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) { + t.Helper() + if err := fixture.SetFlag(ctx, false); err != nil { + t.Fatalf("disabling versioned history: %v", err) + } + id := fixture.IssuePrefix + "-legacy-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 = %d before the flag was ever turned on, want NULL — "+ + "this case cannot test the legacy-record fence against a record that was never actually legacy", + id, *gen) + } + + if err := fixture.SetFlag(ctx, true); err != nil { + t.Fatalf("enabling 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 on a "+ + "legacy (participation_generation IS NULL) record with the flag now on, want unchanged: "+ + "design §16.2b requires the writer to skip minting for a record it has not positively "+ + "promoted", id, beforeCount, afterCount) + } + if afterRevision != beforeRevision { + t.Errorf("current_revision for %s went from %d to %d across the same skipped mutation, want "+ + "unchanged: a skip means neither half of RecordVersionInTx's write runs, not just the "+ + "version-row half", id, beforeRevision, afterRevision) + } +} + +// RunParticipationGenerationProceedsForPromotedRecord is the fence's +// not-vacuous check: an update-shaped mutation against a record whose +// participation_generation is ALREADY stamped (created with the flag on, +// i.e. positively declared, not legacy) must mint normally. Without this +// case, an implementation that skips every update unconditionally would +// still pass RunParticipationGenerationSkipsUpdateOnLegacyRecord. +func RunParticipationGenerationProceedsForPromotedRecord(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 + "-promoted-proceeds" + 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 promoted-record path against a record that was never actually "+ + "promoted", id) + } + + 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) + } + afterCount, err := fixture.VersionRowCount(ctx, id) + if err != nil { + t.Fatalf("counting version rows for %s: %v", id, err) + } + if afterCount != beforeCount+1 { + t.Errorf("version row count for %s went from %d to %d across an update-shaped mutation on an "+ + "already-promoted record, want exactly +1: the fence must skip only a legacy (NULL) record, "+ + "not every update (design §16.2b)", id, beforeCount, afterCount) + } +} + +// 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 +// record, which is what ProceedsForPromotedRecord's name refers to.) The +// issues row a promotion inserts is brand new on that plane, and the wisp +// behind it was never versioned and never declared participation (FR-8), so +// there is no legacy state to preserve: with the flag on, the promotion stamps +// participation_generation and mints the record's first version, as a create +// there would. Treated as UPDATE-shaped, the fence finds the new row NULL and +// skips, and because nothing stamps the column afterwards every later update +// skips too, so a record created with the flag on is never versioned at all. +func RunParticipationGenerationWispPromotionBeginsHistory(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) { + t.Helper() + runWispArrivalBeginsHistory(t, ctx, fixture, "promote", fixture.PromoteWisp) +} + +// RunParticipationGenerationWispPersistenceMoveBeginsHistory is +// RunParticipationGenerationWispPromotionBeginsHistory for the other way a +// wisp reaches the issues plane, a persistence-mode update (bd update +// --persistent). It needs its own case because it reaches a different mint +// site than promotion on every leg (see MovePersistent). +func RunParticipationGenerationWispPersistenceMoveBeginsHistory(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) { + t.Helper() + runWispArrivalBeginsHistory(t, ctx, fixture, "move-persistent", fixture.MovePersistent) +} + +// runWispArrivalBeginsHistory is the body the two wisp-arrival cases share: +// with the flag on, a wisp that arrives on the issues plane through arrive +// carries a stamped participation_generation and exactly one version row, +// and the next update-shaped mutation mints normally. +func runWispArrivalBeginsHistory(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture, how string, arrive func(context.Context, string) error) { + t.Helper() + if err := fixture.SetFlag(ctx, true); err != nil { + t.Fatalf("enabling versioned history: %v", err) + } + id := fixture.IssuePrefix + "-" + how + if err := fixture.CreateWisp(ctx, id); err != nil { + t.Fatalf("creating wisp %s: %v", id, err) + } + if err := arrive(ctx, id); err != nil { + t.Fatalf("moving wisp %s onto the issues plane (%s): %v", id, how, err) + } + + gen, err := fixture.ParticipationGeneration(ctx, id) + if err != nil { + t.Fatalf("reading participation_generation for %s: %v", id, err) + } + if gen == nil { + t.Errorf("participation_generation for %s is NULL after the wisp reached the issues plane (%s) with "+ + "the flag on, want a stamped value: the issues row is new, so the arrival is create-shaped "+ + "(design §16.2b), and a NULL here leaves the record fenced as legacy for good", id, how) + } + arrivedCount, err := fixture.VersionRowCount(ctx, id) + if err != nil { + t.Fatalf("counting version rows for %s: %v", id, err) + } + if arrivedCount != 1 { + t.Errorf("version row count for %s = %d after the wisp reached the issues plane (%s) with the flag "+ + "on, want 1: a wisp is never versioned (FR-8), so the arrival mints the record's first version", + id, arrivedCount, how) + } + + if err := fixture.MutateExisting(ctx, id); err != nil { + t.Fatalf("mutating existing %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 != arrivedCount+1 { + t.Errorf("version row count for %s went from %d to %d across an update-shaped mutation after the "+ + "wisp reached the issues plane (%s), want exactly +1: a record that arrived with the flag on is "+ + "not legacy, so the fence must let its updates mint", id, arrivedCount, afterCount, how) + } +} + +// RunParticipationGenerationWispFlagClearMintsNothing pins that the fence +// decides a row's plane by the TABLE that holds it, not by the row's flags. +// bd mol squash clears a wisp root's ephemeral flag in place, so the row +// stays in the wisps table carrying neither Ephemeral nor NoHistory, and a +// plane test read off those flags takes it for an issues-plane row. It is +// not one: a wisps-table row is never versioned (FR-8) and has no issues row +// whose participation_generation the fence could read. So the update must +// succeed and mint nothing. Read off the flags, the fence either aborts the +// whole update looking for an issues row that is not there, or, without the +// fence, mints a stray version for a wisp. +func RunParticipationGenerationWispFlagClearMintsNothing(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) { + t.Helper() + runWispTableRowMintsNothing(t, ctx, fixture, "flag-clear", fixture.CreateWisp, fixture.ClearWispFlag) +} + +// RunParticipationGenerationWispRootSquashMintsNothing is +// RunParticipationGenerationWispFlagClearMintsNothing in the shape bd mol +// squash actually runs it: the root's close and its flag clear in one +// transaction, so a mint that fails on the cleared row takes the close down +// with it and the squash cannot complete. +func RunParticipationGenerationWispRootSquashMintsNothing(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) { + t.Helper() + runWispTableRowMintsNothing(t, ctx, fixture, "squash", fixture.CreateWisp, fixture.SquashWispRoot) +} + +// RunParticipationGenerationUnflaggedWispCreateMintsNothing pins the +// create-shaped half of the same rule: a row CREATED in the wisps table +// without either flag (import's "wisp_plane" marker) reaches the +// create-shaped mint, and must come out of it with no error and no version, +// exactly as a flagged wisp does. +func RunParticipationGenerationUnflaggedWispCreateMintsNothing(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) { + t.Helper() + runWispTableRowMintsNothing(t, ctx, fixture, "unflagged-create", fixture.CreateUnflaggedWisp) +} + +// runWispTableRowMintsNothing is the body the three wisps-table cases share: +// with the flag on, every step succeeds on id, the wisps table still holds id +// afterwards, and id ends with no issue_versions row. +func runWispTableRowMintsNothing(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture, how string, steps ...func(context.Context, string) error) { + t.Helper() + if err := fixture.SetFlag(ctx, true); err != nil { + t.Fatalf("enabling versioned history: %v", err) + } + id := fixture.IssuePrefix + "-" + how + for i, step := range steps { + if err := step(ctx, id); err != nil { + t.Fatalf("step %d of %s on wisps-table row %s with the flag on: %v — a row the wisps table "+ + "holds is never versioned (FR-8), so its mint must be a no-op, not an error that aborts "+ + "the mutation", i+1, how, id, err) + } + } + // The precondition, checked after the steps rather than assumed: a step + // that moved the row to the issues table would leave a NULL + // participation_generation there, the update-shaped mint would be fenced + // as legacy, and the zero count below would hold without saying anything + // about a wisps-table row. + if inWisps, err := fixture.InWispsTable(ctx, id); err != nil { + t.Fatalf("checking whether the wisps table holds %s: %v", id, err) + } else if !inWisps { + t.Fatalf("%s is not in the wisps table after %s — this case pins that a wisps-table row mints "+ + "nothing, and cannot say so about a row a step moved out of that table", id, how) + } + count, err := fixture.VersionRowCount(ctx, id) + if err != nil { + t.Fatalf("counting version rows for %s: %v", id, err) + } + if count != 0 { + t.Errorf("version row count for wisps-table row %s = %d after %s with the flag on, want 0: a "+ + "wisp is never versioned (FR-8), whatever its flags say", id, count, how) + } +} + +// RunParticipationGenerationNoHistoryIssueCreateDeclaresParticipation pins +// that a create declares participation for every ISSUES-table row it makes +// with the flag on, a row carrying NoHistory included. Import keeps a +// promoted no-history wisp's durable row on the issues plane with its stray +// no_history=true (bd-r9uce). While the row says no-history it is not +// versioned, so the create mints nothing. But it was created with history +// on, so it is not legacy: once bd update --persistent repairs the flag in +// place (a same-plane normalize, update-shaped by design), the repair and +// every update after it must mint. Left NULL by the create, the column reads +// as legacy to the fence, and the row is never versioned at all. +func RunParticipationGenerationNoHistoryIssueCreateDeclaresParticipation(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 + "-no-history-create" + if err := fixture.CreateNoHistoryIssue(ctx, id); err != nil { + t.Fatalf("creating no-history issues-plane row %s: %v", id, err) + } + gen, err := fixture.ParticipationGeneration(ctx, id) + if err != nil { + t.Fatalf("reading participation_generation for %s: %v", id, err) + } + if gen == nil { + t.Errorf("participation_generation for %s is NULL after a create with the flag on, want a stamped "+ + "value: the row is new on the issues plane, so the create declares participation (design "+ + "§16.2b) even though its NoHistory flag keeps it unversioned for now", id) + } + if count, err := fixture.VersionRowCount(ctx, id); err != nil { + t.Fatalf("counting version rows for %s: %v", id, err) + } else if count != 0 { + t.Errorf("version row count for %s = %d after a create carrying NoHistory, want 0: a no-history "+ + "row is not versioned while it says so", id, count) + } + + if err := fixture.MovePersistent(ctx, id); err != nil { + t.Fatalf("repairing %s to persistent: %v", id, err) + } + repairedCount, err := fixture.VersionRowCount(ctx, id) + if err != nil { + t.Fatalf("counting version rows for %s: %v", id, err) + } + if repairedCount != 1 { + t.Errorf("version row count for %s = %d after the persistent repair, want 1: the row was created "+ + "with the flag on, so the fence must let the repair's update-shaped mint through", id, repairedCount) + } + + if err := fixture.MutateExisting(ctx, id); err != nil { + t.Fatalf("mutating existing %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 != repairedCount+1 { + t.Errorf("version row count for %s went from %d to %d across an update-shaped mutation after the "+ + "repair, want exactly +1", id, repairedCount, afterCount) + } +} + +// RunParticipationGenerationLegacyNoHistoryIssueStaysLegacy is +// RunParticipationGenerationNoHistoryIssueCreateDeclaresParticipation's +// negative twin, and pins R2.3: an ordinary write never promotes a legacy +// record. The same no-history issues-table row, created while the flag was +// OFF, is legacy. Only a create-shaped call stamps a flagged row, so once the +// flag is on, an update-shaped mutation must leave participation_generation +// NULL and mint nothing. So must the bd update --persistent repair that then +// clears the flag in place: that repair is update-shaped too (a same-plane +// normalize), so the row it leaves is an ordinary legacy row, still fenced. +func RunParticipationGenerationLegacyNoHistoryIssueStaysLegacy(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) { + t.Helper() + if err := fixture.SetFlag(ctx, false); err != nil { + t.Fatalf("disabling versioned history: %v", err) + } + id := fixture.IssuePrefix + "-no-history-legacy" + if err := fixture.CreateNoHistoryIssue(ctx, id); err != nil { + t.Fatalf("creating no-history issues-plane row %s with the flag off: %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 = %d before the flag was ever turned on, want NULL — "+ + "this case cannot test that a legacy no-history row stays legacy against a row that was never "+ + "legacy", id, *gen) + } + + if err := fixture.SetFlag(ctx, true); err != nil { + t.Fatalf("enabling versioned history: %v", err) + } + beforeRevision, err := fixture.CurrentRevision(ctx, id) + if err != nil { + t.Fatalf("reading current_revision for %s: %v", id, err) + } + + assertStillLegacy := func(after string) { + t.Helper() + if gen, err := fixture.ParticipationGeneration(ctx, id); err != nil { + t.Fatalf("reading participation_generation for %s: %v", id, err) + } else if gen != nil { + t.Errorf("participation_generation for %s = %d after %s with the flag on, want NULL: the row "+ + "was created with the flag off, and an update-shaped write must not promote a legacy "+ + "record (R2.3), whatever its no-history flag says", id, *gen, after) + } + if count, err := fixture.VersionRowCount(ctx, id); err != nil { + t.Fatalf("counting version rows for %s: %v", id, err) + } else if count != 0 { + t.Errorf("version row count for %s = %d after %s with the flag on, want 0: a legacy row's "+ + "update-shaped mint is fenced (design §16.2b)", id, count, after) + } + if revision, err := fixture.CurrentRevision(ctx, id); err != nil { + t.Fatalf("reading current_revision for %s: %v", id, err) + } else if revision != beforeRevision { + t.Errorf("current_revision for %s went from %d to %d after %s, want unchanged: a fenced "+ + "mint runs neither half of the seam's write", id, beforeRevision, revision, after) + } + } + + if err := fixture.MutateExisting(ctx, id); err != nil { + t.Fatalf("mutating existing %s: %v", id, err) + } + assertStillLegacy("an update-shaped mutation") + + if err := fixture.MovePersistent(ctx, id); err != nil { + t.Fatalf("repairing %s to persistent: %v", id, err) + } + assertStillLegacy("the persistent repair") +} + +// RunParticipationGenerationFenceIgnoresSchemaSkewHatch pins design §16.2(c): +// BD_IGNORE_SCHEMA_SKEW=1 downgrades CheckForwardDrift's refusal to a warning +// (internal/storage/schema/schema.go), but it must have no effect on this +// fence — the fence keys on the participation_generation column's real data, +// not on the migration cursor the hatch is about, so a write admitted through +// that hatch is still, correctly, skipped when the record is legacy. +func RunParticipationGenerationFenceIgnoresSchemaSkewHatch(t *testing.T, ctx context.Context, fixture ParticipationGenerationFixture) { + t.Helper() + t.Setenv("BD_IGNORE_SCHEMA_SKEW", "1") + + if err := fixture.SetFlag(ctx, false); err != nil { + t.Fatalf("disabling versioned history: %v", err) + } + id := fixture.IssuePrefix + "-schema-skew-hatch" + if err := fixture.Mutate(ctx, id); err != nil { + t.Fatalf("mutating %s: %v", id, err) + } + if err := fixture.SetFlag(ctx, true); err != nil { + t.Fatalf("enabling versioned history: %v", 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) + } + + 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 with BD_IGNORE_SCHEMA_SKEW=1 set, want "+ + "unchanged: the schema-skew hatch must not bypass the participation_generation fence — they "+ + "key on different planes (migration cursor vs. real column data) — so a write admitted "+ + "through the hatch against a legacy record must still be skipped", id, beforeCount, afterCount) + } +} diff --git a/internal/httpclient/BUILD.bazel b/internal/httpclient/BUILD.bazel index d3cdff60f..c28468acf 100644 --- a/internal/httpclient/BUILD.bazel +++ b/internal/httpclient/BUILD.bazel @@ -172,6 +172,7 @@ go_test( "served_memories_deps_test.go", "served_metadata_cas_test.go", "served_molecule_test.go", + "served_participation_generation_test.go", "served_project_swap_test.go", "served_querier_test.go", "served_reader_test.go", diff --git a/internal/httpclient/served_participation_generation_test.go b/internal/httpclient/served_participation_generation_test.go new file mode 100644 index 000000000..fed38636d --- /dev/null +++ b/internal/httpclient/served_participation_generation_test.go @@ -0,0 +1,193 @@ +//go:build cgo + +package httpclient + +import ( + "context" + "database/sql" + "fmt" + "testing" + + "github.com/steveyegge/beads/backend/conformance" + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/issueops" +) + +// The ParticipationGenerationFixture contracts (design §16.2b's write fence), +// run through client → in-process bd serve → reference store, the same shape +// as served_dualwrite_history_test.go. +// +// The mutations under test are the CLIENT'S. Mutate is Lifecycle.Create, +// MutateExisting is Lifecycle.Update, MovePersistent is the persistence-mode +// Lifecycle.Update that bd update --persistent sends, and PromoteWisp is +// issueops.Promote over the client's own roles, the one library entry bd +// promote dials over http. On the server those reach ExecuteCreate and the +// guarded update (ExecuteUpdate). The store legs' MutateExisting goes through +// store.UpdateIssue instead, so this leg is the one that runs the fence +// behind the update a connected workspace actually sends. +// +// SetFlag flips the REFERENCE store's versioned-history flag, and +// CurrentRevision, VersionRowCount and ParticipationGeneration read its raw +// columns, as served_dualwrite_history_test.go's fixture does. CreateWisp is a +// seed, so it goes through the reference store (the harness rule in +// served_harness_test.go). +// +// ClearWispFlag, SquashWispRoot, CreateUnflaggedWisp and InWispsTable stay nil, +// and the cases that need them stay unwired, along with the one whose subject is a +// no-history issues-table create. None of those mutations has a form on this +// wire; see participationGenerationWireGapWaiverReason in +// internal/storage/leg_contract_wiring_test.go. CreateNoHistoryIssue is bound, +// but only as the reference-store seed of the legacy no-history case. +// +// The fixture gets its OWN env (newServedEnv), never the shared composition, +// for the reason served_dualwrite_history_test.go gives: the flag is a knob on +// the reference store instance the server's roles are bound to. +func newServedParticipationGenerationFixture(t *testing.T, prefix string) conformance.ParticipationGenerationFixture { + t.Helper() + env := newServedEnv(t, prefix) + configurer, ok := any(env.reference).(storage.VersionedHistoryConfigurer) + if !ok { + t.Fatalf("%T does not implement storage.VersionedHistoryConfigurer", env.reference) + } + lifecycle, err := env.subject.IssueLifecycle() + if err != nil { + t.Fatalf("IssueLifecycle(): %v", err) + } + reader, err := env.subject.IssueReader() + if err != nil { + t.Fatalf("IssueReader(): %v", err) + } + commenter, err := env.subject.Commenter() + if err != nil { + t.Fatalf("Commenter(): %v", err) + } + // The flag is instance-scoped and outlives nothing past this env, but turn + // it off anyway so a later hook on the same env never inherits it. + t.Cleanup(func() { configurer.SetVersionedHistoryEnabled(false) }) + + persistent := func(ctx context.Context, id string) error { + result, err := lifecycle.Update(ctx, issueops.UpdateRequest{ + Actor: "writer", + IssueID: id, + Patch: issueops.IssuePatch{Persistence: set(issueops.PersistenceModePersistent)}, + }) + if err == nil && !result.Changed { + err = fmt.Errorf("persistence move of %s reported no change", id) + } + return err + } + + return conformance.ParticipationGenerationFixture{ + IssuePrefix: env.prefix, + SetFlag: func(_ context.Context, enabled bool) error { + configurer.SetVersionedHistoryEnabled(enabled) + return nil + }, + Mutate: func(ctx context.Context, id string) error { + _, err := lifecycle.Create(ctx, issueops.CreateRequest{ + Actor: "writer", + ForceIDPrefix: true, + Issue: &types.Issue{ + ID: id, Title: "t-" + id, Status: types.StatusOpen, + Priority: 1, IssueType: types.TypeTask, + }, + }) + return err + }, + MutateExisting: func(ctx context.Context, id string) error { + // A different value than Mutate gave it, so the server's + // DiscardNoopIssueUpdates cannot discard the update before it + // reaches the fence. + _, err := lifecycle.Update(ctx, issueops.UpdateRequest{ + Actor: "writer", + IssueID: id, + Patch: issueops.IssuePatch{Title: set("updated-" + id)}, + }) + return err + }, + CreateWisp: func(ctx context.Context, id string) error { + return env.createWisp(ctx, &types.Issue{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + }, "actor") + }, + PromoteWisp: func(ctx context.Context, id string) error { + promoted, err := issueops.Promote(ctx, issueops.PromoteRoles{ + Reader: reader, Lifecycle: lifecycle, Commenter: commenter, + }, issueops.PromoteRequest{Actor: "writer", IssueID: id}) + if err != nil { + return err + } + return promoted.CommentErr + }, + MovePersistent: persistent, + // A SEED, not a subject: the one case wired here that uses it creates + // the row with the flag OFF, as the precondition for the client's + // update and repair. It goes through the reference store because no + // client create can land a no-history row in the issues table (see + // participationGenerationWireGapWaiverReason), which is also why the + // case whose subject is this create stays waived. + CreateNoHistoryIssue: func(ctx context.Context, id string) error { + durable := false + return env.reference.CreateIssuesWithFullOptions(ctx, []*types.Issue{{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + NoHistory: true, WispPlaneOverride: &durable, + }}, "actor", storage.BatchCreateOptions{SkipPrefixValidation: true}) + }, + CurrentRevision: func(ctx context.Context, id string) (int64, error) { + var revision int64 + err := env.queryScalar(ctx, "SELECT current_revision FROM issues WHERE id = ?", []any{id}, &revision) + return revision, err + }, + VersionRowCount: func(ctx context.Context, id string) (int, error) { + var count int + err := env.queryScalar(ctx, "SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?", []any{id}, &count) + return count, err + }, + ParticipationGeneration: func(ctx context.Context, id string) (*int64, error) { + var gen sql.NullInt64 + if err := env.queryScalar(ctx, + "SELECT participation_generation FROM issues WHERE id = ?", []any{id}, &gen); err != nil { + return nil, err + } + if !gen.Valid { + return nil, nil + } + return &gen.Int64, nil + }, + } +} + +// TestServedParticipationGenerationFence runs every participation-generation +// case this wire can express. Nothing here is parallel, so the schema-skew +// case's t.Setenv can run as a subtest; the in-process server reads the same +// environment. +func TestServedParticipationGenerationFence(t *testing.T) { + ctx := t.Context() + fixture := newServedParticipationGenerationFixture(t, "hpg") + + t.Run("CreateWithFlagOnStampsAValue", func(t *testing.T) { + conformance.RunParticipationGenerationCreateWithFlagOnStampsAValue(t, ctx, fixture) + }) + t.Run("CreateWithFlagOffLeavesLegacyNull", func(t *testing.T) { + conformance.RunParticipationGenerationCreateWithFlagOffLeavesLegacyNull(t, ctx, fixture) + }) + t.Run("SkipsUpdateOnLegacyRecord", func(t *testing.T) { + conformance.RunParticipationGenerationSkipsUpdateOnLegacyRecord(t, ctx, fixture) + }) + t.Run("ProceedsForPromotedRecord", func(t *testing.T) { + conformance.RunParticipationGenerationProceedsForPromotedRecord(t, ctx, fixture) + }) + t.Run("FenceIgnoresSchemaSkewHatch", func(t *testing.T) { + conformance.RunParticipationGenerationFenceIgnoresSchemaSkewHatch(t, ctx, fixture) + }) + t.Run("WispPromotionBeginsHistory", func(t *testing.T) { + conformance.RunParticipationGenerationWispPromotionBeginsHistory(t, ctx, fixture) + }) + t.Run("WispPersistenceMoveBeginsHistory", func(t *testing.T) { + conformance.RunParticipationGenerationWispPersistenceMoveBeginsHistory(t, ctx, fixture) + }) + t.Run("LegacyNoHistoryIssueStaysLegacy", func(t *testing.T) { + conformance.RunParticipationGenerationLegacyNoHistoryIssueStaysLegacy(t, ctx, fixture) + }) +} diff --git a/internal/storage/createbatchequiv/createbatchequiv.go b/internal/storage/createbatchequiv/createbatchequiv.go index afe503e24..78a93af91 100644 --- a/internal/storage/createbatchequiv/createbatchequiv.go +++ b/internal/storage/createbatchequiv/createbatchequiv.go @@ -68,8 +68,11 @@ func scenarios() []scenario { return []scenario{ {name: "small", seed: seed, afterSeed: plantStaleBlocked("s4"), batch: batch}, {name: "apply", seed: seedApply, apply: applyRequest}, - {name: "depadd", seed: seedDepAdd, afterSeed: plantParentCycle, run: runDepAdd}, - {name: "waitsfor", seed: seedWaitsFor, run: runWaitsFor}, + {name: "depadd", seed: seedDepAdd, afterSeed: func(t *testing.T, db *sql.DB) { + plantParentCycle(t, db) + stampParticipation(t, db) + }, run: runDepAdd}, + {name: "waitsfor", seed: seedWaitsFor, afterSeed: stampParticipation, run: runWaitsFor}, } } @@ -89,11 +92,21 @@ 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. One deliberate behavior change since: the create -// role defaults an empty created_by to the request's actor +// what that code stored, apart from two 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 // events digests were re-recorded with every apply-created row carrying -// created_by "apply-writer"; nothing else moved. +// created_by "apply-writer"; nothing else in apply.json moved. +// +// Second, the issue_versions digests of small, import458 and +// import458-reject-stale were re-recorded when the participation-generation +// fence (design §16.2b) landed. Their seeded rows are legacy (the seed runs +// with versioned history off), and the batch's upserts of them no longer +// mint; that is the fenced outcome they now pin. depadd and waitsfor stamp +// 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. const GoldenDirEnv = "CREATEBATCHEQUIV_GOLDEN_DIR" // Run seeds fresh databases, applies each scenario's batch through the fast @@ -154,8 +167,13 @@ func runScenarios(t *testing.T, open Open, list []scenario) { } fast := applyScenario(t, open, sc, false) if sc.run != nil { - if len(fast.Skipped) == 0 { - t.Fatalf("%s: run recorded nothing", sc.name) + // A run that mints no version row no longer exercises + // versioned history at all (its seeded rows went legacy, or + // the paths it drives stopped minting), and a digest recorded + // from it would pin the empty set. + if len(fast.Skipped) == 0 || len(fast.Tables["issue_versions"]) == 0 { + t.Fatalf("%s: run exercised nothing: lines=%d versions=%d", sc.name, + len(fast.Skipped), len(fast.Tables["issue_versions"])) } checkGolden(t, sc.name, fast) return @@ -373,6 +391,20 @@ func plantStaleBlocked(suffix string) func(t *testing.T, db *sql.DB) { } } +// stampParticipation declares every seeded issues-table row participating +// (design §16.2b), as a create with versioned history on would have. The seed +// runs with history off, so without it every seeded row is legacy and the +// write fence keeps a run's dependency adds, closes and reopens on those rows +// from minting at all. The value is store_epoch's seed, 1. Setting updated_at +// to itself keeps the column's ON UPDATE CURRENT_TIMESTAMP from replacing the +// seeded timestamp. Wisps are never stamped (FR-8). +func stampParticipation(t *testing.T, db *sql.DB) { + t.Helper() + if _, err := db.Exec("UPDATE issues SET participation_generation = 1, updated_at = updated_at"); err != nil { + t.Fatalf("stamp participation_generation: %v", err) + } +} + func applyScenario(t *testing.T, open Open, sc scenario, perRow bool) Outcome { t.Helper() ctx := context.Background() diff --git a/internal/storage/createbatchequiv/golden/import458-reject-stale.json b/internal/storage/createbatchequiv/golden/import458-reject-stale.json index 1a3376df1..caa557ad6 100644 --- a/internal/storage/createbatchequiv/golden/import458-reject-stale.json +++ b/internal/storage/createbatchequiv/golden/import458-reject-stale.json @@ -25,8 +25,8 @@ "sha256": "463b88039039693423eadf4cb9dfbb5a438f3600bacac608beb657d8f2ef17fd" }, "issue_versions": { - "rows": 396, - "sha256": "e9bea2d947cd2d2b8129de6aca0ca91ed38f5a82320bb5261fc3aa3b540bd8cd" + "rows": 394, + "sha256": "f8f85d333902058116ce0bbd344fe728217e49e1c4557a64d82ebaa1978d7b6d" }, "issues": { "rows": 404, diff --git a/internal/storage/createbatchequiv/golden/import458.json b/internal/storage/createbatchequiv/golden/import458.json index 1e69a4f7f..f6cfacb92 100644 --- a/internal/storage/createbatchequiv/golden/import458.json +++ b/internal/storage/createbatchequiv/golden/import458.json @@ -25,8 +25,8 @@ "sha256": "9fd68da3b9386eec784e7aa73e4a84c00f5eac6d0cd5189baebc4a6889fb8b69" }, "issue_versions": { - "rows": 398, - "sha256": "92a48b220cd3ccf4348a0879729e00f2a76f365c8861e527964fd7787043d013" + "rows": 394, + "sha256": "f8f85d333902058116ce0bbd344fe728217e49e1c4557a64d82ebaa1978d7b6d" }, "issues": { "rows": 404, diff --git a/internal/storage/createbatchequiv/golden/small.json b/internal/storage/createbatchequiv/golden/small.json index 0ae61885d..83aec24c6 100644 --- a/internal/storage/createbatchequiv/golden/small.json +++ b/internal/storage/createbatchequiv/golden/small.json @@ -25,8 +25,8 @@ "sha256": "3ac2e0ef8128f8fd730ed8432446696c1d7b19a6aea38c47dd051df0a3145ba8" }, "issue_versions": { - "rows": 40, - "sha256": "521720fb99afd6620884b3c4f309624339caefa7a9d0f93a8926727918834785" + "rows": 37, + "sha256": "e91e4e06302a9697582672591ea7037f75d4dc7dd69f4d7ab095b2b8ce5bb604" }, "issues": { "rows": 42, diff --git a/internal/storage/dolt/BUILD.bazel b/internal/storage/dolt/BUILD.bazel index 8869f5995..506ffafed 100644 --- a/internal/storage/dolt/BUILD.bazel +++ b/internal/storage/dolt/BUILD.bazel @@ -217,6 +217,7 @@ go_test( "dolt_test.go", "draincall_regression_test.go", "dualwrite_history_contract_test.go", + "dualwrite_participation_generation_contract_test.go", "edge_reader_contract_test.go", "empty_commit_test.go", "ephemeral_routing_test.go", diff --git a/internal/storage/dolt/dualwrite_history_contract_test.go b/internal/storage/dolt/dualwrite_history_contract_test.go index b8baf11b5..b00534d82 100644 --- a/internal/storage/dolt/dualwrite_history_contract_test.go +++ b/internal/storage/dolt/dualwrite_history_contract_test.go @@ -2,6 +2,7 @@ package dolt import ( "context" + "database/sql" "testing" "github.com/steveyegge/beads/backend/conformance" @@ -313,10 +314,15 @@ func TestDualWriteVersionRowsRideTheMutationsDoltCommit(t *testing.T) { // sweptTables and nothing else, leaving those version rows in the working set // while issuing its own DOLT_COMMIT. // -// The delete path is also the only one of the three where the store_epoch -// assertion is load-bearing without arranging for it: history is turned on AFTER -// the fixture rows exist, so the delete's own transaction takes the first mint in -// this store and seeds the epoch singleton inside it. +// History is turned on BEFORE the fixture rows exist, so the neighbor is created +// as a participating record. A neighbor created with history off would be a +// legacy record (participation_generation NULL), and design §16.2b's write fence +// skips every update-shaped mint on a legacy record: the rewrite would mint +// nothing, and there would be no version row for this test to find. The same +// fence means a delete can no longer take a store's first mint — the only record +// its rewrite can version is one whose own create already seeded store_epoch — +// so store_epoch in the dolt_status loop below guards the delete plane's staged +// table list rather than a row this transaction writes. func TestDualWriteDeleteNeighborRewriteRidesTheDeletesDoltCommit(t *testing.T) { store, storeCleanup := setupTestStore(t) defer storeCleanup() @@ -326,6 +332,8 @@ func TestDualWriteDeleteNeighborRewriteRidesTheDeletesDoltCommit(t *testing.T) { if !ok { t.Fatalf("%T does not implement storage.VersionedHistoryConfigurer", store) } + configurer.SetVersionedHistoryEnabled(true) + defer configurer.SetVersionedHistoryEnabled(false) const target, neighbor = "dwdel-target", "dwdel-neighbor" fixtures := []*types.Issue{ @@ -348,8 +356,18 @@ func TestDualWriteDeleteNeighborRewriteRidesTheDeletesDoltCommit(t *testing.T) { t.Fatalf("add dep: %v", err) } - configurer.SetVersionedHistoryEnabled(true) - defer configurer.SetVersionedHistoryEnabled(false) + neighborVersions := func() int { + t.Helper() + var versions int + if err := store.db.QueryRowContext(ctx, + `SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?`, neighbor).Scan(&versions); err != nil { + t.Fatalf("count issue_versions for %s: %v", neighbor, err) + } + return versions + } + // The neighbor's create and its dependency add have already minted rows of + // their own; only what the delete adds on top of them is this test's concern. + versionsBefore := neighborVersions() deleter, err := store.Deleter() if err != nil { @@ -365,13 +383,17 @@ func TestDualWriteDeleteNeighborRewriteRidesTheDeletesDoltCommit(t *testing.T) { t.Fatalf("ReferencesUpdated = %d, want 1 — the citation rewrite did not run, so this case is not exercising the minting delete path it exists for", result.ReferencesUpdated) } - var versions int - if err := store.db.QueryRowContext(ctx, - `SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?`, neighbor).Scan(&versions); err != nil { - t.Fatalf("count issue_versions for %s: %v", neighbor, err) + if minted := neighborVersions() - versionsBefore; minted != 1 { + t.Fatalf("the delete minted %d issue_versions rows for the rewritten neighbor %s, want 1 — the delete's own transaction is not scoped for minting", minted, neighbor) } - if versions != 1 { - t.Fatalf("issue_versions rows for the rewritten neighbor %s = %d, want 1 — the delete's own transaction is not scoped for minting", neighbor, versions) + var latestActor string + if err := store.db.QueryRowContext(ctx, + `SELECT COALESCE(change_actor, '') FROM issue_versions WHERE issue_id = ? ORDER BY revision DESC LIMIT 1`, + neighbor).Scan(&latestActor); err != nil { + t.Fatalf("read the newest issue_versions row for %s: %v", neighbor, err) + } + if latestActor != "deleter" { + t.Fatalf("the newest issue_versions row for %s is attributed to %q, want %q — it is not the delete's citation rewrite", neighbor, latestActor, "deleter") } for _, table := range []string{"issue_versions", "store_epoch", "issues"} { @@ -385,3 +407,81 @@ func TestDualWriteDeleteNeighborRewriteRidesTheDeletesDoltCommit(t *testing.T) { } } } + +// TestDualWriteDeleteSkipsALegacyNeighborsRewrite is the other half of the case +// above: a neighbor created while history was OFF is a legacy record +// (participation_generation NULL), so design §16.2b's write fence skips the +// delete's citation rewrite for it. The rewrite still runs and the delete still +// commits cleanly; it just mints nothing. Without this, a change that let the +// delete mint for a legacy neighbor would go unnoticed now that the test above +// creates its neighbor with history on. +func TestDualWriteDeleteSkipsALegacyNeighborsRewrite(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) + + const target, neighbor = "dwdel-legacy-target", "dwdel-legacy-neighbor" + for _, issue := range []*types.Issue{ + {ID: target, Title: "doomed", IssueType: types.TypeTask, Status: types.StatusOpen}, + {ID: neighbor, Title: "survivor", Description: "blocked by " + target, + IssueType: types.TypeTask, Status: types.StatusOpen}, + } { + if err := store.CreateIssue(ctx, issue, "creator"); err != nil { + t.Fatalf("create %s: %v", issue.ID, err) + } + } + if err := store.AddDependency(ctx, &types.Dependency{ + IssueID: neighbor, DependsOnID: target, Type: types.DepBlocks, + }, "linker"); err != nil { + t.Fatalf("add dep: %v", err) + } + // Only now, after the neighbor already exists as a legacy record. + configurer.SetVersionedHistoryEnabled(true) + + deleter, err := store.Deleter() + if err != nil { + t.Fatalf("Deleter(): %v", err) + } + result, err := deleter.Delete(ctx, publicops.DeleteRequest{ + IDs: []string{target}, Force: true, Actor: "deleter", + }) + if err != nil { + t.Fatalf("delete %s: %v", target, err) + } + if result.ReferencesUpdated != 1 { + t.Fatalf("ReferencesUpdated = %d, want 1 — the citation rewrite did not run, so this case is not exercising the path it exists for", result.ReferencesUpdated) + } + + var versions int + if err := store.db.QueryRowContext(ctx, + `SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?`, neighbor).Scan(&versions); err != nil { + t.Fatalf("count issue_versions for %s: %v", neighbor, err) + } + if versions != 0 { + t.Errorf("the delete minted %d issue_versions rows for the legacy neighbor %s, want 0: the rewrite is an update-shaped write to a record that has not declared participation (design §16.2b)", versions, neighbor) + } + var generation sql.NullInt64 + if err := store.db.QueryRowContext(ctx, + `SELECT participation_generation FROM issues WHERE id = ?`, neighbor).Scan(&generation); err != nil { + t.Fatalf("read participation_generation for %s: %v", neighbor, err) + } + if generation.Valid { + t.Errorf("participation_generation for the legacy neighbor %s = %d after the delete, want NULL: an ordinary write must not promote a legacy record (R2.3)", neighbor, generation.Int64) + } + for _, table := range []string{"issue_versions", "store_epoch", "issues"} { + var dirty int + if err := store.db.QueryRowContext(ctx, + `SELECT COUNT(*) FROM dolt_status WHERE table_name = ?`, table).Scan(&dirty); err != nil { + t.Fatalf("read dolt_status for %s: %v", table, err) + } + if dirty != 0 { + t.Errorf("dolt_status still reports %s dirty after the delete committed", table) + } + } +} diff --git a/internal/storage/dolt/dualwrite_participation_generation_contract_test.go b/internal/storage/dolt/dualwrite_participation_generation_contract_test.go new file mode 100644 index 000000000..5380b4db2 --- /dev/null +++ b/internal/storage/dolt/dualwrite_participation_generation_contract_test.go @@ -0,0 +1,345 @@ +package dolt + +import ( + "context" + "database/sql" + "fmt" + "testing" + + "github.com/steveyegge/beads/backend/conformance" + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/types" + publicops "github.com/steveyegge/beads/issueops" +) + +// TestParticipationGenerationFence runs the design §16.2(b) write-fence +// contract (backend/conformance/dualwrite_participation_generation_contract.go) +// against the dolt leg. Like TestDualWriteContract, this is an engine check +// rather than an independent per-leg vote: all three legs share +// RecordVersionInTx's one fence check, and the dolt leg is where a fence +// check that ran outside the mutation's own transaction, or that missed a +// call site, would have somewhere concrete to go wrong. +func TestParticipationGenerationFence(t *testing.T) { + fixture, ctx, cleanup := newDoltParticipationGenerationFixture(t, "pg") + defer cleanup() + + t.Run("CreateWithFlagOnStampsAValue", func(t *testing.T) { + conformance.RunParticipationGenerationCreateWithFlagOnStampsAValue(t, ctx, fixture) + }) + t.Run("CreateWithFlagOffLeavesLegacyNull", func(t *testing.T) { + conformance.RunParticipationGenerationCreateWithFlagOffLeavesLegacyNull(t, ctx, fixture) + }) + t.Run("SkipsUpdateOnLegacyRecord", func(t *testing.T) { + conformance.RunParticipationGenerationSkipsUpdateOnLegacyRecord(t, ctx, fixture) + }) + t.Run("ProceedsForPromotedRecord", func(t *testing.T) { + conformance.RunParticipationGenerationProceedsForPromotedRecord(t, ctx, fixture) + }) + t.Run("WispPromotionBeginsHistory", func(t *testing.T) { + conformance.RunParticipationGenerationWispPromotionBeginsHistory(t, ctx, fixture) + }) + t.Run("WispPersistenceMoveBeginsHistory", func(t *testing.T) { + conformance.RunParticipationGenerationWispPersistenceMoveBeginsHistory(t, ctx, fixture) + }) + t.Run("WispFlagClearMintsNothing", func(t *testing.T) { + conformance.RunParticipationGenerationWispFlagClearMintsNothing(t, ctx, fixture) + }) + t.Run("WispRootSquashMintsNothing", func(t *testing.T) { + conformance.RunParticipationGenerationWispRootSquashMintsNothing(t, ctx, fixture) + }) + t.Run("UnflaggedWispCreateMintsNothing", func(t *testing.T) { + conformance.RunParticipationGenerationUnflaggedWispCreateMintsNothing(t, ctx, fixture) + }) + t.Run("NoHistoryIssueCreateDeclaresParticipation", func(t *testing.T) { + conformance.RunParticipationGenerationNoHistoryIssueCreateDeclaresParticipation(t, ctx, fixture) + }) + t.Run("LegacyNoHistoryIssueStaysLegacy", func(t *testing.T) { + conformance.RunParticipationGenerationLegacyNoHistoryIssueStaysLegacy(t, ctx, fixture) + }) +} + +// TestParticipationGenerationFence_FenceIgnoresSchemaSkewHatch pins the same +// design §16.2(c) case as TestParticipationGenerationFence's other subtests, +// but as its own non-parallel top-level test against a dedicated database +// rather than a fifth t.Run under it: this case's conformance function calls +// t.Setenv, which Go forbids anywhere in a parallel test's tree, and the +// fixture above is built via setupTestStore, which calls t.Parallel() (the +// two combined panic the whole test binary). schema_skew_test.go's +// TestCheckForwardDrift_EscapeHatch_ReturnsNil hits the identical constraint +// and solves it the same way: a store built outside setupTestStore. +func TestParticipationGenerationFence_FenceIgnoresSchemaSkewHatch(t *testing.T) { + fixture, ctx, cleanup := newDoltParticipationGenerationFixtureSerial(t, "pgh") + defer cleanup() + conformance.RunParticipationGenerationFenceIgnoresSchemaSkewHatch(t, ctx, fixture) +} + +// TestParticipationGenerationFixtureKitIsWired is the explicit per-leg +// guardrail design §8.5 calls for in place of AST auto-discovery — see the +// dual-write contract's TestDualWriteFixtureKitIsWired for why the guardrail +// is needed even though TestEveryLegWiresEveryRoleContract's scan already +// enumerates and confirms wiring for every RunParticipationGenerationXxx +// entrypoint. +func TestParticipationGenerationFixtureKitIsWired(t *testing.T) { + fixture, _, cleanup := newDoltParticipationGenerationFixture(t, "pgk") + defer cleanup() + + if fixture.SetFlag == nil { + t.Error("ParticipationGenerationFixture.SetFlag is nil") + } + if fixture.Mutate == nil { + t.Error("ParticipationGenerationFixture.Mutate is nil") + } + if fixture.MutateExisting == nil { + t.Error("ParticipationGenerationFixture.MutateExisting is nil") + } + if fixture.CreateWisp == nil { + t.Error("ParticipationGenerationFixture.CreateWisp is nil") + } + if fixture.PromoteWisp == nil { + t.Error("ParticipationGenerationFixture.PromoteWisp is nil") + } + if fixture.MovePersistent == nil { + t.Error("ParticipationGenerationFixture.MovePersistent is nil") + } + if fixture.ClearWispFlag == nil { + t.Error("ParticipationGenerationFixture.ClearWispFlag is nil") + } + if fixture.SquashWispRoot == nil { + t.Error("ParticipationGenerationFixture.SquashWispRoot is nil") + } + if fixture.CreateUnflaggedWisp == nil { + t.Error("ParticipationGenerationFixture.CreateUnflaggedWisp is nil") + } + if fixture.CreateNoHistoryIssue == nil { + t.Error("ParticipationGenerationFixture.CreateNoHistoryIssue is nil") + } + if fixture.CurrentRevision == nil { + t.Error("ParticipationGenerationFixture.CurrentRevision is nil") + } + if fixture.VersionRowCount == nil { + t.Error("ParticipationGenerationFixture.VersionRowCount is nil") + } + if fixture.ParticipationGeneration == nil { + t.Error("ParticipationGenerationFixture.ParticipationGeneration is nil") + } + if fixture.InWispsTable == nil { + t.Error("ParticipationGenerationFixture.InWispsTable is nil") + } +} + +func newDoltParticipationGenerationFixture(t *testing.T, prefix string) (conformance.ParticipationGenerationFixture, context.Context, func()) { + t.Helper() + store, storeCleanup := setupTestStore(t) + ctx, cancel := testContext(t) + // Through the type assertion `bd serve` makes, never the concrete method + // set — same discipline as newDoltDualWriteFixture above. + configurer, ok := any(store).(storage.VersionedHistoryConfigurer) + if !ok { + cancel() + storeCleanup() + t.Fatalf("%T does not implement storage.VersionedHistoryConfigurer", store) + } + fixture := buildParticipationGenerationFixture(store, configurer, prefix) + return fixture, ctx, func() { + // Dual-write is instance-scoped, and this store outlives the fixture + // in the shared-database harness — same reasoning as + // newDoltDualWriteFixture's cleanup above. + configurer.SetVersionedHistoryEnabled(false) + cancel() + storeCleanup() + } +} + +// newDoltParticipationGenerationFixtureSerial is +// newDoltParticipationGenerationFixture's non-parallel twin, for the one case +// (TestParticipationGenerationFence_FenceIgnoresSchemaSkewHatch) that needs +// t.Setenv: a dedicated, freshly created database instead of a branch on the +// shared test database, built the same way schema_skew_test.go's +// TestCheckForwardDrift_EscapeHatch_ReturnsNil builds its store, so the +// caller never triggers setupTestStore's t.Parallel(). +func newDoltParticipationGenerationFixtureSerial(t *testing.T, prefix string) (conformance.ParticipationGenerationFixture, context.Context, func()) { + t.Helper() + skipIfNoDolt(t) + ctx, cancel := testContext(t) + + store, err := New(ctx, &Config{ + Path: t.TempDir(), + CommitterName: "test", + CommitterEmail: "test@example.com", + Database: uniqueTestDBName(t), + CreateIfMissing: true, + }) + if err != nil { + cancel() + t.Fatalf("failed to create Dolt store: %v", err) + } + if _, err := initSchemaOnDB(ctx, store.db); err != nil { + store.Close() + cancel() + t.Fatalf("failed to initialize schema: %v", err) + } + // A standalone database starts with an empty config table — unlike + // setupTestStore's shared database, which testmain_test.go seeds once. + // CreateIssue's ReadConfigPrefix check requires this row to exist at all; + // it does not need to match the ID prefix used elsewhere in the suite. + if err := store.SetConfig(ctx, "issue_prefix", prefix); err != nil { + store.Close() + cancel() + t.Fatalf("set issue_prefix to %q: %v", prefix, err) + } + configurer, ok := any(store).(storage.VersionedHistoryConfigurer) + if !ok { + store.Close() + cancel() + t.Fatalf("%T does not implement storage.VersionedHistoryConfigurer", store) + } + fixture := buildParticipationGenerationFixture(store, configurer, prefix) + return fixture, ctx, func() { + configurer.SetVersionedHistoryEnabled(false) + cancel() + // Do not DROP DATABASE here: rapid CREATE/DROP cycles can crash the + // Dolt testcontainer, same reasoning as the escape-hatch test's own + // cleanup. The random test database is discarded with the container. + store.Close() + } +} + +// buildParticipationGenerationFixture wires a ParticipationGenerationFixture +// against an already-constructed, already-schema-initialized store — the +// part newDoltParticipationGenerationFixture and its serial twin share, +// factored out so the t.Parallel()-vs-t.Setenv split above does not fork the +// fixture wiring itself into two copies that could drift. +func buildParticipationGenerationFixture(store *DoltStore, configurer storage.VersionedHistoryConfigurer, prefix string) conformance.ParticipationGenerationFixture { + return conformance.ParticipationGenerationFixture{ + IssuePrefix: prefix, + SetFlag: func(ctx context.Context, enabled bool) error { + configurer.SetVersionedHistoryEnabled(enabled) + return nil + }, + Mutate: func(ctx context.Context, id string) error { + return store.CreateIssue(ctx, &types.Issue{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + }, "actor") + }, + MutateExisting: func(ctx context.Context, id string) error { + // A different value than Mutate gave it, not a re-assertion of the + // same title: DiscardNoopIssueUpdates would discard the latter + // before it ever reached the fence this contract is testing. + return store.UpdateIssue(ctx, id, map[string]any{"title": "updated-" + id}, "actor") + }, + CreateWisp: func(ctx context.Context, id string) error { + return store.CreateIssue(ctx, &types.Issue{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, Ephemeral: true, + }, "actor") + }, + PromoteWisp: func(ctx context.Context, id string) error { + return store.PromoteFromEphemeral(ctx, id, "actor") + }, + MovePersistent: func(ctx context.Context, id string) error { + // The guarded update bd update --persistent runs, so the move + // takes the update's one end-of-update mint rather than + // MoveIssuePersistenceInTx's own. + ops, err := NewIssueOperations(store) + if err != nil { + return err + } + result, err := ops.Update(ctx, publicops.UpdateRequest{Actor: "actor", IssueID: id, Patch: publicops.IssuePatch{ + Persistence: publicops.Field[publicops.PersistenceMode]{Set: true, Value: publicops.PersistenceModePersistent}, + }}) + if err == nil && !result.Changed { + err = fmt.Errorf("persistence move of %s reported no change", id) + } + return err + }, + ClearWispFlag: func(ctx context.Context, id string) error { + // The flag clear alone, in the journal-enabled transaction shape + // (withEventsJournal), so it reaches the mint on this leg. A bare + // store.UpdateIssue would go through updateWisp, whose transaction + // versioned history never scopes, and the case would pass whatever + // the fence did. + return withEventsJournal(store, func() error { + return store.RunInTransaction(ctx, "clear wisp flag "+id, func(tx storage.Transaction) error { + return tx.UpdateIssue(ctx, id, map[string]any{"wisp": false}, "actor") + }) + }) + }, + SquashWispRoot: func(ctx context.Context, id string) error { + // bd mol squash's own shape: the root's close and its flag clear + // in the one transaction the squash commits, in the + // journal-enabled shape that reaches the mint (withEventsJournal). + return withEventsJournal(store, func() error { + return store.RunInTransaction(ctx, "squash "+id, func(tx storage.Transaction) error { + if err := tx.CloseIssue(ctx, id, "squashed", "actor", ""); err != nil { + return err + } + return tx.UpdateIssue(ctx, id, map[string]any{"wisp": false}, "actor") + }) + }) + }, + CreateUnflaggedWisp: func(ctx context.Context, id string) error { + // Import's "wisp_plane" marker: the override, not the flags, puts + // the row in the wisps table. + wispPlane := true + return store.CreateIssuesWithFullOptions(ctx, []*types.Issue{{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + WispPlaneOverride: &wispPlane, + }}, "actor", storage.BatchCreateOptions{SkipPrefixValidation: true}) + }, + CreateNoHistoryIssue: func(ctx context.Context, id string) error { + // Import's promoted-no-history shape (bd-r9uce): the flag stays on + // the row, and the override pins it to the issues table. + durable := false + return store.CreateIssuesWithFullOptions(ctx, []*types.Issue{{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + NoHistory: true, WispPlaneOverride: &durable, + }}, "actor", storage.BatchCreateOptions{SkipPrefixValidation: true}) + }, + CurrentRevision: func(ctx context.Context, id string) (int64, error) { + var revision int64 + err := store.db.QueryRowContext(ctx, `SELECT current_revision FROM issues WHERE id = ?`, id). + Scan(&revision) + return revision, err + }, + VersionRowCount: func(ctx context.Context, id string) (int, error) { + var count int + err := store.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?`, id). + Scan(&count) + return count, err + }, + ParticipationGeneration: func(ctx context.Context, id string) (*int64, error) { + var gen sql.NullInt64 + if err := store.db.QueryRowContext(ctx, + `SELECT participation_generation FROM issues WHERE id = ?`, id).Scan(&gen); err != nil { + return nil, err + } + if !gen.Valid { + return nil, nil + } + return &gen.Int64, nil + }, + InWispsTable: func(ctx context.Context, id string) (bool, error) { + var rows int + if err := store.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM wisps WHERE id = ?`, id). + Scan(&rows); err != nil { + return false, err + } + return rows > 0, nil + }, + } +} + +// withEventsJournal runs fn with store's events journal on and then restores +// whatever setting the store had before, rather than assuming it was off. +// +// With the journal off, RunInTransaction runs wisp writes on a separate +// ignored-table transaction that versioned history never scopes, and a lone +// store.UpdateIssue on a wisp (updateWisp) opens a transaction it never scopes +// either, so neither reaches the mint the wisps-table cases pin. A +// journal-enabled workspace pins both planes to the one regular, scoped +// transaction, which is the shape that reaches it. +func withEventsJournal(store *DoltStore, fn func() error) error { + previous := store.eventsJournalEnabled.Load() + store.SetEventsJournalEnabled(true) + defer store.SetEventsJournalEnabled(previous) + return fn() +} diff --git a/internal/storage/dolt/issue_operations_persistence_test.go b/internal/storage/dolt/issue_operations_persistence_test.go index a7c1ef504..bc260863f 100644 --- a/internal/storage/dolt/issue_operations_persistence_test.go +++ b/internal/storage/dolt/issue_operations_persistence_test.go @@ -9,6 +9,7 @@ import ( "github.com/steveyegge/beads/internal/storage" "github.com/steveyegge/beads/internal/storage/issueops" "github.com/steveyegge/beads/internal/types" + publicops "github.com/steveyegge/beads/issueops" ) func TestMoveIssuePersistenceInTxMovesAggregateAndReportsTables(t *testing.T) { @@ -390,3 +391,95 @@ func TestMoveIssuePersistenceInTxRepairsFlagsInTheIssuesPlane(t *testing.T) { t.Errorf("wisps rows = %d, want 0: a same-plane repair must not move the row", wisps) } } + +// TestPersistenceRepairKeepsTheRowsOwnParticipation pins the one persistence +// path that mints update-shaped on purpose. A repair (the same-plane branch +// above: an issues-plane row carrying a wisp flag, made persistent in place) +// leaves the row where it is, so the row keeps its own +// participation_generation. With versioned history on, a legacy row stays +// legacy and mints nothing, because a repair is an ordinary write and must +// not promote it (design §16.2b, R2.3). A row created with the flag on mints +// one version, as any update of it would. A move out of the wisps table is +// different: it inserts a new issues row, so it is create-shaped +// (RunParticipationGenerationWispPersistenceMoveBeginsHistory). Both repair +// entry points are covered, because they mint at different sites: +// MoveIssuePersistenceInTx's own repair mint, and the guarded update's one +// end-of-update mint. +func TestPersistenceRepairKeepsTheRowsOwnParticipation(t *testing.T) { + store, cleanup := setupTestStore(t) + defer cleanup() + defer store.SetVersionedHistoryEnabled(false) + ctx := context.Background() + ops, err := NewIssueOperations(store) + if err != nil { + t.Fatal(err) + } + repairs := map[string]func(id string) error{ + "move": func(id string) error { + return store.withRetryTx(ctx, func(tx *sql.Tx) error { + current, err := issueops.GetIssueInTx(ctx, tx, id) + if err != nil { + return err + } + _, err = issueops.MoveIssuePersistenceInTx(ctx, tx, current, types.PersistenceModePersistent, "repairer") + return err + }) + }, + "update": func(id string) error { + _, err := ops.Update(ctx, publicops.UpdateRequest{Actor: "repairer", IssueID: id, Patch: publicops.IssuePatch{ + Persistence: publicops.Field[publicops.PersistenceMode]{Set: true, Value: publicops.PersistenceModePersistent}, + }}) + return err + }, + } + state := func(id string) (versions int, 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.Fatal(err) + } + if err := store.db.QueryRowContext(ctx, `SELECT participation_generation FROM issues WHERE id = ?`, id).Scan(&generation); err != nil { + t.Fatal(err) + } + return versions, generation + } + + for _, legacy := range []bool{true, false} { + for _, via := range []string{"move", "update"} { + id := "persist-repair-pg-" + via + if legacy { + id += "-legacy" + } + // A legacy row is created with the flag off; either way the + // repair itself runs with it on. + store.SetVersionedHistoryEnabled(!legacy) + if err := store.CreateIssue(ctx, &types.Issue{ID: id, Title: id, Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask}, "tester"); err != nil { + t.Fatal(err) + } + store.SetVersionedHistoryEnabled(true) + if _, err := store.db.ExecContext(ctx, `UPDATE issues SET ephemeral = 1 WHERE id = ?`, id); err != nil { + t.Fatal(err) + } + beforeVersions, beforeGeneration := state(id) + + if err := repairs[via](id); err != nil { + t.Fatalf("%s: repairing %s: %v", via, id, err) + } + + afterVersions, afterGeneration := state(id) + if afterGeneration != beforeGeneration { + t.Errorf("%s: participation_generation for %s went from %v to %v across the repair, want it "+ + "unchanged: the row stays on the issues plane, so its participation is its own", + via, id, beforeGeneration, afterGeneration) + } + wantVersions := beforeVersions + 1 + if legacy { + wantVersions = beforeVersions + } + if afterVersions != wantVersions { + t.Errorf("%s: version rows for %s (legacy=%v) went from %d to %d across the repair, want %d: "+ + "a repair is update-shaped, so it mints for a participating row and skips a legacy one", + via, id, legacy, beforeVersions, afterVersions, wantVersions) + } + } + } +} diff --git a/internal/storage/domain/db/issue.go b/internal/storage/domain/db/issue.go index ddc4dc18f..def36a502 100644 --- a/internal/storage/domain/db/issue.go +++ b/internal/storage/domain/db/issue.go @@ -84,7 +84,38 @@ func (r *issueSQLRepositoryImpl) Insert(ctx context.Context, issue *types.Issue, if err := issueops.RecordEventInTx(ctx, r.runner, issueops.EventCreate, issue.ID, actor); err != nil { return err } - return issueops.RecordVersionInTx(ctx, r.runner, issue.ID, actor) + // EnsureIssueIDAvailableInTx above already refused a collision, so this + // strict insert is unconditionally a new row. + return issueops.RecordVersionForCreateInTx(ctx, r.runner, issue.ID, actor) + } + // insertIssueRow is an upsert (ON DUPLICATE KEY UPDATE): unlike the + // CreateOnly branch above, "create" here can resolve to an already-existing + // row. The participation_generation write-fence (design §16.2b) needs to + // know which, so check existence before the upsert overwrites it. With + // versioned history off both mint entries return before reading anything, + // so the answer is unused and the probe is skipped: this create costs the + // round trips it did before the fence. + // + // A wisps-table insert mints update-shaped without a probe. It never + // creates an issues row, and the seam snapshots the issues table first + // (GetIssueInTx), so the only issues row it can resolve is a twin that + // already held this id. A create-shaped mint would stamp and version that + // twin, and so promote a legacy record (R2.3) through an ordinary wisp + // write. Update-shaped, the fence leaves a legacy twin alone, and a + // wisp-only id mints nothing through either entry (FR-8). + // + // A twin that already participates passes the fence, so it still gets + // the one version main minted for it, although this write never touched + // it. That dual presence (GH#4455) predates the fence and is accepted + // here, as on main: unlike issueops' create path + // (checkCrossTableIDCollisionCached), this upsert does not refuse the + // collision. + existed := false + if !opts.UseWispsTable && issueops.VersionedHistoryEnabledFor(r.runner) { + var err error + if existed, err = r.Exists(ctx, issue.ID, domain.IssueTableOpts{}); err != nil { + return err + } } if err := insertIssueRow(ctx, r.runner, table, issue); err != nil { return err @@ -99,7 +130,10 @@ func (r *issueSQLRepositoryImpl) Insert(ctx context.Context, issue *types.Issue, if err := issueops.RecordEventInTx(ctx, r.runner, issueops.EventCreate, issue.ID, actor); err != nil { return err } - return issueops.RecordVersionInTx(ctx, r.runner, issue.ID, actor) + if existed || opts.UseWispsTable { + return issueops.RecordVersionInTx(ctx, r.runner, issue.ID, actor) + } + return issueops.RecordVersionForCreateInTx(ctx, r.runner, issue.ID, actor) } func (r *issueSQLRepositoryImpl) InsertBatch(ctx context.Context, issues []*types.Issue, actor string, opts domain.InsertIssueOpts) error { diff --git a/internal/storage/embeddeddolt/BUILD.bazel b/internal/storage/embeddeddolt/BUILD.bazel index 91d707a6c..5b9d3687f 100644 --- a/internal/storage/embeddeddolt/BUILD.bazel +++ b/internal/storage/embeddeddolt/BUILD.bazel @@ -134,6 +134,7 @@ go_test( "counts_missing_table_test.go", "counts_wisp_test.go", "create_batch_equivalence_test.go", + "create_batch_participation_generation_test.go", "create_issue_test.go", "cross_record_invariant_contract_test.go", "cross_table_id_collision_test.go", @@ -147,6 +148,7 @@ go_test( "detection_test.go", "dirty_tables_gate_test.go", "dualwrite_history_contract_test.go", + "dualwrite_participation_generation_contract_test.go", "edge_reader_contract_test.go", "events_since_test.go", "expected_revision_contract_test.go", diff --git a/internal/storage/embeddeddolt/create_batch_participation_generation_test.go b/internal/storage/embeddeddolt/create_batch_participation_generation_test.go new file mode 100644 index 000000000..1f16fbadd --- /dev/null +++ b/internal/storage/embeddeddolt/create_batch_participation_generation_test.go @@ -0,0 +1,403 @@ +//go:build cgo + +package embeddeddolt_test + +import ( + "context" + "database/sql" + "errors" + "fmt" + "slices" + "testing" + "time" + + "github.com/steveyegge/beads/internal/storage/embeddeddolt" + "github.com/steveyegge/beads/internal/storage/issueops" + "github.com/steveyegge/beads/internal/types" +) + +// batchActor is the actor every batch in this file is created under, and so +// the change_actor its version rows must carry. +const batchActor = "tester" + +// batchRow is one issues row's write-fence state. +type batchRow struct { + id string + generation sql.NullInt64 + revision int64 +} + +func (r batchRow) String() string { + generation := "NULL" + if r.generation.Valid { + generation = fmt.Sprint(r.generation.Int64) + } + return fmt.Sprintf("%s{participation_generation: %s, current_revision: %d}", r.id, generation, r.revision) +} + +// batchVersion is one issue_versions row, less its durable_state payload. +type batchVersion struct { + id string + revision int64 + actor string +} + +// batchSnapshot is what a batch create leaves behind that the participation +// write fence governs, read on one connection: every issues row, every version +// row and the store epoch a stamp is sourced from. rows and versions are in id +// (then revision) order. +type batchSnapshot struct { + rows []batchRow + versions []batchVersion + // epoch is invalid while store_epoch has no row: the first mint seeds it. + epoch sql.NullInt64 +} + +func (s batchSnapshot) row(id string) (batchRow, bool) { + for _, row := range s.rows { + if row.id == id { + return row, true + } + } + return batchRow{}, false +} + +func (s batchSnapshot) versionsOf(id string) []batchVersion { + var versions []batchVersion + for _, version := range s.versions { + if version.id == id { + versions = append(versions, version) + } + } + return versions +} + +func snapshotBatch(t *testing.T, ctx context.Context, te *testEnv) batchSnapshot { + t.Helper() + db, cleanup, err := embeddeddolt.OpenSQL(ctx, te.dataDir, te.database, "main") + if err != nil { + t.Fatalf("OpenSQL: %v", err) + } + defer func() { _ = cleanup() }() + + var snap batchSnapshot + readRows(t, ctx, db, "SELECT id, participation_generation, current_revision FROM issues ORDER BY id", + func(rows *sql.Rows) error { + var row batchRow + err := rows.Scan(&row.id, &row.generation, &row.revision) + snap.rows = append(snap.rows, row) + return err + }) + readRows(t, ctx, db, "SELECT issue_id, revision, change_actor FROM issue_versions ORDER BY issue_id, revision", + func(rows *sql.Rows) error { + var version batchVersion + err := rows.Scan(&version.id, &version.revision, &version.actor) + snap.versions = append(snap.versions, version) + return err + }) + // store_epoch is seeded by the first mint, so a store that never minted has + // no row to read. + err = db.QueryRowContext(ctx, "SELECT epoch FROM store_epoch WHERE id = 1").Scan(&snap.epoch) + if err != nil && !errors.Is(err, sql.ErrNoRows) { + t.Fatalf("read store_epoch: %v", err) + } + return snap +} + +// readRows runs query on db and hands each result row to scan. +func readRows(t *testing.T, ctx context.Context, db *sql.DB, query string, scan func(rows *sql.Rows) error) { + t.Helper() + rows, err := db.QueryContext(ctx, query) + if err != nil { + t.Fatalf("%s: %v", query, err) + } + defer rows.Close() + for rows.Next() { + if err := scan(rows); err != nil { + t.Fatalf("%s: scan: %v", query, err) + } + } + if err := rows.Err(); err != nil { + t.Fatalf("%s: %v", query, err) + } +} + +// firstDiff describes the first entry at which a and b differ, or returns "" +// when they are equal. +func firstDiff[T comparable](a, b []T) string { + for i := range max(len(a), len(b)) { + switch { + case i >= len(a): + return fmt.Sprintf("entry %d is only in the second list: %v (%d entries vs %d)", i, b[i], len(a), len(b)) + case i >= len(b): + return fmt.Sprintf("entry %d is only in the first list: %v (%d entries vs %d)", i, a[i], len(a), len(b)) + case a[i] != b[i]: + return fmt.Sprintf("entry %d: %v vs %v", i, a[i], b[i]) + } + } + return "" +} + +// batchIDs returns n explicit issue ids under prefix. Explicit ids absent from +// both planes are what make a batch eligible for the deferred multi-row insert. +func batchIDs(prefix string, n int) []string { + ids := make([]string, n) + for i := range ids { + ids[i] = fmt.Sprintf("%s-b%04d", prefix, i+1) + } + return ids +} + +func newBatchIssue(id, title string) *types.Issue { + return &types.Issue{ID: id, Title: title, Priority: 2, IssueType: types.TypeTask, Status: types.StatusOpen} +} + +// createBatch creates the n issues batchIDs(prefix, n) names in one CreateIssues +// call on a fresh store and reports what the batch left behind. history sets +// whether versioned history is on for the call. perRow turns the batch-create +// fast paths off for it, so every row takes the per-row body instead of the +// deferred multi-row insert; they are back on before createBatch returns. +func createBatch(t *testing.T, prefix string, n int, history, perRow bool) batchSnapshot { + t.Helper() + ctx := t.Context() + te := newTestEnv(t, prefix) + te.store.SetVersionedHistoryEnabled(history) + + issues := make([]*types.Issue, 0, n) + for _, id := range batchIDs(prefix, n) { + issues = append(issues, newBatchIssue(id, "batch row "+id)) + } + if perRow { + restore := issueops.DisableCreateFastPathsForTest() + defer restore() + } + if err := te.store.CreateIssues(ctx, issues, batchActor); err != nil { + t.Fatalf("CreateIssues of %d rows: %v", n, err) + } + return snapshotBatch(t, ctx, te) +} + +// requireStamped fails the test unless every id names an issue whose history +// the batch began: participation_generation equal to the store epoch, exactly +// one issue_versions row (revision 1, written by batchActor) and +// current_revision at that revision. current_revision's column default is also +// 1, so it is the stamp and the version row that show a mint happened. +func requireStamped(t *testing.T, snap batchSnapshot, ids ...string) { + t.Helper() + if !snap.epoch.Valid { + t.Errorf("store_epoch has no row after the batch, so nothing minted a version: want %d rows stamped", len(ids)) + return + } + var unstamped []string + for _, id := range ids { + row, found := snap.row(id) + versions := snap.versionsOf(id) + wantVersions := []batchVersion{{id: id, revision: 1, actor: batchActor}} + if !found || row.generation != (sql.NullInt64{Int64: snap.epoch.Int64, Valid: true}) || + row.revision != 1 || !slices.Equal(versions, wantVersions) { + unstamped = append(unstamped, fmt.Sprintf("%v with versions %v", row, versions)) + } + } + if len(unstamped) > 0 { + t.Errorf("%d of %d batch-created rows are not stamped with store epoch %d at revision 1 by %q; first: %s", + len(unstamped), len(ids), snap.epoch.Int64, batchActor, unstamped[0]) + } +} + +// TestCreateBatchParticipationGeneration pins the participation write fence at +// the seam a batch create mints through. A batch writes every row first and +// mints each created row's first version last, after the creation-time edges +// land, so the mint has to keep each row's shape across that deferral: a row +// the batch inserted is create-shaped and is stamped with the store epoch, and +// a row the batch only upserted over is update-shaped and is skipped while it +// is a legacy row (its participation_generation NULL). +// +// The subtests run one after another and none is parallel: the first turns the +// batch-create fast paths off for the whole process while its comparison run +// executes. +func TestCreateBatchParticipationGeneration(t *testing.T) { + skipUnlessEmbeddedDolt(t) + + t.Run("BrandNewRowsAreStampedAndMatchPerRow", func(t *testing.T) { + for _, tc := range []struct { + name string + prefix string + rows int + // slow cases are skipped under -race. + slow bool + }{ + {name: "FitsOneInsertStatement", prefix: "pga", rows: 5}, + // The multi-row INSERT writes 100 rows per statement, so 250 rows + // take three statements (100, 100 and 50). + {name: "SpansThreeInsertStatements", prefix: "pgb", rows: 250, slow: true}, + } { + t.Run(tc.name, func(t *testing.T) { + if tc.slow && raceEnabled { + t.Skip("250-row batch skipped under -race, where the in-process engine's own instrumentation makes a batch this size very slow; the 5-row case still runs") + } + ids := batchIDs(tc.prefix, tc.rows) + + batch := createBatch(t, tc.prefix, tc.rows, true, false) + requireStamped(t, batch, ids...) + // An empty version list would pass the comparison below + // against another empty one, so stop before it. + if len(batch.rows) != tc.rows || len(batch.versions) != tc.rows { + t.Fatalf("batch of %d new issues left %d issues rows and %d issue_versions rows, want one version row per issue", + tc.rows, len(batch.rows), len(batch.versions)) + } + + // The same input one row at a time, on a second fresh store. The + // stamp and the version rows must not depend on which body ran. + perRow := createBatch(t, tc.prefix, tc.rows, true, true) + requireStamped(t, perRow, ids...) + if diff := firstDiff(batch.versions, perRow.versions); diff != "" { + t.Errorf("issue_versions (issue_id, revision, change_actor) differ between the batch and per-row paths: %s", diff) + } + if diff := firstDiff(batch.rows, perRow.rows); diff != "" { + t.Errorf("issues write-fence state differs between the batch and per-row paths: %s", diff) + } + }) + } + }) + + t.Run("ExistingLegacyRowStaysNull", func(t *testing.T) { + ctx := t.Context() + te := newTestEnv(t, "pgl") + const ( + legacyID = "pgl-old" + newAID = "pgl-newa" + newBID = "pgl-newb" + rewritten = "legacy row, rewritten by the batch" + ) + + // A row created while history is off is a legacy row: nothing stamps it. + te.store.SetVersionedHistoryEnabled(false) + if err := te.store.CreateIssue(ctx, newBatchIssue(legacyID, "legacy row"), batchActor); err != nil { + t.Fatalf("create legacy row: %v", err) + } + before := snapshotBatch(t, ctx, te) + legacy, found := before.row(legacyID) + if !found || legacy.generation.Valid { + t.Fatalf("setup: row created with history off is %v (found %t), want a NULL participation_generation", legacy, found) + } + + // The batch carries the legacy id again with a new title, so it takes + // the per-row upsert (isNew false), beside two rows that are brand new. + te.store.SetVersionedHistoryEnabled(true) + batch := []*types.Issue{ + newBatchIssue(legacyID, rewritten), + newBatchIssue(newAID, "new row a"), + newBatchIssue(newBID, "new row b"), + } + if err := te.store.CreateIssues(ctx, batch, batchActor); err != nil { + t.Fatalf("CreateIssues over the existing id %s: %v", legacyID, err) + } + te.assertIssueTitle(t, ctx, "issues", legacyID, rewritten) + + after := snapshotBatch(t, ctx, te) + if got, _ := after.row(legacyID); got != legacy { + t.Errorf("the batch changed the legacy row's write-fence state: before %v, after %v; "+ + "an upsert over a row that never began history must leave it that way", legacy, got) + } + if versions := after.versionsOf(legacyID); len(versions) != 0 { + t.Errorf("legacy row %s has issue_versions rows %v after the batch, want none", legacyID, versions) + } + requireStamped(t, after, newAID, newBID) + }) + + t.Run("StampKeepsTheCallersUpdatedAt", func(t *testing.T) { + ctx := t.Context() + te := newTestEnv(t, "pgu") + te.store.SetVersionedHistoryEnabled(true) + + // An import supplies each row's timestamps and the batch stores them as + // given. issues.updated_at is ON UPDATE CURRENT_TIMESTAMP, so the UPDATE + // that stamps a row replaces the supplied value with the clock unless it + // sets the column to itself. + supplied := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC) + ids := batchIDs("pgu", 5) + batch := make([]*types.Issue, 0, len(ids)) + for _, id := range ids { + issue := newBatchIssue(id, "imported row "+id) + issue.CreatedAt, issue.UpdatedAt = supplied, supplied + batch = append(batch, issue) + } + if err := te.store.CreateIssues(ctx, batch, batchActor); err != nil { + t.Fatalf("CreateIssues of %d rows: %v", len(ids), err) + } + + // A mint that never ran would leave updated_at alone too, so require the + // stamp first. + requireStamped(t, snapshotBatch(t, ctx, te), ids...) + for _, id := range ids { + var got time.Time + te.queryScalar(t, ctx, "SELECT updated_at FROM issues WHERE id = ?", []any{id}, &got) + if !got.UTC().Equal(supplied) { + t.Errorf("%s: updated_at is %v after the batch, want the supplied %v", id, got.UTC(), supplied) + } + } + }) + + t.Run("NoHistoryRowIsStampedUnversionedAndKeepsTheCallersUpdatedAt", func(t *testing.T) { + ctx := t.Context() + te := newTestEnv(t, "pgn") + te.store.SetVersionedHistoryEnabled(true) + + // Import's promoted-no-history shape (bd-r9uce): a durable row whose + // stray no_history=true is preserved while the override pins it to the + // issues table. The create declares participation without minting a + // version, and that stamp is an UPDATE too, so it must keep the + // supplied updated_at the same way the minting stamp does. + supplied := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC) + ids := batchIDs("pgn", 5) + batch := make([]*types.Issue, 0, len(ids)) + for _, id := range ids { + issue := newBatchIssue(id, "imported no-history row "+id) + issue.CreatedAt, issue.UpdatedAt = supplied, supplied + durable := false + issue.NoHistory, issue.WispPlaneOverride = true, &durable + batch = append(batch, issue) + } + if err := te.store.CreateIssues(ctx, batch, batchActor); err != nil { + t.Fatalf("CreateIssues of %d rows: %v", len(ids), err) + } + + snap := snapshotBatch(t, ctx, te) + if !snap.epoch.Valid { + t.Fatalf("store_epoch has no row after the batch, so nothing stamped the %d rows", len(ids)) + } + for _, id := range ids { + row, found := snap.row(id) + if !found || row.generation != (sql.NullInt64{Int64: snap.epoch.Int64, Valid: true}) { + t.Errorf("%s: row %v after the batch, want it on the issues plane stamped with store epoch %d", + id, row, snap.epoch.Int64) + } + if versions := snap.versionsOf(id); len(versions) != 0 { + t.Errorf("%s: issue_versions rows %v after the batch, want none for a no-history row", id, versions) + } + var got time.Time + te.queryScalar(t, ctx, "SELECT updated_at FROM issues WHERE id = ?", []any{id}, &got) + if !got.UTC().Equal(supplied) { + t.Errorf("%s: updated_at is %v after the batch, want the supplied %v", id, got.UTC(), supplied) + } + } + }) + + t.Run("HistoryOffLeavesNull", func(t *testing.T) { + const rows = 5 + batch := createBatch(t, "pgo", rows, false, false) + if len(batch.rows) != rows { + t.Fatalf("batch of %d new issues left %d issues rows", rows, len(batch.rows)) + } + for _, row := range batch.rows { + // 1 is current_revision's column default, so a row nothing minted + // for still reads 1. + if row.generation.Valid || row.revision != 1 { + t.Errorf("row created with history off is %v, want a NULL participation_generation and the default current_revision 1", row) + } + } + if len(batch.versions) != 0 { + t.Errorf("history off left %d issue_versions rows, want none; first: %v", len(batch.versions), batch.versions[0]) + } + }) +} diff --git a/internal/storage/embeddeddolt/dualwrite_participation_generation_contract_test.go b/internal/storage/embeddeddolt/dualwrite_participation_generation_contract_test.go new file mode 100644 index 000000000..6c2b5aa88 --- /dev/null +++ b/internal/storage/embeddeddolt/dualwrite_participation_generation_contract_test.go @@ -0,0 +1,236 @@ +//go:build cgo + +package embeddeddolt_test + +import ( + "context" + "database/sql" + "fmt" + "testing" + + "github.com/steveyegge/beads/backend/conformance" + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/storage/embeddeddolt" + "github.com/steveyegge/beads/internal/types" + publicops "github.com/steveyegge/beads/issueops" +) + +// TestParticipationGenerationFence runs the design §16.2(b) write-fence +// contract (backend/conformance/dualwrite_participation_generation_contract.go) +// against the embedded store. Like TestDualWriteContract, this is an ENGINE +// CHECK rather than an independent vote: all three legs share +// RecordVersionInTx's one fence check, and this leg is where a wrapper that +// loses the transaction the fence's skip-or-proceed decision must land in +// would have somewhere concrete to go wrong. +func TestParticipationGenerationFence(t *testing.T) { + skipUnlessEmbeddedDolt(t) + te := newTestEnv(t, "pg") + ctx := t.Context() + fixture := newEmbeddedParticipationGenerationFixture(t, te, "pg") + + t.Run("CreateWithFlagOnStampsAValue", func(t *testing.T) { + conformance.RunParticipationGenerationCreateWithFlagOnStampsAValue(t, ctx, fixture) + }) + t.Run("CreateWithFlagOffLeavesLegacyNull", func(t *testing.T) { + conformance.RunParticipationGenerationCreateWithFlagOffLeavesLegacyNull(t, ctx, fixture) + }) + t.Run("SkipsUpdateOnLegacyRecord", func(t *testing.T) { + conformance.RunParticipationGenerationSkipsUpdateOnLegacyRecord(t, ctx, fixture) + }) + t.Run("ProceedsForPromotedRecord", func(t *testing.T) { + conformance.RunParticipationGenerationProceedsForPromotedRecord(t, ctx, fixture) + }) + t.Run("FenceIgnoresSchemaSkewHatch", func(t *testing.T) { + conformance.RunParticipationGenerationFenceIgnoresSchemaSkewHatch(t, ctx, fixture) + }) + t.Run("WispPromotionBeginsHistory", func(t *testing.T) { + conformance.RunParticipationGenerationWispPromotionBeginsHistory(t, ctx, fixture) + }) + t.Run("WispPersistenceMoveBeginsHistory", func(t *testing.T) { + conformance.RunParticipationGenerationWispPersistenceMoveBeginsHistory(t, ctx, fixture) + }) + t.Run("WispFlagClearMintsNothing", func(t *testing.T) { + conformance.RunParticipationGenerationWispFlagClearMintsNothing(t, ctx, fixture) + }) + t.Run("WispRootSquashMintsNothing", func(t *testing.T) { + conformance.RunParticipationGenerationWispRootSquashMintsNothing(t, ctx, fixture) + }) + t.Run("UnflaggedWispCreateMintsNothing", func(t *testing.T) { + conformance.RunParticipationGenerationUnflaggedWispCreateMintsNothing(t, ctx, fixture) + }) + t.Run("NoHistoryIssueCreateDeclaresParticipation", func(t *testing.T) { + conformance.RunParticipationGenerationNoHistoryIssueCreateDeclaresParticipation(t, ctx, fixture) + }) + t.Run("LegacyNoHistoryIssueStaysLegacy", func(t *testing.T) { + conformance.RunParticipationGenerationLegacyNoHistoryIssueStaysLegacy(t, ctx, fixture) + }) +} + +// TestParticipationGenerationFixtureKitIsWired is this leg's half of the +// explicit per-leg guardrail design §8.5 calls for in place of AST +// auto-discovery — see the dolt leg's TestParticipationGenerationFixtureKitIsWired +// for why the guardrail is needed even though TestEveryLegWiresEveryRoleContract's +// scan already enumerates and confirms wiring for every +// RunParticipationGenerationXxx entrypoint. +func TestParticipationGenerationFixtureKitIsWired(t *testing.T) { + skipUnlessEmbeddedDolt(t) + te := newTestEnv(t, "pgk") + fixture := newEmbeddedParticipationGenerationFixture(t, te, "pgk") + + if fixture.SetFlag == nil { + t.Error("ParticipationGenerationFixture.SetFlag is nil") + } + if fixture.Mutate == nil { + t.Error("ParticipationGenerationFixture.Mutate is nil") + } + if fixture.MutateExisting == nil { + t.Error("ParticipationGenerationFixture.MutateExisting is nil") + } + if fixture.CreateWisp == nil { + t.Error("ParticipationGenerationFixture.CreateWisp is nil") + } + if fixture.PromoteWisp == nil { + t.Error("ParticipationGenerationFixture.PromoteWisp is nil") + } + if fixture.MovePersistent == nil { + t.Error("ParticipationGenerationFixture.MovePersistent is nil") + } + if fixture.ClearWispFlag == nil { + t.Error("ParticipationGenerationFixture.ClearWispFlag is nil") + } + if fixture.SquashWispRoot == nil { + t.Error("ParticipationGenerationFixture.SquashWispRoot is nil") + } + if fixture.CreateUnflaggedWisp == nil { + t.Error("ParticipationGenerationFixture.CreateUnflaggedWisp is nil") + } + if fixture.CreateNoHistoryIssue == nil { + t.Error("ParticipationGenerationFixture.CreateNoHistoryIssue is nil") + } + if fixture.CurrentRevision == nil { + t.Error("ParticipationGenerationFixture.CurrentRevision is nil") + } + if fixture.VersionRowCount == nil { + t.Error("ParticipationGenerationFixture.VersionRowCount is nil") + } + if fixture.ParticipationGeneration == nil { + t.Error("ParticipationGenerationFixture.ParticipationGeneration is nil") + } + if fixture.InWispsTable == nil { + t.Error("ParticipationGenerationFixture.InWispsTable is nil") + } +} + +func newEmbeddedParticipationGenerationFixture(t *testing.T, te *testEnv, prefix string) conformance.ParticipationGenerationFixture { + t.Helper() + store := te.store + // Through the type assertion `bd serve` makes, never the concrete method + // set — same discipline as newEmbeddedDualWriteFixture above. + configurer, ok := any(store).(storage.VersionedHistoryConfigurer) + if !ok { + t.Fatalf("%T does not implement storage.VersionedHistoryConfigurer", store) + } + + kit := newEmbeddedRoleFixtureKit(te, prefix) + return conformance.ParticipationGenerationFixture{ + IssuePrefix: prefix, + SetFlag: func(ctx context.Context, enabled bool) error { + configurer.SetVersionedHistoryEnabled(enabled) + return nil + }, + Mutate: func(ctx context.Context, id string) error { + return store.CreateIssue(ctx, &types.Issue{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + }, "actor") + }, + MutateExisting: func(ctx context.Context, id string) error { + // A different value than Mutate gave it, not a re-assertion of the + // same title: DiscardNoopIssueUpdates would discard the latter + // before it ever reached the fence this contract is testing. + return store.UpdateIssue(ctx, id, map[string]any{"title": "updated-" + id}, "actor") + }, + CreateWisp: func(ctx context.Context, id string) error { + return store.CreateIssue(ctx, &types.Issue{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, Ephemeral: true, + }, "actor") + }, + PromoteWisp: func(ctx context.Context, id string) error { + return store.PromoteFromEphemeral(ctx, id, "actor") + }, + MovePersistent: func(ctx context.Context, id string) error { + // The guarded update bd update --persistent runs, so the move + // takes the update's one end-of-update mint rather than + // MoveIssuePersistenceInTx's own. + ops, err := embeddeddolt.NewIssueOperations(store) + if err != nil { + return err + } + result, err := ops.Update(ctx, publicops.UpdateRequest{Actor: "actor", IssueID: id, Patch: publicops.IssuePatch{ + Persistence: publicops.Field[publicops.PersistenceMode]{Set: true, Value: publicops.PersistenceModePersistent}, + }}) + if err == nil && !result.Changed { + err = fmt.Errorf("persistence move of %s reported no change", id) + } + return err + }, + ClearWispFlag: func(ctx context.Context, id string) error { + return store.UpdateIssue(ctx, id, map[string]any{"wisp": false}, "actor") + }, + SquashWispRoot: func(ctx context.Context, id string) error { + // bd mol squash's own shape: the root's close and its flag clear + // in the one transaction the squash commits. + return store.RunInTransaction(ctx, "squash "+id, func(tx storage.Transaction) error { + if err := tx.CloseIssue(ctx, id, "squashed", "actor", ""); err != nil { + return err + } + return tx.UpdateIssue(ctx, id, map[string]any{"wisp": false}, "actor") + }) + }, + CreateUnflaggedWisp: func(ctx context.Context, id string) error { + // Import's "wisp_plane" marker: the override, not the flags, puts + // the row in the wisps table. + wispPlane := true + return store.CreateIssuesWithFullOptions(ctx, []*types.Issue{{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + WispPlaneOverride: &wispPlane, + }}, "actor", storage.BatchCreateOptions{SkipPrefixValidation: true}) + }, + CreateNoHistoryIssue: func(ctx context.Context, id string) error { + // Import's promoted-no-history shape (bd-r9uce): the flag stays on + // the row, and the override pins it to the issues table. + durable := false + return store.CreateIssuesWithFullOptions(ctx, []*types.Issue{{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + NoHistory: true, WispPlaneOverride: &durable, + }}, "actor", storage.BatchCreateOptions{SkipPrefixValidation: true}) + }, + CurrentRevision: func(ctx context.Context, id string) (int64, error) { + var revision int64 + err := kit.QueryScalar(ctx, "SELECT current_revision FROM issues WHERE id = ?", []any{id}, &revision) + return revision, err + }, + VersionRowCount: func(ctx context.Context, id string) (int, error) { + var count int + err := kit.QueryScalar(ctx, "SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?", []any{id}, &count) + return count, err + }, + ParticipationGeneration: func(ctx context.Context, id string) (*int64, error) { + var gen sql.NullInt64 + if err := kit.QueryScalar(ctx, + "SELECT participation_generation FROM issues WHERE id = ?", []any{id}, &gen); err != nil { + return nil, err + } + if !gen.Valid { + return nil, nil + } + return &gen.Int64, nil + }, + InWispsTable: func(ctx context.Context, id string) (bool, error) { + var rows int + if err := kit.QueryScalar(ctx, "SELECT COUNT(*) FROM wisps WHERE id = ?", []any{id}, &rows); err != nil { + return false, err + } + return rows > 0, nil + }, + } +} diff --git a/internal/storage/issueops/create.go b/internal/storage/issueops/create.go index b699e9d86..97104ad32 100644 --- a/internal/storage/issueops/create.go +++ b/internal/storage/issueops/create.go @@ -97,6 +97,17 @@ type CreateIssueResult struct { // Set only on the path that would otherwise have minted, so the batch // mints for exactly the issues a singular create would have. versionDeferred bool + // isNew is whether this create actually inserted a new row, as opposed + // to resolving to an already-existing one. On the per-row path + // (CreateIssueInTxWithResult) it is InsertIssueIfNew's result; a row + // written by deferredCreates' multi-row INSERT reaches + // finishCreateIssueInTx directly and is always new, since only an id + // absent from both planes is deferrable. The participation_generation + // write-fence (design §16.2b) needs this to choose + // RecordVersionForCreateInTx over RecordVersionInTx; a batch that defers + // its mint (BatchContext.DeferVersionMint) carries it here since the + // per-issue isNew local is out of scope by the time the batch mints. + isNew bool } type persistedDependency struct { @@ -183,6 +194,7 @@ func prepareCreateIssueInTx(ctx context.Context, tx DBTX, bc *BatchContext, issu func finishCreateIssueInTx(ctx context.Context, tx DBTX, bc *BatchContext, issue *types.Issue, actor, issueTable, eventTable string, isNew bool) (CreateIssueResult, error) { var result CreateIssueResult result.markChanged(issueTable) + result.isNew = isNew // Reconcile the ephemeral lease row with the accepted issue state // (restore an imported lease / drop an orphaned one — see @@ -241,6 +253,10 @@ func finishCreateIssueInTx(ctx context.Context, tx DBTX, bc *BatchContext, issue // create has nothing after this point and mints here. if bc.DeferVersionMint { result.versionDeferred = true + } else if isNew { + if err := RecordVersionForCreateInTx(ctx, tx, issue.ID, actor); err != nil { + return result, err + } } else if err := RecordVersionInTx(ctx, tx, issue.ID, actor); err != nil { return result, err } @@ -320,6 +336,17 @@ func CreateIssuesInTxWithResult(ctx context.Context, tx DBTX, issues []*types.Is return CreateIssuesInTxWithContext(ctx, tx, bc, issues, actor) } +// deferredVersion carries a create's issue id and whether it was a genuinely +// new row (CreateIssueResult.isNew) from the per-issue loop in +// CreateIssuesInTxWithContext to that function's own final mint pass. The +// loop fills it from both of its write paths: a row CreateIssueInTxWithResult +// wrote on its own, and a row deferredCreates wrote in a multi-row INSERT and +// finished through finishCreateIssueInTx, which is always new. +type deferredVersion struct { + id string + isNew bool +} + // CreateIssuesInTxWithContext is CreateIssuesInTxWithResult with a // caller-supplied BatchContext. Callers that split config reads from row // writes across SQL sessions (doltTransaction's wisp tier) build the context @@ -365,11 +392,11 @@ func CreateIssuesInTxWithContext(ctx context.Context, tx DBTX, bc *BatchContext, result := CreateIssuesResult{} accepted := issues[:0:0] - var toVersion []string + var toVersion []deferredVersion record := func(issue *types.Issue, issueResult CreateIssueResult) { result.merge(issueResult.ChangedTables) if issueResult.versionDeferred { - toVersion = append(toVersion, issue.ID) + toVersion = append(toVersion, deferredVersion{id: issue.ID, isNew: issueResult.isNew}) } if issueResult.StaleRejected { return // stale snapshot: keep its deps out of the batch too @@ -462,8 +489,14 @@ func CreateIssuesInTxWithContext(ctx context.Context, tx DBTX, bc *BatchContext, // outgoing edge set. PersistDependenciesWithOptionsResult writes the edge // rows directly and mints nothing itself, so this is the one version per // issue at creation. Wisps are excluded by the seam. - for _, id := range toVersion { - if err := RecordVersionInTx(ctx, tx, id, actor); err != nil { + for _, dv := range toVersion { + if dv.isNew { + if err := RecordVersionForCreateInTx(ctx, tx, dv.id, actor); err != nil { + return CreateIssuesResult{}, err + } + continue + } + if err := RecordVersionInTx(ctx, tx, dv.id, actor); err != nil { return CreateIssuesResult{}, err } } diff --git a/internal/storage/issueops/execution.go b/internal/storage/issueops/execution.go index bdfdeb743..3c00bcde0 100644 --- a/internal/storage/issueops/execution.go +++ b/internal/storage/issueops/execution.go @@ -270,6 +270,7 @@ func executeUpdate(ctx context.Context, tx *sql.Tx, request publicops.UpdateRequ tables.Add("issues") } } + enteredIssuesPlane := false if attempt.Patch.Persistence.Set { current, err := GetIssueInTx(ctx, tx, attempt.IssueID) if err != nil { @@ -283,13 +284,21 @@ func executeUpdate(ctx context.Context, tx *sql.Tx, request publicops.UpdateRequ changedAny = true tables.Merge(moved.ChangedTables) } + enteredIssuesPlane = moved.EnteredIssuesPlane } // The one mint for this guarded update, LAST: after the claim, the row // write, the label and parent patches and the persistence move. Nothing // changed means nothing to version (the FR-2 no-op case), and a row that - // moved to the wisp plane is excluded by the seam itself. + // moved to the wisp plane is excluded by the seam itself. A persistence + // move that brought a wisp onto the issues plane makes this the record's + // first version, so it mints create-shaped (design §16.2b), the same as + // MoveIssuePersistenceInTx's own mint for that move. if changedAny { - if err := RecordVersionInTx(ctx, tx, attempt.IssueID, attempt.Actor); err != nil { + if enteredIssuesPlane { + if err := RecordVersionForCreateInTx(ctx, tx, attempt.IssueID, attempt.Actor); err != nil { + return publicops.UpdateResult{}, nil, err + } + } else if err := RecordVersionInTx(ctx, tx, attempt.IssueID, attempt.Actor); err != nil { return publicops.UpdateResult{}, nil, err } } diff --git a/internal/storage/issueops/journal_completeness_test.go b/internal/storage/issueops/journal_completeness_test.go index 5fa0c9451..9af2f61d1 100644 --- a/internal/storage/issueops/journal_completeness_test.go +++ b/internal/storage/issueops/journal_completeness_test.go @@ -209,6 +209,11 @@ var beadDMLExemptions = map[string]string{ // its own) — 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", } // journalExemptMutations are mutation paths that deliberately do NOT journal diff --git a/internal/storage/issueops/persistence.go b/internal/storage/issueops/persistence.go index 6a395c75c..18c7084f4 100644 --- a/internal/storage/issueops/persistence.go +++ b/internal/storage/issueops/persistence.go @@ -13,6 +13,13 @@ import ( type PersistenceMoveResult struct { Changed bool ChangedTables map[string]bool + // EnteredIssuesPlane reports that the move took the row out of the wisps + // table into issues. The issues row is new and a wisp never declares + // participation, so the record's next version is its first and must be + // minted create-shaped (design §16.2b). A same-plane repair does not set + // it: that row keeps its own participation. A caller that mints for the + // move itself, as ExecuteUpdate does, reads this to pick the entry point. + EnteredIssuesPlane bool } // MoveIssuePersistenceInTx moves a complete issue aggregate to the requested @@ -81,7 +88,11 @@ func moveIssuePersistenceInTx(ctx context.Context, tx DBTX, current *types.Issue return PersistenceMoveResult{}, err } // Versioned only on the issues plane; a wisp-plane normalize keeps - // the wisp exclusion. + // the wisp exclusion. Unlike a move, this mint stays update-shaped + // (design §16.2b): the row already lives on the issues plane and + // keeps its own participation_generation. A row created with the flag + // on proceeds; a legacy row stays legacy, since a repair is an + // ordinary write and must not promote it (R2.3). if mintVersion && !targetWisp { if err := RecordVersionInTx(ctx, tx, current.ID, actor); err != nil { return PersistenceMoveResult{}, err @@ -156,11 +167,15 @@ func moveIssuePersistenceInTx(ctx context.Context, tx DBTX, current *types.Issue // blocked-state maintenance has settled. A move INTO the issues plane // then mints the row's first version there, after its auxiliary copies // and retargeted edges exist; a move into the wisp plane mints nothing. + // That first mint is create-shaped (design §16.2b): the issues row was + // inserted above without participation_generation, which a wisp never + // declares, so the update-shaped entry would fence it as legacy. if err := RecordEventInTx(ctx, tx, EventUpdate, current.ID, actor); err != nil { return PersistenceMoveResult{}, err } + result.EnteredIssuesPlane = !targetWisp if mintVersion && !targetWisp { - if err := RecordVersionInTx(ctx, tx, current.ID, actor); err != nil { + if err := RecordVersionForCreateInTx(ctx, tx, current.ID, actor); err != nil { return PersistenceMoveResult{}, err } } diff --git a/internal/storage/issueops/promote.go b/internal/storage/issueops/promote.go index 59a01c02a..1d3a3d449 100644 --- a/internal/storage/issueops/promote.go +++ b/internal/storage/issueops/promote.go @@ -53,7 +53,8 @@ func PromoteFromEphemeralInTx(ctx context.Context, tx DBTX, id string, actor str if err := PrepareIssueForInsert(issue, types.CustomStatusNames(customStatuses), customTypes); err != nil { return fmt.Errorf("promote wisp to issues: %w", err) } - if _, _, err := InsertIssueIfNew(ctx, tx, "issues", issue, storage.BatchCreateOptions{}); err != nil { + isNew, _, err := InsertIssueIfNew(ctx, tx, "issues", issue, storage.BatchCreateOptions{}) + if err != nil { return fmt.Errorf("promote wisp to issues: %w", err) } @@ -134,9 +135,21 @@ func PromoteFromEphemeralInTx(ctx context.Context, tx DBTX, id string, actor str // maintenance has settled — and mint its first version: the promoted row // is new durable state on the issues plane (a wisp is never versioned, so // nothing precedes it), minted once after its labels, dependencies and - // comments have been copied across. + // comments have been copied across. That makes the mint create-shaped + // (design §16.2b): the issues row inserted above has no + // participation_generation, since a wisp never declares one, and the + // update-shaped entry would read that NULL as legacy and skip this mint + // and every later one. The exception is an id the issues plane already + // held (GH#4455 records such dual presence): GetIssueInTx read that row, + // the upsert resolved to it, and it keeps whatever participation it had, + // so the mint is update-shaped, as finishCreateIssueInTx's is for a create + // that resolved to an existing row. Stamping it would promote a legacy + // record (R2.3). if err := RecordEventInTx(ctx, tx, EventUpdate, id, actor); err != nil { return err } + if isNew { + return RecordVersionForCreateInTx(ctx, tx, id, actor) + } return RecordVersionInTx(ctx, tx, id, actor) } diff --git a/internal/storage/issueops/row_lock_guard_test.go b/internal/storage/issueops/row_lock_guard_test.go index 077269263..f7bc0dc13 100644 --- a/internal/storage/issueops/row_lock_guard_test.go +++ b/internal/storage/issueops/row_lock_guard_test.go @@ -141,19 +141,28 @@ 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) 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. - // RecordVersionInTx's own `UPDATE issues SET current_revision = ?` only - // advances a denormalized pointer to the issue_versions row it just - // inserted; it deliberately does not touch 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", + // recordVersionInTx (version_history.go) is the private seam both public + // entry points — RecordVersionInTx (update-shaped) and + // 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 + // 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", } // TestAllIssueRowWritesStampRowLock is the load-bearing completeness guard for diff --git a/internal/storage/issueops/version_completeness_test.go b/internal/storage/issueops/version_completeness_test.go index ae3448df4..3b9b08dbe 100644 --- a/internal/storage/issueops/version_completeness_test.go +++ b/internal/storage/issueops/version_completeness_test.go @@ -33,7 +33,8 @@ import ( // named helper (mintDependencyVersion, addLabelInTx, updateIssueInTx, ...) // whose mint it did not switch off — see versionMintGate. var versionMintHelpers = map[string]bool{ - "RecordVersionInTx": true, + "RecordVersionInTx": true, + "RecordVersionForCreateInTx": true, } // versionMintGate names the boolean parameter the constituent helpers @@ -151,6 +152,213 @@ var versionedEntryPoints = []string{ "ApplyBatchInTx", } +// versionCreateShapedMintHelper is the create-shaped entry to the seam +// (design §16.2b). It stamps participation_generation instead of checking it, +// so it is right only for a row that is brand new on the issues plane, and +// wrong anywhere else: an update-shaped mutation that reached it would stamp +// a legacy row and so promote it, which R2.3 forbids an ordinary write. +var versionCreateShapedMintHelper = map[string]bool{"RecordVersionForCreateInTx": true} + +// versionUpdateShapedMintHelper is the update-shaped entry: it reads +// participation_generation and mints nothing for a legacy (NULL) row. +var versionUpdateShapedMintHelper = map[string]bool{"RecordVersionInTx": true} + +// versionCreateShapedMintSites are the PURE create-shaped mint sites: every +// row each one mints for is new on the issues plane, so each must call +// RecordVersionForCreateInTx itself and must never call RecordVersionInTx. +// None is left today. PromoteFromEphemeralInTx was one until it learned that +// the issues plane can already hold the id it promotes; it is listed in +// versionDualShapeMintSites now. +var versionCreateShapedMintSites = []string{} + +// versionDualShapeMintSites choose the entry per row at run time: create-shaped +// on the branch where the row is new on the issues plane, update-shaped on the +// branch where it already lived there. Each branch is a common path, so each +// site must call BOTH entries itself. Reaching either one through a delegate +// is not enough: executeUpdate runs its persistence move with +// mintVersion=false, and a batch create switches finishCreateIssueInTx's own +// mint off at run time (DeferVersionMint), so the call graph would credit each +// with mints its constituents never perform. +// +// A site that calls only one entry has had a branch switched to the other. If +// the update-shaped branch now calls the create-shaped entry, an ordinary +// write stamps a legacy row and promotes it (R2.3). If the create-shaped +// branch now calls the update-shaped entry, the fence reads the new row's NULL +// as legacy, and the record is never versioned. +// +// One production dual-shape site lives outside this package, where this +// guard's parse (journalscan.ParsePackage(".")) cannot list it: domain/db's +// issueSQLRepositoryImpl.Insert. Its CreateOnly branch is create-shaped. Its +// upsert, the create that is not CreateOnly, is create-shaped only when it +// inserted a new issues row; it is update-shaped when the issues table +// already held the id, and for every wisps-table insert. The uow leg's +// TestParticipationGenerationUpsertCreate holds those upsert branches at run +// time instead. +var versionDualShapeMintSites = map[string]string{ + "finishCreateIssueInTx": "a singular create mints create-shaped when it inserted the row and update-shaped when it resolved to an existing one", + "CreateIssuesInTxWithContext": "a batch create's deferred mint pass is create-shaped for a row the batch inserted and update-shaped for an existing row it resolved to", + "moveIssuePersistenceInTx": "a move out of the wisps table is create-shaped; the same-plane normalize (bd update --persistent repairing an issues-plane row's flags in place) is update-shaped", + "executeUpdate": "the guarded update's EnteredIssuesPlane branch is create-shaped; every other change it mints for is update-shaped", + "PromoteFromEphemeralInTx": "a wisp promoted onto the issues plane mints create-shaped; when the issues plane already held the id (dual presence, GH#4455) the upsert resolved to that row and the mint is update-shaped", +} + +// versionCreateShapedEntryPoints are the entry points whose every mint is +// create-shaped, so each must reach RecordVersionForCreateInTx. +// deferredCreates.flush (#7205's multi-row INSERT path) is one: it hands +// finishCreateIssueInTx isNew=true for every row. The call graph cannot read +// that literal, so flush still reaches the update-shaped entry through +// finishCreateIssueInTx, and it is held only to the create half. +var versionCreateShapedEntryPoints = []string{ + "deferredCreates.flush", +} + +// versionDualShapeEntryPoints reach both entries by design. Each delegates to +// a dual-shape mint site, or composes create- and update-shaped mutations in +// one call, so it must reach both and is held to neither half of the split on +// its own. The dual-shape mint sites above pin which branch calls which entry. +var versionDualShapeEntryPoints = map[string]string{ + "CreateIssueInTx": "delegates to finishCreateIssueInTx", + "CreateIssueInTxWithResult": "delegates to finishCreateIssueInTx", + "CreateIssuesInTx": "delegates to CreateIssuesInTxWithContext", + "CreateIssuesInTxWithResult": "delegates to CreateIssuesInTxWithContext", + "CreateIssuesInTxWithContext": "a dual-shape mint site itself", + "MoveIssuePersistenceInTx": "delegates to moveIssuePersistenceInTx with its mint on", + "PromoteFromEphemeralInTx": "a dual-shape mint site itself", + "ExecuteCreate": "delegates to the create path, which ends in finishCreateIssueInTx", + "ExecuteCreateBatch": "delegates to CreateIssuesInTxWithContext", + "ExecuteUpdate": "delegates to executeUpdate", + "ApplyBatchInTx": "batch apply runs create items and update items in one transaction", +} + +func versionShapedMints(t *testing.T) (fns map[string]*journalscan.FuncInfo, createShaped, updateShaped map[string]bool) { + t.Helper() + fns, err := journalscan.ParsePackage(".") + if err != nil { + t.Fatalf("parse package: %v", err) + } + edges := versionMintEdges(fns) + createShaped = journalscan.Fixpoint(fns, + func(f *journalscan.FuncInfo) bool { return f.CallsAnyOf(versionCreateShapedMintHelper) }, edges) + updateShaped = journalscan.Fixpoint(fns, + func(f *journalscan.FuncInfo) bool { return f.CallsAnyOf(versionUpdateShapedMintHelper) }, edges) + return fns, createShaped, updateShaped +} + +// TestCreateShapedEntryPointsMintCreateShaped pins the create half of the +// shape split: each pure create-shaped mint site calls +// RecordVersionForCreateInTx itself and never RecordVersionInTx, and every +// pure create-shaped entry point reaches it. If one of them falls back to +// RecordVersionInTx, the fence finds the new row's participation_generation +// NULL, skips the mint, and the record is never versioned. +// TestEveryVersionedEntryPointMints cannot see that, because +// RecordVersionInTx satisfies it. +func TestCreateShapedEntryPointsMintCreateShaped(t *testing.T) { + fns, createShaped, _ := versionShapedMints(t) + for _, site := range versionCreateShapedMintSites { + f, defined := fns[site] + if !defined { + t.Errorf("create-shaped mint site %q not found in issueops — was it renamed? update versionCreateShapedMintSites", site) + continue + } + if !f.CallsAnyOf(versionCreateShapedMintHelper) { + t.Errorf("create-shaped mint site %q does not call RecordVersionForCreateInTx itself; the row it mints for is new on the issues plane, so an update-shaped mint there is fenced as legacy", site) + } + if f.CallsAnyOf(versionUpdateShapedMintHelper) { + t.Errorf("create-shaped mint site %q calls RecordVersionInTx; every row it mints for is new on the issues plane, so that mint is fenced as legacy — or, if it now also mints for an existing row, list it in versionDualShapeMintSites", site) + } + } + for _, entry := range versionCreateShapedEntryPoints { + if _, defined := fns[entry]; !defined { + t.Errorf("create-shaped entry point %q not found in issueops — was it renamed? update versionCreateShapedEntryPoints", entry) + continue + } + if !createShaped[entry] { + t.Errorf("create-shaped entry point %q does not reach RecordVersionForCreateInTx, directly or transitively", entry) + } + } +} + +// TestDualShapeMintSitesCallBothEntries pins the dual-shape sites, the ones +// the update half below has to skip. Each calls RecordVersionInTx and +// RecordVersionForCreateInTx itself, so switching either branch to the +// other entry fails here. Each dual-shape entry point reaches both, so a +// delegate that stopped minting one shape is not silently skipped by the +// update half. +func TestDualShapeMintSitesCallBothEntries(t *testing.T) { + fns, createShaped, updateShaped := versionShapedMints(t) + for _, site := range sortedShapeKeys(versionDualShapeMintSites) { + if versionDualShapeMintSites[site] == "" { + t.Errorf("dual-shape mint site %s has an empty reason", site) + } + f, defined := fns[site] + if !defined { + t.Errorf("dual-shape mint site %q not found in issueops — was it renamed? update versionDualShapeMintSites", site) + continue + } + if !f.CallsAnyOf(versionCreateShapedMintHelper) { + t.Errorf("dual-shape mint site %q no longer calls RecordVersionForCreateInTx itself; its branch for a row new on the issues plane (%s) now fences that row as legacy, and the record is never versioned", site, versionDualShapeMintSites[site]) + } + if !f.CallsAnyOf(versionUpdateShapedMintHelper) { + t.Errorf("dual-shape mint site %q no longer calls RecordVersionInTx itself; its branch for a row already on the issues plane (%s) now stamps participation_generation and promotes a legacy record (R2.3)", site, versionDualShapeMintSites[site]) + } + } + for _, entry := range sortedShapeKeys(versionDualShapeEntryPoints) { + if versionDualShapeEntryPoints[entry] == "" { + t.Errorf("dual-shape entry point %s has an empty reason", entry) + } + if _, defined := fns[entry]; !defined { + t.Errorf("dual-shape entry point %q not found in issueops — was it renamed? update versionDualShapeEntryPoints", entry) + continue + } + if !createShaped[entry] { + t.Errorf("dual-shape entry point %q no longer reaches RecordVersionForCreateInTx — list it as update-shaped instead (remove it from versionDualShapeEntryPoints)", entry) + } + if !updateShaped[entry] { + t.Errorf("dual-shape entry point %q no longer reaches RecordVersionInTx — list it in versionCreateShapedEntryPoints instead", entry) + } + } +} + +// TestUpdateShapedEntryPointsNeverMintCreateShaped pins the update half: +// every versioned entry point that is neither create-shaped nor dual-shape +// must not reach RecordVersionForCreateInTx, so no ordinary write of an +// existing row can stamp it out of legacy. The update-shaped branch inside a +// dual-shape site is TestDualShapeMintSitesCallBothEntries's to pin. +func TestUpdateShapedEntryPointsNeverMintCreateShaped(t *testing.T) { + _, createShaped, _ := versionShapedMints(t) + create := map[string]bool{} + for _, entry := range versionCreateShapedEntryPoints { + create[entry] = true + } + var checked int + for _, entry := range versionedEntryPoints { + if create[entry] { + continue + } + if _, dual := versionDualShapeEntryPoints[entry]; dual { + continue + } + checked++ + if createShaped[entry] { + t.Errorf("update-shaped entry point %q reaches RecordVersionForCreateInTx, so it can stamp participation_generation on an existing row and promote a legacy record (R2.3) — mint it through RecordVersionInTx, or list it in versionCreateShapedEntryPoints or versionDualShapeEntryPoints if a row it mints for is new on the issues plane", entry) + } + } + if checked == 0 { + t.Fatal("no update-shaped entry point was checked — versionedEntryPoints or the shape lists changed; the guard is not actually running") + } +} + +// sortedShapeKeys returns m's keys in order, so the shape guards report in a +// stable order. +func sortedShapeKeys(m map[string]string) []string { + keys := make([]string, 0, len(m)) + for k := range m { + keys = append(keys, k) + } + sort.Strings(keys) + return keys +} + // 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 @@ -223,7 +431,8 @@ var versionExemptions = map[string]string{ // the seam itself: its UPDATE issues SET current_revision is the // 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", + "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", } // versionNeverMints pins the deliberate NOT-versioned rulings from the other diff --git a/internal/storage/issueops/version_history.go b/internal/storage/issueops/version_history.go index ff579fbd6..cd2ae2319 100644 --- a/internal/storage/issueops/version_history.go +++ b/internal/storage/issueops/version_history.go @@ -21,13 +21,15 @@ import ( // BeginTx, so enabling history on one store instance cannot turn it on for // any other sharing the process. // -// RecordVersionInTx is the single seam both direct-SQL legs (dolt, -// embeddeddolt) and the domain/db package (used by uow) call through, from -// inside the same already-short-circuited functions that call -// RecordEventInTx — every accepted mutation of an issue's durable state -// (create, update, close, reopen, claim, release, lease reclaim, defer wake, -// label add/remove, dependency add/remove, promote, persistence move) mints -// exactly one row, as its LAST durable-state write; a no-op mints none. A +// RecordVersionInTx (and its create-shaped sibling, RecordVersionForCreateInTx +// — design §16.2b's write fence, see that function's own doc) is the single +// seam both direct-SQL legs (dolt, embeddeddolt) and the domain/db package +// (used by uow) call through, from inside the same already-short-circuited +// functions that call RecordEventInTx — every accepted mutation of an +// issue's durable state (create, update, close, reopen, claim, release, +// lease reclaim, defer wake, label add/remove, dependency add/remove, +// promote, persistence move) mints exactly one row, as its LAST +// durable-state write; a no-op mints none. A // mutation DiscardNoopIssueUpdates has already discarded never reaches either // seam; the label and dependency helpers, which that filter does not cover, // gate on their own inserted/deleted row instead (an idempotent re-add or an @@ -64,17 +66,20 @@ import ( // RunDualWrite* contract cases exclude concurrent writers, so no test // speaks to it. Tracked as gastownhall/beads#6379 (item 4). // -// MINT COST, deferred deliberately: each mint adds ~5-6 round-trips inside +// MINT COST, deferred deliberately: each mint adds ~6-7 round-trips inside // the write transaction (the GetIssueInTx snapshot and its label hydration, -// the dependency load, the store_epoch read, the MAX(revision) scan, the -// version INSERT, the current_revision UPDATE), and the MAX(revision) scan -// grows with an issue's history depth -- on paths that previously ran one or -// two statements, so it lengthens write-lock hold time. Harmless while the -// flag is off, which is every build so far. Before any phase enables it, seed -// the next ordinal from the current_revision the snapshot above already read -// in this transaction and retire the aggregate scan -- a natural pairing with -// the version_id UUID swap, since that swap is what makes the ordinal stop -// being the key. Tracked as gastownhall/beads#6379 alongside item 4. +// the participation_generation fence read, the dependency load, the +// store_epoch read, the MAX(revision) scan, the version INSERT, the +// current_revision UPDATE), and the MAX(revision) scan grows with an issue's +// history depth -- on paths that previously ran one or two statements, so it +// lengthens write-lock hold time. Harmless while the flag is off, which is +// every build so far. Before any phase enables it, seed the next ordinal from +// the row's current_revision and retire the aggregate scan -- a natural +// pairing with the version_id UUID swap, since that swap is what makes the +// ordinal stop being the key. The snapshot does not read current_revision; +// the fence read can select it beside participation_generation, so the seed +// costs no extra round-trip. Tracked as gastownhall/beads#6379 alongside +// item 4. var versionedHistoryTransactions sync.Map // map[DBTX]bool; entries live for one transaction @@ -208,8 +213,9 @@ func canonicalDurableState(issue any) ([]byte, error) { // 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 -// when issueID resolves to a wisp: wisps carry current_revision for shape -// parity only and are never versioned this phase (design FR-8). IsWisp is +// when issueID resolves to a wisp -- a row the wisps table holds, whatever +// its flags say: wisps carry current_revision for shape parity only and are +// never versioned this phase (design FR-8). IsWisp is // Ephemeral || NoHistory, so a promoted no-history bead -- a durable // issues-plane row with NoHistory=true -- is also never versioned; that is // what no-history means, not an FR-8 wisp rule, and the write-path doc's @@ -223,7 +229,42 @@ func canonicalDurableState(issue any) ([]byte, error) { // version row's attribution — "" when the mutation path genuinely has none, // matching RecordEventInTx's own convention. It also drives // attribution_status via attributionStatusForActor. +// +// This is the UPDATE-shaped entry point: design §16.2b's write fence. A +// record whose participation_generation is NULL is legacy — never +// positively promoted — and an update-shaped mutation against it mints +// nothing, neither half of this seam's write (no issue_versions row, no +// current_revision bump). A record that already carries a non-NULL +// participation_generation proceeds normally. Use RecordVersionForCreateInTx +// 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. func RecordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string) error { + return recordVersionInTx(ctx, tx, issueID, actor, false) +} + +// RecordVersionForCreateInTx is RecordVersionInTx's create-shaped sibling +// (design §16.2b). The write fence does not apply to a brand-new row, so +// instead of checking participation_generation, this stamps it — sourced +// from store_epoch.epoch, the same source the fence reads — as part of the +// row's first mint, whenever versioned history is enabled. A create with the +// flag off never reaches the stamp (this whole seam no-ops while the flag is +// off, same as RecordVersionInTx), leaving the column NULL — indistinguishable +// from a true legacy row (FR-7). A wisp arriving on the issues plane, by +// promotion or a persistence move out of the wisps table, mints through here +// too: its issues row is just as new, and a wisp never declares +// participation (FR-8). A new issues-table row that carries NoHistory (or a +// stray Ephemeral) is stamped but not versioned: no-history keeps it out of +// history for now, but it was created with the flag on, so it is not +// legacy once that flag is repaired. A row the wisps table holds mints and +// stamps nothing, whatever its flags say: it has no issues row to stamp, and +// 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 } @@ -232,7 +273,71 @@ func RecordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string) erro 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 { + 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. + var participationGeneration sql.NullInt64 + if err := tx.QueryRowContext(ctx, + "SELECT participation_generation FROM issues WHERE id = ?", issueID, + ).Scan(&participationGeneration); err != nil { + if errors.Is(err, sql.ErrNoRows) { + return nil + } + return fmt.Errorf("versioned history: read participation_generation for %s: %w", issueID, err) + } if IsWisp(issue) { + // Only a create-shaped call gets here: an issues-table row that + // carries NoHistory (or a stray Ephemeral). It is not versioned while + // its flags say so, so this mints nothing. But it is brand new on the + // issues plane with the flag on, so it is not legacy, and the create + // still declares its participation. Import keeps a promoted + // no-history row on the issues plane exactly this way (bd-r9uce). + // When bd update --persistent later repairs the flag in place, that + // repair mints update-shaped: through the guarded update's one + // end-of-update mint (executeUpdate) on dolt and embeddeddolt, or + // MoveIssuePersistenceInTx's own on the unit-of-work path. Left NULL + // here, the fence would read the row as legacy for good. Same source + // and same updated_at rule as the stamp at the end of this function. + epoch, err := readStoreEpochInTx(ctx, tx) + if err != nil { + return err + } + if _, err := tx.ExecContext(ctx, + "UPDATE issues SET participation_generation = ?, updated_at = updated_at WHERE id = ?", + epoch, issueID, + ); err != nil { + return fmt.Errorf("versioned history: stamp participation_generation for %s: %w", issueID, err) + } + return nil + } + if !isCreate && !participationGeneration.Valid { return nil } @@ -261,21 +366,9 @@ func RecordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string) erro } issue.Dependencies = deps[issueID] - // store_epoch is one shared row (id = 1) that every minting transaction - // reads. Read first and seed only when the row is absent, so the seed - // INSERT happens once per store rather than once per mint: an INSERT IGNORE - // on every mint put that shared row into every write transaction's - // footprint for nothing. - var epoch int - err = tx.QueryRowContext(ctx, "SELECT epoch FROM store_epoch WHERE id = 1").Scan(&epoch) - if errors.Is(err, sql.ErrNoRows) { - if _, seedErr := tx.ExecContext(ctx, "INSERT IGNORE INTO store_epoch (id, epoch) VALUES (1, 1)"); seedErr != nil { - return fmt.Errorf("versioned history: seed store epoch: %w", seedErr) - } - err = tx.QueryRowContext(ctx, "SELECT epoch FROM store_epoch WHERE id = 1").Scan(&epoch) - } + epoch, err := readStoreEpochInTx(ctx, tx) if err != nil { - return fmt.Errorf("versioned history: read store epoch: %w", err) + return err } var newRevision int64 @@ -301,6 +394,22 @@ func RecordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string) erro return fmt.Errorf("versioned history: insert version row for %s: %w", issueID, err) } + if isCreate { + // 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 + // above for this same transaction's version row. Setting updated_at to + // itself keeps the column's ON UPDATE CURRENT_TIMESTAMP clause from + // replacing the timestamp the row was created with, which an import + // supplies. + if _, err := tx.ExecContext(ctx, + "UPDATE issues SET current_revision = ?, participation_generation = ?, updated_at = updated_at WHERE id = ?", + newRevision, epoch, issueID, + ); err != nil { + return fmt.Errorf("versioned history: advance current_revision for %s: %w", issueID, err) + } + return nil + } if _, err := tx.ExecContext(ctx, "UPDATE issues SET current_revision = ? WHERE id = ?", newRevision, issueID, ); err != nil { @@ -308,3 +417,26 @@ func RecordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string) erro } return nil } + +// readStoreEpochInTx reads store_epoch.epoch as of tx, the source of both a +// version row's epoch and a participation_generation stamp. +// +// store_epoch is one shared row (id = 1) that every minting transaction +// reads. Read first and seed only when the row is absent, so the seed +// INSERT happens once per store rather than once per mint: an INSERT IGNORE +// on every mint put that shared row into every write transaction's +// footprint for nothing. +func readStoreEpochInTx(ctx context.Context, tx DBTX) (int, error) { + var epoch int + err := tx.QueryRowContext(ctx, "SELECT epoch FROM store_epoch WHERE id = 1").Scan(&epoch) + if errors.Is(err, sql.ErrNoRows) { + if _, seedErr := tx.ExecContext(ctx, "INSERT IGNORE INTO store_epoch (id, epoch) VALUES (1, 1)"); seedErr != nil { + return 0, fmt.Errorf("versioned history: seed store epoch: %w", seedErr) + } + err = tx.QueryRowContext(ctx, "SELECT epoch FROM store_epoch WHERE id = 1").Scan(&epoch) + } + if err != nil { + return 0, fmt.Errorf("versioned history: read store epoch: %w", err) + } + return epoch, nil +} diff --git a/internal/storage/leg_contract_wiring_test.go b/internal/storage/leg_contract_wiring_test.go index 7306fbc59..78ac5200b 100644 --- a/internal/storage/leg_contract_wiring_test.go +++ b/internal/storage/leg_contract_wiring_test.go @@ -120,6 +120,11 @@ func init() { "RunLifecycleUpdateExpectedVersionSingleWinnerWithDisjointColumnsUnderConcurrency": issuePatchFieldsNotOnUpdateWireWaiverReason, "RunLifecycleUpdateExpectedVersionSingleWinnerAcrossUpdateAndCloseUnderConcurrency": issuePatchFieldsNotOnUpdateWireWaiverReason, + + "RunParticipationGenerationNoHistoryIssueCreateDeclaresParticipation": participationGenerationWireGapWaiverReason, + "RunParticipationGenerationUnflaggedWispCreateMintsNothing": participationGenerationWireGapWaiverReason, + "RunParticipationGenerationWispFlagClearMintsNothing": participationGenerationWireGapWaiverReason, + "RunParticipationGenerationWispRootSquashMintsNothing": participationGenerationWireGapWaiverReason, }) } @@ -333,6 +338,41 @@ const issuePatchFieldsNotOnUpdateWireWaiverReason = "PENDING, not permanent (tra "closing the rest of the gap means publishing spec_id and owner on IssuePatchBody, which is a wire change " + "to the write role (S4b), not something this leg's test wiring can bind around today" +// participationGenerationWireGapWaiverReason covers the four +// ParticipationGenerationFixture cases whose mutation has no form on this +// wire. The other cases run on the http leg +// (internal/httpclient/served_participation_generation_test.go): the client +// creates and updates, and the fixture flips the reference store's flag and +// reads its raw columns, as served_dualwrite_history_test.go does. +// +// Each waived case needs a mutation the client cannot send: +// - WispFlagClearMintsNothing clears a wisp's flag IN PLACE with the untyped +// UpdateIssue map {"wisp": false}. storage.UpdateIssue is on this client's +// unsupported allowlist (D8), and IssuePatch has no in-place flag member: +// its Persistence member moves the row between tables, which the +// wisp-arrival cases already run here. +// - WispRootSquashMintsNothing runs the close and that flag clear in ONE +// transaction. RunInTransaction is on the unsupported allowlist too, and +// the wire publishes no squash operation. +// - UnflaggedWispCreateMintsNothing creates an unflagged row in the wisps +// table through import's WispPlaneOverride = &true. The wire drops that +// member (roleIgnoredCreateIssueMembers in batchcreator.go), so an +// unflagged create lands in the issues table. +// - NoHistoryIssueCreateDeclaresParticipation has a no-history ISSUES-table +// create as its subject (WispPlaneOverride = &false). With that member +// dropped, a client create carrying no_history routes to the wisps table +// (TableRouting). Seeding the row through the reference store instead +// would make the create under test the store's own, a property of the +// store the server happens to share a process with, never of the client. +const participationGenerationWireGapWaiverReason = "PENDING, not permanent (no slice tracks it yet; each case runs " + + "on this leg once the wire publishes its mutation: an in-place wisp flag clear, a squash operation, or a create " + + "that names its table plane the way import's WispPlaneOverride does): " + + "the mutation this case needs has no form on the http wire: " + + "an in-place wisp flag clear is an untyped UpdateIssue map and the squash a RunInTransaction, both on this " + + "client's unsupported allowlist (D8), and IssuePatch.Persistence moves the row rather than clearing the flag in " + + "place; an unflagged wisps-table create and a no-history issues-table create both need WispPlaneOverride, " + + "which the wire drops (roleIgnoredCreateIssueMembers), so the first lands in issues and the second in wisps" + // TestEveryLegWiresEveryRoleContract fails when a backend leg skips a role // contract the conformance package exports. // diff --git a/internal/storage/schema/BUILD.bazel b/internal/storage/schema/BUILD.bazel index 57e38358c..09be66e8f 100644 --- a/internal/storage/schema/BUILD.bazel +++ b/internal/storage/schema/BUILD.bazel @@ -118,6 +118,8 @@ go_library( "migrations/ignored/0026_dep_rekey_dedup_marker.up.sql", "migrations/ignored/0027_add_wisps_current_revision.up.sql", "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", ], importpath = "github.com/steveyegge/beads/internal/storage/schema", visibility = ["//:__subpackages__"], @@ -151,6 +153,7 @@ go_test( "migration_0067_versioned_beads_test.go", "migration_0068_add_attribution_status_test.go", "migration_0069_datetime_precision_test.go", + "migration_0070_add_participation_generation_test.go", "migration_body_drain_test.go", "migration_freeze_test.go", "migration_watchdog_test.go", diff --git a/internal/storage/schema/cli_migrations.go b/internal/storage/schema/cli_migrations.go index ade8014c6..8b595c17a 100644 --- a/internal/storage/schema/cli_migrations.go +++ b/internal/storage/schema/cli_migrations.go @@ -157,6 +157,17 @@ func cliCompatibleMigrationSQL(name, sqlText string) string { // 0067 creates both as plain DATETIME and 0068 retypes only // durable_state -- so both of 0069's MODIFYs always fire here too. return cliMigration0069WidenIssueVersionsDatetimePrecision + case "0070_add_participation_generation.up.sql": + // Direct DDL for the same reason as 0067: the source migration's + // PREPARE guards (INFORMATION_SCHEMA probes) are what make the raw + // .up.sql idempotent when replayed onto an already-migrated store, + // and the 2.2.x CLI no-ops a prepared ADD COLUMN. issues and wisps + // both exist by this point in the series (0067 creates the versioned + // columns on both) and neither carries participation_generation yet, + // so both of 0070's ALTERs always fire on a fresh bundle -- this + // substitute ALTERs wisps directly, the same as 0067's, so it + // belongs on cliSubstituteAssumesWispTables too. + return cliMigration0070AddParticipationGeneration default: return sqlText } @@ -193,6 +204,11 @@ func cliSubstituteAssumesWispTables(name string) bool { // cliMigration0067AddVersionedBeadsSchema drops the source's // @wisps_cr_needs_add table-exists guard and ALTERs wisps directly. return true + case "0070_add_participation_generation.up.sql": + // cliMigration0070AddParticipationGeneration drops the source's + // @wisps_pg_needs_add table-exists guard and ALTERs wisps directly, + // the same shape 0067's override already uses for current_revision. + return true default: return false } @@ -290,6 +306,18 @@ ALTER TABLE issue_versions MODIFY COLUMN durable_state LONGBLOB;` const cliMigration0069WidenIssueVersionsDatetimePrecision = `ALTER TABLE issue_versions MODIFY COLUMN change_at DATETIME(6) NOT NULL; ALTER TABLE issue_versions MODIFY COLUMN removed_at DATETIME(6);` +// cliMigration0070AddParticipationGeneration is 0070 with its two guarded +// PREPARE blocks replaced by the direct ALTERs they would run on a fresh +// database: participation_generation BIGINT NULL on issues, mirrored +// inertly on wisps (design §16.3 steps 4-5, be-dt74u amendment, be-h89oq). +// issues and wisps both exist by this point in the series (0067 creates the +// versioned columns on both) and neither carries participation_generation +// yet, so both ALTERs always fire on a fresh bundle -- this substitute +// ALTERs wisps directly, the same as 0067's, so it belongs on +// cliSubstituteAssumesWispTables too. +const cliMigration0070AddParticipationGeneration = `ALTER TABLE issues ADD COLUMN participation_generation BIGINT NULL; +ALTER TABLE wisps ADD COLUMN participation_generation BIGINT NULL;` + const cliMigration0041SplitDependenciesTarget = `DELETE FROM dolt_nonlocal_tables; CALL DOLT_COMMIT('-Am', 'disable nonlocal tables for fk migrations'); SET FOREIGN_KEY_CHECKS = 0; diff --git a/internal/storage/schema/migration_0069_datetime_precision_test.go b/internal/storage/schema/migration_0069_datetime_precision_test.go index bc1883fa6..ea6bcc8cd 100644 --- a/internal/storage/schema/migration_0069_datetime_precision_test.go +++ b/internal/storage/schema/migration_0069_datetime_precision_test.go @@ -39,21 +39,6 @@ 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 pins the real next free slot this -// migration claims, superseding 0068's own version of this test -// (LatestVersion() moved from 68 to 69 the moment this migration file was -// added). Deliberately a hardcoded literal for the same reason 0067's and -// 0068's were: LatestVersion() drifting to 69 for the wrong reason (an -// unrelated migration landing first) should still be caught by this test -// failing to explain why 69 is datetime-precision-shaped, which the CLI test -// below checks. -func TestLatestVersionIncludesMigration0069(t *testing.T) { - const want = 69 - if got := LatestVersion(); got != want { - t.Fatalf("LatestVersion() = %d, want %d (issue_versions change_at/removed_at DATETIME(6) migration slot claimed by be-hs42e.8)", got, want) - } -} - // TestMigration0069WidensChangeAtAndRemovedAtPrecision is the pure-Go, // DB-independent half of the pin, mirroring // TestMigration0068AddsAttributionStatus's shape: it checks the frozen diff --git a/internal/storage/schema/migration_0070_add_participation_generation_test.go b/internal/storage/schema/migration_0070_add_participation_generation_test.go new file mode 100644 index 000000000..e6d5a7369 --- /dev/null +++ b/internal/storage/schema/migration_0070_add_participation_generation_test.go @@ -0,0 +1,153 @@ +package schema + +import ( + "os" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/testutil" +) + +// Migration 0070 (design §16.3 steps 4-5, be-dt74u amendment, be-h89oq) adds +// a nullable participation_generation to issues, mirrored inertly on wisps. +// NULL means legacy-unmigrated; any non-NULL is a positive declaration +// sourced from store_epoch.epoch. RecordVersionInTx's write fence (design +// §16.2b, in internal/storage/issueops/version_history.go) reads this column +// to decide whether an update-shaped mutation against a legacy record mints +// a version row at all -- a create-shaped mutation stamps a fresh value +// instead. No backfill: NULL is the correct default for every existing row, +// on both planes. +// +// It was first drafted as steps 4-5 appended to the then-unmerged 0068; +// be-v33pa's own attribution_status-only version of 0068 shipped to main +// first (2026-09-28 15:46Z), which froze that file, so these steps have +// their own slot here (mayor ruling 2026-09-29 on tracker be-waare) -- the +// same reason 0069 got its own slot rather than landing as 0068's step 8. +// +// wisps.participation_generation is guarded on the wisps table existing as +// well as the column, mirroring 0067's wisps.current_revision guard exactly +// (see that migration's header): wisps is dolt-ignored/clone-local, so a +// clone that never synced the local wisp tables must no-op rather than +// abort. The clone-local twin for a workspace that never synced the wisps +// table at all is ignored/0028_add_wisps_participation_generation.up.sql. +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) + } +} + +// TestMigration0070AddsParticipationGeneration is the pure-Go, DB-independent +// half of the pin, mirroring TestMigration0069WidensChangeAtAndRemovedAtPrecision's +// shape: it checks the frozen migration bytes and the CLI-bundle override +// text directly, no `dolt` binary required. +func TestMigration0070AddsParticipationGeneration(t *testing.T) { + upSQL, err := MigrationSQL(migration0070Up) + if err != nil { + t.Fatalf("MigrationSQL(%s) error = %v, want the migration file to exist", migration0070Up, err) + } + for _, want := range []string{ + "ALTER TABLE issues ADD COLUMN participation_generation BIGINT NULL", + "@issues_pg_needs_add", + "ALTER TABLE wisps ADD COLUMN participation_generation BIGINT NULL", + "@wisps_pg_needs_add", + } { + if !strings.Contains(upSQL, want) { + t.Errorf("0070 up migration missing %q (design §16.3 steps 4-5)\nfull SQL:\n%s", want, upSQL) + } + } + if n := strings.Count(upSQL, "COLUMN_NAME = 'participation_generation'"); n != 2 { + t.Errorf("0070 up migration has %d INFORMATION_SCHEMA probes for participation_generation, want 2 (one for issues, one for wisps)\nfull SQL:\n%s", n, upSQL) + } + if !strings.Contains(strings.ToUpper(upSQL), "PREPARE STMT FROM @SQL") { + t.Error("0070 up migration must keep its guarded PREPARE blocks — they are what make 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 cliMigration0070AddParticipationGeneration.") + } + + // The bundle override is what keeps the two PREPARE blocks above off the + // pre-2.3 CLI path. + bundle := cliCompatibleMigrationSQL(migration0070Up, upSQL) + for _, want := range []string{ + "ALTER TABLE issues ADD COLUMN participation_generation BIGINT NULL;", + "ALTER TABLE wisps ADD COLUMN participation_generation BIGINT NULL;", + } { + if !strings.Contains(bundle, want) { + t.Errorf("0070's CLI bundle substitute (cliMigration0070AddParticipationGeneration) missing direct DDL %q", want) + } + } + // Design §16.3 step 5 (be-dt74u amendment, be-h89oq) makes 0070's CLI + // substitute ALTER wisps directly, the same unconditional-wisps-ALTER + // shape 0067's current_revision override already uses (see + // cliSubstituteAssumesWispTables' 0067 case). + if !cliSubstituteAssumesWispTables(migration0070Up) { + t.Error("0070's CLI substitute ALTERs wisps unguarded, so it must be listed in cliSubstituteAssumesWispTables — a replay over a clone that never synced the wisp tables has to fall back to the frozen source text") + } + + // 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 + // TestMigration0068AddsAttributionStatus's precedent. + downBytes, err := os.ReadFile("migrations/" + migration0070Down) + if err != nil { + t.Fatalf("read %s: %v, want the migration file to exist", migration0070Down, err) + } + downSQL := string(downBytes) + for _, want := range []string{ + "ALTER TABLE issues DROP COLUMN participation_generation", + "ALTER TABLE wisps DROP COLUMN participation_generation", + } { + if !strings.Contains(downSQL, want) { + t.Errorf("0070 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 — 0068's/0069's downs are the + // precedent. + if !strings.Contains(strings.ToUpper(downSQL), "PREPARE STMT FROM @SQL") { + t.Error("0070 down migration must guard its DROP COLUMNs the way the up migration guards its ADD COLUMNs, so a partially-applied or already-rolled-back workspace rolls back safely") + } +} + +// TestMigration0070AddsParticipationGenerationThroughDoltCLI 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, on both planes. +func TestMigration0070AddsParticipationGenerationThroughDoltCLI(t *testing.T) { + testutil.RequireDoltBinary(t) + + dir := t.TempDir() + runDoltCommand(t, dir, "init", "--name", "test", "--email", "test@example.com") + runDoltSQL(t, dir, AllMigrationsSQL()) + + requireDoltDataType(t, dir, "issues", "participation_generation", "bigint", "YES") + requireDoltDataType(t, dir, "wisps", "participation_generation", "bigint", "YES") + + // No backfill: design §16.2a's "NULL = legacy-unmigrated" declaration + // needs every pre-existing (and freshly-inserted, pre-fence) row to read + // back NULL. Only issues is round-tripped here — the column is read and + // written on that plane; wisps carries it for schema-parity shape only + // (§16.2a) and is never read or written by this phase. + runDoltSQL(t, dir, `INSERT INTO issues (id, title, description, design, acceptance_criteria, notes) VALUES ('pg-1', 't', 'd', 'des', 'ac', 'n')`) + // id rides along with the target column: dolt sql -r csv emits no data + // line at all for a single-column result whose only value is NULL (just + // the header survives) -- reproduced identically against pre-existing + // unrelated nullable columns (assignee, closed_at), so it's a CSV-writer + // quirk, not something specific to this migration. A second, + // always-populated column keeps the row real. + rows := queryDoltCSV(t, dir, `SELECT id, participation_generation FROM issues WHERE id = 'pg-1'`) + if len(rows) != 1 || rows[0]["participation_generation"] != "" { + t.Fatalf("participation_generation for a freshly-inserted issues row = %v, want NULL (empty string in CSV form)", rows) + } +} diff --git a/internal/storage/schema/migrations/0070_add_participation_generation.down.sql b/internal/storage/schema/migrations/0070_add_participation_generation.down.sql new file mode 100644 index 000000000..e37d545f9 --- /dev/null +++ b/internal/storage/schema/migrations/0070_add_participation_generation.down.sql @@ -0,0 +1,34 @@ +-- Reverse of migration 0070 (participation_generation on issues and wisps, +-- design section 16.3 steps 4-5, be-dt74u amendment, be-h89oq), undone in +-- reverse order. +-- +-- issue_versions is guaranteed empty in any real rollback scenario for the +-- same reason 0068's NOT NULL-no-default is safe (Phase 2 is that table's +-- first writer), but this migration touches issues/wisps, not +-- issue_versions -- participation_generation is dropped unconditionally on +-- both planes if present, guarded on INFORMATION_SCHEMA the same way 0068's +-- down is, 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 @issues_pg_has = ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'issues' + AND COLUMN_NAME = 'participation_generation' +); +SET @sql = IF(@issues_pg_has > 0, + 'ALTER TABLE issues DROP COLUMN participation_generation', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @wisps_pg_has = ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'wisps' + AND COLUMN_NAME = 'participation_generation' +); +SET @sql = IF(@wisps_pg_has > 0, + 'ALTER TABLE wisps DROP COLUMN participation_generation', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; diff --git a/internal/storage/schema/migrations/0070_add_participation_generation.up.sql b/internal/storage/schema/migrations/0070_add_participation_generation.up.sql new file mode 100644 index 000000000..8cf0fb392 --- /dev/null +++ b/internal/storage/schema/migrations/0070_add_participation_generation.up.sql @@ -0,0 +1,69 @@ +-- Migration 0070: participation_generation on issues and wisps (design +-- section 16.3 steps 4-5, be-dt74u amendment, be-h89oq). +-- +-- Originally written as steps 4-5 appended to 0068_add_attribution_status +-- (be-h89oq's lineage), while that file was still unmerged. be-v33pa's own +-- attribution_status-only version of 0068 shipped to main first (2026-09-28 +-- 15:46Z), freezing that file's content -- scripts/check-migration-hygiene.sh +-- Check C protects any migration already shipped on the base branch, so +-- these steps move here instead of reconciling by editing 0068 (mayor ruling +-- 2026-09-29 on tracker be-waare). Numbered 0070: 0068 and 0069 are already +-- taken on origin/main, the latter by an unrelated migration +-- (widen_issue_versions_datetime_precision) that landed independently while +-- this lineage was in flight. +-- +-- participation_generation BIGINT NULL on issues, mirrored inertly on wisps. +-- NULL means legacy-unmigrated; any non-NULL is a positive declaration +-- sourced from store_epoch.epoch. RecordVersionInTx's write fence (design +-- §16.2b, in internal/storage/issueops/version_history.go) reads this column +-- to decide whether an update-shaped mutation against a legacy record mints +-- a version row at all -- a create-shaped mutation stamps a fresh value +-- instead. No backfill: NULL is the correct default for every existing row, +-- on both planes, so a plain ADD COLUMN with no DEFAULT is exactly what's +-- wanted. +-- +-- This migration must run before versioned history is turned on. The fence +-- reads this column on every flag-on mint of an issues-plane row, and on a +-- store without it that read fails, so the mutation fails with it rather +-- than skipping. With the flag off (the default) the seam returns before +-- the read, so a store below this migration writes exactly as before. +-- +-- Guarded the same way 0067/0068's ADD COLUMNs are (INFORMATION_SCHEMA probe +-- + PREPARE, since Dolt 2.2.3's ADD COLUMN has no MariaDB-only IF NOT +-- EXISTS), making a raw-SQL replay of this file a clean no-op on an +-- already-migrated store. Needs a CLI-bundle direct-DDL override +-- (cliMigration0070AddParticipationGeneration in cli_migrations.go), the same +-- dolthub/dolt#11345 escape hatch 0067/0068 use. +SET @issues_pg_needs_add = ( + SELECT IF(COUNT(*) = 0, 1, 0) + FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'issues' + AND COLUMN_NAME = 'participation_generation' +); +SET @sql = IF(@issues_pg_needs_add = 1, + 'ALTER TABLE issues ADD COLUMN participation_generation BIGINT NULL', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +-- wisps.participation_generation -- shape parity only, never read or written +-- on this plane (design §16.2a). Guarded on the wisps table existing as well +-- as the column, mirroring 0067's wisps.current_revision guard exactly (see +-- that migration's header): wisps is dolt-ignored/clone-local, so a clone +-- that never synced the local wisp tables must no-op rather than abort. The +-- clone-local twin for a workspace that never synced the wisps table at all +-- is ignored/0028_add_wisps_participation_generation.up.sql. +SET @wisps_pg_needs_add = IF( + (SELECT COUNT(*) FROM INFORMATION_SCHEMA.TABLES + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'wisps') > 0 + AND + (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'wisps' + AND COLUMN_NAME = 'participation_generation') = 0, + 1, 0 +); +SET @sql = IF(@wisps_pg_needs_add = 1, + 'ALTER TABLE wisps ADD COLUMN participation_generation BIGINT NULL', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; diff --git a/internal/storage/schema/migrations/ignored/0028_add_wisps_participation_generation.up.sql b/internal/storage/schema/migrations/ignored/0028_add_wisps_participation_generation.up.sql new file mode 100644 index 000000000..4ed7a3c58 --- /dev/null +++ b/internal/storage/schema/migrations/ignored/0028_add_wisps_participation_generation.up.sql @@ -0,0 +1,36 @@ +-- Ignored migration 0028: ensure wisps.participation_generation exists on +-- every clone (design be-hs42e.3 §16.2-16.3 / be-h89oq / be-x8tpz). +-- +-- Synced migration 0070 adds participation_generation to issues and wisps -- +-- but wisps is dolt-ignored (migration 0019), so its schema is clone-local, +-- and a workspace that bootstraps or re-clones from a remote whose +-- schema_migrations cursor is already >= 0070 adopts the cursor without ever +-- executing 0070. Its wisps table would then permanently lack the column, +-- and the shared issues/wisps column lists would drift by one column between +-- the fresh-clone door and the fresh-init door. Same mechanism, same shape, +-- same fix as ignored/0013 (wisps.row_lock, wy-pt82l), ignored/0020 +-- (wisps.storage_class, wy-98eh5), and ignored/0027 (wisps.current_revision). +-- +-- Carried here for SHAPE only, exactly like 0070's own issues/wisps split: +-- nothing reads or writes this column on the wisps plane (design §16.2a). +-- wisps.row_lock and wisps.current_revision are the precedent for a column +-- that exists on both planes and means something on only one. +-- +-- The guard makes this a no-op on in-place-upgraded workspaces where synced +-- 0070 already added the column, and on workspaces with no local wisps table +-- yet. Definition mirrors 0070's own wisps.participation_generation guard +-- exactly: BIGINT NULL, no default, no backfill. +SET @needs_add = IF( + (SELECT COUNT(*) FROM INFORMATION_SCHEMA.TABLES + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'wisps') > 0 + AND + (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'wisps' + AND COLUMN_NAME = 'participation_generation') = 0, + 1, 0 +); +SET @sql = IF(@needs_add = 1, + 'ALTER TABLE wisps ADD COLUMN participation_generation BIGINT NULL', + 'SELECT 1'); +PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt; diff --git a/internal/storage/schema/schema_test.go b/internal/storage/schema/schema_test.go index 857df4487..c1ffe2b30 100644 --- a/internal/storage/schema/schema_test.go +++ b/internal/storage/schema/schema_test.go @@ -1971,6 +1971,9 @@ func TestAllMigrationsSQLUsesDirectDDLForKnownCLIIncompatibilities(t *testing.T) // removed_at to DATETIME(6)), same shape as 0068's step 7. "ALTER TABLE issue_versions MODIFY COLUMN change_at DATETIME(6) NOT NULL;", "ALTER TABLE issue_versions MODIFY COLUMN removed_at DATETIME(6);", + // 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;", } { if !strings.Contains(got, want) { t.Fatalf("AllMigrationsSQL missing direct CLI DDL %q", want) @@ -2004,6 +2007,9 @@ func TestAllMigrationsSQLUsesDirectDDLForKnownCLIIncompatibilities(t *testing.T) // 0069 guards both of its MODIFYs the same way. "@issue_versions_change_at_needs_widen", "@issue_versions_removed_at_needs_widen", + // 0070 guards both planes' ALTERs the same way, mirroring 0067's pair. + "@issues_pg_needs_add", + "@wisps_pg_needs_add", } { if strings.Contains(got, forbidden) { t.Fatalf("AllMigrationsSQL contains source prepared-DDL guard %q", forbidden) diff --git a/internal/storage/uow/BUILD.bazel b/internal/storage/uow/BUILD.bazel index 36cb010b8..ac9440eec 100644 --- a/internal/storage/uow/BUILD.bazel +++ b/internal/storage/uow/BUILD.bazel @@ -118,6 +118,7 @@ go_test( "doltserver_provider_test.go", "doltserver_tx_test.go", "dualwrite_history_contract_test.go", + "dualwrite_participation_generation_contract_test.go", "edge_reader_contract_test.go", "errors_test.go", "expected_revision_contract_test.go", diff --git a/internal/storage/uow/dualwrite_participation_generation_contract_test.go b/internal/storage/uow/dualwrite_participation_generation_contract_test.go new file mode 100644 index 000000000..4f2a585df --- /dev/null +++ b/internal/storage/uow/dualwrite_participation_generation_contract_test.go @@ -0,0 +1,385 @@ +package uow + +import ( + "context" + "testing" + + "github.com/steveyegge/beads/backend/conformance" + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/storage/domain" + "github.com/steveyegge/beads/internal/types" +) + +// TestParticipationGenerationFence runs the design §16.2(b) write-fence +// contract (backend/conformance/dualwrite_participation_generation_contract.go) +// against the unit-of-work provider. Like TestDualWriteContract, this is an +// engine check rather than a second vote: all three legs share +// RecordVersionInTx's one body, and this is the only leg where the mutation's +// own commit is assembled by composition rather than opened directly against +// a *sql.DB. +func TestParticipationGenerationFence(t *testing.T) { + ctx := context.Background() + fixture := newUOWParticipationGenerationFixture(t, ctx, "pg") + + t.Run("CreateWithFlagOnStampsAValue", func(t *testing.T) { + conformance.RunParticipationGenerationCreateWithFlagOnStampsAValue(t, ctx, fixture) + }) + t.Run("CreateWithFlagOffLeavesLegacyNull", func(t *testing.T) { + conformance.RunParticipationGenerationCreateWithFlagOffLeavesLegacyNull(t, ctx, fixture) + }) + t.Run("SkipsUpdateOnLegacyRecord", func(t *testing.T) { + conformance.RunParticipationGenerationSkipsUpdateOnLegacyRecord(t, ctx, fixture) + }) + t.Run("ProceedsForPromotedRecord", func(t *testing.T) { + conformance.RunParticipationGenerationProceedsForPromotedRecord(t, ctx, fixture) + }) + t.Run("FenceIgnoresSchemaSkewHatch", func(t *testing.T) { + conformance.RunParticipationGenerationFenceIgnoresSchemaSkewHatch(t, ctx, fixture) + }) + t.Run("WispPromotionBeginsHistory", func(t *testing.T) { + conformance.RunParticipationGenerationWispPromotionBeginsHistory(t, ctx, fixture) + }) + t.Run("WispPersistenceMoveBeginsHistory", func(t *testing.T) { + conformance.RunParticipationGenerationWispPersistenceMoveBeginsHistory(t, ctx, fixture) + }) + t.Run("WispFlagClearMintsNothing", func(t *testing.T) { + conformance.RunParticipationGenerationWispFlagClearMintsNothing(t, ctx, fixture) + }) + t.Run("WispRootSquashMintsNothing", func(t *testing.T) { + conformance.RunParticipationGenerationWispRootSquashMintsNothing(t, ctx, fixture) + }) + t.Run("UnflaggedWispCreateMintsNothing", func(t *testing.T) { + conformance.RunParticipationGenerationUnflaggedWispCreateMintsNothing(t, ctx, fixture) + }) + t.Run("NoHistoryIssueCreateDeclaresParticipation", func(t *testing.T) { + conformance.RunParticipationGenerationNoHistoryIssueCreateDeclaresParticipation(t, ctx, fixture) + }) + t.Run("LegacyNoHistoryIssueStaysLegacy", func(t *testing.T) { + conformance.RunParticipationGenerationLegacyNoHistoryIssueStaysLegacy(t, ctx, fixture) + }) +} + +// TestParticipationGenerationFixtureKitIsWired is this leg's half of the +// explicit per-leg guardrail design §8.5 calls for in place of AST +// auto-discovery — see the dolt leg's TestParticipationGenerationFixtureKitIsWired +// for why the guardrail is needed even though TestEveryLegWiresEveryRoleContract's +// scan already enumerates and confirms wiring for every +// RunParticipationGenerationXxx entrypoint. +func TestParticipationGenerationFixtureKitIsWired(t *testing.T) { + ctx := context.Background() + fixture := newUOWParticipationGenerationFixture(t, ctx, "pgk") + + if fixture.SetFlag == nil { + t.Error("ParticipationGenerationFixture.SetFlag is nil") + } + if fixture.Mutate == nil { + t.Error("ParticipationGenerationFixture.Mutate is nil") + } + if fixture.MutateExisting == nil { + t.Error("ParticipationGenerationFixture.MutateExisting is nil") + } + if fixture.CreateWisp == nil { + t.Error("ParticipationGenerationFixture.CreateWisp is nil") + } + if fixture.PromoteWisp == nil { + t.Error("ParticipationGenerationFixture.PromoteWisp is nil") + } + if fixture.MovePersistent == nil { + t.Error("ParticipationGenerationFixture.MovePersistent is nil") + } + if fixture.ClearWispFlag == nil { + t.Error("ParticipationGenerationFixture.ClearWispFlag is nil") + } + if fixture.SquashWispRoot == nil { + t.Error("ParticipationGenerationFixture.SquashWispRoot is nil") + } + if fixture.CreateUnflaggedWisp == nil { + t.Error("ParticipationGenerationFixture.CreateUnflaggedWisp is nil") + } + if fixture.CreateNoHistoryIssue == nil { + t.Error("ParticipationGenerationFixture.CreateNoHistoryIssue is nil") + } + if fixture.CurrentRevision == nil { + t.Error("ParticipationGenerationFixture.CurrentRevision is nil") + } + if fixture.VersionRowCount == nil { + t.Error("ParticipationGenerationFixture.VersionRowCount is nil") + } + if fixture.ParticipationGeneration == nil { + t.Error("ParticipationGenerationFixture.ParticipationGeneration is nil") + } + if fixture.InWispsTable == nil { + t.Error("ParticipationGenerationFixture.InWispsTable is nil") + } +} + +// TestParticipationGenerationUpsertCreate pins the write fence (design +// §16.2b) on the unit-of-work create that is not CreateOnly, the default for +// bd batch, bd todo, tracker sync and mol port. That create's insert is an +// upsert, so db.Insert has to tell a new row (create-shaped mint: stamp the +// column) from an existing one the upsert resolved to (update-shaped: fenced +// when legacy). TestParticipationGenerationFence cannot see that choice: its +// Mutate is CreateOnly, and so is every served create (createParams), so no +// other leg reaches this branch at all. +// +// PromoteOverDualPresenceKeepsLegacy asks the same question of +// PromoteFromEphemeralInTx's upsert: a wisp whose id the issues plane already +// holds (GH#4455's dual presence, written the way a store corrupted before +// that fix holds it) is promoted onto that existing row. +// WispOverLegacyIssuesRowKeepsItLegacy asks it of the wisps-table half of the +// same db.Insert (bd mol port's CreateWisp): that insert never creates an +// issues row, so the only issues row its mint can reach is a twin that +// already held the id. +func TestParticipationGenerationUpsertCreate(t *testing.T) { + ctx := context.Background() + provider := newUOWRoleFixtureProvider(t, ctx, "pgu") + fixture := uowParticipationGenerationFixtureFor(t, provider, "pgu") + + setFlag := func(t *testing.T, enabled bool) { + t.Helper() + if err := fixture.SetFlag(ctx, enabled); err != nil { + t.Fatalf("setting versioned history to %v: %v", enabled, err) + } + } + upsert := func(t *testing.T, id, title string) { + t.Helper() + if err := RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) { + _, err := uw.IssueUseCase().CreateIssue(ctx, domain.CreateIssueParams{ + Issue: &types.Issue{ + ID: id, Title: title, IssueType: types.TypeTask, Status: types.StatusOpen, + }, + ExplicitID: id, + }, "actor") + return "upsert " + id, err + }); err != nil { + t.Fatalf("upsert-creating %s: %v", id, err) + } + } + requireState := func(t *testing.T, id string, wantStamped bool, wantVersions int, why string) { + t.Helper() + gen, err := fixture.ParticipationGeneration(ctx, id) + if err != nil { + t.Fatalf("reading participation_generation for %s: %v", id, err) + } + if stamped := gen != nil; stamped != wantStamped { + t.Errorf("participation_generation for %s stamped=%v, want %v: %s", id, stamped, wantStamped, why) + } + versions, err := fixture.VersionRowCount(ctx, id) + if err != nil { + t.Fatalf("counting version rows for %s: %v", id, err) + } + if versions != wantVersions { + t.Errorf("version row count for %s = %d, want %d: %s", id, versions, wantVersions, why) + } + } + + t.Run("NewRowIsCreateShaped", func(t *testing.T) { + setFlag(t, true) + id := "pgu-new" + upsert(t, id, "t-"+id) + requireState(t, id, true, 1, "an upsert that inserted the row is a create, so it stamps the column and begins the history") + }) + t.Run("LegacyRowStaysLegacy", func(t *testing.T) { + setFlag(t, false) + id := "pgu-legacy" + upsert(t, id, "t-"+id) + requireState(t, id, false, 0, "a create with history off leaves the row legacy") + setFlag(t, true) + upsert(t, id, "resynced-"+id) + requireState(t, id, false, 0, "an upsert that resolved to a legacy row is update-shaped and fenced; stamping it would promote a legacy record (R2.3)") + }) + t.Run("StampedRowMintsOnce", func(t *testing.T) { + setFlag(t, true) + id := "pgu-stamped" + upsert(t, id, "t-"+id) + upsert(t, id, "resynced-"+id) + requireState(t, id, true, 2, "an upsert that resolved to a participating row mints exactly one more version") + }) + t.Run("PromoteOverDualPresenceKeepsLegacy", func(t *testing.T) { + setFlag(t, false) + id := "pgu-dual" + if err := fixture.Mutate(ctx, id); err != nil { + t.Fatalf("creating legacy %s: %v", id, err) + } + if err := RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) { + _, err := uw.RawSQLUseCase().Exec(ctx, + "INSERT INTO wisps (id, title, status, priority, issue_type, ephemeral, created_at, updated_at) "+ + "SELECT id, title, status, priority, issue_type, 1, created_at, updated_at FROM issues WHERE id = ?", id) + return "plant wisp twin " + id, err + }); err != nil { + t.Fatalf("planting a wisps-table twin of %s: %v", id, err) + } + setFlag(t, true) + if err := fixture.PromoteWisp(ctx, id); err != nil { + t.Fatalf("promoting %s: %v", id, err) + } + if inWisps, err := fixture.InWispsTable(ctx, id); err != nil { + t.Fatalf("checking the wisps table for %s: %v", id, err) + } else if inWisps { + t.Fatalf("%s is still in the wisps table after its promote", id) + } + requireState(t, id, false, 0, "a promote whose upsert resolved to an existing legacy issues row is update-shaped and fenced; stamping it would promote a legacy record (R2.3)") + }) + t.Run("WispOverLegacyIssuesRowKeepsItLegacy", func(t *testing.T) { + setFlag(t, false) + id := "pgu-wisp-twin" + upsert(t, id, "t-"+id) + requireState(t, id, false, 0, "a create with history off leaves the row legacy") + setFlag(t, true) + if err := RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) { + _, err := uw.IssueUseCase().CreateWisp(ctx, domain.CreateIssueParams{ + Issue: &types.Issue{ + ID: id, Title: "wisp-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, Ephemeral: true, + }, + ExplicitID: id, + }, "actor") + return "wisp upsert " + id, err + }); err != nil { + t.Fatalf("wisp-creating %s over its issues row: %v", id, err) + } + if inWisps, err := fixture.InWispsTable(ctx, id); err != nil { + t.Fatalf("checking the wisps table for %s: %v", id, err) + } else if !inWisps { + t.Fatalf("%s is not in the wisps table after its wisp create; the case needs both planes to hold the id", id) + } + requireState(t, id, false, 0, "a wisps-table insert never creates the issues row the seam snapshots, so its mint is update-shaped and fenced; stamping that legacy twin would promote a legacy record (R2.3)") + }) +} + +func newUOWParticipationGenerationFixture(t *testing.T, ctx context.Context, prefix string) conformance.ParticipationGenerationFixture { + t.Helper() + return uowParticipationGenerationFixtureFor(t, newUOWRoleFixtureProvider(t, ctx, prefix), prefix) +} + +// uowParticipationGenerationFixtureFor is newUOWParticipationGenerationFixture +// over a provider the caller already holds, for a test that also drives that +// provider directly. +func uowParticipationGenerationFixtureFor(t *testing.T, provider UnitOfWorkProvider, prefix string) conformance.ParticipationGenerationFixture { + t.Helper() + // Through the capability accessor's operator half, the same way + // newUOWVersionedHistoryProvider reaches it above — SetFlag here needs to + // toggle more than once per case, so this fixture keeps its own handle + // rather than fixing the flag once at construction the way + // newUOWVersionedHistoryProvider does for the dual-write fixture. + configurer, ok := provider.(storage.VersionedHistoryConfigurer) + if !ok { + t.Fatalf("provider %T does not implement storage.VersionedHistoryConfigurer", provider) + } + kit := newUOWRoleFixtureKit(provider, prefix) + return conformance.ParticipationGenerationFixture{ + IssuePrefix: prefix, + SetFlag: func(ctx context.Context, enabled bool) error { + configurer.SetVersionedHistoryEnabled(enabled) + return nil + }, + Mutate: func(ctx context.Context, id string) error { + return RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) { + _, err := uw.IssueUseCase().CreateIssue(ctx, domain.CreateIssueParams{ + Issue: &types.Issue{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + }, + ExplicitID: id, + CreateOnly: true, + }, "actor") + return "create " + id, err + }) + }, + MutateExisting: func(ctx context.Context, id string) error { + // A different value than Mutate gave it, not a re-assertion of the + // same title: DiscardNoopIssueUpdates would discard the latter + // before it ever reached the fence this contract is testing. + return RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) { + return "update " + id, uw.IssueUseCase().UpdateIssue(ctx, id, + map[string]any{"title": "updated-" + id}, "actor") + }) + }, + CreateWisp: func(ctx context.Context, id string) error { + return kit.CreateWisp(ctx, &types.Issue{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, Ephemeral: true, + }, "actor") + }, + PromoteWisp: func(ctx context.Context, id string) error { + return RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) { + return "promote " + id, uw.IssueUseCase().PromoteWisp(ctx, id, "actor") + }) + }, + MovePersistent: func(ctx context.Context, id string) error { + // ApplyUpdate's persistence step, which runs MovePersistence and + // so MoveIssuePersistenceInTx's own mint, not a guarded update's. + persistent := types.PersistenceModePersistent + return RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) { + _, err := uw.IssueUseCase().ApplyUpdate(ctx, id, domain.UpdateSpec{Persistence: &persistent}, "actor") + return "move persistent " + id, err + }) + }, + ClearWispFlag: func(ctx context.Context, id string) error { + // UpdateWisp, as the molecule writer routes bd mol squash's flag + // clear for a row it found on the wisp plane. + return RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) { + return "clear wisp flag " + id, uw.IssueUseCase().UpdateWisp(ctx, id, + map[string]any{"wisp": false}, "actor") + }) + }, + SquashWispRoot: func(ctx context.Context, id string) error { + // The proxied bd mol squash's shape: CloseWisp then UpdateWisp in + // the one unit of work the squash commits. + return RunTx(ctx, provider, func(ctx context.Context, uw UnitOfWork) (string, error) { + if _, err := uw.IssueUseCase().CloseWisp(ctx, id, domain.CloseIssueParams{Reason: "squashed"}, "actor"); err != nil { + return "", err + } + return "squash " + id, uw.IssueUseCase().UpdateWisp(ctx, id, + map[string]any{"wisp": false}, "actor") + }) + }, + CreateUnflaggedWisp: func(ctx context.Context, id string) error { + // CreateWisp routes by the call, so neither flag is needed to land + // the row in the wisps table. + return kit.CreateWisp(ctx, &types.Issue{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, + }, "actor") + }, + CreateNoHistoryIssue: func(ctx context.Context, id string) error { + // CreateIssue routes by the call, so the NoHistory flag rides on an + // issues-table row without moving it to the wisps table. + return kit.CreateIssue(ctx, &types.Issue{ + ID: id, Title: "t-" + id, IssueType: types.TypeTask, Status: types.StatusOpen, NoHistory: true, + }, "actor") + }, + CurrentRevision: func(ctx context.Context, id string) (int64, error) { + var revision int64 + err := kit.QueryScalar(ctx, "SELECT current_revision FROM issues WHERE id = ?", []any{id}, &revision) + return revision, err + }, + VersionRowCount: func(ctx context.Context, id string) (int, error) { + var count int + err := kit.QueryScalar(ctx, "SELECT COUNT(*) FROM issue_versions WHERE issue_id = ?", []any{id}, &count) + return count, err + }, + ParticipationGeneration: func(ctx context.Context, id string) (*int64, error) { + // scanRawSQLValue refuses a NULL numeric destination outright + // (issue_operations_contract_test.go's frozen scaffolding surface, + // bd-kue5t) rather than decaying it to zero, so a bare + // participation_generation read cannot scan into *sql.NullInt64 the + // way the dolt/embeddeddolt legs' std-library Scan does. epoch is + // seeded at 1 and only ever increments (version_history.go), so a + // stamped participation_generation is always >= 1 and -1 is an + // unambiguous "still NULL" sentinel for the COALESCE. + var gen int64 + if err := kit.QueryScalar(ctx, + "SELECT COALESCE(participation_generation, -1) FROM issues WHERE id = ?", []any{id}, &gen); err != nil { + return nil, err + } + if gen == -1 { + return nil, nil + } + return &gen, nil + }, + InWispsTable: func(ctx context.Context, id string) (bool, error) { + var rows int + if err := kit.QueryScalar(ctx, "SELECT COUNT(*) FROM wisps WHERE id = ?", []any{id}, &rows); err != nil { + return false, err + } + return rows > 0, nil + }, + } +}