Fix: CLI/runtime schema parity oracle ignored-column handling + pool-heal cherry-pick (be-krza3) (#5878)

* fix(dolt): make schema parity oracle deterministic and ignored-column-aware (be-0v3l)

TestCLIBundleMatchesRuntimeCommittedSchema failed for two independent
reasons. Cause 1 (a random snapshot category reading as empty on a
freshly migrated store) was fixed in be-itm5. This addresses Cause 2,
the remaining stable failure: leases.granted_node is added by the
ignored migration stream (migrations/ignored/0016_add_lease_granted_node.up.sql),
so it exists in the runtime schema but never in the CLI bundle, and the
oracle's exclusions were all table-level -- none could exclude a single
column on an otherwise main-stream table.

- Iterate committedSchemaSnapshotQueries() in sorted key order in both
  snapshot helpers, instead of ranging over the map directly, removing
  the run-to-run variation in which query hits the DB first.
- Exclude leases.granted_node from the columns query, and extend the
  comment to state that the ignored stream owns both whole tables and
  individual columns on main-stream tables.

Verified live (podman-backed Dolt, DOCKER_HOST=unix:///run/user/1000/podman/podman.sock):
unmodified test fails deterministically 2/2 on the single granted_node
diff (genuine RED, no code change needed to observe it); fixed test
passes 6/6 consecutive -count=1 runs (GREEN).

Agent-Signature: claude-code-claude-sonnet-5-unknown-reasoning on behalf of Jim Wordelman

* test(feat): red — Fix: first read after a migrating store open fails with table-not-found and never self-heals (refs be-itm5)

* feat: green — Fix: first read after a migrating store open fails with table-not-found and never self-heals (refs be-itm5)

* docs(release-gates): be-krza3 gate PASS 7/7 — schema parity oracle + pool-heal cherry-pick

Deploy bead be-krza3, review be-8xjjg (PASS round 2), build be-pouv5.
Commit e0c39aa25b7429ddfc88ca085b78f038b80bf87a rebased onto origin/main
tip d38ac728b (0 conflicts). Pushed to headfork per rig precedent —
origin push disabled, and attempt_bounded_self_rebase's internal push
is still hardcoded to origin (be-z3iuv, unfixed as of this gate despite
a mail claiming otherwise).
This commit is contained in:
Jim Wordelman 2026-08-20 06:35:53 -07:00 • committed by GitHub
commit 072f0f8799
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 287 additions and 12 deletions

View file

@ -378,3 +378,38 @@ func TestPool_CloseReleasesUnderlyingConnections(t *testing.T) {
t.Errorf("opens=%d closes=%d — Close should release every opened connection", opens, closes)
}
}
// --- post-migration pool rebuild gate --------------------------------------
// TestRebuildPoolAfterMigration_NoopWhenNotMigrated is the be-itm5 Done-when
// guard: a non-migrating open (applied == 0, the common re-open-of-an-
// already-migrated-database path) must not pay for a pool rebuild it does
// not need. applied == 0 must return before ever touching s.db.
func TestRebuildPoolAfterMigration_NoopWhenNotMigrated(t *testing.T) {
t.Parallel()
db, drv := openMockDB(t)
t.Cleanup(func() { _ = db.Close() })
// Warm up the one connection newServerMode's startup Ping would have
// already pinned into s.db before initSchema/rebuildPoolAfterMigration
// ever run. Without this, the baseline is 0 opens and the assertion
// below can't distinguish "no-op" from "never dialed anything".
if err := db.PingContext(context.Background()); err != nil {
t.Fatalf("warm-up ping: %v", err)
}
s := &DoltStore{db: db, connStr: "ignored", cfg: &Config{}}
before := s.db
if err := s.rebuildPoolAfterMigration(context.Background(), 0); err != nil {
t.Fatalf("rebuildPoolAfterMigration(applied=0): %v", err)
}
if s.db != before {
t.Errorf("pool was rebuilt when applied=0; must be a no-op for a non-migrating open")
}
if opens := drv.opens.Load(); opens != 1 {
t.Errorf("driver opens = %d, want 1 (applied=0 must not open a new connection)", opens)
}
}

View file

@ -0,0 +1,69 @@
//go:build integration
package dolt
import (
"path/filepath"
"testing"
)
// TestMigratingOpen_FirstReadSucceeds reproduces be-itm5 (be-jjv2 harness):
// a store open that applies migrations left the connection sitting in
// store.db pinned to the pre-migration Dolt session root. Its first
// statement read that stale root and failed with "table not found"; a
// FAILING query never advances the session root, so the error did not
// self-heal on retry — only an unrelated SUCCEEDING query (e.g. an
// information_schema probe) advanced it. See /var/tmp/be-jjv2-dump for the
// full evidence trail this test is derived from.
//
// The test issues exactly one query — the very first statement against the
// store after New() returns — because a second, unrelated query would mask
// the bug by advancing the session root itself.
func TestMigratingOpen_FirstReadSucceeds(t *testing.T) {
skipIfNoDolt(t)
t.Parallel()
acquireTestSlot()
t.Cleanup(releaseTestSlot)
ctx, cancel := testContext(t)
defer cancel()
dbName := uniqueTestDBName(t)
runtimeDir := filepath.Join(t.TempDir(), "runtime")
store, err := New(ctx, &Config{
Path: runtimeDir,
CommitterName: "test",
CommitterEmail: "test@example.com",
ServerHost: "127.0.0.1",
ServerPort: testServerPort,
Database: dbName,
CreateIfMissing: true,
})
if err != nil {
t.Fatalf("New (migrating open): %v", err)
}
t.Cleanup(func() { _ = store.Close() })
// The FIRST statement against the store after a migrating open. Do not
// add any query before this one — a single successful statement (even an
// information_schema probe) masks the bug entirely.
rows, err := store.db.QueryContext(ctx, "SELECT `key` FROM config")
if err != nil {
t.Fatalf("first read after migrating open: %v (this is be-itm5: a connection "+
"established before migrations ran stays pinned to the pre-migration "+
"session root)", err)
}
defer rows.Close()
n := 0
for rows.Next() {
n++
}
if err := rows.Err(); err != nil {
t.Fatalf("iterating config rows: %v", err)
}
if n == 0 {
t.Fatalf("first read after migrating open returned 0 rows; want the migrated config seed data")
}
}

View file

@ -62,9 +62,10 @@ func TestCLIBundleMatchesRuntimeCommittedSchema(t *testing.T) {
func cliCommittedSchemaSnapshot(t *testing.T, dir string) []string {
t.Helper()
queries := committedSchemaSnapshotQueries()
var snapshot []string
for name, query := range committedSchemaSnapshotQueries() {
for _, row := range queryCSV(t, dir, query) {
for _, name := range sortedSnapshotQueryNames(queries) {
for _, row := range queryCSV(t, dir, queries[name]) {
snapshot = append(snapshot, name+"|"+row["line"])
}
}
@ -78,8 +79,10 @@ func runtimeCommittedSchemaSnapshot(t *testing.T, db *sql.DB) []string {
ctx, cancel := testContext(t)
defer cancel()
queries := committedSchemaSnapshotQueries()
var snapshot []string
for name, query := range committedSchemaSnapshotQueries() {
for _, name := range sortedSnapshotQueryNames(queries) {
query := queries[name]
rows, err := db.QueryContext(ctx, query)
if err != nil {
t.Fatalf("query runtime %s snapshot: %v", name, err)
@ -102,10 +105,29 @@ func runtimeCommittedSchemaSnapshot(t *testing.T, db *sql.DB) []string {
return snapshot
}
// sortedSnapshotQueryNames returns the query names in sorted order so both
// snapshot helpers issue queries in a fixed sequence. The runtime side reads
// through a session whose root only advances once a query has succeeded
// (be-itm5); ranging over the map directly let a different category run
// first on every invocation and made whichever one drew that slot read as
// spuriously empty.
func sortedSnapshotQueryNames(queries map[string]string) []string {
names := make([]string, 0, len(queries))
for name := range queries {
names = append(names, name)
}
sort.Strings(names)
return names
}
func committedSchemaSnapshotQueries() map[string]string {
// Wisp tables are owned by the ignored-migration stream and are intentionally
// excluded from the committed-schema parity oracle. CLI substitutions that
// touch wisps still have focused coverage in internal/storage/schema tests.
// The ignored-migration stream owns objects at two levels: whole tables
// (wisps, excluded below by name/prefix) and individual columns bolted
// onto an otherwise main-stream table (leases.granted_node, added by
// migrations/ignored/0016_add_lease_granted_node.up.sql). Both levels are
// intentionally excluded from the committed-schema parity oracle, which
// compares the main migration stream only. CLI substitutions that touch
// wisps still have focused coverage in internal/storage/schema tests.
return map[string]string{
"tables": `
SELECT CONCAT('table|', t.table_name, '|', t.table_type) AS line
@ -125,7 +147,8 @@ JOIN information_schema.tables t
WHERE c.table_schema = DATABASE()
AND t.table_name NOT IN ('ignored_schema_migrations', 'local_metadata', 'repo_mtimes', 'wisps')
AND LEFT(t.table_name, 5) <> 'wisp_'
AND LEFT(t.table_name, 5) <> 'dolt_'`,
AND LEFT(t.table_name, 5) <> 'dolt_'
AND NOT (c.table_name = 'leases' AND c.column_name = 'granted_node')`,
"indexes": `
SELECT CONCAT('index|', s.table_name, '|', s.index_name, '|', LPAD(s.seq_in_index, 3, '0'), '|',
s.column_name, '|', s.non_unique, '|', COALESCE(s.sub_part, ''), '|',

View file

@ -318,6 +318,7 @@ type DoltStore struct {
// instance only (storage.EventsJournalConfigurer); never process-global.
eventsJournalEnabled atomic.Bool
connStr string // Connection string for reconnection
cfg *Config // Config this store was opened with (rebuildPoolAfterMigration)
serverEndpoint string // Exact endpoint bound to bootstrap reset authority
mu sync.RWMutex // Protects concurrent access
readOnly bool // True if opened in read-only mode
@ -1949,6 +1950,7 @@ func newServerMode(ctx context.Context, cfg *Config) (*DoltStore, error) {
database: cfg.Database,
localActiveDatabaseDir: resolveLocalActiveDatabaseDir(cfg),
connStr: connStr,
cfg: cfg,
serverEndpoint: serverEndpointIdentity(cfg),
breaker: breaker,
committerName: cfg.CommitterName,
@ -2019,9 +2021,19 @@ func newServerMode(ctx context.Context, cfg *Config) (*DoltStore, error) {
// ReadOnly for schema — the forward-drift guard above still protects a stale client
// binary.
if !cfg.ReadOnly && !cfg.Gateway {
if err := store.initSchema(ctx, dbFacts.bootstrapHeal); err != nil {
applied, err := store.initSchema(ctx, dbFacts.bootstrapHeal)
if err != nil {
return nil, fmt.Errorf("failed to initialize schema: %w", err)
}
// initSchema runs migrations over a separate pool (openMigrationDB).
// The Ping above already pinned a connection in store.db to the
// pre-migration session root; without a rebuild, the first read
// through that stale connection returns 0 rows / table-not-found
// and does not self-heal on retry (be-itm5). Only a migrating open
// (applied > 0) needs this — rebuildPoolAfterMigration no-ops otherwise.
if err := store.rebuildPoolAfterMigration(ctx, applied); err != nil {
return nil, fmt.Errorf("failed to rebuild pool after migration: %w", err)
}
}
if isLocalHost(cfg.ServerHost) {
@ -2654,7 +2666,7 @@ func initSchemaOnDBWithRetryAndGateBootstrapHeal(
return applied, err
}
func (s *DoltStore) initSchema(ctx context.Context, bootstrapHeal *schema.FreshBootstrapHealCapability) error {
func (s *DoltStore) initSchema(ctx context.Context, bootstrapHeal *schema.FreshBootstrapHealCapability) (int, error) {
// Schema migrations can run arbitrarily long (e.g. full-table recomputes
// such as the is_blocked backfill in migration 0047). The main connection
// pool sets a 10s ReadTimeout (see buildServerDSN); a slow migration over
@ -2664,7 +2676,7 @@ func (s *DoltStore) initSchema(ctx context.Context, bootstrapHeal *schema.FreshB
// is governed by the caller's context, not a fixed deadline.
migDB, err := s.openMigrationDB()
if err != nil {
return err
return 0, err
}
defer migDB.Close()
// #4259: refuse to silently apply pending migrations to a remote-backed,
@ -2705,8 +2717,8 @@ func (s *DoltStore) initSchema(ctx context.Context, bootstrapHeal *schema.FreshB
gate := func(ctx context.Context, db *sql.DB) error {
return schema.CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(ctx, db, s.remote, s.hasPersistedCLIRemote, adopt)
}
_, err = initSchemaOnDBWithRetryAndGateBootstrapHeal(ctx, migDB, gate, bootstrapHeal, s.serverEndpoint)
return err
applied, err := initSchemaOnDBWithRetryAndGateBootstrapHeal(ctx, migDB, gate, bootstrapHeal, s.serverEndpoint)
return applied, err
}
// ApplySchemaMigrations runs idempotent schema migrations under the
@ -2740,6 +2752,36 @@ func (s *DoltStore) openMigrationDB() (*sql.DB, error) {
return db, nil
}
// rebuildPoolAfterMigration replaces the main connection pool (s.db) after a
// migrating open. Migrations run over a separate one-off pool
// (openMigrationDB); a connection already pooled in s.db before migrations
// ran (e.g. the startup Ping in newServerMode) stays pinned to the
// pre-migration Dolt session root, so the first read through it returns 0
// rows / table-not-found and does not self-heal on retry (be-itm5). A
// non-migrating open (applied == 0 — the common re-open-of-an-
// already-migrated-database path) has no stale state to fix and must return
// before touching s.db or dialing anything.
func (s *DoltStore) rebuildPoolAfterMigration(ctx context.Context, applied int) error {
if applied == 0 {
return nil
}
newDB, err := sql.Open("mysql", s.connStr)
if err != nil {
return fmt.Errorf("rebuild pool after migration: %w", err)
}
applyPoolLimits(newDB, s.cfg)
if err := newDB.PingContext(ctx); err != nil {
_ = newDB.Close()
return fmt.Errorf("rebuild pool after migration: %w", err)
}
old := s.db
s.db = newDB
return old.Close()
}
// IsClosed returns true if the store has been closed.
func (s *DoltStore) IsClosed() bool {
return s.closed.Load()

View file

@ -0,0 +1,106 @@
# Release gate — CLI/runtime schema parity oracle + pool-heal cherry-pick (be-krza3)
- **Deploy bead:** be-krza3 (needs-deploy, routed beads/deployer)
- **Build bead:** be-pouv5 — tdd_green `e0c39aa25b7429ddfc88ca085b78f038b80bf87a` (no separate red commit for this round; fix lives in the test oracle plus an already-cherry-picked store.go fix)
- **Review bead:** be-8xjjg — verdict **PASS** (round 2), closed with reason `pass`
- **Commit deployed:** `e0c39aa25b7429ddfc88ca085b78f038b80bf87a` (deploy source; branch cut from exactly this SHA)
- **Source branch:** `builder/be-0v3l` — provenance only, never a push target
- **Related beads:** be-0v3l (original bug — CLI/runtime schema parity oracle mishandles ignored-stream columns), be-itm5 (canonical `rebuildPoolAfterMigration` fix, cherry-picked byte-for-byte — patch-id verified exact match `cdcf9ed1e97fc4e64a28ed01368192718ebff0e9`; already 3-round-reviewed and mayor-waived on its own gate), be-3c78s (pre-existing, unrelated P0 cross-tenant isolation bug that explains 14 non-diff-owned full-package failures; since fixed via PR #5836 — does not retroactively invalidate the "not caused by this diff" attribution, since the reviewer's snapshot was accurate at the time it was taken)
- **Deploy branch:** `deploy/be-krza3-gate`, derived mechanically via `resolve_deploy_branch_target`
- **Push target:** `headfork` (`quad341/beads-sec003-contrib.git`) — `origin` push is disabled by design on this rig (`DISABLED-upstream-is-fetch-only-push-to-fork-and-PR`)
- **PR:** (recorded below once opened)
- **Evaluated:** 2026-08-20 by beads/deployer
## Scope
The CLI/runtime schema parity oracle (`schema_cli_parity_integration_test.go`)
could not express ignored-stream columns and read a random category as empty,
producing false parity mismatches. Fix adds a static exclusion clause for the
known ignored column and a deterministic map-iteration helper
(`sortedSnapshotQueryNames`) so oracle output order stops depending on Go map
iteration order.
Round-2 rework additionally incorporates be-itm5's canonical
`rebuildPoolAfterMigration` fix (`store.go`) — cherry-picked byte-for-byte
(confirmed via `git patch-id --stable`, exact match) — because with `store.go`
reverted to its pre-itm5 state, this round's own test files fail to *compile*,
making the original spec's Done-when criteria (#3 non-determinism, #4 no
production files) mechanically contradictory. Round-1's reviewer directed the
store.go inclusion as the correct resolution (documented in build bead
be-pouv5's notes); round-2's reviewer independently re-verified that authority
chain rather than accepting the carve-out on say-so, and independently
re-proved the compile-fails-without-it claim.
Single feature theme: both commits in the deploy range cite be-krza3, be-0v3l,
or be-itm5, confirmed by `assert_deploy_ancestry_scope` (see criterion 6).
## Gate criteria
| # | Criterion | Verdict | Evidence |
|---|-----------|---------|----------|
| 0 | Already merged? (pre-flight) | **NO** | `gh pr list --search "be-krza3 OR be-8xjjg OR e0c39aa25... OR 7d294b4b5..."` (state all) → empty. `git merge-base --is-ancestor e0c39aa25... origin/main` → not an ancestor. Proceeded. |
| 1 | Review PASS present | **PASS** | be-8xjjg, `verdict: pass`, round 2, closed with reason `pass`. |
| 2 | Acceptance criteria met | **PASS** | be-8xjjg `decide_findings`: scope-authorization concern (store.go touched) resolved against the documented round-1-reviewer authority chain, not builder/reviewer say-so; round-2 independently RED/GREEN-proved store.go's inclusion is compile-mechanically necessary; `uncovered_criteria: none`. Non-determinism criterion independently re-verified: `TestCLIBundleMatchesRuntimeCommittedSchema -count=5` fresh run, 5/5 PASS. |
| 3 | Tests pass (diff-owned-SKIP=FAIL rule) | **PASS** | 9/9 diff-owned tests PASS, 0 FAIL, 0 SKIP, 19.002s wall, isolated run (test names: TestApplyPoolLimits_Defaults/Overrides/ClampsIdleToOpen, TestPool_SequentialQueriesReuseSingleConnection, TestPool_ConcurrentQueriesRespectMaxOpen, TestPool_CloseReleasesUnderlyingConnections, TestRebuildPoolAfterMigration_NoopWhenNotMigrated, TestMigratingOpen_FirstReadSucceeds, TestCLIBundleMatchesRuntimeCommittedSchema). Real Dolt-container execution (rootless podman), not a SKIP-substitute result. Independently re-verified by deployer after rebase onto current origin/main tip: `gofmt -l` (4 diff-owned files) clean, `go build ./...` clean, `go vet ./...` clean. |
| 3a | Pre-existing-failure attribution (non-diff-owned) | **PASS** | Full-package run (193 tests) shows 14 FAIL, all non-diff-owned, all in `federation_test.go`. 13/14 fail at a uniform ~45s (pre-existing per-test timeout under package-scale parallel-slot contention, not diff-caused); the 14th (`TestFederationDatabaseIsolation`) is the tracked pre-existing P0 be-3c78s, same assertion text/location. Matched base-ref (merge-base `6ec78f3a2`) narrowed comparison on the same 14 tests reproduces identically: 13 PASS + 1 FAIL (same test, same assertion). Diff changes nothing about these 14 tests' outcomes — confirmed by direct comparison, not assumed. All 4 attribution clauses satisfied: not diff-owned, tracked bead (be-3c78s / capacity characteristic documented on be-pouv5), proven pre-existing at base-ref, no path overlap with the diff. |
| 3b | Policy / lint lane | **PASS** | `golangci-lint run` against the package path: "0 issues" (be-8xjjg's own from-scratch run — 3rd independent clean gofmt/vet/lint verification on this diff, after round-1 reviewer and round-2 builder). |
| 4 | No open HIGH findings | **PASS** | be-8xjjg: explicit OWASP Top 10 walk (injection, auth, access control, XXE/SSRF/deserialization/XSS, misconfig, vulnerable deps, logging) — none blocker/major/minor. store.go's unlocked pool swap verified safe (single call site, pre-publish, in constructor). Zero style findings. |
| 5 | Branch clean | **PASS** | Working tree clean at HEAD after restore + rebase re-verification (`git status --short` empty). |
| 6 | Diverges cleanly from main | **PASS** | `assert_deploy_ancestry_scope origin/main 7d294b4b5... be-krza3 be-0v3l be-itm5` → rc=0 (re-run post-rebase; no `.claude/**` paths, all commits cite an accepted bead id). `attempt_bounded_self_rebase deploy/be-krza3-gate main` completed the rebase itself cleanly (0 conflicts) onto origin/main tip `d38ac728b`: BEFORE_SHA=`e0c39aa25b7429ddfc88ca085b78f038b80bf87a`, AFTER_SHA=`7d294b4b5ae49561f6da272ba2a04eff89f44c79`. Its internal force-with-lease push (hardcoded to `origin`) then failed rc=13 against this rig's disabled origin remote — the known be-z3iuv infra gap, not a real conflict; the rebase result itself is valid and unaffected. `assert_safe_push_target deploy/be-krza3-gate` → rc=0. |
| 7 | Single feature theme | **PASS** | be-0v3l (oracle fix) + authorized be-itm5 cherry-pick (compile-necessary dependency), both cited across the commit range; ancestry-scope check found no stray commits. |
## Tests run by deployer on the cut branch (independent of review)
| Check | Result |
|---|---|
| `gofmt -l` (4 diff-owned files: connection_pool_test.go, post_migration_pool_heal_integration_test.go, schema_cli_parity_integration_test.go, store.go) | clean (no output) |
| `go build ./...` | clean, exit 0 |
| `go vet ./...` | clean, exit 0 |
Re-run after the branch was rebased onto the current `origin/main` tip
(`d38ac728b`) and after this session recovered the branch from a dangling
commit — this worktree's `pre_start` hard-reset the local branch pointer back
to `origin/main` between rounds, but `origin/main` had not moved, the rebased
commit object (`AFTER_SHA`) was still present in the local object store
(`git cat-file -e`), and the bead's own notes already recorded the SHA as
durable state — so the branch was restored via `git reset --hard AFTER_SHA`
rather than redone, and every gate check re-run fresh against the restored
state before proceeding. Full container-backed test execution (9/9 diff-owned
PASS) was not re-run by the deployer — already performed by the reviewer with
real CI-equivalent commands and logged evidence (be-8xjjg); PR CI provides the
additional independent real-world confirmation.
## Push target
`origin` (`gastownhall/beads`) denies push
(`DISABLED-upstream-is-fetch-only-push-to-fork-and-PR` sentinel); `headfork`
(`quad341/beads-sec003-contrib.git`) accepts, per established precedent on
this rig (be-r3ysh). PR opens cross-repo against `gastownhall/beads:main` with
head `quad341:deploy/be-krza3-gate`.
Note on be-z3iuv: this gate's criterion 6 push used a direct, manual push to
`headfork` rather than a fresh invocation of `attempt_bounded_self_rebase`,
because that function's *internal* force-with-lease push is still hardcoded to
`origin` at the canonical path
(`/home/jaword/projects/gc-management/packs/actual/deployer/scripts/rebase-resolve-lib.sh`,
line 489) as of this gate's evaluation — independently re-verified by reading
the file directly and confirming `f195bbdbe` is not an ancestor of
`gc-management` main (`306348db3`), despite a mayor mail (`gm-wisp-wt8fd8`)
claiming this fix already shipped. The rebase itself (performed by that same
function in an earlier round) succeeded cleanly and is unaffected by its
push-step bug; only the internal push call was bypassed here.
## Merge authority
`gastownhall/beads` is a contributor-only repo for this rig — no rig agent has
merge access. Per established precedent (be-vc1m, be-gd3v, be-79jh, be-39ss,
be-pp7e, be-r3ysh), the deployer's job ends at the open, verified PR. No
merge-request is routed to mayor/mpr; gate result reported to mayor via mail.
## Verdict
**PASS 7/7** — branch recovered and re-verified after a local ref reset,
rebase re-confirmed clean against current main, build/vet/gofmt independently
re-run, pushed to headfork, PR opened and confirmed OPEN/MERGEABLE. Standing
down; PR CI will provide further real-world confirmation but is not a
precondition for this gate.