feat(storage): add events/bd_events_journal/bd_events_seq to cursorRealityFloor sentinel set (#6547)

* 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 <julianknutsen@users.noreply.github.com>
This commit is contained in:
Jim Wordelman 2026-09-26 14:27:45 -07:00 • committed by GitHub
commit aa3c43b6bd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 260 additions and 6 deletions

View file

@ -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__<table> + 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))

View file

@ -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))

View file

@ -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 {