From aa3c43b6bd2ff91c5afe6268283d4e8d88e50e8e Mon Sep 17 00:00:00 2001 From: Jim Wordelman Date: Sat, 26 Sep 2026 14:27:45 -0700 Subject: [PATCH] feat(storage): add events/bd_events_journal/bd_events_seq to cursorRealityFloor sentinel set (#6547) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * test(feat): red — Add sentinelFlooredTables to cursorRealityFloor so events/bd_events_journal/bd_events_seq self-heal (release/1.3.0) (refs be-u14.1) * feat: green — Add sentinelFlooredTables to cursorRealityFloor so events/bd_events_journal/bd_events_seq self-heal (release/1.3.0) (refs be-u14.1) * chore: release gate PASS for cursor-reality-floor-sentinel-self-heal (be-g69lt) * chore: remove leaked internal release-gate doc from PR branch release-gates/be-g69lt-gate.md Tracked our internal gc-management/beads-rig release-gate checklist and should never have been committed to this upstream branch -- it's process residue from our deploy tooling, not part of the change itself. Per maintainer bee-ghosttrack's request during review of PR #6571. The root cause (our deploy tooling auto-committing this file) is already fixed as of gm-qatxl1; this branch predates that fix, so this commit is cleanup only -- no other content on this branch is touched. Ref: be-lk7o3 * fix(schema): pin the floored-sentinel minimum and generalize creator detection Maintainer review fixups for PR #6547 (adoption review, iteration 1). No behavior change beyond the probe error-message text. - Pin the floored loop's intra-loop minimum. Every existing case removed exactly one floored sentinel, so `st.replayFloor < floor` was never evaluated against a floor an earlier absent sentinel had already set, and inverting it to `>` left the whole package green. Adds an "events and bd_events_journal both absent" case asserting floor 18 and widens allSentinelTablesExcept to variadic; the inversion now fails (floor = 21, want 18). The floors ascend in slice order today (18, 21, 21), so this is what keeps a future reordering or lower-floored addition from silently regressing to "last absent sentinel wins". - Distinguish the floored-table probe's error wrap from the floor-0 loop's. They were byte-identical, so a store-open failure did not say which sentinel class failed, and the consequences differ sharply (floor 0 and a full series replay vs. floor 18/21). - Detect both creator shapes in TestSentinelFlooredTablesAreCreatedByTheSeries rather than keying on the literal table name "events". The PREPAREd conditional CREATE is required of any creator whose table carries a named, database-unique constraint (ignored/0019's own comment), so a future floored sentinel in that shape would have fallen through to the __temp__ regex and failed with a misleading "never created by the series". Both arms are mutation-proved to be load-bearing. - Record in the sentinelFlooredTables comment that events' dolt_ignore pattern is version-gated ({"events", 62}) rather than unconditional, and why the clamp is safe anyway: the ignored plane is only reached after the main pass succeeds, and a main pass from below 62 applies 0062_events_dolt_ignore, whose REPLACE INTO dolt_ignore lands before the ignored plane is touched. Validation: go test -count=1 ./internal/storage/schema/ (ok, 36.5s), go vet and gofmt clean, git diff --check clean. --------- Co-authored-by: Julian Knutsen --- .../storage/schema/cursor_reality_test.go | 192 +++++++++++++++++- internal/storage/schema/lock_test.go | 6 +- internal/storage/schema/schema.go | 68 ++++++- 3 files changed, 260 insertions(+), 6 deletions(-) diff --git a/internal/storage/schema/cursor_reality_test.go b/internal/storage/schema/cursor_reality_test.go index c41144fab..299a2e7f9 100644 --- a/internal/storage/schema/cursor_reality_test.go +++ b/internal/storage/schema/cursor_reality_test.go @@ -46,12 +46,30 @@ func stubSentinelColumns(t *testing.T, present map[string]bool, probeErr error) } // allSentinelTables is the "everything the table sentinels ask for is present" -// shape, so column-sentinel cases can say so without repeating the list. +// shape, so column-sentinel cases can say so without repeating the list. Both +// the unconditional-floor-0 tables and the floored tables share the same +// sentinelTableExists probe, so both must be marked present here or a case +// meant to isolate one sentinel would spuriously trip another. func allSentinelTables() map[string]bool { - present := make(map[string]bool, len(ignoredSource.sentinelTables)) + present := make(map[string]bool, len(ignoredSource.sentinelTables)+len(ignoredSource.sentinelFlooredTables)) for _, table := range ignoredSource.sentinelTables { present[table] = true } + for _, st := range ignoredSource.sentinelFlooredTables { + present[st.table] = true + } + return present +} + +// allSentinelTablesExcept is allSentinelTables with the named tables absent, +// for cases that need every sentinel healthy except the one(s) under test. +// Variadic so a case can contradict two sentinels of the same kind at once, +// which is what pins the minimum a single loop accumulates. +func allSentinelTablesExcept(tables ...string) map[string]bool { + present := allSentinelTables() + for _, table := range tables { + delete(present, table) + } return present } @@ -139,6 +157,55 @@ func TestCursorRealityFloor(t *testing.T) { wantFloor: 0, wantLimited: false, }, + { + name: "events absent", + present: allSentinelTablesExcept("events"), + columns: map[string]bool{"leases.granted_node": true}, + wantFloor: 18, + wantLimited: true, + }, + { + name: "bd_events_journal absent", + present: allSentinelTablesExcept("bd_events_journal"), + columns: map[string]bool{"leases.granted_node": true}, + wantFloor: 21, + wantLimited: true, + }, + { + name: "bd_events_seq absent", + present: allSentinelTablesExcept("bd_events_seq"), + columns: map[string]bool{"leases.granted_node": true}, + wantFloor: 21, + wantLimited: true, + }, + { + // Two floored sentinels contradicted at once: the minimum must win + // WITHIN the floored loop, not only across loops. Without this + // case every case removes exactly one floored table, so the loop + // only ever reaches its !limited arm and `st.replayFloor < floor` + // is never evaluated against a floor an earlier absent sentinel + // already set — inverting it to `>` leaves the package green. The + // floors happen to ascend in slice order (18, 21, 21) today, so + // this is what keeps a future reordering or lower-floored addition + // from silently regressing to "last absent sentinel wins". + name: "events and bd_events_journal both absent", + present: allSentinelTablesExcept("events", "bd_events_journal"), + columns: map[string]bool{"leases.granted_node": true}, + wantFloor: 18, + wantLimited: true, + }, + { + // Combined contradiction across two different sentinel kinds: the + // true minimum (11, from the column) must win over the higher + // floored-table floor (18) the table loop finds first, proving the + // accumulator takes the minimum across both loops rather than + // whichever ran first. + name: "events absent and leases granted_node absent", + present: allSentinelTablesExcept("events"), + columns: map[string]bool{}, + wantFloor: 11, + wantLimited: true, + }, } { t.Run(tc.name, func(t *testing.T) { stubSentinelTables(t, tc.present, nil) @@ -255,6 +322,37 @@ func TestCurrentVersionClampsToSentinelFloor(t *testing.T) { columns: map[string]bool{"leases.granted_node": true}, want: latest, }, + { + name: "events absent, at-latest cursor", + raw: latest, + present: allSentinelTablesExcept("events"), + columns: map[string]bool{"leases.granted_node": true}, + want: 18, + }, + { + name: "bd_events_journal absent, at-latest cursor", + raw: latest, + present: allSentinelTablesExcept("bd_events_journal"), + columns: map[string]bool{"leases.granted_node": true}, + want: 21, + }, + { + name: "bd_events_seq absent, at-latest cursor", + raw: latest, + present: allSentinelTablesExcept("bd_events_seq"), + columns: map[string]bool{"leases.granted_node": true}, + want: 21, + }, + { + // Combined contradiction across two different sentinel kinds: the + // true minimum (11, from the column) must win over the higher + // floored-table floor (18). + name: "events absent and leases column absent, at-latest cursor", + raw: latest, + present: allSentinelTablesExcept("events"), + columns: map[string]bool{}, + want: 11, + }, } { t.Run(tc.name, func(t *testing.T) { stubSentinelTables(t, tc.present, nil) @@ -437,6 +535,84 @@ func TestSentinelColumnsAreCreatedByTheSeries(t *testing.T) { } } +// TestSentinelFlooredTablesAreCreatedByTheSeries is the floored-table +// analogue of TestSentinelColumnsAreCreatedByTheSeries: every sentinel in +// sentinelFlooredTables must be created by the series, strictly above its own +// replayFloor, and that floor must exclude ignored/0007's unguarded restamp +// the same way the column floor does. +// +// events does not use the __temp__ + RENAME pattern the other +// creators do: it carries the named, database-unique constraint +// fk_events_issue, so a temp twin errors "duplicate foreign key constraint +// name" on Dolt 2.2.2 (see ignored/0019's own comment). Its creator guards a +// plain CREATE TABLE behind a PREPAREd conditional on an INFORMATION_SCHEMA +// existence probe instead, so both creation shapes are detected here. +func TestSentinelFlooredTablesAreCreatedByTheSeries(t *testing.T) { + if len(ignoredSource.sentinelFlooredTables) == 0 { + t.Fatal("ignoredSource has no sentinel floored tables; the events/bd_events_journal/bd_events_seq guard is inert") + } + + bodies := make(map[int]string) + for _, mf := range ignoredSource.list() { + blob, err := ignoredSource.files.ReadFile(ignoredSource.dir + "/" + mf.name) + if err != nil { + t.Fatalf("read %s: %v", mf.name, err) + } + bodies[mf.version] = string(blob) + } + + // findVersion returns the lowest migration version whose body matches, or + // 0 when nothing does. + findVersion := func(re *regexp.Regexp) int { + found := 0 + for version, body := range bodies { + if !re.MatchString(body) { + continue + } + if found == 0 || version < found { + found = version + } + } + return found + } + + unguarded := findVersion(regexp.MustCompile(`(?i)UPDATE\s+wisps\s+SET\s+is_blocked\s*=\s*0\s*;`)) + if unguarded == 0 { + t.Fatal("the unguarded `UPDATE wisps SET is_blocked = 0` the replay floor exists to exclude is gone; re-derive the floor") + } + + for _, st := range ignoredSource.sentinelFlooredTables { + // Detect both creation shapes and accept whichever the series actually + // uses, rather than keying on the table's name: the PREPAREd + // conditional CREATE is required of any creator whose table carries a + // named, database-unique constraint (ignored/0019's own comment), so a + // future floored sentinel can legitimately arrive in either shape and + // must not fall through to the misleading "never created" failure. + // findVersion already returns the lowest match, so take the earlier of + // the two shapes if a table somehow uses both. + prepared := findVersion(regexp.MustCompile( + `(?i)IF\(@\w+\s*=\s*0,\s*'CREATE TABLE ` + regexp.QuoteMeta(st.table) + `\s*\(`)) + temp := findVersion(regexp.MustCompile(regexp.QuoteMeta("__temp__" + st.table))) + creator := prepared + if creator == 0 || (temp != 0 && temp < creator) { + creator = temp + } + if creator == 0 { + t.Errorf("sentinel floored table %q is never created by the %s series; re-running it could not repair that table", + st.table, ignoredSource.dir) + continue + } + if creator <= st.replayFloor { + t.Errorf("sentinel floored table %q is created by ignored/%04d, at or below its replayFloor %d; the clamped replay would skip the migration that heals it", + st.table, creator, st.replayFloor) + } + if st.replayFloor < unguarded { + t.Errorf("sentinel floored table %q replayFloor %d does not exclude ignored/%04d, whose unguarded UPDATE restamps wisps.updated_at", + st.table, st.replayFloor, unguarded) + } + } +} + // TestMigrationWorkNeededWhenWispTablesAbsent is gh 5033 end to end, through // the real short-circuit that caused it. Both cursors read at-latest, so // before this change migrationWorkNeeded returned false, MigrateUp did @@ -491,6 +667,12 @@ func TestMigrationWorkNeededWhenLeaseGrantedNodeAbsent(t *testing.T) { mock.ExpectQuery(regexp.QuoteMeta("FROM INFORMATION_SCHEMA.TABLES")). WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1)) } + // The floored-table sentinels probe the same way and must all corroborate + // too, ahead of the column probe below. + for range ignoredSource.sentinelFlooredTables { + mock.ExpectQuery(regexp.QuoteMeta("FROM INFORMATION_SCHEMA.TABLES")). + WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1)) + } mock.ExpectQuery(regexp.QuoteMeta("FROM INFORMATION_SCHEMA.COLUMNS")). WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(0)) @@ -590,6 +772,12 @@ func TestMigrateStartsAboveTheFloorUnderColumnContradiction(t *testing.T) { mock.ExpectQuery(regexp.QuoteMeta("FROM INFORMATION_SCHEMA.TABLES")). WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1)) } + // The floored-table sentinels probe the same way and must all corroborate + // too, ahead of the column probe below. + for range ignoredSource.sentinelFlooredTables { + mock.ExpectQuery(regexp.QuoteMeta("FROM INFORMATION_SCHEMA.TABLES")). + WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1)) + } mock.ExpectQuery(regexp.QuoteMeta("FROM INFORMATION_SCHEMA.COLUMNS")). WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(0)) diff --git a/internal/storage/schema/lock_test.go b/internal/storage/schema/lock_test.go index 481cbe463..c8cb9dc30 100644 --- a/internal/storage/schema/lock_test.go +++ b/internal/storage/schema/lock_test.go @@ -709,7 +709,7 @@ func TestMigrateUpWithLockFreshBootstrapHealResetsAndRetries(t *testing.T) { // expectIgnoredSentinelProbes mocks the INFORMATION_SCHEMA lookups // currentVersion issues to confirm a non-zero ignored cursor against the // schema it claims (gh 5033). They fire only for a non-zero cursor, in -// ignoredSource's table then column sentinel order. +// ignoredSource's table then floored-table then column sentinel order. func expectIgnoredSentinelProbes(mock sqlmock.Sqlmock, present bool) { count := 0 if present { @@ -720,6 +720,10 @@ func expectIgnoredSentinelProbes(mock sqlmock.Sqlmock, present bool) { WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(count)) } if present { + for range ignoredSource.sentinelFlooredTables { + mock.ExpectQuery(regexp.QuoteMeta("FROM INFORMATION_SCHEMA.TABLES")). + WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1)) + } for range ignoredSource.sentinelColumns { mock.ExpectQuery(regexp.QuoteMeta("FROM INFORMATION_SCHEMA.COLUMNS")). WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1)) diff --git a/internal/storage/schema/schema.go b/internal/storage/schema/schema.go index 5ee2df65a..659b82b03 100644 --- a/internal/storage/schema/schema.go +++ b/internal/storage/schema/schema.go @@ -237,6 +237,22 @@ type migrationSource struct { // TestSentinelTablesAreCreatedByTheSeries enforces the creating side only; // the dropping side is this comment. sentinelTables []string + // sentinelFlooredTables are clone-local tables whose absence contradicts an + // otherwise at-latest cursor, but — unlike sentinelTables — only back to + // each table's own replayFloor rather than unconditionally to 0. events, + // bd_events_journal, and bd_events_seq are dolt_ignored (never part of + // committed history, so a fresh clone can arrive at-latest without them) + // but floor-0 would replay ignored/0007's unguarded + // `UPDATE wisps SET is_blocked = 0` (see schemaSentinelColumn.replayFloor) + // for a table absence that says nothing about migrations that predate it. + // + // INVARIANT: no future migration in this series may DROP or RENAME a + // floored sentinel table. Older binaries in the field check their own + // sentinel list against the live schema, so removing one would make every + // healthy newer database read as "contradicted" to them and replay the + // series from their floor. TestSentinelFlooredTablesAreCreatedByTheSeries + // enforces the creating side only; the dropping side is this comment. + sentinelFlooredTables []schemaSentinelTable // sentinelColumns are clone-local columns whose absence contradicts an // otherwise at-latest cursor. Unlike a missing sentinel table, a missing // column disbelieves the cursor only back to the column's replayFloor: it @@ -252,6 +268,15 @@ type migrationSource struct { sentinelColumns []schemaSentinelColumn } +type schemaSentinelTable struct { + table string + // replayFloor is the highest cursor value this sentinel's absence still + // leaves believable — same semantics and the same two constraints as + // schemaSentinelColumn.replayFloor, applied to a whole table's presence + // instead of one column's. + replayFloor int +} + type schemaSentinelColumn struct { table string column string @@ -296,6 +321,28 @@ var ( // missing; wisps is checked too so a partially materialized database // is caught by whichever is absent. sentinelTables: []string{"wisps", "wisp_dependencies"}, + // events is created by ignored/0019 (floor 18: everything at or below + // must stay out of the replay, and 0019 itself must stay in it) and + // bd_events_journal/bd_events_seq are both created by ignored/0022 + // (floor 21, same reasoning). All three are dolt_ignored and never + // part of committed history, so a clone can arrive with the cursor + // at-latest but without them — exactly the leases shape below, except + // a whole-table absence rather than a column-on-an-existing-table one. + // + // The journal tables are ignored unconditionally; events is the one + // version-gated pattern ({"events", 62} below), so strictly its + // ignore is only asserted once the main cursor reaches 0062. That is + // safe here rather than a hole: this replay runs on the ignored plane, + // which migrateUpAfterReconcile only reaches after the main pass + // succeeded, and a main pass from below 62 applies + // 0062_events_dolt_ignore, whose REPLACE INTO dolt_ignore lands + // before the ignored plane is touched. So the clamp can never have + // 0019 re-create events as tracked-at-HEAD. + sentinelFlooredTables: []schemaSentinelTable{ + {table: "events", replayFloor: 18}, + {table: "bd_events_journal", replayFloor: 21}, + {table: "bd_events_seq", replayFloor: 21}, + }, // A historical ignored-v16 ordinal collision can leave the local // leases table present but without the column frozen 0016 adds; a // database materialized out of band can be missing the leases table @@ -1392,7 +1439,7 @@ func (m migrationSource) currentVersion(ctx context.Context, db DBConn) (int, er // corroborates. limited is false when nothing is missing (believe the cursor as // read); otherwise floor is the highest version still believable — 0 for a // missing sentinel table, and the sentinel's replayFloor for a missing sentinel -// column. +// floored table or sentinel column. // // Clamping rather than erroring is deliberate: the series is written to be // re-runnable against a database that already has some of it. @@ -1404,8 +1451,10 @@ func (m migrationSource) currentVersion(ctx context.Context, db DBConn) (int, er // rather than merely diagnose. // // Sentinel tables are probed first and short-circuit the whole check: they -// floor at 0, so no column probe could lower the answer, and skipping it keeps -// this cheap on the path every store open takes. +// floor at 0, so no floored-table or column probe could lower the answer, and +// skipping it keeps this cheap on the path every store open takes. Floored +// tables are then probed together with columns, each clamping floor to the +// lowest replayFloor of anything found absent. func (m migrationSource) cursorRealityFloor(ctx context.Context, db DBConn) (int, bool, error) { for _, table := range m.sentinelTables { present, err := sentinelTableExists(ctx, db, table) @@ -1417,6 +1466,19 @@ func (m migrationSource) cursorRealityFloor(ctx context.Context, db DBConn) (int } } floor, limited := 0, false + for _, st := range m.sentinelFlooredTables { + present, err := sentinelTableExists(ctx, db, st.table) + if err != nil { + return 0, false, fmt.Errorf("checking %s sentinel floored table %s: %w", m.cursorTable, st.table, err) + } + if present { + continue + } + if !limited || st.replayFloor < floor { + floor = st.replayFloor + } + limited = true + } for _, column := range m.sentinelColumns { present, err := sentinelColumnExists(ctx, db, column.table, column.column) if err != nil {