fix(issueops): decide the fence's plane by the table that holds the row

recordVersionInTx chose the plane from the row's flags (IsWisp: Ephemeral
|| NoHistory) and then read participation_generation from the issues table
only. A wisps-TABLE row can carry neither flag, so it passed the IsWisp
return and the issues read failed with sql.ErrNoRows, aborting the whole
mutation whenever versioned history is on. Two producers:

  - bd mol squash clears an ephemeral root's flag in place
    (UpdateIssue {"wisp": false}, after the root's close, in the squash's
    one transaction); update.go and the uow repository's Update both mint
    after it unconditionally.
  - import's "wisp_plane" marker (WispPlaneOverride = &true, flags false)
    routes the row to wisps, and the batch create mints it create-shaped.

On origin/main the same paths do not fail but mint a stray issue_versions
row for a wisps-table row, an FR-8 leak (wisps are never versioned).

Fix: no issues row means nothing to version. ErrNoRows on the
participation_generation read now returns nil (no version, no error) for
update- and create-shaped calls alike. That read is the right signal and
IsActiveWispInTx is not: GetIssueInTx has already resolved the row, so
ErrNoRows on the issues read can only mean "not in issues", which is
exactly the question the fence has to answer before it stamps or advances
an issues row. It costs no extra query. IsActiveWispInTx asks the inverse
question ("is it in wisps?") with one more query per mint, and it folds
every error, including a transient one, into "not a wisp".

Tests come first, as three new conformance contracts with three new
ParticipationGenerationFixture hooks (ClearWispFlag, SquashWispRoot,
CreateUnflaggedWisp). They are wired on the dolt, embeddeddolt and uow legs
as subtests of each leg's TestParticipationGenerationFence (no new
top-level test, so the shard manifests do not change) and waived on http
with participationGenerationRawStoreWaiverReason:

  RunParticipationGenerationWispFlagClearMintsNothing      (create wisp,
      UpdateIssue {"wisp": false}: no error, 0 versions)
  RunParticipationGenerationWispRootSquashMintsNothing     (close +
      UpdateIssue {"wisp": false} in one transaction: no error, 0 versions)
  RunParticipationGenerationUnflaggedWispCreateMintsNothing (CreateIssues
      with WispPlaneOverride=&true, flags false: no error, 0 versions)

Red before the fix, green after, run both ways:
  embeddeddolt (BEADS_TEST_EMBEDDED_DOLT=1): all three FAIL with
    "versioned history: read participation_generation for pg-...: sql: no
    rows in result set"; all three PASS after.
  uow: all three FAIL with the same error; all three PASS after.
  dolt (BEADS_TEST_DOLT_SERVER=local): WispRootSquash and UnflaggedWispCreate
    FAIL with the same error; both PASS after. WispFlagClear passes both
    ways on this leg. The store-level wisp update (updateWisp) runs in a
    transaction versioned history never scopes, so it never reaches the
    mint. For the same reason the leg's SquashWispRoot hook turns the events
    journal on for its one transaction: that pins the wisp writes to the
    scoped regular transaction, as in a journal-enabled workspace, so that
    case does reach the seam.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-10-18 03:02:48 +00:00
commit ec52d29030
6 changed files with 232 additions and 3 deletions

View file

@ -79,6 +79,22 @@ type ParticipationGenerationFixture struct {
// a different site on every leg: the guarded update's one end-of-update
// mint on dolt and embeddeddolt, MoveIssuePersistenceInTx's own on uow.
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
// 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.
@ -314,6 +330,67 @@ func runWispArrivalBeginsHistory(t *testing.T, ctx context.Context, fixture Part
}
}
// 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 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)
}
}
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)
}
}
// 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

View file

@ -41,6 +41,15 @@ func TestParticipationGenerationFence(t *testing.T) {
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)
})
}
// TestParticipationGenerationFence_FenceIgnoresSchemaSkewHatch pins the same
@ -86,6 +95,15 @@ func TestParticipationGenerationFixtureKitIsWired(t *testing.T) {
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.CurrentRevision == nil {
t.Error("ParticipationGenerationFixture.CurrentRevision is nil")
}
@ -221,6 +239,38 @@ func buildParticipationGenerationFixture(store *DoltStore, configurer storage.Ve
}
return err
},
ClearWispFlag: func(ctx context.Context, id string) error {
// This leg's store-level wisp update runs in a transaction
// versioned history does not scope, so it never reaches the mint;
// SquashWispRoot below is the case that does on this leg.
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. With the events
// journal off, RunInTransaction runs wisp writes on a separate
// ignored-table transaction versioned history never scopes, so
// the squash would never reach the mint this case pins; a
// journal-enabled workspace pins both planes to the one regular,
// scoped transaction. Take that shape for this one transaction.
store.SetEventsJournalEnabled(true)
defer store.SetEventsJournalEnabled(false)
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})
},
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).

View file

@ -49,6 +49,15 @@ func TestParticipationGenerationFence(t *testing.T) {
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)
})
}
// TestParticipationGenerationFixtureKitIsWired is this leg's half of the
@ -80,6 +89,15 @@ func TestParticipationGenerationFixtureKitIsWired(t *testing.T) {
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.CurrentRevision == nil {
t.Error("ParticipationGenerationFixture.CurrentRevision is nil")
}
@ -143,6 +161,28 @@ func newEmbeddedParticipationGenerationFixture(t *testing.T, te *testEnv, prefix
}
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})
},
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)

View file

@ -210,8 +210,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
@ -279,10 +280,24 @@ func recordVersionInTx(ctx context.Context, tx DBTX, issueID, actor string, isCr
// 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
// above 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 !isCreate && !participationGeneration.Valid {

View file

@ -126,8 +126,11 @@ func init() {
"RunParticipationGenerationFenceIgnoresSchemaSkewHatch": participationGenerationRawStoreWaiverReason,
"RunParticipationGenerationProceedsForPromotedRecord": participationGenerationRawStoreWaiverReason,
"RunParticipationGenerationSkipsUpdateOnLegacyRecord": participationGenerationRawStoreWaiverReason,
"RunParticipationGenerationUnflaggedWispCreateMintsNothing": participationGenerationRawStoreWaiverReason,
"RunParticipationGenerationWispFlagClearMintsNothing": participationGenerationRawStoreWaiverReason,
"RunParticipationGenerationWispPersistenceMoveBeginsHistory": participationGenerationRawStoreWaiverReason,
"RunParticipationGenerationWispPromotionBeginsHistory": participationGenerationRawStoreWaiverReason,
"RunParticipationGenerationWispRootSquashMintsNothing": participationGenerationRawStoreWaiverReason,
})
}
@ -341,7 +344,7 @@ 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"
// participationGenerationRawStoreWaiverReason covers the seven
// participationGenerationRawStoreWaiverReason covers the
// ParticipationGenerationFixture cases: a storage capability, not a claim the
// HTTP client serves.
//

View file

@ -42,6 +42,15 @@ func TestParticipationGenerationFence(t *testing.T) {
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)
})
}
// TestParticipationGenerationFixtureKitIsWired is this leg's half of the
@ -72,6 +81,15 @@ func TestParticipationGenerationFixtureKitIsWired(t *testing.T) {
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.CurrentRevision == nil {
t.Error("ParticipationGenerationFixture.CurrentRevision is nil")
}
@ -142,6 +160,32 @@ func newUOWParticipationGenerationFixture(t *testing.T, ctx context.Context, pre
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")
},
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)