@substrat-run/adapter-cloudflare 0.140.0 → 0.142.0

package/dist/control-plane-do.js

@@ -1,8 +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, 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 { 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, SCOPE_STORAGE_DDL, forgetScopeStorage, listScopeStorageAttemptRows, listScopeStorageRows, pruneScopeStorageRows, recordScopeStorageRows, 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 { switchSqlOver } from './scope-do.js';
 import { blankSqlComments, executableSqlStatements } from '@substrat-run/kernel';
+import { COPY_BACKFILL_SCOPE_SQL, COPY_BACKFILL_SQL, COPY_BACKFILL_SUPERSEDE_SQL, COPY_CLAIM_SQL, COPY_EXPIRED_SQL, copyBackfillParams, copyBackfillRefusal, 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';
 /**
@@ -139,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.
@@ -154,12 +159,34 @@ const DIRECTORY_DDL = `
     -- filter (archived longer than N days); null for scopes that never archived. Stamped
     -- by transitionScope on the edge into archived, cleared on unarchive.
     archived_at TEXT,
+    -- #1524: the status it was archived FROM. 'provisioning' = it never held data, so the
+    -- storage gauge neither reads nor counts it. Written with archived_at, cleared with it.
+    archived_from_status TEXT,
     -- The scope's data lives in THIS dispatch script (#286). NULL = legacy per-version
     -- dispatch (the bound version's own script). Set at provision once the vertical has
     -- a serving script, or by adopt-serving when a legacy scope's data is moved over.
     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,
@@ -607,6 +634,8 @@ const DIRECTORY_DDL = `
   );
   CREATE INDEX IF NOT EXISTS _substrat_model_usage_tenant ON _substrat_model_usage (tenant_id, at);
   CREATE INDEX IF NOT EXISTS _substrat_model_usage_at ON _substrat_model_usage (at);
+  -- #1524: the stored storage gauge — one row per (scope, UTC day), kernel-owned DDL.
+  ${SCOPE_STORAGE_DDL}
   CREATE INDEX IF NOT EXISTS scopes_tenant ON scopes (tenant_id, scope_id);
   -- #1713: the lifecycle each hosted scope's deployment last acknowledged, as
   -- "<scope status>/<tenant status>" (lifecycleReceipt). A CP-less deployment has no
@@ -653,6 +682,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',
@@ -663,6 +694,7 @@ const SCOPE_COLUMNS_ADDED = [
     'expires_at TEXT',
     'serving_ref TEXT',
     'archived_at TEXT',
+    'archived_from_status TEXT',
 ];
 /**
  * A directory DDL's statements in the order `applyDirectorySchema` runs them: `loop` before
@@ -1299,6 +1331,8 @@ export class ControlPlaneDO extends DurableObject {
             '_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
+            '_substrat_scope_storage', // #1524: storage samples of scopes whose storage is gone
+            '_substrat_scope_storage_attempts', // #1524: and the phase's last try at each
         ]) {
             this.sql.exec(`DELETE FROM ${table} WHERE tenant_id = ?`, tenantId);
         }
@@ -1649,11 +1683,12 @@ export class ControlPlaneDO extends DurableObject {
             // 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.
+            // #1524: the status it left is recorded beside the stamp and cleared with it.
             if (to === 'archived') {
-                this.sql.exec('UPDATE scopes SET status = ?, archived_at = ? WHERE scope_id = ?', to, new Date().toISOString(), scopeId);
+                this.sql.exec('UPDATE scopes SET status = ?, archived_at = ?, archived_from_status = ? WHERE scope_id = ?', to, new Date().toISOString(), row.status, scopeId);
             }
             else if (to === 'active') {
-                this.sql.exec('UPDATE scopes SET status = ?, archived_at = NULL WHERE scope_id = ?', to, scopeId);
+                this.sql.exec('UPDATE scopes SET status = ?, archived_at = NULL, archived_from_status = NULL WHERE scope_id = ?', to, scopeId);
             }
             else {
                 this.sql.exec('UPDATE scopes SET status = ? WHERE scope_id = ?', to, scopeId);
@@ -1664,6 +1699,8 @@ export class ControlPlaneDO extends DurableObject {
             if (to === 'reaped') {
                 forgetSwitchesOf(this.kernelSql, scopeId);
                 this.forgetLifecycleDeliveries('scope_id = ?', scopeId);
+                // #1524: its storage is gone, so its samples describe nothing.
+                forgetScopeStorage(doRedactionSql(this.sql), scopeId);
             }
             this.bumpLifecycleRevision(`scope:${scopeId}`); // #1713, with the status it counts
         });
@@ -2081,9 +2118,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) {
@@ -2107,13 +2146,152 @@ 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));
+                this.sql.exec(COPY_BACKFILL_SUPERSEDE_SQL, tenant_id, scopeId);
+            }
+            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
+    }
+    /**
+     * Record a pre-ledger copy, and its `backfillScopeCopy` audit row in the same unit (#1722): the row
+     * carries the erasure epoch read here, which the backfill orders erasures by, so an entry with no
+     * row (an audit write lost after the insert) would let a later run compare against an older epoch.
+     */
+    backfillScopeScriptCopy(tenantId, scopeId, scriptRef, audit) {
+        return this.ctx.storage.transactionSync(() => {
+            const written = this.sql.exec(COPY_BACKFILL_SQL, ...copyBackfillParams(tenantId, scopeId, scriptRef)).rowsWritten > 0;
+            const scope = this.sql.exec(COPY_BACKFILL_SCOPE_SQL, tenantId, scopeId).toArray()[0];
+            if (!written)
+                return copyBackfillRefusal(scope);
+            this.recordAdmin({ ...audit, before: { erasureEpoch: scope.erasure_epoch } });
+            return 'recorded';
+        });
+    }
+    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.ctx.storage.transactionSync(() => {
+            const settled = 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;
+            if (settled && state === 'done')
+                this.sql.exec(COPY_BACKFILL_SUPERSEDE_SQL, tenantId, scopeId);
+            return settled;
+        });
+    }
+    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).
@@ -2141,6 +2319,7 @@ export class ControlPlaneDO extends DurableObject {
             this.sql.exec('DELETE FROM hostnames WHERE scope_id = ?', scopeId);
             forgetSwitchesOf(this.kernelSql, scopeId);
             this.forgetLifecycleDeliveries('scope_id = ?', scopeId);
+            forgetScopeStorage(doRedactionSql(this.sql), scopeId);
             this.sql.exec('DELETE FROM scopes WHERE scope_id = ?', scopeId);
         });
     }
@@ -2436,13 +2615,29 @@ export class ControlPlaneDO extends DurableObject {
                 .exec(`SELECT tenant_id, slug, status FROM tenants${where}`, ...args)
                 .toArray(),
             scopes: this.sql
-                .exec(`SELECT tenant_id, status FROM scopes${where}`, ...args)
+                .exec(`SELECT tenant_id, status, archived_from_status FROM scopes${where}`, ...args)
                 .toArray(),
             entitlements: this.sql
                 .exec(`SELECT tenant_id, entitlement_key, plan, expires_at FROM _substrat_entitlements${where}`, ...args)
                 .toArray(),
+            // #1524: the stored gauge's latest sample per non-reaped scope. A directory read only.
+            storage: listScopeStorageRows(doRedactionSql(this.sql), { tenantId: tenantId, latest: true }),
+            storageAttempts: listScopeStorageAttemptRows(doRedactionSql(this.sql), tenantId),
         };
     }
+    // -- the stored storage gauge (#1524) — kernel `storage-gauge.ts` --------------
+    recordScopeStorage(readings) {
+        return { recorded: this.ctx.storage.transactionSync(() => recordScopeStorageRows(doRedactionSql(this.sql), readings)) };
+    }
+    listScopeStorage(filter) {
+        return listScopeStorageRows(doRedactionSql(this.sql), filter);
+    }
+    listScopeStorageAttempts() {
+        return listScopeStorageAttemptRows(doRedactionSql(this.sql));
+    }
+    pruneScopeStorage(limit) {
+        return pruneScopeStorageRows(doRedactionSql(this.sql), Date.now(), limit);
+    }
     // -- identity pools (K-23) --------------------------------------------------
     readPool(provider) {
         return this.sql