@substrat-run/adapter-cloudflare 0.139.0 → 0.141.0

package/dist/control-plane-do.js

@@ -1,7 +1,9 @@
 import { DurableObject } from 'cloudflare:workers';
-import { membershipFencesBackfillSql, MEMBERSHIP_FENCES_DDL, MEMBERSHIP_FENCES_TABLE, membershipFencesTableExists, MEMBERSHIP_FENCE_SINCE_SQL, RAISE_MEMBERSHIP_FENCE_SQL, memberAddedAudit, orgChangeBound, tenantCoverage, IMPERSONATION_COLUMNS, IMPERSONATION_DDL, impersonationByIdQuery, impersonationListQuery, impersonationRowValues, ISSUE_RETENTION_DAYS, telemetryRetentionStatements, FINDINGS_DDL, createFindingRule, findingOfOpsFailure, findingOfSweepRun, pruneFindings, listFindingRules, listFindings, observeFinding, revokeFindingRule, setFindingStatus, assertRowLimit, OPS_FAILURE_RETENTION_DAYS, SWEEP_RUN_RETENTION_DAYS, SWEEP_RUNS_INTENT_INDEX, sweepRunsIntentHasKind, PEER_SWITCHES_DDL, SWITCH_OWED_DDL, clearSwitchOwed, markSwitchOwed, scopeOwesSwitch, switchesOwedOf, SWITCH_KINDS, SYSTEM_SWITCHES_DDL, forgetSwitchesOf, listSystemSwitchRecords, recordSwitchedOff, recordSwitchedOn, recordWriteSuperseded, restoreSwitchRecord, scopesSwitchedOffFor, switchRecordStatesOf, switchRecordsOf, switchesBackfillSqlOf, switchesDdlOf, switchesTableExists, switchesTableOf, tenantHeldOf, VERSION_MIGRATIONS_DDL, splitVersionMigrationsBatch, versionMigrationsOf, versionsAwaitSplit, writeVersionMigrations, MODEL_USAGE_RETENTION_DAYS, DO_SQL_LIMITS, ulid, isPrimaryScopeRow, resolveVerticalInstanceFrom, LEGACY_SCOPE_ROWS_BACKFILL, loadDirectoryDump, redactSubjectDirectoryText, ISSUE_EXEMPLAR_OWNER_BACKFILL_SQL, issueExemplarOwner, } from '@substrat-run/kernel';
+import { membershipFencesBackfillSql, MEMBERSHIP_FENCES_DDL, MEMBERSHIP_FENCES_TABLE, membershipFencesTableExists, MEMBERSHIP_FENCE_SINCE_SQL, RAISE_MEMBERSHIP_FENCE_SQL, memberAddedAudit, orgChangeBound, tenantCoverage, IMPERSONATION_COLUMNS, IMPERSONATION_DDL, impersonationByIdQuery, impersonationListQuery, impersonationRowValues, ISSUE_RETENTION_DAYS, telemetryRetentionStatements, FINDINGS_DDL, CONNECT_LINKS_DDL, consumeConnectLinkRow, insertConnectLink as insertConnectLinkRow, listConnectLinks as listConnectLinkRows, readConnectLink as readConnectLinkRow, restoreConnectLinkRow, revokeConnectLinkRow, createFindingRule, findingOfOpsFailure, findingOfSweepRun, pruneFindings, listFindingRules, listFindings, observeFinding, revokeFindingRule, setFindingStatus, assertRowLimit, OPS_FAILURE_RETENTION_DAYS, SWEEP_RUN_RETENTION_DAYS, SWEEP_RUNS_INTENT_INDEX, sweepRunsIntentHasKind, PEER_SWITCHES_DDL, PEER_BINDINGS_DDL, SWITCH_OWED_DDL, clearSwitchOwed, markSwitchOwed, scopeOwesSwitch, switchesOwedOf, SWITCH_KINDS, SYSTEM_SWITCHES_DDL, forgetSwitchesOf, listSystemSwitchRecords, recordSwitchedOff, recordSwitchedOn, recordWriteSuperseded, restoreSwitchRecord, scopesSwitchedOffFor, switchRecordStatesOf, switchRecordsOf, switchesBackfillSqlOf, switchesDdlOf, switchesTableExists, switchesTableOf, tenantHeldOf, VERSION_MIGRATIONS_DDL, splitVersionMigrationsBatch, versionMigrationsOf, versionsAwaitSplit, writeVersionMigrations, MODEL_USAGE_RETENTION_DAYS, DO_SQL_LIMITS, ulid, isPrimaryScopeRow, resolveVerticalInstanceFrom, resolvePeerInstanceFrom, LEGACY_SCOPE_ROWS_BACKFILL, loadDirectoryDump, redactSubjectDirectoryText, ISSUE_EXEMPLAR_OWNER_BACKFILL_SQL, issueExemplarOwner, SETTLE_INTENT_SQL, SETTLE_OUTCOME_SQL, settleOutcomeParamsOf, unknownOutcomeOf, ADMIN_LOG_INDEX_DDL, ADMIN_LOG_INDEXES_SQL, readAuditedOperations, } from '@substrat-run/kernel';
 import { replyOf } from './do-reply.js';
-import { splitSqlStatements, switchSqlOver } from './scope-do.js';
+import { switchSqlOver } from './scope-do.js';
+import { blankSqlComments, executableSqlStatements } from '@substrat-run/kernel';
+import { COPY_CLAIM_SQL, COPY_EXPIRED_SQL, COPY_MOVE_CONFIRM_SQL, COPY_MOVE_LIVE_PREDICATE, SCOPE_COPY_LEASE_MS, SCOPE_SCRIPT_COPY_COLUMNS, copyMoveConfirmParams, copyMoveLiveParams, } from '@substrat-run/kernel';
 import { doBuiltColumnsOf, doRedactionSql } from './sql.js';
 import { assertReplayableDump, opsFailureFingerprint, ROUTE_SCOPE_HOSTNAMES_MAX, SCOPE_GATE_REASONS, substratError } from '@substrat-run/contracts';
 /**
@@ -138,6 +140,10 @@ const DIRECTORY_DDL = `
     status TEXT NOT NULL DEFAULT 'active',
     schema_version TEXT NOT NULL DEFAULT '0',
     vertical_version_id TEXT,
+    erasure_epoch INTEGER,
+    -- #1722: set once a reap has started draining this scope's script copies, and never
+    -- cleared: only deleting the row ends it. While set, no copy move is recorded or bound.
+    reap_claimed_at TEXT,
     -- Last FAILED migration attempt (§5.3). All null / 0 = healthy. Written on the
     -- failure path so a scope that fails closed stops rendering as active, and
     -- cleared on the next success. See ScopeDO.applyPendingMigrations.
@@ -159,6 +165,26 @@ const DIRECTORY_DDL = `
     serving_ref TEXT,
     created_at TEXT NOT NULL
   );
+  -- #1722: durable inventory of per-script copies. A fresh directory has no rows;
+  -- the historical audit-log backfill runs separately, after this additive migration.
+  CREATE TABLE IF NOT EXISTS scope_script_copies (
+    tenant_id TEXT NOT NULL,
+    scope_id TEXT NOT NULL,
+    script_ref TEXT NOT NULL,
+    move_id TEXT NOT NULL,
+    state TEXT NOT NULL,
+    load_stamp TEXT,
+    revision TEXT,
+    last_attempt_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    -- 'source' | 'destination'. A pending entry belongs to its move until lease_until; a
+    -- sweep that claims it after that sets lease_owner (kernel scope-copy-ledger.ts).
+    role TEXT,
+    lease_until TEXT,
+    lease_owner TEXT,
+    PRIMARY KEY (tenant_id, scope_id, script_ref, move_id)
+  );
+  CREATE INDEX IF NOT EXISTS scope_script_copies_state ON scope_script_copies (state, scope_id);
+  ${PEER_BINDINGS_DDL}
   CREATE TABLE IF NOT EXISTS hostnames (
     hostname      TEXT PRIMARY KEY,
     tenant_id     TEXT NOT NULL,
@@ -416,6 +442,9 @@ const DIRECTORY_DDL = `
     updated_at    TEXT NOT NULL,
     PRIMARY KEY (connection_id, state_key)
   );
+  -- A vertical's mailed connect links (connections.md §3.5.4) — kernel-owned DDL, so
+  -- both adapters build the same table.
+  ${CONNECT_LINKS_DDL}
   CREATE TABLE IF NOT EXISTS _substrat_identities (
     provider     TEXT NOT NULL,
     external_id  TEXT NOT NULL,
@@ -478,16 +507,12 @@ const DIRECTORY_DDL = `
     on_behalf_of TEXT,
     at TEXT NOT NULL
   );
-  -- Read-path indexes for the console (control-plane.md §4.5). The admin log is
-  -- append-only and only grows, so every filter it offers needs one.
+  -- Every admin-log index, from the kernel's one list (#2064), which the legacy
+  -- rebuild runs again after its rename.
   -- NOTE: keep every comment in this DDL free of semicolons. The constructor
   -- splits this string on the statement separator, and a semicolon inside a
   -- comment strands a comment-only fragment that execs as "no statement".
-  CREATE INDEX IF NOT EXISTS _substrat_admin_log_tenant ON _substrat_admin_log (tenant_id, id);
-  CREATE INDEX IF NOT EXISTS _substrat_admin_log_scope ON _substrat_admin_log (scope_id, id);
-  CREATE INDEX IF NOT EXISTS _substrat_admin_log_actor ON _substrat_admin_log (actor, id);
-  CREATE INDEX IF NOT EXISTS _substrat_admin_log_action ON _substrat_admin_log (action, id);
-  CREATE INDEX IF NOT EXISTS _substrat_admin_log_at ON _substrat_admin_log (at);
+  ${ADMIN_LOG_INDEXES_SQL}
   -- Operational failures (#559) - what the platform could NOT do, and why. NOT the
   -- admin log (that is the never-swept compliance witness of successful mutations)
   -- but retention-bounded telemetry, pruned on write after OPS_FAILURE_RETENTION_DAYS.
@@ -652,6 +677,8 @@ const SCOPE_COLUMNS_ADDED = [
     'name TEXT',
     'vertical TEXT',
     'vertical_version_id TEXT',
+    'erasure_epoch INTEGER',
+    'reap_claimed_at TEXT',
     'provisioned_version_id TEXT',
     'migration_failed_version TEXT',
     'migration_error TEXT',
@@ -674,8 +701,8 @@ const SCOPE_COLUMNS_ADDED = [
  * 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 all = executableSqlStatements(ddl);
+    const afterColumns = executableSqlStatements(VERSION_MIGRATIONS_DDL);
     const held = new Set(afterColumns);
     return {
         loop: all.filter((stmt) => !held.has(stmt)),
@@ -825,7 +852,7 @@ export class ControlPlaneDO extends DurableObject {
         this.buildDirectorySchema({ holdSwitchRecords: newRecords, holdFences: fencesAreNew });
         for (const kind of newRecords) {
             this.ctx.storage.transactionSync(() => {
-                for (const stmt of splitSqlStatements(switchesDdlOf(kind)))
+                for (const stmt of executableSqlStatements(switchesDdlOf(kind)))
                     this.sql.exec(stmt);
                 this.sql.exec(switchesBackfillSqlOf(kind));
             });
@@ -833,7 +860,7 @@ export class ControlPlaneDO extends DurableObject {
         // #1184: the removal fence and its backfill from the admin log, together, the same way.
         if (fencesAreNew) {
             this.ctx.storage.transactionSync(() => {
-                for (const stmt of splitSqlStatements(MEMBERSHIP_FENCES_DDL))
+                for (const stmt of executableSqlStatements(MEMBERSHIP_FENCES_DDL))
                     this.sql.exec(stmt);
                 // Stamped now, inside this unit (`membershipFencesBackfillSql` says why).
                 this.sql.exec(membershipFencesBackfillSql(new Date().toISOString()));
@@ -907,7 +934,7 @@ export class ControlPlaneDO extends DurableObject {
     rebuildAtomically(statements) {
         this.ctx.storage.transactionSync(() => {
             for (const stmt of statements)
-                this.sql.exec(stmt);
+                this.sql.exec(blankSqlComments(stmt));
         });
     }
     /**
@@ -972,6 +999,8 @@ export class ControlPlaneDO extends DurableObject {
          FROM _substrat_admin_log`,
             'DROP TABLE _substrat_admin_log',
             'ALTER TABLE _substrat_admin_log_new RENAME TO _substrat_admin_log',
+            // The DROP took every index on the table: rebuild them from the kernel's list (#2064).
+            ...ADMIN_LOG_INDEX_DDL,
         ]);
     }
     /**
@@ -1292,6 +1321,7 @@ export class ControlPlaneDO extends DurableObject {
             '_substrat_system_switches', // #1674: the schedule switch's record, per scope
             '_substrat_membership_fences', // #1184: the latest removal, per principal
             '_substrat_peer_switches', // #2029: the peer switch's record, per scope
+            'peer_bindings', // #1720: a tenant's explicit caller-to-target choices
             '_substrat_switch_owed', // #2045: subjects owed a re-assert, per scope
             '_substrat_findings', // #1748: the tenant's findings
             '_substrat_finding_rules', // #1748: the tenant's suppress rules
@@ -1654,6 +1684,9 @@ export class ControlPlaneDO extends DurableObject {
             else {
                 this.sql.exec('UPDATE scopes SET status = ? WHERE scope_id = ?', to, scopeId);
             }
+            if (to === 'archived' || to === 'reaped') {
+                this.sql.exec('UPDATE peer_bindings SET invalidated = 1 WHERE tenant_id = ? AND target_scope_id = ?', tenantId, scopeId);
+            }
             if (to === 'reaped') {
                 forgetSwitchesOf(this.kernelSql, scopeId);
                 this.forgetLifecycleDeliveries('scope_id = ?', scopeId);
@@ -1761,21 +1794,74 @@ export class ControlPlaneDO extends DurableObject {
             forkedFrom: r.forked_from ?? null,
         })), tenantId, vertical);
     }
+    /** Binding is read at call execution, so a queued invoke follows the current explicit choice. */
+    resolvePeerInstance(tenantId, callerScopeId, vertical) {
+        const rows = this.sql.exec(`SELECT scope_id, tenant_id, vertical, status, kind, forked_from FROM scopes
+       WHERE tenant_id = ? AND vertical = ?`, tenantId, vertical).toArray();
+        const binding = this.sql.exec('SELECT target_scope_id, invalidated FROM peer_bindings WHERE tenant_id = ? AND caller_scope_id = ? AND vertical = ?', tenantId, callerScopeId, vertical).toArray()[0];
+        return resolvePeerInstanceFrom(rows.map((r) => ({
+            id: r.scope_id,
+            tenantId: r.tenant_id,
+            vertical: r.vertical,
+            status: r.status,
+            kind: r.kind ?? '',
+            forkedFrom: r.forked_from,
+        })), tenantId, vertical, binding?.target_scope_id ?? null, binding?.invalidated === 1);
+    }
+    peerBinding(tenantId, callerScopeId, vertical) {
+        return this.sql.exec('SELECT target_scope_id, invalidated FROM peer_bindings WHERE tenant_id = ? AND caller_scope_id = ? AND vertical = ?', tenantId, callerScopeId, vertical).toArray()[0];
+    }
+    peerBindings(tenantId, callerScopeId) {
+        return this.sql.exec('SELECT vertical, target_scope_id, invalidated FROM peer_bindings WHERE tenant_id = ? AND caller_scope_id = ? ORDER BY vertical', tenantId, callerScopeId).toArray();
+    }
+    /** Directory write and endpoint checks share this DO's serialized unit. */
+    setPeerBinding(tenantId, callerScopeId, vertical, targetScopeId) {
+        const caller = this.sql.exec('SELECT tenant_id, status, kind, forked_from FROM scopes WHERE scope_id = ?', callerScopeId).toArray()[0];
+        if (!caller || caller.tenant_id !== tenantId || caller.status !== 'active' || !isPrimaryScopeRow(caller)) {
+            return { ok: false, code: 'not_found', message: 'calling app is not a live primary scope in this tenant' };
+        }
+        if (targetScopeId !== null) {
+            const target = this.sql.exec('SELECT tenant_id, vertical, status, kind, forked_from FROM scopes WHERE scope_id = ?', targetScopeId).toArray()[0];
+            if (!target || target.tenant_id !== tenantId || target.vertical !== vertical || target.status !== 'active' || !isPrimaryScopeRow(target)) {
+                return { ok: false, code: 'not_found', message: 'target is not a live primary instance of this vertical in this tenant' };
+            }
+        }
+        const before = this.peerBinding(tenantId, callerScopeId, vertical);
+        const previous = before?.target_scope_id ?? null;
+        if (previous === targetScopeId && before?.invalidated !== 1)
+            return { ok: true, changed: false, previous };
+        if (targetScopeId === null) {
+            this.sql.exec('DELETE FROM peer_bindings WHERE tenant_id = ? AND caller_scope_id = ? AND vertical = ?', tenantId, callerScopeId, vertical);
+        }
+        else {
+            this.sql.exec(`INSERT INTO peer_bindings (tenant_id, caller_scope_id, vertical, target_scope_id)
+         VALUES (?, ?, ?, ?) ON CONFLICT (tenant_id, caller_scope_id, vertical)
+         DO UPDATE SET target_scope_id = excluded.target_scope_id, invalidated = 0`, tenantId, callerScopeId, vertical, targetScopeId);
+        }
+        return { ok: true, changed: true, previous };
+    }
     /**
      * Everything the router needs to place ONE peer call (#1706), in one round trip: the
      * CALLER's own scope record, and the target instance of `vertical` in that tenant with the
      * script and dispatch parameters that instance runs under.
      *
-     * One read rather than three, because this sits on a request path. The caller's record is
+     * One directory RPC and two SQL reads, because this sits on a request path. The binding
+     * joins the caller read, so even an unbound singleton adds no round trip. The caller's record is
      * what decides whether it may call at all — live, primary, and the vertical it claims — and
      * it is read HERE rather than inferred from routing, so this path does not inherit #1713.
-     * The target side applies the kernel's one rule (`resolveVerticalInstanceFrom`), the same
+     * The target side applies the kernel's one rule (`resolvePeerInstanceFrom`), the same
      * rule the pure host and the local broker apply.
      */
     peerCallTarget(tenantId, callerScopeId, callerVertical, vertical) {
         const caller = this.sql
-            .exec(`SELECT s.tenant_id, s.vertical, s.status, s.kind, s.forked_from, t.status AS tenant_status
-           FROM scopes s LEFT JOIN tenants t ON t.tenant_id = s.tenant_id WHERE s.scope_id = ?`, callerScopeId)
+            .exec(`SELECT s.tenant_id, s.vertical, s.status, s.kind, s.forked_from,
+                t.status AS tenant_status, pb.target_scope_id AS bound_target_scope_id,
+                pb.invalidated AS binding_invalidated
+           FROM scopes s
+           LEFT JOIN tenants t ON t.tenant_id = s.tenant_id
+           LEFT JOIN peer_bindings pb ON pb.tenant_id = s.tenant_id
+             AND pb.caller_scope_id = s.scope_id AND pb.vertical = ?
+          WHERE s.scope_id = ?`, vertical, callerScopeId)
             .toArray()[0];
         const candidates = this.sql
             .exec(`SELECT s.scope_id, s.tenant_id, s.vertical, s.status, s.kind, s.forked_from,
@@ -1792,14 +1878,14 @@ export class ControlPlaneDO extends DurableObject {
            LEFT JOIN vertical_versions sv ON sv.id = vr.serving_version_id
           WHERE s.tenant_id = ? AND s.vertical = ?`, tenantId, vertical)
             .toArray();
-        const resolution = resolveVerticalInstanceFrom(candidates.map((r) => ({
+        const resolution = resolvePeerInstanceFrom(candidates.map((r) => ({
             id: r.scope_id,
             tenantId: r.tenant_id,
             vertical: r.vertical,
             status: r.status,
             kind: r.kind ?? '',
             forkedFrom: r.forked_from ?? null,
-        })), tenantId, vertical);
+        })), tenantId, vertical, caller?.bound_target_scope_id ?? null, caller?.binding_invalidated === 1);
         const target = resolution.outcome === 'resolved'
             ? (candidates.find((r) => r.scope_id === resolution.instance.scopeId) ?? null)
             : null;
@@ -2021,9 +2107,11 @@ export class ControlPlaneDO extends DurableObject {
         this.sql.exec(`UPDATE verticals SET serving_ref = ?, serving_version_id = ?,
               serving_do_classes = ?, serving_migration_tag = ? WHERE slug = ?`, s.ref, s.versionId, s.doClassesJson, s.migrationTag, slug);
     }
-    /** Point a scope's routing at the serving script its data now lives in (#286). */
-    setScopeServingRef(scopeId, servingRef) {
-        this.sql.exec('UPDATE scopes SET serving_ref = ? WHERE scope_id = ?', servingRef, scopeId);
+    /** Point a scope's routing at the serving script its data now lives in (#286). False when a
+     *  conditional move lost its compare-and-set: the host throws, since a refusal thrown here
+     *  would cross the RPC boundary without its code. */
+    setScopeServingRef(scopeId, servingRef, expectedErasureEpoch, confirmMove) {
+        return this.moveScopeRow('serving_ref = ?', [servingRef], scopeId, { expectedErasureEpoch, confirmMove });
     }
     /** Move a fork's GC deadline forward, or pin it (`null`) — preview-and-snapshots.md §9. */
     setScopeExpiresAt(scopeId, expiresAt) {
@@ -2047,13 +2135,131 @@ export class ControlPlaneDO extends DurableObject {
     setAdmission(id, admission, note) {
         this.sql.exec('UPDATE vertical_versions SET admission = ?, admission_note = ? WHERE id = ?', admission, note, id);
     }
-    bindScopeVersion(scopeId, versionId, verticalSlug, expectedVersionId) {
-        const update = expectedVersionId === undefined
-            ? this.sql.exec('UPDATE scopes SET vertical_version_id = ?, vertical = ? WHERE scope_id = ?', versionId, verticalSlug, scopeId)
-            : this.sql.exec('UPDATE scopes SET vertical_version_id = ?, vertical = ? WHERE scope_id = ? AND vertical_version_id IS ?', versionId, verticalSlug, scopeId, expectedVersionId);
-        if (update.rowsWritten === 0) {
-            throw substratError('precondition_failed', 'scope binding changed; reload the scope and retry');
+    /** False when a conditional bind lost its compare-and-set (the host throws, as above). */
+    bindScopeVersion(scopeId, versionId, verticalSlug, expectedVersionId, expectedErasureEpoch, confirmMove) {
+        return this.moveScopeRow('vertical_version_id = ?, vertical = ?', [versionId, verticalSlug], scopeId, { expectedVersionId, expectedErasureEpoch, confirmMove });
+    }
+    /**
+     * Move a scope's binding or route (#1722), conditionally: on the binding the caller read, on
+     * the erasure epoch its carry read (a NULL epoch, from before the column, is 0) with no reap
+     * claimed, and on its copy move still owning a live lease. The move's confirmation commits in
+     * the same transaction as the row. False when any condition failed and nothing was written.
+     */
+    moveScopeRow(set, setArgs, scopeId, cond) {
+        const now = new Date().toISOString();
+        return this.ctx.storage.transactionSync(() => {
+            const moved = this.sql.exec(`UPDATE scopes SET ${set} WHERE scope_id = ?
+         ${cond.expectedVersionId === undefined ? '' : 'AND vertical_version_id IS ?'}
+         ${cond.expectedErasureEpoch === undefined ? '' : 'AND COALESCE(erasure_epoch, 0) = ? AND reap_claimed_at IS NULL'}
+         ${cond.confirmMove === undefined ? '' : COPY_MOVE_LIVE_PREDICATE}`, ...setArgs, scopeId, ...(cond.expectedVersionId === undefined ? [] : [cond.expectedVersionId]), ...(cond.expectedErasureEpoch === undefined ? [] : [cond.expectedErasureEpoch]), ...(cond.confirmMove === undefined ? [] : copyMoveLiveParams(cond.confirmMove, now)));
+            if (moved.rowsWritten === 0)
+                return false;
+            if (cond.confirmMove) {
+                const { tenant_id } = this.sql.exec('SELECT tenant_id FROM scopes WHERE scope_id = ?', scopeId).one();
+                this.sql.exec(COPY_MOVE_CONFIRM_SQL, ...copyMoveConfirmParams(cond.confirmMove, tenant_id, scopeId, now));
+            }
+            return true;
+        });
+    }
+    scopeErasureEpoch(tenantId, scopeId) {
+        // NULL on every row from before the column (#1722): the same 0 every CAS compares against.
+        const row = this.sql.exec('SELECT COALESCE(erasure_epoch, 0) AS erasure_epoch FROM scopes WHERE tenant_id = ? AND scope_id = ?', tenantId, scopeId)
+            .toArray()[0];
+        if (!row)
+            throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
+        return row.erasure_epoch;
+    }
+    claimSubjectErasure(tenantId, scopeId, expectedVersionId, expectedServingRef, expectedEpoch, expectedCopyCount) {
+        return this.sql.exec(`UPDATE scopes SET erasure_epoch = COALESCE(erasure_epoch, 0) + 1
+       WHERE tenant_id = ? AND scope_id = ? AND vertical_version_id IS ?
+         AND serving_ref IS ? AND COALESCE(erasure_epoch, 0) = ?
+         AND NOT EXISTS (SELECT 1 FROM scope_script_copies AS copy
+           WHERE copy.tenant_id = scopes.tenant_id AND copy.scope_id = scopes.scope_id
+             AND copy.state = 'pending')
+         AND (SELECT COUNT(*) FROM scope_script_copies AS copy
+           WHERE copy.tenant_id = scopes.tenant_id AND copy.scope_id = scopes.scope_id) = ?`, tenantId, scopeId, expectedVersionId, expectedServingRef, expectedEpoch, expectedCopyCount).rowsWritten > 0;
+    }
+    recordScopeScriptCopy(tenantId, scopeId, scriptRef, moveId, role = null, loadStamp = null, leaseMs = SCOPE_COPY_LEASE_MS) {
+        if (!scriptRef || !moveId)
+            return 'invalid';
+        const written = this.sql.exec(`INSERT INTO scope_script_copies (tenant_id, scope_id, script_ref, move_id, state, role, load_stamp, lease_until)
+       SELECT tenant_id, scope_id, ?, ?, 'pending', ?, ?, ? FROM scopes
+       WHERE tenant_id = ? AND scope_id = ? AND reap_claimed_at IS NULL
+       ON CONFLICT (tenant_id, scope_id, script_ref, move_id) DO NOTHING`, scriptRef, moveId, role, loadStamp, new Date(Date.now() + leaseMs).toISOString(), tenantId, scopeId);
+        if (written.rowsWritten > 0)
+            return 'recorded';
+        const scope = this.sql.exec('SELECT reap_claimed_at FROM scopes WHERE tenant_id = ? AND scope_id = ?', tenantId, scopeId)
+            .toArray()[0];
+        if (!scope)
+            return 'missing';
+        if (scope.reap_claimed_at !== null)
+            return 'reaping';
+        return 'recorded'; // idempotent retry of this move
+    }
+    claimExpiredScopeScriptCopies(input) {
+        const limit = assertRowLimit('limit', input.limit);
+        return this.ctx.storage.transactionSync(() => {
+            const due = this.sql.exec(COPY_EXPIRED_SQL, input.now, limit).toArray();
+            const claimed = [];
+            for (const r of due) {
+                if (this.sql.exec(COPY_CLAIM_SQL, input.owner, input.leaseUntil, r.tenant_id, r.scope_id, r.script_ref, r.move_id, input.now).rowsWritten === 0)
+                    continue;
+                claimed.push(this.sql.exec(`SELECT ${SCOPE_SCRIPT_COPY_COLUMNS} FROM scope_script_copies
+           WHERE tenant_id = ? AND scope_id = ? AND script_ref = ? AND move_id = ?`, r.tenant_id, r.scope_id, r.script_ref, r.move_id).one());
+            }
+            return claimed;
+        });
+    }
+    beginScopeScriptReap(tenantId, scopeId) {
+        const written = this.sql.exec(`UPDATE scopes SET reap_claimed_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')
+       WHERE tenant_id = ? AND scope_id = ? AND reap_claimed_at IS NULL
+         AND NOT EXISTS (SELECT 1 FROM scope_script_copies AS move
+           WHERE move.tenant_id = scopes.tenant_id AND move.scope_id = scopes.scope_id
+             AND move.state = 'pending')`, tenantId, scopeId);
+        if (written.rowsWritten > 0)
+            return 'claimed';
+        const scope = this.sql.exec('SELECT reap_claimed_at FROM scopes WHERE tenant_id = ? AND scope_id = ?', tenantId, scopeId)
+            .toArray()[0];
+        if (!scope)
+            return 'missing';
+        return scope.reap_claimed_at !== null ? 'claimed' : 'pending'; // a reaper resumes its earlier claim
+    }
+    settleScopeScriptCopy(tenantId, scopeId, scriptRef, moveId, state, loadStamp, revision, claimedBy) {
+        return this.sql.exec(`UPDATE scope_script_copies SET state = ?, load_stamp = ?, revision = ?,
+         last_attempt_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')
+       WHERE tenant_id = ? AND scope_id = ? AND script_ref = ? AND move_id = ?
+         AND (state <> 'done' OR ? = 'done')
+         ${claimedBy === undefined ? '' : "AND state = 'pending' AND lease_owner = ?"}`, state, loadStamp, revision, tenantId, scopeId, scriptRef, moveId, state, ...(claimedBy === undefined ? [] : [claimedBy])).rowsWritten > 0;
+    }
+    touchScopeScriptCopy(tenantId, scopeId, scriptRef, moveId) {
+        this.sql.exec(`UPDATE scope_script_copies SET last_attempt_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')
+       WHERE tenant_id = ? AND scope_id = ? AND script_ref = ? AND move_id = ? AND state = 'eligible'`, tenantId, scopeId, scriptRef, moveId);
+    }
+    listScopeScriptCopies(filter) {
+        const where = [];
+        const args = [];
+        if (filter.tenantId) {
+            where.push('tenant_id = ?');
+            args.push(filter.tenantId);
+        }
+        if (filter.scopeId) {
+            where.push('scope_id = ?');
+            args.push(filter.scopeId);
+        }
+        if (filter.state) {
+            where.push('state = ?');
+            args.push(filter.state);
+        }
+        if (filter.after) {
+            if (!filter.tenantId || !filter.scopeId)
+                throw substratError('validation_failed', 'copy cursor requires tenant and scope');
+            where.push('(script_ref > ? OR (script_ref = ? AND move_id > ?))');
+            args.push(filter.after.scriptRef, filter.after.scriptRef, filter.after.moveId);
         }
+        const limit = assertRowLimit('limit', filter.limit ?? 100);
+        const order = filter.scopeId ? 'script_ref, move_id' : 'last_attempt_at, tenant_id, scope_id, script_ref';
+        return this.sql.exec(`SELECT ${SCOPE_SCRIPT_COPY_COLUMNS} FROM scope_script_copies ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+       ORDER BY ${order} LIMIT ?`, ...args, limit).toArray();
     }
     /**
      * Record which version this scope's provision last ran against (#1172).
@@ -2077,6 +2283,7 @@ export class ControlPlaneDO extends DurableObject {
      */
     deleteScopeDirectory(scopeId) {
         this.ctx.storage.transactionSync(() => {
+            this.sql.exec('UPDATE peer_bindings SET invalidated = 1 WHERE target_scope_id = ?', scopeId);
             this.sql.exec('DELETE FROM hostnames WHERE scope_id = ?', scopeId);
             forgetSwitchesOf(this.kernelSql, scopeId);
             this.forgetLifecycleDeliveries('scope_id = ?', scopeId);
@@ -2585,6 +2792,42 @@ export class ControlPlaneDO extends DurableObject {
        WHERE connection_id = ? AND revoked_at IS NULL`, at, id);
         return true;
     }
+    // -- a vertical's mailed connect links (connections.md §3.5.4) ------------------
+    // The kernel's statements (`connect-links.ts`), shared with the pure adapter. Each
+    // runs inside this single-threaded object with no await between its read and its
+    // write, which is what makes consume's single-use hold across racing callbacks here;
+    // the UPDATE's own WHERE holds it again regardless. `now` is the coordinator's. A move
+    // and the audit row it hands back commit in one unit: `audit` is the row the host
+    // minted (actor, attribution), completed here from what the move changed.
+    insertConnectLink(row, audit) {
+        return this.auditedConnectLink(audit, (sql, write) => insertConnectLinkRow(sql, row, write));
+    }
+    readConnectLink(key) {
+        return readConnectLinkRow(doRedactionSql(this.sql), key);
+    }
+    listConnectLinks(filter, now) {
+        return listConnectLinkRows(doRedactionSql(this.sql), filter, now);
+    }
+    revokeConnectLink(key, audit) {
+        return this.auditedConnectLink(audit, (sql, write) => revokeConnectLinkRow(sql, key, write));
+    }
+    consumeConnectLink(input, now, audit) {
+        return this.auditedConnectLink(audit, (sql, write) => consumeConnectLinkRow(sql, input, now, write));
+    }
+    restoreConnectLink(key, now, audit) {
+        return this.auditedConnectLink(audit, (sql, write) => restoreConnectLinkRow(sql, key, now, write));
+    }
+    auditedConnectLink(audit, run) {
+        return this.ctx.storage.transactionSync(() => run(doRedactionSql(this.sql), (a) => this.recordAdmin({
+            ...audit,
+            action: a.action,
+            tenantId: a.target.tenantId,
+            scopeId: a.target.scopeId,
+            vertical: a.target.vertical,
+            before: a.before,
+            after: a.after,
+        })));
+    }
     /**
      * Record a connection grant directory-side (#592) — written by `grantToConnection`
      * alongside the enforcement tuple, upserting in place on re-grant (the unique
@@ -2955,7 +3198,7 @@ export class ControlPlaneDO extends DurableObject {
      * #1713: the scopes whose lifecycle a deployment must hold, with their lifecycle as this
      * directory holds it. A scope with a vertical (only a deployment serves one), past provisioning
      * and not reaped (a reaped store must not be recreated by a delivery), under a tenant that is
-     * not reaped. `scopeId` narrows it to one scope and `tenantId` to one tenant's scopes, the
+     * not reaped, of a vertical that does not declare its lifecycle held at the router. `scopeId` narrows it to one scope and `tenantId` to one tenant's scopes, the
      * fan-out of a tenant transition. With `drift`, only the scopes the heal sweep must deliver to:
      * a receipt that differs from the directory, and every scope held now. Re-delivering a held
      * scope every pass is what puts a hold back on a store a carry or a restore landed without it,
@@ -2966,6 +3209,10 @@ export class ControlPlaneDO extends DurableObject {
             's.vertical IS NOT NULL',
             "s.status NOT IN ('provisioning', 'reaped')",
             "t.status <> 'reaped'",
+            // A vertical that declares its lifecycle held at the router (`lifecycleHold`) has no route
+            // to deliver to and nothing a delivery would hold: none of its scopes is a target, for a
+            // transition, the heal's drift, or the #2016 tenant-record ask alike.
+            `COALESCE(CASE WHEN json_valid(v.install_spec) THEN json_extract(v.install_spec, '$.lifecycle') END, '') <> 'router'`,
         ];
         const params = [];
         if (filter.tenantId) {
@@ -3004,6 +3251,7 @@ export class ControlPlaneDO extends DurableObject {
                 ${epoch} AS epoch, COALESCE(rs.revision, 0) AS scope_rev, COALESCE(rt.revision, 0) AS tenant_rev
            FROM scopes s
            JOIN tenants t ON t.tenant_id = s.tenant_id
+           LEFT JOIN verticals v ON v.slug = s.vertical
            LEFT JOIN scope_lifecycle_receipts r ON r.scope_id = s.scope_id
            LEFT JOIN scope_tenant_asks a ON a.scope_id = s.scope_id
            LEFT JOIN lifecycle_revisions rs ON rs.subject = 'scope:' || s.scope_id
@@ -3055,50 +3303,99 @@ export class ControlPlaneDO extends DurableObject {
     recordOpsFailure(row) {
         // #1748: the evidence, its issue and its finding in ONE unit — a detector that throws takes
         // the evidence with it, so the caller's retry observes it rather than losing the observation.
-        this.ctx.storage.transactionSync(() => {
-            this.sql.exec(`INSERT INTO _substrat_ops_failures
-           (id, actor, operation, stage, tenant_id, scope_id, vertical, version, status, message, reference, origin, code, fingerprint, at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, row.id, row.actor, row.operation, row.stage, row.tenant_id, row.scope_id, row.vertical, row.version, row.status, row.message, row.reference, row.origin, row.code, row.fingerprint, row.at);
-            // Prune-on-write (#559): the retention lives HERE, not in a cron — every insert
-            // pays for its own housekeeping, so the table stays bounded even on a deployment
-            // whose scheduled pass is broken (the exact circumstance this table records).
-            const horizon = new Date(Date.now() - OPS_FAILURE_RETENTION_DAYS * 86_400_000).toISOString();
-            this.sql.exec('DELETE FROM _substrat_ops_failures WHERE at < ?', horizon);
-            // The issues materialization (#1233): the group's counters live on their own
-            // row, bumped in the same call, because the evidence self-prunes above and a
-            // count must survive its own exemplars. A fresh arrival regresses a resolved
-            // issue; an ignored one stays ignored — that is what ignoring means.
-            if (row.fingerprint !== null) {
-                this.sql.exec(`INSERT INTO _substrat_issues
-             (fingerprint, operation, stage, origin, code, status, seen_count, first_seen, last_seen, last_message, last_tenant_id, last_owner_kind, last_vertical, last_version, resolved_version, resolved_at)
-           VALUES (?, ?, ?, ?, ?, 'new', 1, ?, ?, ?, ?, ?, ?, ?, NULL, NULL)
-           ON CONFLICT (fingerprint) DO UPDATE SET
-             seen_count = seen_count + 1,
-             last_seen = excluded.last_seen,
-             last_message = excluded.last_message,
-             last_tenant_id = excluded.last_tenant_id,
-             last_owner_kind = excluded.last_owner_kind,
-             last_vertical = COALESCE(excluded.last_vertical, last_vertical),
-             last_version = COALESCE(excluded.last_version, last_version),
-             origin = COALESCE(excluded.origin, origin),
-             status = CASE WHEN status = 'resolved' THEN 'regressed' ELSE status END`, row.fingerprint, row.operation, row.stage, row.origin, row.code, row.at, row.at, row.message, row.tenant_id, issueExemplarOwner(row.tenant_id), row.vertical, row.version);
-                const issueHorizon = new Date(Date.now() - ISSUE_RETENTION_DAYS * 86_400_000).toISOString();
-                this.sql.exec('DELETE FROM _substrat_issues WHERE last_seen < ?', issueHorizon);
-                // #1748: the tenant's Recurring finding, over the tenant's own occurrences only.
-                const finding = findingOfOpsFailure({
-                    tenantId: row.tenant_id,
-                    scopeId: row.scope_id,
-                    operation: row.operation,
-                    stage: row.stage,
-                    code: row.code,
-                    vertical: row.vertical,
-                    version: row.version,
-                });
-                if (finding)
-                    observeFinding(doRedactionSql(this.sql), finding, row.at);
+        this.ctx.storage.transactionSync(() => this.insertOpsFailure(row));
+    }
+    /**
+     * #2064: settle an audited-change intent with no outcome — read it, and only if no outcome row
+     * exists for its operation, write the `unknown` row and its ops-failure row. One unit, so two
+     * racing passes settle once and the digest row cannot be lost. See the kernel's `audit-outcome.ts`.
+     */
+    settleUnrecordedOutcome(input) {
+        return this.ctx.storage.transactionSync(() => {
+            const row = this.sql.exec(SETTLE_INTENT_SQL, input.intentId).toArray()[0];
+            const outcome = unknownOutcomeOf(row, input.intentId, input.error);
+            if (this.sql.exec(SETTLE_OUTCOME_SQL, ...settleOutcomeParamsOf(outcome.operation)).toArray().length > 0) {
+                return false;
             }
+            const at = new Date().toISOString();
+            this.recordAdmin({
+                id: ulid(),
+                actor: input.actor,
+                action: outcome.action,
+                ...outcome.target,
+                before: null,
+                after: outcome.after,
+                at,
+            });
+            const failure = { ...outcome.failure, actor: input.actor };
+            this.insertOpsFailure({
+                id: ulid(),
+                actor: input.actor,
+                operation: failure.operation,
+                stage: failure.stage ?? null,
+                tenant_id: failure.tenantId ?? null,
+                scope_id: failure.scopeId ?? null,
+                vertical: failure.vertical ?? null,
+                version: null,
+                status: null,
+                message: failure.message.slice(0, 2000),
+                reference: failure.reference ?? null,
+                origin: null,
+                code: null,
+                fingerprint: opsFailureFingerprint(failure),
+                at,
+            });
+            return true;
         });
     }
+    /** #2064: an audited operation's rows, by the operation-id index, in bounded batches. */
+    auditedOperations(refs) {
+        return readAuditedOperations((sql, params) => this.sql.exec(sql, ...params).toArray(), refs);
+    }
+    /** The body of `recordOpsFailure`, for a caller already inside a transaction. */
+    insertOpsFailure(row) {
+        this.sql.exec(`INSERT INTO _substrat_ops_failures
+         (id, actor, operation, stage, tenant_id, scope_id, vertical, version, status, message, reference, origin, code, fingerprint, at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, row.id, row.actor, row.operation, row.stage, row.tenant_id, row.scope_id, row.vertical, row.version, row.status, row.message, row.reference, row.origin, row.code, row.fingerprint, row.at);
+        // Prune-on-write (#559): the retention lives HERE, not in a cron — every insert
+        // pays for its own housekeeping, so the table stays bounded even on a deployment
+        // whose scheduled pass is broken (the exact circumstance this table records).
+        const horizon = new Date(Date.now() - OPS_FAILURE_RETENTION_DAYS * 86_400_000).toISOString();
+        this.sql.exec('DELETE FROM _substrat_ops_failures WHERE at < ?', horizon);
+        // The issues materialization (#1233): the group's counters live on their own
+        // row, bumped in the same call, because the evidence self-prunes above and a
+        // count must survive its own exemplars. A fresh arrival regresses a resolved
+        // issue; an ignored one stays ignored — that is what ignoring means.
+        if (row.fingerprint !== null) {
+            this.sql.exec(`INSERT INTO _substrat_issues
+           (fingerprint, operation, stage, origin, code, status, seen_count, first_seen, last_seen, last_message, last_tenant_id, last_owner_kind, last_vertical, last_version, resolved_version, resolved_at)
+         VALUES (?, ?, ?, ?, ?, 'new', 1, ?, ?, ?, ?, ?, ?, ?, NULL, NULL)
+         ON CONFLICT (fingerprint) DO UPDATE SET
+           seen_count = seen_count + 1,
+           last_seen = excluded.last_seen,
+           last_message = excluded.last_message,
+           last_tenant_id = excluded.last_tenant_id,
+           last_owner_kind = excluded.last_owner_kind,
+           last_vertical = COALESCE(excluded.last_vertical, last_vertical),
+           last_version = COALESCE(excluded.last_version, last_version),
+           origin = COALESCE(excluded.origin, origin),
+           status = CASE WHEN status = 'resolved' THEN 'regressed' ELSE status END`, row.fingerprint, row.operation, row.stage, row.origin, row.code, row.at, row.at, row.message, row.tenant_id, issueExemplarOwner(row.tenant_id), row.vertical, row.version);
+            const issueHorizon = new Date(Date.now() - ISSUE_RETENTION_DAYS * 86_400_000).toISOString();
+            this.sql.exec('DELETE FROM _substrat_issues WHERE last_seen < ?', issueHorizon);
+            // #1748: the tenant's Recurring finding, over the tenant's own occurrences only.
+            const finding = findingOfOpsFailure({
+                tenantId: row.tenant_id,
+                scopeId: row.scope_id,
+                operation: row.operation,
+                stage: row.stage,
+                code: row.code,
+                vertical: row.vertical,
+                version: row.version,
+            });
+            if (finding)
+                observeFinding(doRedactionSql(this.sql), finding, row.at);
+        }
+    }
     /**
      * #1632: subject erasure's directory half — the failure text this directory keeps about a
      * scope's subject. The kernel's walk, so the SQLite host runs the identical statements.