@substrat-run/adapter-cloudflare 0.120.0 → 0.122.0

package/dist/control-plane-do.js

@@ -1,7 +1,7 @@
 import { DurableObject } from 'cloudflare:workers';
-import { IMPERSONATION_COLUMNS, IMPERSONATION_DDL, impersonationByIdQuery, impersonationListQuery, impersonationRowValues, ISSUE_RETENTION_DAYS, OPS_FAILURE_RETENTION_DAYS, SWEEP_RUN_RETENTION_DAYS, SWEEP_RUNS_INTENT_INDEX, sweepRunsIntentHasKind, MODEL_USAGE_RETENTION_DAYS, isPrimaryScope, resolveVerticalInstanceFrom, } from '@substrat-run/kernel';
-import { splitSqlStatements } from './scope-do.js';
-import { assertReplayableDump } from '@substrat-run/contracts';
+import { IMPERSONATION_COLUMNS, IMPERSONATION_DDL, impersonationByIdQuery, impersonationListQuery, impersonationRowValues, ISSUE_RETENTION_DAYS, OPS_FAILURE_RETENTION_DAYS, SWEEP_RUN_RETENTION_DAYS, SWEEP_RUNS_INTENT_INDEX, sweepRunsIntentHasKind, SYSTEM_SWITCHES_BACKFILL_SQL, SYSTEM_SWITCHES_DDL, forgetSystemSwitchesOf, listSystemSwitchRecords, recordSystemSwitchedOff, recordSystemSwitchedOn, restoreSystemSwitchRecord, switchedOffModulesOf, systemSwitchRecordsOf, systemSwitchesTableExists, VERSION_MIGRATIONS_DDL, splitVersionMigrationsBatch, versionMigrationsOf, versionsAwaitSplit, writeVersionMigrations, MODEL_USAGE_RETENTION_DAYS, ulid, isPrimaryScope, resolveVerticalInstanceFrom, } from '@substrat-run/kernel';
+import { splitSqlStatements, switchSqlOver } from './scope-do.js';
+import { assertReplayableDump, opsFailureFingerprint } from '@substrat-run/contracts';
 /** snake_case row → the camelCase `issueEntry` shape (#1233). */
 function issueOf(r) {
     return {
@@ -217,10 +217,16 @@ const DIRECTORY_DDL = `
     -- The full DeployManifest as pushed (JSON). What promote/backout rebuild the
     -- serving upload's metadata from — the archive script stores the module BYTES,
     -- this stores the shape (entry, compat, doClasses, bindings). NULL = pre-#286 push.
+    -- Stored WITHOUT its SQL migrations, which live in vertical_version_migrations (#1764).
     manifest_json     TEXT,
+    -- How many migration rows the version stored. NULL = it carries no SQL to show.
+    migration_count   INTEGER,
+    -- 1 once the SQL is out of manifest_json. NULL = stored before #1764, not yet backfilled.
+    migrations_split  INTEGER,
     created_at        TEXT NOT NULL,
     UNIQUE (vertical_slug, version)
   );
+  ${VERSION_MIGRATIONS_DDL}
   CREATE TABLE IF NOT EXISTS vertical_channels (
     vertical_slug TEXT NOT NULL,
     channel       TEXT NOT NULL,
@@ -407,6 +413,7 @@ const DIRECTORY_DDL = `
     PRIMARY KEY (scope_id, subject_id)
   );
   ${IMPERSONATION_DDL}
+  ${SYSTEM_SWITCHES_DDL}
   CREATE TABLE IF NOT EXISTS _substrat_admin_log (
     id TEXT PRIMARY KEY,
     actor TEXT NOT NULL,
@@ -541,6 +548,12 @@ const DIRECTORY_DDL = `
   CREATE INDEX IF NOT EXISTS _substrat_model_usage_at ON _substrat_model_usage (at);
   CREATE INDEX IF NOT EXISTS scopes_tenant ON scopes (tenant_id, scope_id);
 `;
+/**
+ * `DIRECTORY_DDL`, split once into what runs before the column additions and after (#1764).
+ * Checked at module load: it is a constant, so a drift is a build that never works rather
+ * than a directory that quietly skips or double-runs a statement.
+ */
+export const DIRECTORY_DDL_PLAN = assertDirectoryDdlPlan(planDirectoryDdl(DIRECTORY_DDL));
 /** The scope columns added after the directory's first shape shipped. */
 const SCOPE_COLUMNS_ADDED = [
     'parent_scope_id TEXT',
@@ -560,15 +573,164 @@ const SCOPE_COLUMNS_ADDED = [
     'serving_ref TEXT',
     'archived_at TEXT',
 ];
+/**
+ * A directory DDL's statements in the order `applyDirectorySchema` runs them: `loop` before
+ * the column additions, `afterColumns` after. `VERSION_MIGRATIONS_DDL` indexes a column a
+ * directory from before #1764 gets only from those additions, so its statements are held back.
+ *
+ * Held back by EXACT statement, never by a name a statement contains: a later statement that
+ * merely mentions the table runs in the loop like any other, rather than being skipped. And
+ * `missing` names any held-back statement the DDL does not carry, which would mean the
+ * fragment and the DDL had parted company (its test holds it empty).
+ */
+export function planDirectoryDdl(ddl) {
+    const all = splitSqlStatements(ddl);
+    const afterColumns = splitSqlStatements(VERSION_MIGRATIONS_DDL);
+    const held = new Set(afterColumns);
+    return {
+        loop: all.filter((stmt) => !held.has(stmt)),
+        afterColumns,
+        missing: afterColumns.filter((stmt) => !all.includes(stmt)),
+    };
+}
+/** Refuses a plan whose held-back statements the DDL does not carry; returns it otherwise. */
+export function assertDirectoryDdlPlan(plan) {
+    if (plan.missing.length > 0) {
+        throw new Error(`the directory DDL does not carry ${plan.missing.length} statement(s) of VERSION_MIGRATIONS_DDL — ` +
+            `interpolate the fragment whole: ${plan.missing[0]}`);
+    }
+    return plan;
+}
+/**
+ * The pause before each #1764 backfill batch. A batch holds the directory DO, which every
+ * control-plane request goes through, so batches are spaced rather than run back to back.
+ */
+const BACKFILL_PAUSE_MS = 1000;
+/** The longest a failing #1764 backfill waits before it tries again. */
+const BACKFILL_BACKOFF_MAX_MS = 60 * 60 * 1000;
+/**
+ * The actor a directory's own ops-failure rows carry: the directory DO acting for itself, with
+ * no request behind it. A fixed ULID, as the sweeper's is.
+ */
+export const DIRECTORY_ACTOR = '01JZ00000000000000000000DR';
+/** The operation a failing #1764 backfill is recorded under in `_substrat_ops_failures`. */
+export const BACKFILL_OPERATION = 'directory.version-migrations-backfill';
+/**
+ * Where the #1764 backfill keeps how many batches have failed in a row: in the DO's storage,
+ * not in the instance, so an eviction between failures does not reset the backoff (or keep
+ * `backoff-capped` from ever being reached). Cleared only after a batch succeeds.
+ */
+export const BACKFILL_FAILURES_KEY = 'versionMigrationsBackfillFailures';
+/** How long the backfill waits after its `failures`-th failure in a row: doubling, capped. */
+export function backfillBackoffMs(failures) {
+    return Math.min(BACKFILL_PAUSE_MS * 2 ** failures, BACKFILL_BACKOFF_MAX_MS);
+}
 export class ControlPlaneDO extends DurableObject {
     sql;
+    /** The directory's store as the kernel's SQL handle — the switch record's helpers (#1674). */
+    kernelSql;
+    /** Settles once the constructor's #1764 backfill check has run (awaited by the tests). */
+    backfillArmed;
     constructor(ctx, env) {
         super(ctx, env);
         this.sql = ctx.storage.sql;
-        for (const stmt of splitSqlStatements(DIRECTORY_DDL)) {
+        this.kernelSql = switchSqlOver(this.sql);
+        this.applyDirectorySchema();
+        this.backfillArmed = ctx.blockConcurrencyWhile(() => this.armVersionMigrationsBackfill());
+    }
+    /**
+     * Schedule the #1764 backfill when a version still carries its SQL in its manifest.
+     *
+     * Only the probe runs here, never the backfill: this is on the constructor's path, and a
+     * directory DO that cannot construct is a control plane that is down. The probe reads the
+     * partial index of versions not yet split, so it costs the same for ten versions or ten
+     * thousand. The alarm then moves a bounded batch per run. A restore arms its own new episode
+     * instead (`importDump`).
+     */
+    async armVersionMigrationsBackfill() {
+        if (!versionsAwaitSplit(this.kernelSql))
+            return;
+        // An alarm already set is kept: it is the backfill's own next run, and a backoff retry
+        // pulled forward to 1 s by any ordinary request would make the backoff meaningless.
+        if ((await this.ctx.storage.getAlarm()) !== null)
+            return;
+        await this.ctx.storage.setAlarm(Date.now() + BACKFILL_PAUSE_MS);
+    }
+    /**
+     * One bounded batch of the #1764 backfill, then re-arm while versions are left. A batch
+     * and its progress marks commit together, so a run that fails moved nothing.
+     *
+     * A failure is caught and the alarm re-armed with a doubling backoff (capped at an hour),
+     * rather than thrown: workerd's own alarm retries give up after a few attempts, and the
+     * backfill would then stay stopped until the DO was next constructed. Nothing is lost
+     * meanwhile, because a version the backfill has not reached reads from its manifest.
+     */
+    async alarm() {
+        let more;
+        try {
+            more = this.ctx.storage.transactionSync(() => splitVersionMigrationsBatch(this.kernelSql)).more;
+        }
+        catch (err) {
+            const failures = ((await this.ctx.storage.get(BACKFILL_FAILURES_KEY)) ?? 0) + 1;
+            await this.ctx.storage.put(BACKFILL_FAILURES_KEY, failures);
+            const delay = backfillBackoffMs(failures);
+            console.error(`substrat: version-migrations backfill failed, retrying in ${delay} ms`, err);
+            // Visible where staff look, not only in logs: once when it starts failing, and once
+            // more when the backoff reaches its cap (a backfill that is stuck, not unlucky).
+            const stage = failures === 1 ? 'first-failure'
+                : delay === BACKFILL_BACKOFF_MAX_MS && backfillBackoffMs(failures - 1) < delay ? 'backoff-capped'
+                    : null;
+            if (stage) {
+                try {
+                    this.recordOpsFailure({
+                        id: ulid(), actor: DIRECTORY_ACTOR, operation: BACKFILL_OPERATION, stage,
+                        tenant_id: null, scope_id: null, vertical: null, version: null, status: null,
+                        message: `failed ${failures} time(s) in a row, retrying in ${delay} ms: ${String(err)}`.slice(0, 2000),
+                        reference: null, origin: null, code: null,
+                        fingerprint: opsFailureFingerprint({ operation: BACKFILL_OPERATION, stage }), at: new Date().toISOString(),
+                    });
+                }
+                catch (recordErr) {
+                    console.error('substrat: could not record the version-migrations backfill failure', recordErr);
+                }
+            }
+            await this.ctx.storage.setAlarm(Date.now() + delay);
+            return;
+        }
+        if ((await this.ctx.storage.get(BACKFILL_FAILURES_KEY)) !== undefined) {
+            await this.ctx.storage.delete(BACKFILL_FAILURES_KEY);
+        }
+        if (more)
+            await this.ctx.storage.setAlarm(Date.now() + BACKFILL_PAUSE_MS);
+    }
+    /**
+     * The DDL, then the migrations for a directory that predates part of it. Run on every
+     * construction and after a directory restore, which may land a dump from before a table.
+     *
+     * The schedule switch's record (#1674) is backfilled from the admin log on a run that
+     * creates its table, and its table is created in the SAME transaction as the backfill
+     * (Copilot review): the gate is "the table does not exist yet", so a table committed ahead
+     * of a backfill that then failed would read as already migrated on every later run. On
+     * such a run its statements are held back from the loop below and run with the backfill.
+     */
+    applyDirectorySchema() {
+        const switchRecordIsNew = !systemSwitchesTableExists(this.kernelSql);
+        for (const stmt of DIRECTORY_DDL_PLAN.loop) {
+            if (switchRecordIsNew && stmt.includes('_substrat_system_switches'))
+                continue;
             this.sql.exec(stmt);
         }
         this.ensureDirectoryColumns();
+        // #1764's, held back by `planDirectoryDdl`: its index names a column added just above.
+        for (const stmt of DIRECTORY_DDL_PLAN.afterColumns)
+            this.sql.exec(stmt);
+        if (switchRecordIsNew) {
+            this.ctx.storage.transactionSync(() => {
+                for (const stmt of splitSqlStatements(SYSTEM_SWITCHES_DDL))
+                    this.sql.exec(stmt);
+                this.sql.exec(SYSTEM_SWITCHES_BACKFILL_SQL);
+            });
+        }
     }
     /**
      * The directory's own migration path (control-plane.md §7). A singleton DO that
@@ -761,6 +923,9 @@ export class ControlPlaneDO extends DurableObject {
         // Push provenance (git CI vs a terminal), as pushed-alongside JSON. NULL = pushed
         // before origin tracking, or by an old CLI.
         this.addColumn('vertical_versions', 'origin_json TEXT');
+        // #1764: the SQL migrations moved out of the manifest, and the backfill's progress.
+        this.addColumn('vertical_versions', 'migration_count INTEGER');
+        this.addColumn('vertical_versions', 'migrations_split INTEGER');
         // #33: the SKU flag learns to express a plan. All nullable — a legacy row
         // reads as a perpetual boolean flag, exactly its pre-widening semantics.
         this.addColumn('_substrat_entitlements', 'expires_at TEXT');
@@ -798,9 +963,12 @@ export class ControlPlaneDO extends DurableObject {
      * did before the restore, which is the opposite of what a recovery is for.
      */
     exportDump() {
+        // Not `_cf_*` either: workerd's own tables (the #1764 backfill's alarm creates
+        // `_cf_METADATA`), which are not the directory's and which it refuses to drop on restore.
         const defs = this.sql
             .exec(`SELECT name, sql FROM sqlite_master
-          WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND sql IS NOT NULL
+          WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT GLOB '_cf_*'
+            AND sql IS NOT NULL
           ORDER BY name`)
             .toArray();
         return defs.map(({ name, sql }) => {
@@ -831,8 +999,10 @@ export class ControlPlaneDO extends DurableObject {
     async importDump(tables) {
         await this.ctx.storage.transaction(async () => {
             this.sql.exec('PRAGMA defer_foreign_keys = ON');
+            // `_cf_*` is workerd's, and dropping it is refused (SQLITE_AUTH), as `exportDump` says.
             const existing = this.sql
-                .exec(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'`)
+                .exec(`SELECT name FROM sqlite_master
+            WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT GLOB '_cf_*'`)
                 .toArray();
             for (const { name } of existing)
                 this.sql.exec(`DROP TABLE IF EXISTS "${name}"`);
@@ -855,9 +1025,21 @@ export class ControlPlaneDO extends DurableObject {
         // Outside the transaction, like the constructor's own path: these are idempotent
         // schema assertions, and an ALTER that has to be tolerated (duplicate column) must
         // not take the restore's data down with it.
-        for (const stmt of splitSqlStatements(DIRECTORY_DDL))
-            this.sql.exec(stmt);
-        this.ensureDirectoryColumns();
+        this.applyDirectorySchema();
+        // A restore is a new #1764 backfill episode. It replaced the data the old failure count and
+        // backoff were about, so neither may delay or silence it: the count is cleared and the next
+        // batch armed outright, a pause away. (An ordinary construction keeps a pending alarm; this
+        // does not.) A dump taken before the backfill lands unsplit versions, so it runs again.
+        // The restore has committed by now, so failing to arm must not report it as failed: the
+        // next construction arms the backfill, since it finds none set.
+        try {
+            await this.ctx.storage.delete(BACKFILL_FAILURES_KEY);
+            if (versionsAwaitSplit(this.kernelSql))
+                await this.ctx.storage.setAlarm(Date.now() + BACKFILL_PAUSE_MS);
+        }
+        catch (err) {
+            console.error('substrat: the restore committed, but its version-migrations backfill was not armed', err);
+        }
     }
     // -- tenant registry (control-plane.md §4.1) --------------------------------
     mapTenant(r) {
@@ -941,6 +1123,7 @@ export class ControlPlaneDO extends DurableObject {
             '_substrat_roles', // operator-defined roles
             '_substrat_entitlements', // per-tenant SKU flags
             'orgs', // K-22 org records
+            '_substrat_system_switches', // #1674: the schedule switch's record, per scope
         ]) {
             this.sql.exec(`DELETE FROM ${table} WHERE tenant_id = ?`, tenantId);
         }
@@ -1145,8 +1328,10 @@ export class ControlPlaneDO extends DurableObject {
             // than degenerating into an unfiltered read of the whole fleet.
             if (filter.status.length === 0)
                 return [];
-            where.push(`status IN (${filter.status.map(() => '?').join(', ')})`);
-            params.push(...filter.status);
+            // ONE bound JSON array, not a `?` per entry (#1776): a DO binds at most 100
+            // parameters, and nothing bounds this list's length (a status may repeat).
+            where.push('status IN (SELECT value FROM json_each(?))');
+            params.push(JSON.stringify(filter.status));
         }
         if (filter.vertical) {
             where.push('vertical = ?');
@@ -1168,22 +1353,38 @@ export class ControlPlaneDO extends DurableObject {
     /**
      * The getScope gate (control-plane.md §4.1/§4.2): validate the scope belongs
      * to the tenant and both records are active, or throw the fail-closed reason.
+     *
+     * Kept for a coordinator from before #1718, which still calls it. The current one
+     * calls `scopeAccessRefusal` instead, because a throw from here reaches it untyped.
      */
     validateScopeAccess(tenantId, scopeId) {
+        const refusal = this.scopeAccessRefusal(tenantId, scopeId);
+        if (refusal)
+            throw new Error(refusal.message);
+    }
+    /**
+     * The same gate, answering its refusal as DATA (#1718). An error thrown in a Durable
+     * Object arrives at the coordinator flattened, its code gone, so a typed throw here
+     * would still reach the caller untyped (#1714 measured it). A record crosses intact, so
+     * the coordinator throws the refusal itself, typed. `code` is set only where a code is
+     * known; the lifecycle refusals keep their bare messages. Null means access is allowed.
+     */
+    scopeAccessRefusal(tenantId, scopeId) {
+        const refuse = (message) => ({ code: null, message });
         const row = this.sql
             .exec('SELECT tenant_id, status FROM scopes WHERE scope_id = ?', scopeId)
             .toArray()[0];
         if (!row || row.tenant_id !== tenantId) {
-            throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
+            return { code: 'not_found', message: `unknown scope for tenant: (${tenantId}, ${scopeId})` };
         }
         const tenantRow = this.sql
             .exec('SELECT status FROM tenants WHERE tenant_id = ?', tenantId)
             .toArray()[0];
         if (!tenantRow) {
-            throw new Error(`scope has no tenant record: (${tenantId}, ${scopeId})`);
+            return refuse(`scope has no tenant record: (${tenantId}, ${scopeId})`);
         }
         if (tenantRow.status !== 'active') {
-            throw new Error(`tenant not active (status: ${tenantRow.status}): ${tenantId}`);
+            return refuse(`tenant not active (status: ${tenantRow.status}): ${tenantId}`);
         }
         if (row.status !== 'active') {
             // A scope stuck in provisioning because its migrations failed must say so.
@@ -1194,42 +1395,68 @@ export class ControlPlaneDO extends DurableObject {
                 .exec('SELECT migration_failed_version, migration_error FROM scopes WHERE scope_id = ?', scopeId)
                 .toArray()[0];
             if (failure?.migration_failed_version) {
-                throw new Error(`migration failed for ${failure.migration_failed_version} — scope fails closed: ` +
+                return refuse(`migration failed for ${failure.migration_failed_version} — scope fails closed: ` +
                     `${failure.migration_error ?? 'unknown error'}`);
             }
-            throw new Error(`scope not active (status: ${row.status}): ${scopeId}`);
+            return refuse(`scope not active (status: ${row.status}): ${scopeId}`);
         }
+        return null;
     }
     /**
      * Validate ownership, enforce the legal transition graph (fail closed on an
      * illegal one), flip the status. Returns the previous status AND the scope's
      * vertical — both for the audit entry, sparing the coordinator a read
      * round-trip. `action` rides along only to name the illegal-transition message.
+     *
+     * Kept for a coordinator from before #1718, which still calls it. The current one
+     * calls `transitionScopeOrRefusal` instead, because a throw from here reaches it untyped.
      */
     transitionScope(tenantId, scopeId, from, to, action) {
+        const outcome = this.transitionScopeOrRefusal(tenantId, scopeId, from, to, action);
+        if (!outcome.ok)
+            throw new Error(outcome.message);
+        return { status: outcome.status, vertical: outcome.vertical };
+    }
+    /**
+     * The same transition, answering its refusal as DATA (#1718) — for the reason
+     * `scopeAccessRefusal` does. The pair check has to be answered HERE, in the same
+     * synchronous read as the write it guards: a coordinator-side pre-read cannot stand in
+     * for it, since the row can be deleted (`deleteScopeDirectory`) between the two.
+     */
+    transitionScopeOrRefusal(tenantId, scopeId, from, to, action) {
         const row = this.sql
             .exec('SELECT tenant_id, status, vertical FROM scopes WHERE scope_id = ?', scopeId)
             .toArray()[0];
         if (!row || row.tenant_id !== tenantId) {
-            throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
+            return { ok: false, code: 'not_found', message: `unknown scope for tenant: (${tenantId}, ${scopeId})` };
         }
         if (!from.includes(row.status)) {
-            throw new Error(`illegal scope transition for ${action}: ${row.status} → ${to} ` +
-                `(allowed from: ${from.join('|')})`);
-        }
-        // Stamp/clear archived_at so the reap sweep can age scopes. Entering `archived`
-        // records when; `unarchive` (→ active, a restore per §4.2) clears it so a later
-        // re-archive dates from the new event. `reaped` keeps it — it is terminal history.
-        if (to === 'archived') {
-            this.sql.exec('UPDATE scopes SET status = ?, archived_at = ? WHERE scope_id = ?', to, new Date().toISOString(), scopeId);
-        }
-        else if (to === 'active') {
-            this.sql.exec('UPDATE scopes SET status = ?, archived_at = NULL WHERE scope_id = ?', to, scopeId);
-        }
-        else {
-            this.sql.exec('UPDATE scopes SET status = ? WHERE scope_id = ?', to, scopeId);
-        }
-        return { status: row.status, vertical: row.vertical };
+            return {
+                ok: false,
+                code: null,
+                message: `illegal scope transition for ${action}: ${row.status} → ${to} ` +
+                    `(allowed from: ${from.join('|')})`,
+            };
+        }
+        // One transaction: the status and — on a reap — the scope's switch records (#1674).
+        // Reaped is terminal, so a cleanup that failed after the flip could never be retried.
+        this.ctx.storage.transactionSync(() => {
+            // Stamp/clear archived_at so the reap sweep can age scopes. Entering `archived`
+            // records when; `unarchive` (→ active, a restore per §4.2) clears it so a later
+            // re-archive dates from the new event. `reaped` keeps it — it is terminal history.
+            if (to === 'archived') {
+                this.sql.exec('UPDATE scopes SET status = ?, archived_at = ? WHERE scope_id = ?', to, new Date().toISOString(), scopeId);
+            }
+            else if (to === 'active') {
+                this.sql.exec('UPDATE scopes SET status = ?, archived_at = NULL WHERE scope_id = ?', to, scopeId);
+            }
+            else {
+                this.sql.exec('UPDATE scopes SET status = ? WHERE scope_id = ?', to, scopeId);
+            }
+            if (to === 'reaped')
+                forgetSystemSwitchesOf(this.kernelSql, scopeId);
+        });
+        return { ok: true, status: row.status, vertical: row.vertical };
     }
     // -- roles (checker rule 1) -------------------------------------------------
     /** INSERT OR REPLACE; return the previous role (for the audit `before`) or null. */
@@ -1541,6 +1768,8 @@ export class ControlPlaneDO extends DurableObject {
     deleteVertical(slug) {
         this.sql.exec('DELETE FROM vertical_channels WHERE vertical_slug = ?', slug);
         this.sql.exec('DELETE FROM vertical_channel_history WHERE vertical_slug = ?', slug);
+        this.sql.exec(`DELETE FROM vertical_version_migrations
+        WHERE version_id IN (SELECT id FROM vertical_versions WHERE vertical_slug = ?)`, slug);
         this.sql.exec('DELETE FROM vertical_versions WHERE vertical_slug = ?', slug);
         this.sql.exec('DELETE FROM verticals WHERE slug = ?', slug);
     }
@@ -1556,12 +1785,24 @@ export class ControlPlaneDO extends DurableObject {
             .exec('SELECT * FROM vertical_versions WHERE id = ?', id)
             .toArray()[0];
     }
+    /**
+     * A version and its SQL migrations (#1764), in one transaction. `manifestJson` arrives with
+     * the SQL already split off (`splitManifestMigrations`); `migrations` is null for a version
+     * that carries none to show.
+     */
     insertVersion(v) {
-        this.sql.exec(`INSERT INTO vertical_versions
-         (id, vertical_slug, version, manifest_digest, permission_digest,
-          migration_digest, deployment_ref, admission, admission_note, manifest_json,
-          origin_json, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, v.id, v.verticalSlug, v.version, v.manifestDigest, v.permissionDigest, v.migrationDigest, v.deploymentRef, v.admission, v.admissionNote, v.manifestJson, v.originJson, v.createdAt);
+        this.ctx.storage.transactionSync(() => {
+            this.sql.exec(`INSERT INTO vertical_versions
+           (id, vertical_slug, version, manifest_digest, permission_digest,
+            migration_digest, deployment_ref, admission, admission_note, manifest_json,
+            origin_json, migration_count, migrations_split, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?)`, v.id, v.verticalSlug, v.version, v.manifestDigest, v.permissionDigest, v.migrationDigest, v.deploymentRef, v.admission, v.admissionNote, v.manifestJson, v.originJson, v.migrations?.length ?? null, v.createdAt);
+            writeVersionMigrations(this.kernelSql, v.id, v.migrations);
+        });
+    }
+    /** One version's SQL migrations (#1764), or `undefined` for no such version. */
+    readVersionMigrations(id) {
+        return versionMigrationsOf(this.kernelSql, id);
     }
     /** Record what the serving script now runs — written only after a successful
      *  in-place upload, so a failed serve leaves the trailing state visible. */
@@ -1581,8 +1822,15 @@ export class ControlPlaneDO extends DurableObject {
         const where = ['vertical_slug = ?'];
         const params = [verticalSlug];
         const tail = keysetTail(where, params, 'id', page);
+        // Named columns, never `manifest_json` itself. `json_valid` first: a manifest that is not
+        // JSON lists with null surfaces, as `outboundOfManifestJson` reads it, rather than
+        // failing the whole page on `->`.
         return this.sql
-            .exec(`SELECT * FROM vertical_versions WHERE ${where.join(' AND ')}${tail}`, ...params)
+            .exec(`SELECT id, vertical_slug, version, manifest_digest, permission_digest, migration_digest,
+                deployment_ref, admission, admission_note, origin_json, created_at,
+                CASE WHEN json_valid(manifest_json) THEN manifest_json -> '$.outbound' END AS outbound_json,
+                CASE WHEN json_valid(manifest_json) THEN manifest_json -> '$.calls' END AS calls_json
+           FROM vertical_versions WHERE ${where.join(' AND ')}${tail}`, ...params)
             .toArray();
     }
     setAdmission(id, admission, note) {
@@ -1608,6 +1856,7 @@ export class ControlPlaneDO extends DurableObject {
      */
     deleteScopeDirectory(scopeId) {
         this.sql.exec('DELETE FROM hostnames WHERE scope_id = ?', scopeId);
+        forgetSystemSwitchesOf(this.kernelSql, scopeId);
         this.sql.exec('DELETE FROM scopes WHERE scope_id = ?', scopeId);
     }
     readChannel(verticalSlug, channel) {
@@ -2036,6 +2285,31 @@ export class ControlPlaneDO extends DurableObject {
           granted_by, granted_at, revoked_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)`, row.connectionId, row.tenantId, row.vertical, row.permission, row.scopeId, row.expiresAt, row.grantedBy, row.grantedAt);
     }
+    // -- the schedule switch's record (#1674) — `system-switch-record.ts` is the whole rule ---
+    /** OFF's write, after the scope's switch held. */
+    recordSystemSwitchedOff(row) {
+        recordSystemSwitchedOff(this.kernelSql, row);
+    }
+    /** ON's write, before the scope moves. Answers the row as it was, for a failed ON to restore. */
+    recordSystemSwitchedOn(row) {
+        return recordSystemSwitchedOn(this.kernelSql, row);
+    }
+    /** Put a row back as `recordSystemSwitchedOn` found it — the ON that followed it failed. */
+    restoreSystemSwitchRecord(key, prior) {
+        restoreSystemSwitchRecord(this.kernelSql, key, prior);
+    }
+    /** The fleet read. */
+    listSystemSwitches(filter) {
+        return listSystemSwitchRecords(this.kernelSql, filter);
+    }
+    /** One scope's recorded positions, by module — the status read's `recorded` join. */
+    systemSwitchRecordsOf(tenantId, scopeId) {
+        return [...systemSwitchRecordsOf(this.kernelSql, tenantId, scopeId)];
+    }
+    /** The modules a re-assert switches back off on one scope. */
+    switchedOffModulesOf(tenantId, scopeId) {
+        return switchedOffModulesOf(this.kernelSql, tenantId, scopeId);
+    }
     /** The tenant's LIVE connection grants (#592) — the provision/reconcile gather read. */
     listConnectionGrants(tenantId) {
         return this.sql
@@ -2279,8 +2553,10 @@ export class ControlPlaneDO extends DurableObject {
         if (query.action) {
             if (query.action.length === 0)
                 return []; // no action is acceptable — match nothing
-            where.push(`action IN (${query.action.map(() => '?').join(', ')})`);
-            params.push(...query.action);
+            // ONE bound JSON array, not a `?` per entry (#1776): a DO binds at most 100
+            // parameters, and nothing bounds this list's length (an action may repeat).
+            where.push('action IN (SELECT value FROM json_each(?))');
+            params.push(JSON.stringify(query.action));
         }
         if (query.since) {
             where.push('at >= ?');