@substrat-run/kernel 0.120.0 → 0.122.0

package/dist/system-switch-record.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The directory's record of the schedule kill switch (#1674), shared by both adapters.
+ *
+ * The switch itself (`system-switch.ts`) lives in the scope's own storage: a `switch:off`
+ * marker beside the module's grants, which is what the runner gates on. That is the right
+ * place for the gate, and the wrong place for the only copy. A scope whose storage is wiped
+ * and re-provisioned (#321/#332), or restored from a dump taken before the switch was pulled,
+ * loses the marker, and the next reconcile seats the grants live again. The switch is then
+ * silently on, on exactly the scopes an operator switched off.
+ *
+ * So the directory keeps one row per (tenant, scope, module): the position the switch was
+ * last moved to, by whom, why, and when. It is the model `_substrat_connection_grants` set
+ * (#592): the enforcement stays where it is checked, and the directory holds what a
+ * reconcile re-asserts FROM. It also answers the fleet question the scope cannot: "which
+ * scopes have a module switched off", without walking every scope's store.
+ *
+ * **OFF wins from either side, and a record never turns anything on.**
+ * - A record of `off` and a scope that has lost its marker: the record wins, and
+ *   `HostAdmin.reassertSystemSwitches` switches it off again, after the seat, so the grants
+ *   the seat recreated are the ones OFF tombstones and a later ON gives back.
+ * - A record of `on` (or none) and a live marker: the marker wins, and it stays off.
+ *   Restore is the lever (#1666), and a reconcile that could turn a kill switch back on
+ *   would be a second one.
+ *
+ * The admin log is still the history. This is only the current position.
+ */
+import type { ListPage } from '@substrat-run/contracts';
+import type { SwitchSql, SystemScheduleState } from './system-switch.js';
+/**
+ * The table. Interpolated into both adapters' directory DDL, so `lint:spine-ddl` sees the
+ * one spelling on each side. No CHECK on `position`: the drift gate does not compare
+ * constraints, and the writers below are the only thing that sets it.
+ */
+export declare const SYSTEM_SWITCHES_DDL = "\n  CREATE TABLE IF NOT EXISTS _substrat_system_switches (\n    tenant_id    TEXT NOT NULL,\n    scope_id     TEXT NOT NULL,\n    module_id    TEXT NOT NULL,\n    -- 'on' or 'off'. A row exists only for a module some switch call actually held.\n    position     TEXT NOT NULL,\n    actor        TEXT NOT NULL,\n    reason       TEXT NOT NULL,\n    -- The switch call's own id, the one its admin-log intent and outcome rows carry.\n    -- A ULID, so it is also the fleet read's chronological keyset cursor.\n    operation_id TEXT NOT NULL,\n    switched_at  TEXT NOT NULL,\n    PRIMARY KEY (tenant_id, scope_id, module_id)\n  );\n  CREATE INDEX IF NOT EXISTS _substrat_system_switches_position\n    ON _substrat_system_switches (position, operation_id);\n  CREATE INDEX IF NOT EXISTS _substrat_system_switches_operation\n    ON _substrat_system_switches (operation_id);\n";
+/**
+ * The one-time backfill from the admin log: every switch moved before the record existed.
+ * Without it, those are exactly the switches a wipe would still lose.
+ *
+ * It reads the admin-log shape `revokeFromSystem` / `restoreToSystem` have written since
+ * #1666, two rows per call sharing `after.operationId`: an `intent` row carrying
+ * `after.moduleId` and `after.reason`, then an outcome row whose `after.phase` is
+ * `applied`, `refused` or `failed`. Only calls whose outcome is `applied` count, because a
+ * refused call moved nothing and a failed one may not have. Of those, only the LATEST per
+ * (tenant, scope, module) is taken, by the intent's ULID id. `at` is the intent's, the
+ * same instant the status read's who/why join reports. A key whose calls include no
+ * applied OFF gets no row, even when its latest applied call is an ON: a live
+ * `restoreToSystem` of a module never switched off writes none either
+ * (`recordSystemSwitchedOn`), and the backfill must not record what the live path would not.
+ *
+ * `INSERT OR IGNORE`, so a row the switch wrote itself is never overwritten by history.
+ * The adapters run it only on the construction that creates the table, so it runs once.
+ */
+export declare const SYSTEM_SWITCHES_BACKFILL_SQL = "\n  WITH applied AS (\n    SELECT DISTINCT action, json_extract(after, '$.operationId') AS operation_id\n      FROM _substrat_admin_log\n     WHERE action IN ('revokeFromSystem', 'restoreToSystem')\n       AND json_extract(after, '$.phase') = 'applied'\n  ),\n  intents AS (\n    SELECT i.id AS id, i.tenant_id AS tenant_id, i.scope_id AS scope_id,\n           json_extract(i.after, '$.moduleId') AS module_id,\n           CASE i.action WHEN 'revokeFromSystem' THEN 'off' ELSE 'on' END AS position,\n           i.actor AS actor,\n           json_extract(i.after, '$.reason') AS reason,\n           json_extract(i.after, '$.operationId') AS operation_id,\n           i.at AS at\n      FROM _substrat_admin_log i\n      JOIN applied a\n        ON a.action = i.action AND a.operation_id = json_extract(i.after, '$.operationId')\n     WHERE i.action IN ('revokeFromSystem', 'restoreToSystem')\n       AND i.tenant_id IS NOT NULL AND i.scope_id IS NOT NULL\n       AND json_extract(i.after, '$.phase') = 'intent'\n       AND json_extract(i.after, '$.moduleId') IS NOT NULL\n       AND json_extract(i.after, '$.reason') IS NOT NULL\n  ),\n  ranked AS (\n    SELECT *,\n           ROW_NUMBER() OVER (PARTITION BY tenant_id, scope_id, module_id ORDER BY id DESC) AS latest,\n           MAX(position = 'off') OVER (PARTITION BY tenant_id, scope_id, module_id) AS ever_off\n      FROM intents\n  )\n  INSERT OR IGNORE INTO _substrat_system_switches\n    (tenant_id, scope_id, module_id, position, actor, reason, operation_id, switched_at)\n  SELECT tenant_id, scope_id, module_id, position, actor, reason, operation_id, at\n    FROM ranked\n   WHERE latest = 1 AND ever_off = 1\n";
+/** "Does the record table exist yet?" — asked BEFORE the DDL, so the backfill runs once. */
+export declare function systemSwitchesTableExists(db: SwitchSql): boolean;
+/** One record row as the directory holds it, with the scope's binding joined on. */
+export interface SystemSwitchRecordRow {
+    tenantId: string;
+    scopeId: string;
+    moduleId: string;
+    vertical: string | null;
+    position: 'on' | 'off';
+    actor: string;
+    reason: string;
+    operationId: string;
+    at: string;
+}
+/**
+ * Filter for the fleet read. Unset `position` means both; the HTTP route defaults it to
+ * `off`. Paged by `operationId` (the exclusive cursor), oldest first unless `order: 'desc'`.
+ */
+export interface SystemSwitchRecordFilter extends ListPage {
+    position?: 'on' | 'off';
+    tenantId?: string;
+    scopeId?: string;
+    moduleId?: string;
+    vertical?: string;
+}
+/**
+ * The fleet read (`GET /system-switches`): records, keyset-paged by `operation_id`.
+ *
+ * The key is the call that last moved the switch, so a row whose switch moves during a walk
+ * is re-keyed to a newer id and jumps to the end of the order. Ascending (the default) never
+ * skips a row for it; at worst it is seen twice, once per position. A DESCENDING walk can
+ * miss a row that moved after the walk started, so use ascending for "every switch".
+ */
+export declare function listSystemSwitchRecords(db: SwitchSql, filter?: SystemSwitchRecordFilter): SystemSwitchRecordRow[];
+/** One scope's record rows by module — what the per-scope status read joins as `recorded`. */
+export declare function systemSwitchRecordsOf(db: SwitchSql, tenantId: string, scopeId: string): Map<string, 'on' | 'off'>;
+/**
+ * The per-scope status read's rows with the record joined on. Each module the scope
+ * reports gets its recorded position (or null). A module the record holds that the scope
+ * no longer reports at all is ADDED, as `ungranted`: that is the scope a wipe emptied, and
+ * the drift is the whole reason to show it. Sorted by module id, as the scope's rows are.
+ */
+export declare function withRecorded(states: {
+    moduleId: string;
+    schedules: SystemScheduleState;
+}[], recorded: Map<string, 'on' | 'off'>): {
+    moduleId: string;
+    schedules: SystemScheduleState;
+    recorded: 'on' | 'off' | null;
+}[];
+/** The modules a reconcile must re-assert OFF on this scope. */
+export declare function switchedOffModulesOf(db: SwitchSql, tenantId: string, scopeId: string): string[];
+/** What one switch call writes into the record. */
+export interface SystemSwitchRecordWrite {
+    tenantId: string;
+    scopeId: string;
+    moduleId: string;
+    actor: string;
+    reason: string;
+    operationId: string;
+    at: string;
+}
+/** The row as it stood before a write, so a failed switch can put it back. */
+export type SystemSwitchRecordPrior = Pick<SystemSwitchRecordRow, 'position' | 'actor' | 'reason' | 'operationId' | 'at'> | null;
+/** What a re-assert did for one recorded-off module — `HostAdmin.reassertSystemSwitches`' answer. */
+export interface SystemSwitchReassert {
+    moduleId: string;
+    held: boolean;
+    changed: boolean;
+}
+/**
+ * OFF's write, made AFTER the scope's switch held. An upsert: a repeat OFF refreshes the
+ * actor, reason and time, as the status read reports the latest reason. Never made for a
+ * call that held nothing, because a row saying `off` for a module the scope never ran
+ * would switch it off on the day it is installed (the kernel's `held` check, for the same
+ * reason).
+ */
+export declare function recordSystemSwitchedOff(db: SwitchSql, row: SystemSwitchRecordWrite): void;
+/**
+ * ON's write, made BEFORE the scope's switch moves, and only to a row that exists. Before,
+ * because the other order fails unsafely: a scope switched on whose record write then
+ * failed would still read `off`, and the next reconcile would switch the operator's
+ * restore back off. This order fails toward a record of `on` beside a live marker, which
+ * the marker wins. Answers the row as it was, for `restoreSystemSwitchRecord`.
+ */
+export declare function recordSystemSwitchedOn(db: SwitchSql, row: SystemSwitchRecordWrite): SystemSwitchRecordPrior;
+/**
+ * Put a row back as `recordSystemSwitchedOn` found it — the ON that wrote it threw, or held
+ * nothing. A compare-and-set on the ON's own `operationId`: if another switch call has
+ * written the row since (a concurrent OFF), the row is left as that call wrote it, so an
+ * ON's undo can never clobber a newer position.
+ */
+export declare function restoreSystemSwitchRecord(db: SwitchSql, on: {
+    tenantId: string;
+    scopeId: string;
+    moduleId: string;
+    operationId: string;
+}, prior: SystemSwitchRecordPrior): void;
+/**
+ * Forget one scope's switch records — the scope's directory row is going too (a reaped
+ * preview or fork, a reaped scope). Without this the fleet read keeps listing a switch on
+ * a scope that no longer exists. The admin log keeps the history, as it keeps the scope's.
+ */
+export declare function forgetSystemSwitchesOf(db: SwitchSql, scopeId: string): void;
+//# sourceMappingURL=system-switch-record.d.ts.map

package/dist/system-switch-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-switch-record.d.ts","sourceRoot":"","sources":["../src/system-switch-record.ts"],"names":[],"mappings":"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"}

package/dist/system-switch-record.js

@@ -0,0 +1,227 @@
+/**
+ * The table. Interpolated into both adapters' directory DDL, so `lint:spine-ddl` sees the
+ * one spelling on each side. No CHECK on `position`: the drift gate does not compare
+ * constraints, and the writers below are the only thing that sets it.
+ */
+export const SYSTEM_SWITCHES_DDL = `
+  CREATE TABLE IF NOT EXISTS _substrat_system_switches (
+    tenant_id    TEXT NOT NULL,
+    scope_id     TEXT NOT NULL,
+    module_id    TEXT NOT NULL,
+    -- 'on' or 'off'. A row exists only for a module some switch call actually held.
+    position     TEXT NOT NULL,
+    actor        TEXT NOT NULL,
+    reason       TEXT NOT NULL,
+    -- The switch call's own id, the one its admin-log intent and outcome rows carry.
+    -- A ULID, so it is also the fleet read's chronological keyset cursor.
+    operation_id TEXT NOT NULL,
+    switched_at  TEXT NOT NULL,
+    PRIMARY KEY (tenant_id, scope_id, module_id)
+  );
+  CREATE INDEX IF NOT EXISTS _substrat_system_switches_position
+    ON _substrat_system_switches (position, operation_id);
+  CREATE INDEX IF NOT EXISTS _substrat_system_switches_operation
+    ON _substrat_system_switches (operation_id);
+`;
+/**
+ * The one-time backfill from the admin log: every switch moved before the record existed.
+ * Without it, those are exactly the switches a wipe would still lose.
+ *
+ * It reads the admin-log shape `revokeFromSystem` / `restoreToSystem` have written since
+ * #1666, two rows per call sharing `after.operationId`: an `intent` row carrying
+ * `after.moduleId` and `after.reason`, then an outcome row whose `after.phase` is
+ * `applied`, `refused` or `failed`. Only calls whose outcome is `applied` count, because a
+ * refused call moved nothing and a failed one may not have. Of those, only the LATEST per
+ * (tenant, scope, module) is taken, by the intent's ULID id. `at` is the intent's, the
+ * same instant the status read's who/why join reports. A key whose calls include no
+ * applied OFF gets no row, even when its latest applied call is an ON: a live
+ * `restoreToSystem` of a module never switched off writes none either
+ * (`recordSystemSwitchedOn`), and the backfill must not record what the live path would not.
+ *
+ * `INSERT OR IGNORE`, so a row the switch wrote itself is never overwritten by history.
+ * The adapters run it only on the construction that creates the table, so it runs once.
+ */
+export const SYSTEM_SWITCHES_BACKFILL_SQL = `
+  WITH applied AS (
+    SELECT DISTINCT action, json_extract(after, '$.operationId') AS operation_id
+      FROM _substrat_admin_log
+     WHERE action IN ('revokeFromSystem', 'restoreToSystem')
+       AND json_extract(after, '$.phase') = 'applied'
+  ),
+  intents AS (
+    SELECT i.id AS id, i.tenant_id AS tenant_id, i.scope_id AS scope_id,
+           json_extract(i.after, '$.moduleId') AS module_id,
+           CASE i.action WHEN 'revokeFromSystem' THEN 'off' ELSE 'on' END AS position,
+           i.actor AS actor,
+           json_extract(i.after, '$.reason') AS reason,
+           json_extract(i.after, '$.operationId') AS operation_id,
+           i.at AS at
+      FROM _substrat_admin_log i
+      JOIN applied a
+        ON a.action = i.action AND a.operation_id = json_extract(i.after, '$.operationId')
+     WHERE i.action IN ('revokeFromSystem', 'restoreToSystem')
+       AND i.tenant_id IS NOT NULL AND i.scope_id IS NOT NULL
+       AND json_extract(i.after, '$.phase') = 'intent'
+       AND json_extract(i.after, '$.moduleId') IS NOT NULL
+       AND json_extract(i.after, '$.reason') IS NOT NULL
+  ),
+  ranked AS (
+    SELECT *,
+           ROW_NUMBER() OVER (PARTITION BY tenant_id, scope_id, module_id ORDER BY id DESC) AS latest,
+           MAX(position = 'off') OVER (PARTITION BY tenant_id, scope_id, module_id) AS ever_off
+      FROM intents
+  )
+  INSERT OR IGNORE INTO _substrat_system_switches
+    (tenant_id, scope_id, module_id, position, actor, reason, operation_id, switched_at)
+  SELECT tenant_id, scope_id, module_id, position, actor, reason, operation_id, at
+    FROM ranked
+   WHERE latest = 1 AND ever_off = 1
+`;
+/** "Does the record table exist yet?" — asked BEFORE the DDL, so the backfill runs once. */
+export function systemSwitchesTableExists(db) {
+    return (db.all(`SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = '_substrat_system_switches'`)
+        .length > 0);
+}
+const positionOf = (v) => (v === 'on' ? 'on' : 'off');
+const COLUMNS = `r.tenant_id, r.scope_id, r.module_id, s.vertical, r.position, r.actor, r.reason,
+  r.operation_id, r.switched_at`;
+const rowOf = (r) => ({
+    tenantId: String(r.tenant_id),
+    scopeId: String(r.scope_id),
+    moduleId: String(r.module_id),
+    vertical: r.vertical == null ? null : String(r.vertical),
+    position: positionOf(r.position),
+    actor: String(r.actor),
+    reason: String(r.reason),
+    operationId: String(r.operation_id),
+    at: String(r.switched_at),
+});
+/**
+ * The fleet read (`GET /system-switches`): records, keyset-paged by `operation_id`.
+ *
+ * The key is the call that last moved the switch, so a row whose switch moves during a walk
+ * is re-keyed to a newer id and jumps to the end of the order. Ascending (the default) never
+ * skips a row for it; at worst it is seen twice, once per position. A DESCENDING walk can
+ * miss a row that moved after the walk started, so use ascending for "every switch".
+ */
+export function listSystemSwitchRecords(db, filter = {}) {
+    const where = [];
+    const params = [];
+    const eq = (col, v) => {
+        if (v !== undefined) {
+            where.push(`${col} = ?`);
+            params.push(v);
+        }
+    };
+    eq('r.position', filter.position);
+    eq('r.tenant_id', filter.tenantId);
+    eq('r.scope_id', filter.scopeId);
+    eq('r.module_id', filter.moduleId);
+    eq('s.vertical', filter.vertical);
+    const order = filter.order === 'desc' ? 'DESC' : 'ASC';
+    if (filter.cursor !== undefined) {
+        where.push(order === 'DESC' ? 'r.operation_id < ?' : 'r.operation_id > ?');
+        params.push(filter.cursor);
+    }
+    // LEFT JOIN: a record outlives nothing it needs from `scopes`, and a scope row the
+    // directory lost must not hide a switch that is still off in the scope's store.
+    let sql = `SELECT ${COLUMNS} FROM _substrat_system_switches r LEFT JOIN scopes s ON s.scope_id = r.scope_id` +
+        (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
+        ` ORDER BY r.operation_id ${order}`;
+    if (filter.limit !== undefined) {
+        sql += ` LIMIT ${Math.max(0, Math.floor(filter.limit))}`;
+    }
+    return db.all(sql, ...params).map(rowOf);
+}
+/** One scope's record rows by module — what the per-scope status read joins as `recorded`. */
+export function systemSwitchRecordsOf(db, tenantId, scopeId) {
+    const rows = db.all(`SELECT module_id, position FROM _substrat_system_switches WHERE tenant_id = ? AND scope_id = ?`, tenantId, scopeId);
+    return new Map(rows.map((r) => [String(r.module_id), positionOf(r.position)]));
+}
+/**
+ * The per-scope status read's rows with the record joined on. Each module the scope
+ * reports gets its recorded position (or null). A module the record holds that the scope
+ * no longer reports at all is ADDED, as `ungranted`: that is the scope a wipe emptied, and
+ * the drift is the whole reason to show it. Sorted by module id, as the scope's rows are.
+ */
+export function withRecorded(states, recorded) {
+    const rows = states.map((s) => ({ ...s, recorded: recorded.get(s.moduleId) ?? null }));
+    const reported = new Set(states.map((s) => s.moduleId));
+    for (const [moduleId, position] of recorded) {
+        if (!reported.has(moduleId))
+            rows.push({ moduleId, schedules: 'ungranted', recorded: position });
+    }
+    return rows.sort((a, b) => (a.moduleId < b.moduleId ? -1 : a.moduleId > b.moduleId ? 1 : 0));
+}
+/** The modules a reconcile must re-assert OFF on this scope. */
+export function switchedOffModulesOf(db, tenantId, scopeId) {
+    return db
+        .all(`SELECT module_id FROM _substrat_system_switches
+        WHERE tenant_id = ? AND scope_id = ? AND position = 'off' ORDER BY module_id`, tenantId, scopeId)
+        .map((r) => String(r.module_id));
+}
+/**
+ * Overwrite one existing row's position and provenance — ON's write, and its undo. With
+ * `ifOperationId`, only while the row is still the one that operation wrote (a CAS).
+ */
+function setRecordRow(db, key, row, ifOperationId) {
+    db.run(`UPDATE _substrat_system_switches
+        SET position = ?, actor = ?, reason = ?, operation_id = ?, switched_at = ?
+      WHERE tenant_id = ? AND scope_id = ? AND module_id = ?` +
+        (ifOperationId === undefined ? '' : ' AND operation_id = ?'), row.position, row.actor, row.reason, row.operationId, row.at, key.tenantId, key.scopeId, key.moduleId, ...(ifOperationId === undefined ? [] : [ifOperationId]));
+}
+/**
+ * OFF's write, made AFTER the scope's switch held. An upsert: a repeat OFF refreshes the
+ * actor, reason and time, as the status read reports the latest reason. Never made for a
+ * call that held nothing, because a row saying `off` for a module the scope never ran
+ * would switch it off on the day it is installed (the kernel's `held` check, for the same
+ * reason).
+ */
+export function recordSystemSwitchedOff(db, row) {
+    db.run(`INSERT INTO _substrat_system_switches
+       (tenant_id, scope_id, module_id, position, actor, reason, operation_id, switched_at)
+     VALUES (?, ?, ?, 'off', ?, ?, ?, ?)
+     ON CONFLICT (tenant_id, scope_id, module_id) DO UPDATE SET
+       position = 'off', actor = excluded.actor, reason = excluded.reason,
+       operation_id = excluded.operation_id, switched_at = excluded.switched_at`, row.tenantId, row.scopeId, row.moduleId, row.actor, row.reason, row.operationId, row.at);
+}
+/**
+ * ON's write, made BEFORE the scope's switch moves, and only to a row that exists. Before,
+ * because the other order fails unsafely: a scope switched on whose record write then
+ * failed would still read `off`, and the next reconcile would switch the operator's
+ * restore back off. This order fails toward a record of `on` beside a live marker, which
+ * the marker wins. Answers the row as it was, for `restoreSystemSwitchRecord`.
+ */
+export function recordSystemSwitchedOn(db, row) {
+    const prior = db.all(`SELECT position, actor, reason, operation_id, switched_at FROM _substrat_system_switches
+      WHERE tenant_id = ? AND scope_id = ? AND module_id = ?`, row.tenantId, row.scopeId, row.moduleId)[0];
+    if (!prior)
+        return null;
+    setRecordRow(db, row, { position: 'on', actor: row.actor, reason: row.reason, operationId: row.operationId, at: row.at });
+    return {
+        position: positionOf(prior.position),
+        actor: String(prior.actor),
+        reason: String(prior.reason),
+        operationId: String(prior.operation_id),
+        at: String(prior.switched_at),
+    };
+}
+/**
+ * Put a row back as `recordSystemSwitchedOn` found it — the ON that wrote it threw, or held
+ * nothing. A compare-and-set on the ON's own `operationId`: if another switch call has
+ * written the row since (a concurrent OFF), the row is left as that call wrote it, so an
+ * ON's undo can never clobber a newer position.
+ */
+export function restoreSystemSwitchRecord(db, on, prior) {
+    if (prior)
+        setRecordRow(db, on, prior, on.operationId);
+}
+/**
+ * Forget one scope's switch records — the scope's directory row is going too (a reaped
+ * preview or fork, a reaped scope). Without this the fleet read keeps listing a switch on
+ * a scope that no longer exists. The admin log keeps the history, as it keeps the scope's.
+ */
+export function forgetSystemSwitchesOf(db, scopeId) {
+    db.run(`DELETE FROM _substrat_system_switches WHERE scope_id = ?`, scopeId);
+}
+//# sourceMappingURL=system-switch-record.js.map

package/dist/system-switch-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-switch-record.js","sourceRoot":"","sources":["../src/system-switch-record.ts"],"names":[],"mappings":"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"}

package/dist/system-switch.d.ts

@@ -47,8 +47,8 @@
 export declare const SYSTEM_SWITCH_OFF_RELATION = "switch:off";
 /** The two statement shapes the switch needs, over either adapter's SQLite handle. */
 export interface SwitchSql {
-    all(sql: string, ...params: (string | null)[]): Record<string, unknown>[];
-    run(sql: string, ...params: (string | null)[]): void;
+    all(sql: string, ...params: (string | number | null)[]): Record<string, unknown>[];
+    run(sql: string, ...params: (string | number | null)[]): void;
 }
 /**
  * Where one module's schedules stand on one scope.

package/dist/system-switch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-switch.d.ts","sourceRoot":"","sources":["../src/system-switch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,4FAA4F;AAC5F,eAAO,MAAM,0BAA0B,eAAe,CAAC;AAKvD,sFAAsF;AACtF,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC1E,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;CACtD;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,KAAK,GAAG,WAAW,CAAC;AAI7D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,oHACmD,CAAC;AAE5F;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAErG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAalG;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,mBAAmB,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAWlF;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK1E;AAED,+FAA+F;AAC/F,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMlF;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,SAAS,EACb,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,GAAG,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACzE,aAAa,CAOf;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,SAAS,EACb,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,GAAG,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACxE,aAAa,CA4Ff"}
+{"version":3,"file":"system-switch.d.ts","sourceRoot":"","sources":["../src/system-switch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,4FAA4F;AAC5F,eAAO,MAAM,0BAA0B,eAAe,CAAC;AAKvD,sFAAsF;AACtF,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACnF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;CAC/D;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,KAAK,GAAG,WAAW,CAAC;AAI7D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,oHACmD,CAAC;AAE5F;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAErG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAalG;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,mBAAmB,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAWlF;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK1E;AAED,+FAA+F;AAC/F,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMlF;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,SAAS,EACb,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,GAAG,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACzE,aAAa,CAOf;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,SAAS,EACb,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,GAAG,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACxE,aAAa,CA4Ff"}

package/dist/ulid.d.ts

@@ -27,6 +27,12 @@ export interface UlidMint {
  */
 export declare function createUlid(): UlidMint;
 export declare function ulid(now?: number): string;
+/**
+ * The greatest ULID a millisecond can carry (#1705 PR 3): every id minted at or before `now`
+ * sorts at or below it, and every id minted after sorts above. It is what "skip to now" moves
+ * a watermark to, because a watermark is compared with `id > cursor`.
+ */
+export declare function ulidCeiling(now: number): string;
 /**
  * The epoch-millisecond timestamp a ULID carries in its first ten characters.
  *

package/dist/ulid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ulid.d.ts","sourceRoot":"","sources":["../src/ulid.ts"],"names":[],"mappings":"AA0CA,yFAAyF;AACzF,MAAM,WAAW,QAAQ;IACvB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,QAAQ,CAmFrC;AAKD,wBAAgB,IAAI,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAErD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAO3C"}
+{"version":3,"file":"ulid.d.ts","sourceRoot":"","sources":["../src/ulid.ts"],"names":[],"mappings":"AAqDA,yFAAyF;AACzF,MAAM,WAAW,QAAQ;IACvB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,QAAQ,CA6ErC;AAKD,wBAAgB,IAAI,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAO3C"}

package/dist/ulid.js

@@ -30,6 +30,16 @@ const MAX_ULID_TIME = 2 ** 48 - 1;
 /** All 26 digits, Crockford's alphabet — `I`, `L`, `O` and `U` are not in it. */
 const ULID_SHAPE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
 const unencodable = (t) => `not an encodable ULID instant: ${t} (want 0..${MAX_ULID_TIME})`;
+/** The ten base32 digits of an instant 48 bits can hold. The caller has range-checked it. */
+function encodeTime(time) {
+    let ts = '';
+    let t = time;
+    for (let i = 0; i < 10; i++) {
+        ts = B32[t % 32] + ts;
+        t = Math.floor(t / 32);
+    }
+    return ts;
+}
 /**
  * A ULID mint with its OWN monotonic state — one writer's floor, not the process's.
  *
@@ -85,16 +95,10 @@ export function createUlid() {
         if (time < 0 || time > MAX_ULID_TIME)
             throw new RangeError(unencodable(time));
         lastTime = time;
-        let ts = '';
-        let t = time;
-        for (let i = 0; i < 10; i++) {
-            ts = B32[t % 32] + ts;
-            t = Math.floor(t / 32);
-        }
         let r = '';
         for (const d of lastRand)
             r += B32[d];
-        return ts + r;
+        return encodeTime(time) + r;
     });
     mint.seedFrom = (id) => {
         const time = ulidTime(id); // refuses anything that is not a ULID
@@ -129,6 +133,16 @@ const processUlid = createUlid();
 export function ulid(now = Date.now()) {
     return processUlid(now);
 }
+/**
+ * The greatest ULID a millisecond can carry (#1705 PR 3): every id minted at or before `now`
+ * sorts at or below it, and every id minted after sorts above. It is what "skip to now" moves
+ * a watermark to, because a watermark is compared with `id > cursor`.
+ */
+export function ulidCeiling(now) {
+    if (!Number.isSafeInteger(now) || now < 0 || now > MAX_ULID_TIME)
+        throw new RangeError(unencodable(now));
+    return encodeTime(now) + 'Z'.repeat(16);
+}
 /**
  * The epoch-millisecond timestamp a ULID carries in its first ten characters.
  *

package/dist/ulid.js.map

@@ -1 +1 @@
-{"version":3,"file":"ulid.js","sourceRoot":"","sources":["../src/ulid.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ulid.js","sourceRoot":"","sources":["../src/ulid.ts"],"names":[],"mappings":"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"}

package/dist/version-migrations.d.ts

@@ -0,0 +1,108 @@
+/**
+ * A version's SQL migrations, stored apart from its manifest (#1764), shared by both adapters.
+ *
+ * Since #1677 a pushed deploy manifest carries its whole cumulative migration set
+ * (`migrations: { moduleId, version, sql }[]`). The manifest is one `manifest_json` column on
+ * `vertical_versions`, so every read of a version moved that SQL too: `readVersion` on every
+ * admit, promote and bind, and every `storedDeployManifest.parse` behind `/registry`, `/model`,
+ * `/schedules` and the serving upload. Only the promote review reads the SQL.
+ *
+ * So `publishVersion` splits the field off: the SQL goes to `vertical_version_migrations`, one
+ * row per migration, and the manifest is stored without it. The wire is unchanged, since the
+ * CLI still sends `migrations` inside the manifest. Two columns on `vertical_versions` carry
+ * what the rows alone cannot:
+ *
+ * - `migration_count`: how many rows the version stored. **NULL means the version carries no
+ *   SQL** (pushed before #1677, over the push's caps, or malformed), which a reader must show
+ *   as "not available", never as "no migrations". `0` is a version whose modules ship none. A
+ *   read whose row count disagrees with it answers null rather than a short list.
+ * - `migrations_split`: 1 once the version's SQL is out of its manifest. NULL is a version
+ *   stored before this, whose manifest may still carry it. The backfill below moves those a
+ *   bounded batch at a time, and until it reaches a version the read falls back to that
+ *   version's manifest. The fallback is only for those rows. A version published by this code
+ *   is split on the way in.
+ */
+import { type DeclaredMigration } from '@substrat-run/contracts';
+import type { SwitchSql } from './system-switch.js';
+/**
+ * The table, and the index the backfill walks. Interpolated into both adapters' directory DDL,
+ * so `lint:spine-ddl` sees one spelling on each side. Anything that references this table or
+ * this index goes in this fragment, which is what the adapters run after their column additions.
+ *
+ * The index is partial: it holds only versions still waiting for the backfill, so "is there
+ * anything left" is one probe that costs nothing once the backfill is done. It names a column
+ * a directory from before #1764 lacks, so the adapters run these statements after their
+ * column additions, not in their DDL loop.
+ */
+export declare const VERSION_MIGRATIONS_DDL = "\n  CREATE TABLE IF NOT EXISTS vertical_version_migrations (\n    version_id TEXT NOT NULL,\n    -- The migration's place in the order the host runs them, from 0.\n    ordinal    INTEGER NOT NULL,\n    module_id  TEXT NOT NULL,\n    -- The module's SqlMigration.version, e.g. 0001-init.\n    version    TEXT NOT NULL,\n    sql        TEXT NOT NULL,\n    PRIMARY KEY (version_id, ordinal)\n  );\n  CREATE INDEX IF NOT EXISTS vertical_versions_unsplit\n    ON vertical_versions (id) WHERE migrations_split IS NULL;\n";
+/** A manifest with its SQL taken out, and the SQL. */
+export interface SplitManifest {
+    /** The manifest to store: without `migrations`, or exactly as given when there was nothing to take. */
+    manifestJson: string | null;
+    /** The migrations to store, or null when the version carries none that can be stored. */
+    migrations: DeclaredMigration[] | null;
+}
+/**
+ * Take `migrations` out of a manifest.
+ *
+ * `push` holds the field to the push boundary's caps (`deployManifest`): at most 2000 entries
+ * and 512 KiB of SQL, which also bounds every row under a Durable Object's 2 MB row limit.
+ * `/deploy` already refuses an over-cap set, before the upload, because it parses the whole
+ * manifest with `deployManifest`. This split caps whatever reaches `publishVersion` by any
+ * route, including `POST /verticals/:slug/versions`, which stores `manifestJson` unparsed
+ * (#1765). There, a field over the caps or not shaped like migrations is dropped and the
+ * version reads as "SQL not available", so the promote dialog still asks. `stored` is for a
+ * manifest already in the directory, whose history the caps must never make unreadable
+ * (`storedDeployManifest`).
+ *
+ * A manifest that is not a JSON object is returned as it came, with no migrations. The
+ * manifest is only rewritten when it has a `migrations` key to remove.
+ */
+export declare function splitManifestMigrations(manifestJson: string | null, mode: 'push' | 'stored'): SplitManifest;
+/** Replace one version's migration rows. The caller sets its `migration_count` and `migrations_split`. */
+export declare function writeVersionMigrations(db: SwitchSql, versionId: string, migrations: readonly DeclaredMigration[] | null): void;
+/**
+ * The two reads that find unsplit versions. Named so the kernel's test can EXPLAIN these
+ * exact strings: each must be answered from `vertical_versions_unsplit`, never by a scan of
+ * every version's row (and its manifest's overflow pages).
+ */
+export declare const UNSPLIT_IDS_SQL = "SELECT id FROM vertical_versions WHERE migrations_split IS NULL ORDER BY id LIMIT ?";
+export declare const UNSPLIT_PROBE_SQL = "SELECT 1 AS present FROM vertical_versions WHERE migrations_split IS NULL LIMIT 1";
+/**
+ * How much manifest one batch reads at most, in UTF-8 bytes (the first version is always
+ * moved). A stored manifest can be up to about 1.5 MiB, and a batch holds the directory DO.
+ * Bytes, because what a batch costs is the bytes it reads: a manifest of four-byte characters
+ * is four times its character count.
+ */
+export declare const BATCH_MANIFEST_BYTES: number;
+/**
+ * Move the SQL out of the next versions stored before #1764: at most `limit` of them, and
+ * at most `BATCH_MANIFEST_BYTES` of manifest. Returns how many it moved, and whether any are
+ * left.
+ *
+ * Bounded so that no one run has to read the whole version history: the Durable-Object
+ * adapter runs one batch per alarm and re-arms while any are left, so its constructor never
+ * does per-version work. Resumable because each version is marked as it is moved, in the
+ * caller's transaction with its rows. A version is moved by the same `splitManifestMigrations`
+ * a push goes through, in `stored` mode, so history is read without the push caps.
+ *
+ * Idempotent: a version that is already split is never selected, and moving one replaces its
+ * rows. A directory restored from a dump taken before the backfill comes back unsplit and is
+ * simply moved again.
+ */
+export declare function splitVersionMigrationsBatch(db: SwitchSql, limit?: number): {
+    moved: number;
+    more: boolean;
+};
+/** Whether any version still waits for the backfill. One probe of the partial index. */
+export declare function versionsAwaitSplit(db: SwitchSql): boolean;
+/**
+ * One version's migrations, in the order the host runs them. `undefined` when there is no
+ * such version. `migrations` is null when the version carries none that can be shown, which
+ * a reader must say as "not available", never as "no migrations".
+ */
+export declare function versionMigrationsOf(db: SwitchSql, versionId: string): {
+    verticalSlug: string;
+    migrations: DeclaredMigration[] | null;
+} | undefined;
+//# sourceMappingURL=version-migrations.d.ts.map

package/dist/version-migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-migrations.d.ts","sourceRoot":"","sources":["../src/version-migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,ugBAalC,CAAC;AAEF,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,uGAAuG;IACvG,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yFAAyF;IACzF,UAAU,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,aAAa,CAkB3G;AAED,0GAA0G;AAC1G,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,SAAS,EACb,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,SAAS,iBAAiB,EAAE,GAAG,IAAI,GAC9C,IAAI,CASN;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,wFAAwF,CAAC;AACrH,eAAO,MAAM,iBAAiB,sFAAsF,CAAC;AAIrH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAkB,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,SAAS,EACb,KAAK,GAAE,MAAuB,GAC7B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAiClC;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,SAAS,EACb,SAAS,EAAE,MAAM,GAChB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAAA;CAAE,GAAG,SAAS,CA4B9E"}