@substrat-run/control-plane-api 0.135.0 → 0.136.0

package/dist/api.js

@@ -1,8 +1,8 @@
 import { resolveObservabilityWindow } from './observability-window.js';
 import { Hono } from 'hono';
-import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ownerTransferInput, OWNER_TRANSFER_AUDIT_ERROR_MAX, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, connectionFilter, connectionHealthState, connectionProvider, connectorDispatchKind, PROVISION_SIBLING_KIND, ARCHIVE_SCOPE_KIND, PROVISION_TENANT_KIND, SET_ENTITLEMENTS_KIND, MODEL_USAGE_KIND, SWEEP_RUNS_KIND, toConnectionHealthEntry, CONNECTION_EXPIRY_WARNING_DAYS, CONNECTION_STALE_DAYS, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, impersonationStamp, promotionAcknowledgement, bindAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, errorCodeOf, capabilityFilterQuery, } from '@substrat-run/contracts';
+import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ownerTransferInput, OWNER_TRANSFER_AUDIT_ERROR_MAX, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, connectionFilter, connectionHealthState, connectionProvider, connectorDispatchKind, PROVISION_SIBLING_KIND, ARCHIVE_SCOPE_KIND, PROVISION_TENANT_KIND, SET_ENTITLEMENTS_KIND, MODEL_USAGE_KIND, SWEEP_RUNS_KIND, toConnectionHealthEntry, CONNECTION_EXPIRY_WARNING_DAYS, CONNECTION_STALE_DAYS, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, impersonationStamp, promotionAcknowledgement, bindAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, errorCodeOf, capabilityFilterQuery, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, } from '@substrat-run/contracts';
 import { attributeFailure } from './failure-attribution.js';
-import { BIND_EXPORT_BREAK_REFUSAL, bindExportBreakRefusal, crossVerticalHealth, exportBreakRefusal, isBindExportBreakRefusal, isExportBreakRefusal, migrationProgress, ulid, } from '@substrat-run/kernel';
+import { BIND_EXPORT_BREAK_REFUSAL, CARRIED_AWAY_KEY, bindExportBreakRefusal, carriedAwayDump, dumpMetaValue, metaValueIn, crossVerticalHealth, exportBreakRefusal, isBindExportBreakRefusal, isExportBreakRefusal, isPrimaryScope, migrationProgress, ulid, } from '@substrat-run/kernel';
 import { TENANT_HEADER, confinedTenant } from './auth.js';
 import { mintTenantToken } from './tenant-token.js';
 import { connectionGrantsForScope } from './vertical-client.js';
@@ -37,6 +37,7 @@ import { TENANT_SERIES_SCOPE_CAP, REQUEST_FACET_KEYS } from './observability.js'
 import { parseTenantRequestQuery, parseTenantWindowQuery, refineTenantWindow, scriptFamiliesOfScopes } from './tenant-request-query.js';
 import { namespacesForScript } from './do-namespaces.js';
 import { backupDirectoryIfDue } from './directory-backup.js';
+import { deployedDoClasses, platformSweeperDecision } from './platform-entry.js';
 import { STORAGE_PAGE_DEFAULT, STORAGE_PAGE_MAX, readStoragePage } from './storage-meter.js';
 import { isCustomHostname, validateBindableHostname, } from './custom-hostnames.js';
 /**
@@ -46,6 +47,13 @@ import { isCustomHostname, validateBindableHostname, } from './custom-hostnames.
  */
 export const CLI_MIN_VERSION_HEADER = 'x-substrat-cli-min-version';
 export const CLI_LATEST_VERSION_HEADER = 'x-substrat-cli-latest-version';
+/**
+ * The directory's classification of a scope that is not primary (#2005), which a verb sends so
+ * the store it writes is marked a copy whatever its own marker says; undefined for a primary one.
+ */
+function copyLineageOf(scope) {
+    return isPrimaryScope(scope) ? undefined : { kind: scope.kind, forkedFrom: scope.forkedFrom };
+}
 /**
  * "This principal is confined to a tenant, and this is not that tenant."
  *
@@ -70,6 +78,27 @@ class ExportBreakRefused extends ControlPlaneError {
         this.breaks = breaks;
     }
 }
+/**
+ * A carry whose source store kept changing between its export and its bind (#1722, Codex #2008
+ * r12): every re-carry from a fresh export found the source changed again before it could bind.
+ * Nothing was bound and the destination's copy was dropped, so the caller retries the bind. Typed,
+ * so a client tells it from the other 409s: `carrySourceChanged` names the two scripts and how many
+ * exports were tried.
+ */
+class CarrySourceChanged extends ControlPlaneError {
+    scopeId;
+    from;
+    to;
+    attempts;
+    constructor(scopeId, from, to, attempts) {
+        super(409, `scope ${scopeId}'s store in '${from}' changed while it was being carried to '${to}', on each of ` +
+            `${attempts} exports, so nothing was bound (#1722). Retry the bind.`);
+        this.scopeId = scopeId;
+        this.from = from;
+        this.to = to;
+        this.attempts = attempts;
+    }
+}
 /** The body a route answers an `ExportBreakRefused` with: the sentence and the listing. */
 function exportBreakBody(e) {
     return { error: e.message, ...(e instanceof ExportBreakRefused ? { exportBreaks: { affected: e.breaks } } : {}) };
@@ -253,6 +282,9 @@ const rebindScopeVerticalBody = z.object({
 // #1756: an adopt moves the scope onto what its vertical serves, and is refused when that breaks
 // an app in the tenant. The body is optional, as it always was.
 const adoptServingBody = z.object({ acknowledge: bindAcknowledgement.optional() });
+// The BULK form starts a run over every still-legacy scope of a vertical, so it reads its body
+// strictly (`readJsonBody`); the single-scope form above keeps the lenient parse it always had.
+const adoptVerticalServingBody = adoptServingBody.strict();
 // A snapshot request (preview-and-snapshots.md §3/§9). `expiresAt` opts into the GC
 // sweep; absent = pinned until deliberately deleted. `kind` defaults to 'archive'.
 const snapshotScopeBody = z.object({
@@ -265,9 +297,43 @@ const snapshotScopeBody = z.object({
 //   false     — the explicit "I accept an unrecoverable wipe"
 //   undefined — back up if a store is configured, proceed without one if not, which is
 //               what keeps every pre-#493 caller (and self-host) working unchanged
-const reapScopeBody = z.object({
+const reapScopeBody = z
+    .object({
     backup: z.boolean().optional(),
-});
+})
+    .strict();
+/**
+ * Read the JSON body of a route whose default is an ACT (a reap, a bulk adoption, a fleet
+ * repair), under one grammar. The old `await c.req.json().catch(() => ({}))` turned a body
+ * that did not parse into the defaults, so a body of `{"backup": true` (cut short on the wire)
+ * ran the action it was cut short of describing.
+ *
+ * **Only a ZERO-LENGTH body takes the defaults.** Any other body must hold a JSON value, or it
+ * is a 400. That is deliberately not "an empty-looking body": a body of whitespace, or of a
+ * byte-order mark and nothing else, is a request that did not arrive intact, and reading it as
+ * "no body" would run the default act on it (a tenant reap of ` \t\n ` reaped with no backup).
+ * So the check is on the BYTES, before any decoding or trimming, and a leading BOM is stripped
+ * only so that JSON following it can parse. Do not "simplify" this to `text.trim() === ''`.
+ *
+ * The schema decides the rest. One that guards an act is `.strict()`, so a misspelt key is
+ * refused rather than dropped.
+ */
+async function readJsonBody(c, schema) {
+    const bytes = await c.req.arrayBuffer();
+    let raw = {};
+    if (bytes.byteLength > 0) {
+        // `ignoreBOM: true` KEEPS the mark in the string; the default decoder would drop it and
+        // let a BOM-only body decode to '' and look empty.
+        const text = new TextDecoder('utf-8', { ignoreBOM: true }).decode(bytes).replace(/^\uFEFF/, '');
+        try {
+            raw = JSON.parse(text);
+        }
+        catch {
+            throw new ControlPlaneError(400, 'the body is not valid JSON');
+        }
+    }
+    return schema.parse(raw);
+}
 // A directory-restore request (#40). `capturedAt` addresses the copy — there is one
 // directory, so that is its whole address. `overwrite` is the guard against the
 // dangerous case: replaying a restore onto a control plane that already recovered.
@@ -695,17 +761,22 @@ export function createControlPlaneApi(options) {
     // The CLI version advisory (#971), stamped on EVERY response — including the 401 the
     // auth middleware below answers with, since a CLI too old to authenticate is exactly
     // the one that needs to hear it. Registered first so nothing can return around it.
-    // Nothing configured ⇒ no header touched, byte-identical to before this existed.
+    // Nothing configured ⇒ no advisory header.
+    //
+    // Beside it, the capability half of the same handshake (#1902): what this plane provides
+    // that a CLI may leave out on its strength. Stamped unconfigured, because it is a fact about
+    // this code rather than about a deployment — the uploader this package ships supplies the
+    // scope sweeper. The CLI asks before omitting one and refuses on silence, which is what an
+    // older plane answers.
     const advisory = options.cliAdvisory;
-    if (advisory?.minVersion || advisory?.latestVersion) {
-        app.use('*', async (c, next) => {
-            await next();
-            if (advisory.minVersion)
-                c.header(CLI_MIN_VERSION_HEADER, advisory.minVersion);
-            if (advisory.latestVersion)
-                c.header(CLI_LATEST_VERSION_HEADER, advisory.latestVersion);
-        });
-    }
+    app.use('*', async (c, next) => {
+        await next();
+        c.header(PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER);
+        if (advisory?.minVersion)
+            c.header(CLI_MIN_VERSION_HEADER, advisory.minVersion);
+        if (advisory?.latestVersion)
+            c.header(CLI_LATEST_VERSION_HEADER, advisory.latestVersion);
+    });
     // Fail closed, before any route runs: no principal, no reach.
     //
     // The TENANT-SCOPED credential is read FIRST (#977), ahead of staff. Not for
@@ -962,6 +1033,9 @@ export function createControlPlaneApi(options) {
         }
         if (err instanceof ExportBreakRefused)
             return c.json(exportBreakBody(err), 409);
+        if (err instanceof CarrySourceChanged) {
+            return c.json({ error: err.message, carrySourceChanged: { scopeId: err.scopeId, from: err.from, to: err.to, attempts: err.attempts } }, 409);
+        }
         const { status, body } = mapError(err);
         // A 5xx is the PLATFORM failing — an unmapped throw, or a downstream vertical's
         // own 5xx passing through (a DO storage fault during a preview restore is the
@@ -1055,7 +1129,7 @@ export function createControlPlaneApi(options) {
     app.post('/tenants/:tenantId/reap', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const actor = c.get('actor');
-        const { backup: wantsBackup } = reapScopeBody.parse(await c.req.json().catch(() => ({})));
+        const { backup: wantsBackup } = await readJsonBody(c, reapScopeBody);
         const tenant = await c.var.admin.getTenant(actor, tenantId);
         if (!tenant)
             return c.json({ error: `unknown tenant: ${tenantId}` }, 404);
@@ -1843,12 +1917,23 @@ export function createControlPlaneApi(options) {
      */
     const restoreCarryingSwitches = async (actor, dest, tenantId, scopeId, tables, 
     /** #1869: the scope `tables` were captured from — `scopeId` itself unless the copy moves —
-     *  and `exact` when the platform exported them itself rather than a caller supplying them. */
+     *  and `exact` when the platform exported them itself rather than a caller supplying them.
+     *  #1722: `loadStamp`, the stamp a carry leaves on the copy it lands, and `expect`, the marker
+     *  the carry read from `dest`, so a store that moved since is never overwritten. */
     source) => {
+        // #2005: every carry, reuse, adopt and governed restore lands here. When the directory says
+        // the destination is not primary, the vertical marks it a copy in its own storage — a carry
+        // of a copy made before every copy carried the marker brings none, and a CP-less host reads
+        // the marker for primacy. Idempotent there; an install is never marked.
+        const rec = await host.admin.getScopeRecord(actor, tenantId, scopeId);
+        const markCopy = rec ? copyLineageOf(rec) : undefined;
         return retryTransient(async () => dest.restoreScope(tenantId, scopeId, tables, {
             ...(await switchCarryFor(host.admin, actor, { tenantId, scopeId })),
             sourceScopeId: source.scopeId,
             exact: source.exact,
+            loadStamp: source.loadStamp,
+            expect: source.expect,
+            ...(markCopy ? { markCopy } : {}),
         }));
     };
     const adoptScopeOntoServing = async (c, tenantId, scopeId, opts = {}) => {
@@ -2042,6 +2127,16 @@ export function createControlPlaneApi(options) {
         await c.var.admin.reassertSystemSwitches(actor, { tenantId, scopeId }, { appliedInUnit: restored.switchedOff });
         return { servingRef: serving.ref, versionId: serving.versionId, tables: restored.tables };
     };
+    /** The script a scope's requests reach: its serving pin, else its bound version's own script. */
+    const routeOf = async (c, scope) => {
+        if (scope.servingRef)
+            return scope.servingRef;
+        if (!scope.vertical || !scope.verticalVersionId)
+            return null;
+        return (await c.var.admin.getVersion(c.get('actor'), scope.verticalVersionId, scope.vertical))?.deploymentRef ?? null;
+    };
+    /** How many exports a carry tries before its source holds still long enough to bind (#1722 r12). */
+    const CARRY_EXPORT_ATTEMPTS = 3;
     /**
      * Carry a scope's data onto the script a version bind is about to route it to (#1710).
      * The caller binds only after this returns.
@@ -2069,11 +2164,23 @@ export function createControlPlaneApi(options) {
      * over any partial copy. A retry after a bind that landed finds the same script on both
      * ends and carries nothing.
      *
+     * #1722: the export is checked before anything is restored. The scope is read again, and a
+     * binding or pin that moved since the caller read it is refused (412): another carry bound
+     * away from this script, which may already have wiped it, and an export from a wiped DO comes
+     * back as an empty store. A dump that carries the `carried_away` tombstone is refused the same
+     * way. The caller binds with `bindAfterCarry`, which wipes the source copy once the bind
+     * lands, so neither check can pass on an export from a copy that is about to go.
+     *
+     * The restore is conditional too. Before the check above, the carry reads the destination's
+     * `LoadMarker` (load stamp and write revision), and the restore is refused inside its own
+     * transaction if the store moved since. So a carry held before its restore cannot overwrite
+     * a store that another carry into the same script has loaded, or that went live under that
+     * carry's bind and took a write: a CI retry of the same version. A deployment built before
+     * #1722 cannot read a marker, and there the binding re-read is all that guards the restore.
+     * Its window: a bind that lands between that re-read and the restore, followed by a write.
+     *
      * What it does not do:
      * - Carry writes that land on the source between the export and the bind. Those are lost.
-     * - Delete the source copy. That copy is unreachable once the caller binds, and it stays
-     *   in the old script, because nothing reaps it yet (#1722). Deleting it here would race
-     *   a concurrent push that is still exporting from it.
      * - Cross lineages. A version of another vertical reads as absent here, and moving a scope
      *   between lineages is `rebindScopeOntoVertical`'s job, behind its migration gate.
      */
@@ -2095,10 +2202,7 @@ export function createControlPlaneApi(options) {
         if (!resolveVersion || (scope.servingRef && !opts.dropServingRef))
             return null;
         const to = incoming.deploymentRef ?? null;
-        const bound = scope.verticalVersionId
-            ? await c.var.admin.getVersion(actor, scope.verticalVersionId, scope.vertical)
-            : undefined;
-        const from = scope.servingRef ?? bound?.deploymentRef ?? null;
+        const from = await routeOf(c, scope);
         if (!to || !from || from === to)
             return null;
         // Resolve each end at exactly the script named above. No fallback to the prod channel:
@@ -2116,13 +2220,343 @@ export function createControlPlaneApi(options) {
             throw new ControlPlaneError(502, `cannot move scope ${scope.id} from '${from}' to '${to}': ${missing} could not be reached, ` +
                 `so the version was not bound (#1710)`);
         }
-        const dump = await retryTransient(() => source.exportScope(scope.id));
-        // #1742: the recorded OFF positions ride the restore, as on adopt and rebind.
+        const { tables: dump, loadStamp: sourceStamp, revision: sourceRevision } = await retryTransient(() => source.exportScopeStamped(scope.id));
+        // What the destination holds now, read before the binding is checked again. The restore
+        // sends it back and is refused if the store moved since: another carry into the same script
+        // loaded it, or it went live under another carry's bind and took a write. That is a CI retry
+        // of the same version, held before its restore while the first run bound and served.
+        const destMarker = await retryTransient(() => dest.loadMarker(scope.id));
+        const now = await c.var.admin.getScopeRecord(actor, scope.tenantId, scope.id);
+        if (!now ||
+            (now.verticalVersionId ?? null) !== (scope.verticalVersionId ?? null) ||
+            (now.servingRef ?? null) !== (scope.servingRef ?? null)) {
+            throw new ControlPlaneError(412, `scope ${scope.id} was re-pointed while its data was being copied out of '${from}', so nothing was ` +
+                `moved or bound (#1722). Reload the scope and retry.`);
+        }
+        if (dumpMetaValue(dump, CARRIED_AWAY_KEY) !== null) {
+            throw new ControlPlaneError(412, `the copy of scope ${scope.id} in '${from}' was already carried to another script and wiped, so nothing ` +
+                `was moved or bound (#1722). Reload the scope and retry.`);
+        }
+        // #1742: the recorded OFF positions ride the restore, as on adopt and rebind. #1722: so does
+        // a stamp of this carry's own, which a refused bind's wipe of the copy expects.
+        const restoredStamp = ulid();
         const restored = await restoreCarryingSwitches(actor, dest, scope.tenantId, scope.id, dump, {
             scopeId: scope.id,
             exact: true,
+            loadStamp: restoredStamp,
+            ...(destMarker === 'unfenced' ? {} : { expect: destMarker }),
+        });
+        return {
+            from,
+            to,
+            tables: restored.tables,
+            switchedOff: restored.switchedOff,
+            source,
+            dest,
+            sourceStamp,
+            sourceRevision,
+            restoredStamp,
+        };
+    };
+    /**
+     * Wipe one copy of a scope that no route reaches (#1722), without reaping it. Fenced where the
+     * deployment can fence it: the wipe runs only if nothing was loaded into that DO since
+     * `expectLoadStamp`, compared inside the wipe's own transaction, and `false` means something
+     * was (a rollback restored there), so the copy stays. A deployment built before the fence
+     * answers `'unfenced'`, and the wipe is then an unconditional load of the tombstone through
+     * the restore verb every deployment has. The caller re-reads the route first; that re-read is
+     * all that guards an unfenced wipe.
+     */
+    const wipeCarriedCopy = async (holder, scope, expect, carriedTo, 
+    /** The scope was read routing elsewhere: a copy changed in any way since is kept (#1722 r8). */
+    protectIfChanged = false) => {
+        const at = new Date().toISOString();
+        // #2005 (Codex #2008 r10): the directory's word that the scope is not primary goes with the
+        // wipe, on both paths, so a copy made before the marker leaves it marked — tombstoned or kept.
+        const markCopy = copyLineageOf(scope);
+        const fenced = await retryTransient(() => holder.wipeCarriedCopy({
+            scopeId: scope.id,
+            expectLoadStamp: expect.loadStamp,
+            ...(expect.revision !== undefined ? { expectRevision: expect.revision } : {}),
+            ...(protectIfChanged ? { protectIfChanged: true } : {}),
+            carriedTo,
+            at,
+            ...(markCopy ? { markCopy } : {}),
+        }));
+        if (fenced !== 'unfenced')
+            return fenced.wiped;
+        await retryTransient(() => holder.restoreScope(scope.tenantId, scope.id, carriedAwayDump({ to: carriedTo, at }), {
+            sourceScopeId: scope.id,
+            exact: true,
+            // #2005: as every restore onto a non-primary scope, so the wiped copy stays a copy.
+            ...(markCopy ? { markCopy } : {}),
+        }));
+        return true;
+    };
+    /**
+     * Where the scope routes now, read again after a carry's bind (null for a scope gone from the
+     * directory). Bound to the carry's own version and unpinned, that is the carry's destination,
+     * which needs no version read.
+     */
+    const currentRoute = async (c, scope, versionId, carried) => {
+        const now = await c.var.admin.getScopeRecord(c.get('actor'), scope.tenantId, scope.id);
+        if (!now)
+            return null;
+        if (!now.servingRef && now.verticalVersionId === versionId)
+            return carried.to;
+        return routeOf(c, now);
+    };
+    /** Whether the scope's store in `holder` is a wiped copy: it holds the `carried_away` tombstone. */
+    const isCarriedAway = async (holder, scope) => {
+        const page = await holder.readScopeTable(scope.id, { table: '_substrat_meta', limit: 100, offset: 0 });
+        return metaValueIn(page.rows, page.columns, CARRIED_AWAY_KEY) !== null;
+    };
+    const recordCarryCleanup = (c, scope, versionId, stage, e) => {
+        const { status } = mapError(e);
+        recordFailure({
+            actor: c.get('actor'),
+            operation: 'scope.carry',
+            stage,
+            tenantId: scope.tenantId,
+            scopeId: scope.id,
+            vertical: scope.vertical ?? null,
+            version: versionId,
+            status,
+            message: e instanceof Error ? e.message : String(e),
+        }, e);
+    };
+    /**
+     * Bind a scope onto `versionId` after `carryOntoVersion` (#1722), and settle the copies. The
+     * one tail every carry caller runs: a preview push, `scope bind`, and the serving-pin repair.
+     *
+     * 1. The bind is compare-and-set on the binding the caller read, which is the version the carry
+     *    exported from. Two pushes that both read v1 cannot both bind: the second is refused (412)
+     *    and never routes the preview to what it carried, which may be an export of a copy the
+     *    first one had already wiped. On any failed bind, the copy this carry restored is wiped, unless
+     *    the scope now routes to that same script: a CI retry of the same version restores into
+     *    the winner's live store, and wiping it there would lose everything.
+     * 2. The pin is cleared (`clearServingRef`) only after the bind lands, so a failure in between
+     *    leaves the route where the data still is, and a retry carries again.
+     * 3. The recorded OFF positions are re-asserted where the scope now routes (#1674).
+     * 4. The copy left in the old script is wiped (`settleCarriedSource`). A failure there is
+     *    recorded and never fails the bind, which has landed: the copy then stays, as before #1722.
+     */
+    const bindAfterCarry = async (c, scope, versionId, carried, opts = {}) => {
+        const actor = c.get('actor');
+        // 0. The source, read again right before the bind (Codex #2008 r12). A store that changed since
+        //    the export (a write, a load, or a staff clear of its copy marker) holds something the
+        //    destination does not, so binding now would serve the stale export. The carry is run
+        //    again from a fresh export, a bounded number of times, and then refused with a typed 409.
+        //    What changes after this read is the source wipe's to fence (`keepOrWipeSource`).
+        for (let attempt = 1; carried; attempt++) {
+            const stale = carried;
+            let now;
+            try {
+                now = await retryTransient(() => stale.source.loadMarker(scope.id));
+            }
+            catch (e) {
+                await dropUnboundCopy(c, scope, versionId, stale); // no bind follows
+                throw e;
+            }
+            if (now === 'unfenced' || (now.loadStamp === stale.sourceStamp && now.revision === stale.sourceRevision))
+                break;
+            let next = null;
+            if (attempt < CARRY_EXPORT_ATTEMPTS && opts.recarry) {
+                try {
+                    next = await opts.recarry();
+                }
+                catch (e) {
+                    await dropUnboundCopy(c, scope, versionId, stale);
+                    throw e;
+                }
+            }
+            if (!next) {
+                await dropUnboundCopy(c, scope, versionId, stale);
+                throw new CarrySourceChanged(scope.id, stale.from, stale.to, attempt);
+            }
+            carried = next;
+        }
+        try {
+            await c.var.admin
+                .bindScopeVersion(actor, scope.tenantId, scope.id, versionId, {
+                acknowledge: opts.acknowledge,
+                ...(opts.snapshot ? { snapshot: true } : {}),
+                expectedVersionId: scope.verticalVersionId ?? null,
+            })
+                .catch(relayHostRefusal);
+        }
+        catch (e) {
+            if (carried)
+                await dropUnboundCopy(c, scope, versionId, carried);
+            throw e;
+        }
+        if (opts.clearServingRef && scope.servingRef) {
+            await c.var.admin.setScopeServingRef(actor, scope.tenantId, scope.id, null).catch(relayHostRefusal);
+        }
+        try {
+            await c.var.admin.reassertSystemSwitches(actor, { tenantId: scope.tenantId, scopeId: scope.id }, { appliedInUnit: carried?.switchedOff });
+        }
+        finally {
+            // Even when the re-assert fails: the route has moved, and a retry finds the same script
+            // on both ends, carries nothing, and so would never come back for this copy.
+            if (carried)
+                await settleCarriedSource(c, scope, versionId, carried);
+        }
+    };
+    /**
+     * The copy a carry restored for a bind that did not land, wiped unless the scope routes to
+     * that script now. Best effort: it never throws, and a failure is recorded.
+     */
+    const dropUnboundCopy = async (c, scope, versionId, carried) => {
+        try {
+            const route = await currentRoute(c, scope, versionId, carried);
+            if (route === carried.to)
+                return;
+            await wipeCarriedCopy(carried.dest, scope, { loadStamp: carried.restoredStamp }, route ?? carried.from);
+        }
+        catch (e) {
+            recordCarryCleanup(c, scope, versionId, 'unbound-copy', e);
+        }
+    };
+    /**
+     * Clear the kept-copy marker of a store the scope routes to (#1722, Codex #2008 r8). A carry
+     * keeps a changed source when it reads the route elsewhere; a rollback binding it a moment later
+     * makes that store live, and a live store holds nothing divergent. Fenced on the revision read
+     * now; re-reads the route first, so it never releases a copy the scope has left.
+     */
+    const releaseIfLive = async (c, scope, versionId, carried, holder, script) => {
+        if (!(await holder.keptCopy(scope.id)))
+            return;
+        if ((await currentRoute(c, scope, versionId, carried)) !== script)
+            return;
+        const marker = await holder.loadMarker(scope.id);
+        if (marker === 'unfenced')
+            return;
+        const markCopy = copyLineageOf(scope);
+        await holder.releaseKeptCopy({
+            scopeId: scope.id,
+            revision: marker.revision,
+            loadStamp: marker.loadStamp, // Codex #2008 r13: the store read, not only its revision
+            ...(markCopy ? { markCopy } : {}),
+        });
+    };
+    /**
+     * A source kept ONLY because staff cleared its copy marker after the carry's export (Codex #2008
+     * r12; the store records that itself, `KeptCopy.clearedOnly`). Its data is what the carry
+     * copied; the fresher decision is the clear, so it is brought to the store the scope runs on:
+     * the destination's marker is cleared, and only then is the source discarded. True when both
+     * landed. Anything else (a write since, a move, a refusal) leaves the source kept, and the caller
+     * records it as any kept copy.
+     *
+     * Every step is fenced on THIS carry, not on whatever the stores hold now (Codex #2008 r13). The
+     * destination must still hold this carry's load (its `restoredStamp`): a governed restore that
+     * replaced it since brings a copy marker that is genuine, and clearing it would let another
+     * scope's copy run its executors. That stamp and the revision read are compared inside the clear's
+     * own transaction, so nothing can land between the check and the clear. The binding is read again
+     * right before the discard, and the discard is fenced on the source's stamp and kept revision.
+     */
+    const bringClearForward = async (c, scope, versionId, carried) => {
+        if (!isPrimaryScope(scope))
+            return false; // only staff clear, and only a primary's marker
+        const kept = await carried.source.keptCopy(scope.id);
+        if (!kept?.clearedOnly)
+            return false;
+        const destMarker = await carried.dest.loadMarker(scope.id);
+        if (destMarker === 'unfenced' || destMarker.loadStamp !== carried.restoredStamp)
+            return false;
+        if ((await currentRoute(c, scope, versionId, carried)) !== carried.to)
+            return false;
+        try {
+            await carried.dest.clearCopyMark(scope.id, { kind: scope.kind, forkedFrom: scope.forkedFrom }, {
+                expect: { loadStamp: carried.restoredStamp, revision: destMarker.revision },
+            });
+        }
+        catch (e) {
+            if (e instanceof ControlPlaneError && (e.status === 412 || e.status === 409))
+                return false;
+            throw e;
+        }
+        if ((await currentRoute(c, scope, versionId, carried)) !== carried.to)
+            return false;
+        const discarded = await carried.source.discardKeptCopy({
+            scopeId: scope.id,
+            revision: kept.clearedOnly.revision,
+            // Clear-only means nothing was loaded there since the export: the stamp the carry read.
+            loadStamp: carried.sourceStamp,
+            carriedTo: carried.to,
+            at: new Date().toISOString(),
         });
-        return { from, to, tables: restored.tables, switchedOff: restored.switchedOff };
+        return 'discarded' in discarded;
+    };
+    /**
+     * The source wipe, fenced on what the export read. Refused means the copy changed after the
+     * export: a write from a request still routed there before the bind, which the carry never
+     * copied. The copy is then kept, holding that write, and recorded so it can be recovered.
+     */
+    const keepOrWipeSource = async (c, scope, versionId, carried, expect) => {
+        // The caller read the route elsewhere, so a copy that changed in any way since the export (a
+        // load as much as a write: a staff restore-forward into it racing this carry, Codex #2008 r8)
+        // is kept in the store rather than left an unmarked orphan.
+        if (await wipeCarriedCopy(carried.source, scope, expect, carried.to, true))
+            return;
+        // A rollback that restored into it since made it the live store again: it is no kept copy, and
+        // a marker this refusal set while the rollback had not yet bound comes off.
+        const route = await currentRoute(c, scope, versionId, carried);
+        if (route === carried.from) {
+            await releaseIfLive(c, scope, versionId, carried, carried.source, carried.from);
+            return;
+        }
+        if (route === carried.to && (await bringClearForward(c, scope, versionId, carried)))
+            return;
+        recordCarryCleanup(c, scope, versionId, 'source-copy-kept', new ControlPlaneError(409, `scope ${scope.id}'s copy in '${carried.from}' changed after it was carried to '${carried.to}', so it was ` +
+            `kept: it holds what reached it in between, which the carry did not copy (#1722)`));
+    };
+    /**
+     * Wipe the copy a landed carry left in its source script (#1722), once nothing routes there.
+     *
+     * The route is read again first. A scope that routes to the source again was bound back to it
+     * (a rollback that has landed), and its copy stays. A scope that routes to this carry's
+     * destination has its store checked for the `carried_away` tombstone first: an unfenced wipe
+     * from an earlier carry out of this script can overtake this carry's restore when this carry
+     * IS the rollback, and then the source, which nothing has wiped yet, is carried again before
+     * it goes. The fenced wipe in a deployment that has it makes the overtaking impossible.
+     *
+     * Left open, for a script built before the fence only: an unfenced wipe whose request reaches
+     * the old script after a rollback's bind and this check, both, still destroys the rollback's
+     * restore. Narrow, and recorded here rather than claimed closed.
+     */
+    const settleCarriedSource = async (c, scope, versionId, carried) => {
+        const actor = c.get('actor');
+        try {
+            const route = await currentRoute(c, scope, versionId, carried);
+            if (route === carried.from)
+                return;
+            // The store this carry landed in is live; a kept marker another carry set while racing it
+            // does not belong on it (#1722 r8).
+            if (route === carried.to)
+                await releaseIfLive(c, scope, versionId, carried, carried.dest, carried.to);
+            if (route === carried.to && (await isCarriedAway(carried.dest, scope))) {
+                const { tables: dump, loadStamp: stamp, revision } = await retryTransient(() => carried.source.exportScopeStamped(scope.id));
+                if (dumpMetaValue(dump, CARRIED_AWAY_KEY) !== null) {
+                    throw new ControlPlaneError(500, `both copies of scope ${scope.id} hold the carried_away tombstone; nothing was wiped`);
+                }
+                await restoreCarryingSwitches(actor, carried.dest, scope.tenantId, scope.id, dump, {
+                    scopeId: scope.id,
+                    exact: true,
+                    loadStamp: ulid(),
+                });
+                if (await isCarriedAway(carried.dest, scope)) {
+                    throw new ControlPlaneError(500, `scope ${scope.id}'s store in '${carried.to}' was wiped again; its source copy stays`);
+                }
+                // Re-carried, so the fence expects what the re-export read.
+                await keepOrWipeSource(c, scope, versionId, carried, { loadStamp: stamp, revision });
+                return;
+            }
+            await keepOrWipeSource(c, scope, versionId, carried, { loadStamp: carried.sourceStamp, revision: carried.sourceRevision });
+        }
+        catch (e) {
+            recordCarryCleanup(c, scope, versionId, 'source-copy', e);
+        }
     };
     app.get('/tenants/:tenantId/scopes/:scopeId/tables', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
@@ -2847,10 +3281,49 @@ export function createControlPlaneApi(options) {
         archive: (admin, a, t, s) => admin.archiveScope(a, t, s),
         unarchive: (admin, a, t, s) => admin.unarchiveScope(a, t, s),
     };
+    /** #2005: the transitions that bring a scope (back) to life — each marks a copy first. */
+    const REACTIVATIONS = new Set(['activate', 'unsuspend', 'unarchive']);
     for (const [action, run] of Object.entries(transitions)) {
         app.post(`/tenants/:tenantId/scopes/:scopeId/${action}`, async (c) => {
             const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
             const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+            // #2005: a copy made before the copy marker existed holds none, and a CP-less host that
+            // finds none runs its effects. So a copy is marked BEFORE it comes back to life, and a
+            // hosted copy whose marker cannot be written is refused here rather than reactivated.
+            if (REACTIVATIONS.has(action)) {
+                const rec = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+                if (rec && !isPrimaryScope(rec)) {
+                    // ANY failed marker write keeps the scope parked: a 503 that says what to do, and an
+                    // ops-failure row, whether the step reported it (no deployment resolves) or the vertical
+                    // refused (an older one has no /internal/mark-copy and answers 404). Passing a 404 or
+                    // a vertical's error through would read as "no such scope" and leave no trace.
+                    let failure;
+                    try {
+                        const step = await markScopeIfCopy(c, rec);
+                        if ('fail' in step)
+                            failure = { error: step.fail.error, cause: NO_CAUSE };
+                    }
+                    catch (e) {
+                        failure = { error: e instanceof Error ? e.message : String(e), cause: e };
+                    }
+                    if (failure) {
+                        const error = `${action} refused: this copy could not be marked as one (${failure.error}); ` +
+                            'redeploy the vertical so it can mark it, then retry — the scope stays as it was';
+                        recordFailure({
+                            actor: c.get('actor'),
+                            operation: `scope.${action}`,
+                            stage: 'mark-copy',
+                            tenantId,
+                            scopeId,
+                            vertical: rec.vertical,
+                            version: rec.verticalVersionId,
+                            status: 503,
+                            message: error,
+                        }, failure.cause);
+                        return c.json({ error }, 503);
+                    }
+                }
+            }
             await run(c.var.admin, c.get('actor'), tenantId, scopeId);
             return c.json(await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId));
         });
@@ -3160,6 +3633,235 @@ export function createControlPlaneApi(options) {
         await c.var.admin.restoreDirectory(actor, dump);
         return c.json({ capturedAt: dump.capturedAt, tables: dump.tables.length });
     });
+    // -- one-time repair of previews that kept a production serving pin (#1724) --------------
+    // A preview adopted onto its vertical's serving script before #1731 still routes by
+    // `COALESCE(servingRef, deploymentRef)`, so it serves production code while its binding
+    // names the version it was pushed from. #1962 heals one on its next `scope bind`; this is
+    // the pass over the previews nobody binds again. It is the SAME act a bind runs, with the
+    // version the preview is already bound to as its target: carry the data off the serving
+    // script into that version's own script, bind it, then clear the pin. A pin that fails to
+    // clear leaves the route where the data still is, and the next pass carries again.
+    //
+    // Staff only, by default-deny: the path is on neither `BUILDER_ROUTES` nor
+    // `TENANT_ROUTES`, so a builder's push token and a tenant credential both 403 before the
+    // handler runs. (A fleet-wide walk is the wrong shape for either, even a tenant's own.)
+    //
+    // Paged and resumable like every fleet walk here: a pass reads one page of ACTIVE
+    // directory rows after `cursor` and repairs at most `limit` previews from it, answering
+    // `nextCursor` until the fleet is exhausted. Bounded by `limit` because each repair is a
+    // data move between two Durable Objects. A scope that fails is reported and the pass
+    // moves on, so one bad preview cannot hold the rest; it is still pinned, so the next walk
+    // from the start visits it again. A healed preview is no longer a candidate, which is
+    // what makes a re-run a no-op. `dryRun` lists the candidates and touches nothing.
+    const REPAIR_SCAN_PAGE = 500;
+    const repairServingPinsBody = z
+        .object({
+        cursor: scopeIdSchema.optional(),
+        limit: z.number().int().min(1).max(100).default(25),
+        dryRun: z.boolean().default(false),
+    })
+        .strict();
+    const repairPreviewServingPin = async (c, scope) => {
+        const actor = c.get('actor');
+        const versionId = scope.verticalVersionId;
+        if (!scope.vertical || !versionId)
+            return { skipped: 'the preview is bound to no version' };
+        // Without its own script the version has nowhere to receive the data, and clearing the pin
+        // would strand it on the serving script.
+        const bound = await c.var.admin.getVersion(actor, versionId, scope.vertical);
+        if (!bound?.deploymentRef)
+            return { skipped: `version ${versionId} has no script of its own` };
+        // The carry and the tail a legacy preview's `scope bind` runs too. The bind expects the
+        // version this pass read, so a push that re-pointed the preview since it was listed wins.
+        const recarry = () => carryOntoVersion(c, scope, versionId, { dropServingRef: true });
+        const carried = await recarry();
+        await bindAfterCarry(c, scope, versionId, carried, { clearServingRef: true, recarry });
+        return { repaired: { from: carried?.from ?? scope.servingRef, to: bound.deploymentRef, tables: carried?.tables ?? 0 } };
+    };
+    app.post('/previews/repair-serving-pins', async (c) => {
+        if (!options.resolveVerticalVersion || !options.resolveVerticalRef) {
+            return c.json({ error: 'repairing serving pins needs dispatch resolution for both ends' }, 501);
+        }
+        const { cursor, limit, dryRun } = await readJsonBody(c, repairServingPinsBody);
+        const actor = c.get('actor');
+        const page = await c.var.admin.listScopes(actor, { status: ['active'], cursor, limit: REPAIR_SCAN_PAGE });
+        const repaired = [];
+        const candidates = [];
+        const skipped = [];
+        const failed = [];
+        let last = cursor;
+        let handled = 0;
+        let stopped = false;
+        for (const scope of page) {
+            if (scope.kind !== 'preview' || !scope.servingRef) {
+                last = scope.id;
+                continue;
+            }
+            if (handled >= limit) {
+                stopped = true;
+                break;
+            }
+            handled += 1;
+            last = scope.id;
+            const at = { tenantId: scope.tenantId, scopeId: scope.id };
+            if (dryRun) {
+                candidates.push({ ...at, servingRef: scope.servingRef });
+                continue;
+            }
+            try {
+                const outcome = await repairPreviewServingPin(c, scope);
+                if ('skipped' in outcome)
+                    skipped.push({ ...at, reason: outcome.skipped });
+                else
+                    repaired.push({ ...at, ...outcome.repaired });
+            }
+            catch (e) {
+                // The status the app's error boundary would have answered, so a host refusal (a push
+                // re-pointed the preview since it was listed) reads as a 412 and not as a platform fault.
+                const { status } = mapError(e);
+                const message = e instanceof Error ? e.message : String(e);
+                if (status >= 500 && status !== 501) {
+                    recordFailure({
+                        actor,
+                        operation: 'preview.repair-serving-pin',
+                        stage: 'repair',
+                        tenantId: scope.tenantId,
+                        scopeId: scope.id,
+                        vertical: scope.vertical,
+                        version: scope.verticalVersionId,
+                        status,
+                        message,
+                    }, e);
+                }
+                failed.push({ ...at, status, error: message });
+            }
+        }
+        // Exhausted only when the page ran short: a full page may be followed by more rows.
+        const nextCursor = stopped || page.length === REPAIR_SCAN_PAGE ? (last ?? null) : null;
+        return c.json({ dryRun, repaired, candidates, skipped, failed, nextCursor });
+    });
+    const markScopeIfCopy = async (c, scope) => {
+        const actor = c.get('actor');
+        if (isPrimaryScope(scope))
+            return { skip: 'primary: an install is never marked' };
+        if (!scope.vertical)
+            return { skip: 'bound to no vertical: no module code runs, so nothing reads the marker' };
+        const vertical = await verticalForScope(c, scope);
+        if (!vertical) {
+            const hosted = scope.servingRef !== null && scope.servingRef !== undefined
+                ? true
+                : scope.verticalVersionId
+                    ? Boolean((await c.var.admin.getVersion(actor, scope.verticalVersionId, scope.vertical))?.deploymentRef)
+                    : false;
+            return hosted
+                ? { fail: { status: 503, error: 'no deployment resolves for this hosted scope, so its copy marker was not written' } }
+                : { skip: 'co-located: the host that runs this scope reads the directory, so it needs no marker' };
+        }
+        const { marked } = await vertical.markCopy(scope.id, { kind: scope.kind, forkedFrom: scope.forkedFrom });
+        await c.var.admin.recordCopyMark(actor, {
+            action: 'mark',
+            tenantId: scope.tenantId,
+            scopeId: scope.id,
+            outcome: marked ? 'marked' : 'already',
+        });
+        return { done: marked ? 'marked' : 'already' };
+    };
+    // -- one-time repair: mark every existing copy as one, in its own storage (#2005) --------
+    // A CP-less hosted vertical has no directory, so it reads a scope's own copy-origin row to
+    // hold a preview's or a fork's executors inert. Every copy carries that row since #2005, and
+    // every carry onto a non-primary scope stamps it (`restoreCarryingSwitches`) — but a copy
+    // made before either, never carried since, holds none and would read as an install there.
+    // This is the pass over those: for each scope the directory says is not primary, ask the
+    // vertical that holds it to stamp the marker (idempotent there), and log the outcome. Active,
+    // suspended and archived scopes alike: a suspended or archived copy can be reactivated, and a
+    // reactivation stamps too (`markScopeIfCopy` in the lifecycle routes), so neither path brings
+    // an unmarked copy back to life. A hosted scope that does not resolve is FAILED, not skipped.
+    //
+    // Staff only, by default-deny, like the serving-pin repair: the path is on neither
+    // `BUILDER_ROUTES` nor `TENANT_ROUTES`. Paged and resumable the same way — one page of
+    // ACTIVE directory rows after `cursor`, at most `limit` scopes marked from it, `nextCursor`
+    // until the fleet is exhausted. A scope that fails is reported and the pass moves on; it is
+    // still unmarked, so the next walk visits it again, and a marked one answers `already`.
+    // `dryRun` lists the candidates and touches nothing. An install is never a candidate.
+    const markCopiesBody = z
+        .object({
+        cursor: scopeIdSchema.optional(),
+        limit: z.number().int().min(1).max(200).default(50),
+        dryRun: z.boolean().default(false),
+    })
+        .strict();
+    app.post('/scopes/mark-copies', async (c) => {
+        const { cursor, limit, dryRun } = await readJsonBody(c, markCopiesBody);
+        const actor = c.get('actor');
+        const page = await c.var.admin.listScopes(actor, {
+            status: ['active', 'suspended', 'archived'],
+            cursor,
+            limit: REPAIR_SCAN_PAGE,
+        });
+        const marked = [];
+        const already = [];
+        const candidates = [];
+        const skipped = [];
+        const failed = [];
+        let last = cursor;
+        let handled = 0;
+        let stopped = false;
+        for (const scope of page) {
+            if (isPrimaryScope(scope)) {
+                last = scope.id;
+                continue;
+            }
+            if (handled >= limit) {
+                stopped = true;
+                break;
+            }
+            handled += 1;
+            last = scope.id;
+            const at = { tenantId: scope.tenantId, scopeId: scope.id };
+            if (dryRun) {
+                candidates.push(at);
+                continue;
+            }
+            try {
+                const step = await markScopeIfCopy(c, scope);
+                if ('skip' in step)
+                    skipped.push({ ...at, reason: step.skip });
+                else if ('fail' in step)
+                    failed.push({ ...at, ...step.fail });
+                else
+                    (step.done === 'marked' ? marked : already).push(at);
+            }
+            catch (e) {
+                const { status } = mapError(e);
+                failed.push({ ...at, status, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        const nextCursor = stopped || page.length === REPAIR_SCAN_PAGE ? (last ?? null) : null;
+        return c.json({ dryRun, marked, already, candidates, skipped, failed, nextCursor });
+    });
+    // The correction for a MISTAKEN copy marker (#2005): a scope the directory says IS primary,
+    // marked by a misclassification, a race or an operator, or restored from another scope's backup
+    // before #2009 split the two facts, whose executors a CP-less host would otherwise hold inert
+    // for good. One scope at a time, staff only by default-deny (the path is on neither allowlist),
+    // logged as `clearScopeCopyMark`. Refused for a scope the directory calls a copy. Clears the
+    // classification only: the events a load brought in stay marked, so they never run here.
+    app.post('/tenants/:tenantId/scopes/:scopeId/clear-copy-mark', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const actor = c.get('actor');
+        const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        if (!isPrimaryScope(scope)) {
+            return c.json({ error: 'clear-copy-mark refused: the directory says this scope is a copy (a preview or a fork)' }, 409);
+        }
+        const vertical = await verticalForScope(c, scope);
+        if (!vertical)
+            return c.json({ error: await diagnoseUnboundScope(actor, scope) }, 501);
+        const { cleared } = await vertical.clearCopyMark(scopeId, { kind: scope.kind, forkedFrom: scope.forkedFrom });
+        await c.var.admin.recordCopyMark(actor, { action: 'clear', tenantId, scopeId, outcome: cleared ? 'cleared' : 'absent' });
+        return c.json({ cleared });
+    });
     // Reap an ARCHIVED primary scope (control-plane.md §4.4): free its DO storage —
     // Cloudflare never garbage-collects a Durable Object, so a deleted app's bytes persist
     // forever otherwise — while keeping the directory row as a tombstone. A POST verb, not
@@ -3260,7 +3962,7 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         // Body is optional so the bare `POST …/reap` every existing caller sends still
         // parses; `backup` tri-states on purpose (see the ordering comment below).
-        const { backup: wantsBackup } = reapScopeBody.parse(await c.req.json().catch(() => ({})));
+        const { backup: wantsBackup } = await readJsonBody(c, reapScopeBody);
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
@@ -3672,7 +4374,7 @@ export function createControlPlaneApi(options) {
             return c.json({ error: 'adopt-serving is a private-vertical operation' }, 409);
         }
         const owned = (await c.var.admin.listScopes(actor, { tenantId: v.ownerTenant, vertical: slug })).filter((s) => !s.forkedFrom && s.kind !== 'preview' && s.status === 'active');
-        const { acknowledge } = adoptServingBody.parse(await c.req.json().catch(() => ({})));
+        const { acknowledge } = await readJsonBody(c, adoptVerticalServingBody);
         const adopted = [];
         const alreadyAdopted = [];
         try {
@@ -3732,6 +4434,226 @@ export function createControlPlaneApi(options) {
         const versionId = z.string().min(1).parse(c.req.query('versionId'));
         return c.json({ affected: await c.var.admin.bindingImpact(c.get('actor'), tenantId, scopeId, versionId) });
     });
+    // -- kept copies (#1722, Codex #2008 r7) ----------------------------------------------------
+    // A kept copy is one a carry's fenced wipe refused because it took a write the carry never
+    // copied (a request still routed to the old script before the bind). The store protects it:
+    // every load into it answers 409 until it is resolved here. The two resolutions both lose
+    // something, so each is named and acknowledged, never defaulted:
+    // - `discard` wipes the kept copy: what reached it after the carry's export is gone.
+    // - `restore-forward` restores the kept copy over the store the scope now routes to, then
+    //   wipes the kept copy: what the live store took since the copy was kept is gone.
+    // There is no merge of two scope dumps. To reconcile by hand, pull the kept copy with
+    // `GET …/kept-copy/export` and the live store with the governed export (`GET …/export`, which
+    // reads the scope's route), re-apply what matters, then discard.
+    //
+    // Staff only, by default-deny: neither path is on BUILDER_ROUTES or TENANT_ROUTES. One scope
+    // at a time, refused unless the copy really is kept, and admin-logged with the write revision
+    // before and after (`recordKeptCopyResolution`).
+    const keptScriptQuery = z.object({ script: z.string().min(1) }).strict();
+    const resolveKeptBody = z.discriminatedUnion('action', [
+        z
+            .object({
+            script: z.string().min(1),
+            action: z.literal('discard'),
+            acknowledge: z.object({ discard: z.literal(true) }).strict(),
+        })
+            .strict(),
+        z
+            .object({
+            script: z.string().min(1),
+            action: z.literal('release'),
+            acknowledge: z.object({ release: z.literal(true) }).strict(),
+        })
+            .strict(),
+        z
+            .object({
+            script: z.string().min(1),
+            action: z.literal('restore-forward'),
+            /** The moment the copy was kept, as its marker says: the live store's writes since are replaced. */
+            acknowledge: z.object({ replacesLiveWritesSince: z.string().min(1) }).strict(),
+        })
+            .strict(),
+    ]);
+    const keptHolder = async (script) => {
+        if (!options.resolveVerticalRef)
+            throw new ControlPlaneError(501, 'kept copies need dispatch resolution by script');
+        const holder = await options.resolveVerticalRef(script);
+        if (!holder)
+            throw new ControlPlaneError(404, `no deployment resolves for script '${script}'`);
+        return holder;
+    };
+    app.get('/tenants/:tenantId/scopes/:scopeId/kept-copy', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const { script } = keptScriptQuery.parse(c.req.query());
+        const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        const kept = await (await keptHolder(script)).keptCopy(scopeId);
+        return c.json({ scopeId, script, kept, routesTo: await routeOf(c, scope) });
+    });
+    // The kept copy's own dump, for reconciling by hand before a discard: the governed export's
+    // rules exactly (`GET …/export` above). Refused outside `global` residency, masked unless
+    // `full=true`, and K-24 access-logged through the same canonical `exportScope`. It reads the
+    // script named, refused unless the copy there is kept, so it never becomes a way to pull a
+    // live store past that route.
+    const keptExportQuery = z
+        .object({ script: z.string().min(1), full: z.enum(['true', 'false']).optional() })
+        .strict();
+    app.get('/tenants/:tenantId/scopes/:scopeId/kept-copy/export', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const { script, full } = keptExportQuery.parse(c.req.query());
+        const actor = c.get('actor');
+        const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        if (scope.jurisdiction !== 'global') {
+            return c.json({
+                error: `scope ${scopeId} is pinned to '${scope.jurisdiction}' — a local pull would ` +
+                    `move its data outside that jurisdiction; refused (K-32, preview-and-snapshots.md §6)`,
+            }, 403);
+        }
+        const holder = await keptHolder(script);
+        const kept = await holder.keptCopy(scopeId);
+        if (!kept)
+            return c.json({ error: `scope ${scopeId} has no kept copy in '${script}'` }, 409);
+        const dump = await c.var.admin.exportScope(actor, tenantId, scopeId);
+        const tables = await holder.exportScope(scopeId);
+        if (full === 'true')
+            return c.json({ ...dump, tables, masked: false, script, kept });
+        const mask = await createPseudonymizer(options.maskSalt ?? crypto.randomUUID());
+        return c.json({ ...dump, tables: await maskDump(tables, mask), masked: true, script, kept });
+    });
+    app.post('/tenants/:tenantId/scopes/:scopeId/kept-copy/resolve', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const body = await readJsonBody(c, resolveKeptBody);
+        const actor = c.get('actor');
+        const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        const holder = await keptHolder(body.script);
+        const kept = await holder.keptCopy(scopeId);
+        if (!kept)
+            return c.json({ error: `scope ${scopeId} has no kept copy in '${body.script}'` }, 409);
+        const route = await routeOf(c, scope);
+        // `release` is for a kept copy the scope routes to (a rollback bound it after a carry kept
+        // it); the other two act on a kept copy the scope has left, against the store it runs on.
+        if (body.action === 'release' ? route !== body.script : !route || route === body.script) {
+            return c.json({
+                error: body.action === 'release'
+                    ? `scope ${scopeId} routes to '${route ?? '(nothing)'}', not to the kept copy in '${body.script}'; release is for a kept copy that is live`
+                    : `scope ${scopeId} routes to '${route ?? '(nothing)'}', so there is no live copy to resolve against`,
+            }, 409);
+        }
+        const at = new Date().toISOString();
+        const revisionOf = async (client) => {
+            const marker = await client.loadMarker(scopeId);
+            return marker === 'unfenced' ? null : marker.revision;
+        };
+        // The kept copy as it stands now, which is what this resolution acts on and is fenced on: a
+        // write that reaches it after this read refuses the wipe. (The marker's own `revision` is the
+        // one it was kept at; writing the marker, and any later write, moved it on.)
+        const before = await holder.loadMarker(scopeId);
+        const revisionBefore = before === 'unfenced' ? null : before.revision;
+        // Codex #2008 r13: and the load stamp with it, so the release or discard refuses a store a load
+        // has replaced since this read (a kept copy refuses every load but its own resolution, so this
+        // is the same fence stated where the act is, not a new one).
+        const stampFence = before === 'unfenced' ? {} : { loadStamp: before.loadStamp };
+        // #2005 (Codex #2008 r10): whatever the resolution leaves in that store, it is a copy when
+        // the directory says the scope is not primary, marker or no marker.
+        const lineage = copyLineageOf(scope);
+        const markCopy = lineage ? { markCopy: lineage } : {};
+        const record = (action, revisionAfter) => c.var.admin.recordKeptCopyResolution(actor, tenantId, scopeId, {
+            action,
+            script: body.script,
+            liveScript: action === 'restore-forward' ? route : null,
+            keptAt: kept.keptAt,
+            revisionBefore,
+            revisionAfter,
+        });
+        if (body.action === 'release') {
+            const out = await holder.releaseKeptCopy({ scopeId, revision: revisionBefore, ...markCopy, ...stampFence });
+            if ('refused' in out) {
+                return c.json({ error: `the kept copy of scope ${scopeId} ${out.refused === 'changed' ? 'changed since it was read' : 'is no longer kept'}; nothing was released` }, 412);
+            }
+            await record('release', revisionBefore);
+            return c.json({ scopeId, script: body.script, action: 'release', revisionBefore });
+        }
+        if (body.action === 'discard') {
+            const out = await holder.discardKeptCopy({ scopeId, revision: revisionBefore, carriedTo: route, at, ...markCopy, ...stampFence });
+            if ('refused' in out) {
+                return c.json({ error: `the kept copy of scope ${scopeId} ${out.refused === 'changed' ? 'changed since it was read' : 'is no longer kept'}; nothing was discarded` }, 412);
+            }
+            const revisionAfter = await revisionOf(holder);
+            await record('discard', revisionAfter);
+            return c.json({ scopeId, script: body.script, action: 'discard', revisionBefore, revisionAfter });
+        }
+        // restore-forward: the acknowledgement names what is replaced, as the marker says it.
+        if (body.acknowledge.replacesLiveWritesSince !== kept.keptAt) {
+            return c.json({
+                error: `a restore forward replaces what the live store took since ${kept.keptAt}; acknowledge exactly that ` +
+                    `(acknowledge.replacesLiveWritesSince: '${kept.keptAt}')`,
+            }, 409);
+        }
+        // Fenced on the binding through the whole resolution (Codex #2008 r8): the kept copy goes only
+        // once its data is in the store the scope still routes to. Every refusal below leaves it kept.
+        const liveScript = route;
+        const live = await keptHolder(liveScript);
+        const bindingHeld = async () => {
+            const now = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
+            return (Boolean(now) &&
+                (now.verticalVersionId ?? null) === (scope.verticalVersionId ?? null) &&
+                (now.servingRef ?? null) === (scope.servingRef ?? null));
+        };
+        const moved = () => c.json({
+            error: `scope ${scopeId} was re-pointed while the kept copy was being restored forward, so nothing was resolved ` +
+                `and the kept copy in '${body.script}' stays kept; read it again and resolve it again`,
+        }, 409);
+        // The live store as read now, and nothing else, is what gets replaced. The binding read again
+        // after the marker ties the marker to the live store: a move that landed before this read
+        // (its wipe minting a tombstone here) changed the binding, and is refused.
+        const liveMarker = await live.loadMarker(scopeId);
+        if (liveMarker === 'unfenced') {
+            return c.json({ error: `the deployment serving scope ${scopeId} ('${liveScript}') predates the fence (#1722); re-push it, then resolve` }, 409);
+        }
+        if (!(await bindingHeld()))
+            return moved();
+        if ((await isCarriedAway(live, scope)) || (await live.keptCopy(scopeId))) {
+            return c.json({ error: `the store scope ${scopeId} routes to in '${liveScript}' is not a live store (wiped or kept); nothing was resolved` }, 409);
+        }
+        const dump = await retryTransient(() => holder.exportScope(scopeId));
+        const restored = await restoreCarryingSwitches(actor, live, tenantId, scopeId, dump, {
+            scopeId,
+            exact: true,
+            loadStamp: ulid(),
+            expect: liveMarker,
+        });
+        await c.var.admin.reassertSystemSwitches(actor, { tenantId, scopeId }, { appliedInUnit: restored.switchedOff });
+        // Still routed there once the data landed? If not, the move that re-pointed the scope keeps
+        // what this restore put in that store (its source wipe protects a copy changed since its
+        // export), and the kept copy here stays kept too: nothing is lost, nothing is discarded.
+        if (!(await bindingHeld()))
+            return moved();
+        const revisionAfter = await revisionOf(live);
+        await record('restore-forward', revisionAfter);
+        const wiped = await holder.discardKeptCopy({
+            scopeId,
+            revision: revisionBefore,
+            carriedTo: liveScript,
+            at,
+            ...markCopy,
+            ...stampFence,
+        });
+        if ('refused' in wiped) {
+            return c.json({
+                error: `restored forward into '${route}', but the kept copy in '${body.script}' changed since it was read, so it ` +
+                    `stays kept: read it again and resolve it again`,
+            }, 409);
+        }
+        return c.json({ scopeId, script: body.script, action: 'restore-forward', liveScript, revisionBefore, revisionAfter });
+    });
     // Pin a scope to a vertical version (#31; orchestration.md §4). Refuses a
     // non-admitted version below the seam — that refusal is the registry's reason to
     // exist. A scope operation, so it keeps the scope route shape. `snapshot: true`
@@ -3768,23 +4690,21 @@ export function createControlPlaneApi(options) {
             if (scope)
                 carried = await carryOntoVersion(c, scope, versionId, { dropServingRef: repairPreviewPin });
         };
-        // #1674: after the bind, the scope may route to a different store (the carry's
-        // destination); put the directory's recorded OFF positions back there. #1742: the carry
-        // already did so in the restore's own event; what it reports is audited here.
-        const reassert = async () => {
-            if (scope) {
-                await c.var.admin.reassertSystemSwitches(actor, { tenantId, scopeId }, { appliedInUnit: carried?.switchedOff });
-            }
-        };
         // The host's own refusal, should the impact have changed since it was read above (a
-        // promote landing in between): relayed as the same 409, never as a 500.
+        // promote landing in between): relayed as the same 409, never as a 500. A known scope
+        // binds through the carry tail (#1722): compare-and-set on the binding read above, the pin
+        // cleared after it, the OFF positions re-asserted where it now routes (#1674), and the copy
+        // the carry left in the old script wiped.
         const bind = async (opts) => {
-            await c.var.admin.bindScopeVersion(actor, tenantId, scopeId, versionId, opts).catch(relayHostRefusal);
-            // Keep the old route until the bind succeeds. If clearing the pin fails, a retry
-            // carries again from the still-serving script before it changes the route.
-            if (repairPreviewPin) {
-                await c.var.admin.setScopeServingRef(actor, tenantId, scopeId, null).catch(relayHostRefusal);
+            if (!scope) {
+                await c.var.admin.bindScopeVersion(actor, tenantId, scopeId, versionId, opts).catch(relayHostRefusal);
+                return;
             }
+            await bindAfterCarry(c, scope, versionId, carried, {
+                ...opts,
+                clearServingRef: repairPreviewPin,
+                recarry: () => carryOntoVersion(c, scope, versionId, { dropServingRef: repairPreviewPin }),
+            });
         };
         if (snapshot) {
             if (!scope) {
@@ -3804,10 +4724,18 @@ export function createControlPlaneApi(options) {
                 }
                 await carry();
                 if (migrationCrossing) {
-                    // Asked again after the carry: a promote landing since the first question would
-                    // otherwise leave an archive behind for a bind the host then refuses.
-                    await refuseOnBreaks(actor, tenantId, scopeId, versionId, { acknowledge });
-                    await orchestratedSnapshot(c, tenantId, scope, {});
+                    try {
+                        // Asked again after the carry: a promote landing since the first question would
+                        // otherwise leave an archive behind for a bind the host then refuses.
+                        await refuseOnBreaks(actor, tenantId, scopeId, versionId, { acknowledge });
+                        await orchestratedSnapshot(c, tenantId, scope, {});
+                    }
+                    catch (e) {
+                        // #1722: no bind follows, so the copy the carry restored is reached by nothing.
+                        if (carried)
+                            await dropUnboundCopy(c, scope, versionId, carried);
+                        throw e;
+                    }
                 }
                 await bind({ acknowledge });
             }
@@ -3815,12 +4743,10 @@ export function createControlPlaneApi(options) {
                 await carry();
                 await bind({ acknowledge, snapshot: true });
             }
-            await reassert();
             return c.json(await c.var.admin.getScopeRecord(actor, tenantId, scopeId));
         }
         await carry();
         await bind({ acknowledge });
-        await reassert();
         return c.json(await c.var.admin.getScopeRecord(actor, tenantId, scopeId));
     });
     // -- instances (K-31) -------------------------------------------------------
@@ -4514,6 +5440,11 @@ export function createControlPlaneApi(options) {
             throw new ControlPlaneError(502, `version ${versionId} retained no manifest — pushed pre-#286; push it again to serve in place`);
         }
         const manifest = storedDeployManifest.parse(JSON.parse(manifestJson));
+        // #1902: the classes this upload DEPLOYS — the manifest's, plus the platform's sweeper when
+        // the version's recorded decision supplies it. The upload, the migration delta and the
+        // serving record below all read this one set; the manifest's own `doClasses` would leave
+        // the record a class short of the script, and the next serve re-declaring a live class.
+        const doClasses = deployedDoClasses(manifest.doClasses, manifest.platformSweeper);
         const serving = await host.admin.verticalServing(actor, slug);
         const ref = serving?.ref ?? stableDeploymentRefFor(slug);
         const modules = await options.fetchVerticalModules(version.deploymentRef);
@@ -4537,7 +5468,7 @@ export function createControlPlaneApi(options) {
             compatibilityDate: manifest.compatibilityDate,
             compatibilityFlags: manifest.compatibilityFlags,
             modules,
-            doClasses: manifest.doClasses,
+            doClasses,
             bindings: [...manifest.bindings, ...storeBindings],
             // #1242: the version now being served, injected as `SUBSTRAT_VERSION_ID` so the
             // scope host stamps the signals `version` dimension. The serving script is one
@@ -4547,6 +5478,10 @@ export function createControlPlaneApi(options) {
             // #1054: the model runtime is bound only for a version that ASKED for it, so the
             // capability is visible in the manifest diff at admit rather than fleet-wide.
             ...(manifest.usesModels ? { usesModels: true } : {}),
+            // #1902: the sweeper decision the PUSH made and recorded, reused — never re-made, so a
+            // promote or a backout cannot refuse a version that was accepted. A version pushed
+            // before the record existed has none and keeps what it had: no platform sweeper.
+            ...(manifest.platformSweeper ? { supplySweeper: true } : {}),
             // #340/#578: the version's static files travel with it onto the serving script —
             // from the RETAINED manifest, with no bytes. The runtime's asset store dedupes
             // per SCRIPT (not namespace-wide — the #578 finding), so the serving script only
@@ -4570,18 +5505,14 @@ export function createControlPlaneApi(options) {
         }, serving
             ? { priorDoClasses: serving.doClasses, priorMigrationTag: serving.migrationTag }
             : undefined);
-        const addedClasses = serving
-            ? manifest.doClasses.some((cls) => !serving.doClasses.includes(cls))
-            : false;
+        const addedClasses = serving ? doClasses.some((cls) => !serving.doClasses.includes(cls)) : false;
         await admin.setVerticalServing(actor, slug, {
             ref,
             versionId,
             // The serving script's class set only ever GROWS (DO classes cannot be deleted
             // while their storage lives), so record the union, and the tag only moves when
             // a migration actually rode the upload.
-            doClasses: serving
-                ? [...new Set([...serving.doClasses, ...manifest.doClasses])]
-                : manifest.doClasses,
+            doClasses: serving ? [...new Set([...serving.doClasses, ...doClasses])] : doClasses,
             migrationTag: serving
                 ? addedClasses
                     ? nextMigrationTag(serving.migrationTag)
@@ -5038,6 +5969,13 @@ export function createControlPlaneApi(options) {
                 error: `${assetParts.size} uploaded asset part(s) are absent from the manifest (${extra}${assetParts.size > 5 ? ', …' : ''})`,
             }, 400);
         }
+        // #1902: whether this version's uploads carry the platform's scope sweeper — decided here,
+        // ONCE, before anything is uploaded, and recorded with the version below so every later
+        // upload of it reuses the answer. A declaration that contradicts itself is refused now,
+        // while it is still a push; it can never become a promote or a backout that refuses.
+        const sweeper = platformSweeperDecision(manifest, { entry: manifest.entry, modules });
+        if ('refuse' in sweeper)
+            return c.json({ error: sweeper.refuse }, 422);
         // Mint the version id first: the deploymentRef (the dispatch script name) is keyed
         // on it, so it is CF-valid and unique per version.
         const id = ulid();
@@ -5053,6 +5991,8 @@ export function createControlPlaneApi(options) {
                 // #1242: the freshly minted version id — this archive script IS that version,
                 // and a preview routed at it stamps the signals `version` dimension honestly.
                 versionId: id,
+                // #1902: the platform's scope sweeper, as decided above and recorded with the version.
+                ...(sweeper.supply ? { supplySweeper: true } : {}),
                 // #340: the verified bytes go up with the bundle. The manifest's routing config
                 // rides along untouched — it decides what the RUNTIME does with paths, and carries
                 // no reach, so there is nothing in it for the sandbox contract to refuse.
@@ -5132,7 +6072,8 @@ export function createControlPlaneApi(options) {
             ...(origin ? { origin } : {}),
             // Retained for the serving upload (#286): the archive script keeps the module
             // bytes, this keeps their shape (entry, compat, doClasses, bindings).
-            manifestJson: JSON.stringify(manifest),
+            // #1902: with the sweeper decision the push made, which no later upload re-makes.
+            manifestJson: JSON.stringify({ ...manifest, platformSweeper: sweeper.supply }),
         });
         // Same spirit as the permission-surface gate, advisory tier: when the push DECLARES
         // surfaces, name any surface that hostnames are still bound to but the declaration
@@ -6080,13 +7021,15 @@ export function createControlPlaneApi(options) {
                 }
                 throw e;
             }
-            // Heal a preview provisioned before #527: clear any inherited serving_ref so routing
-            // follows the bound version (its per-version script), not the prod serving script.
-            if (existing.servingRef)
-                await c.var.admin.setScopeServingRef(actor, tenantId, existing.id, null);
-            await c.var.admin.bindScopeVersion(actor, tenantId, existing.id, opts.versionId);
-            // #1674: re-assert any recorded OFF in the script the preview now routes to.
-            await c.var.admin.reassertSystemSwitches(actor, { tenantId, scopeId: existing.id }, { appliedInUnit: carried?.switchedOff });
+            // The carry tail (#1722): the bind expects the version the carry exported from, so of two
+            // pushes that read the same binding only one lands. Then a preview provisioned before
+            // #527 has its inherited serving_ref cleared, so routing follows the bound version (its
+            // per-version script) and not the prod serving script; the OFF positions are re-asserted
+            // there (#1674); and the copy left in the old script is wiped.
+            await bindAfterCarry(c, existing, opts.versionId, carried, {
+                clearServingRef: true,
+                recarry: () => carryOntoVersion(c, existing, opts.versionId, { dropServingRef: true }),
+            });
             // Renew (or clear) the preview's GC deadline so a reused preview does not silently die.
             await c.var.admin.setScopeExpiresAt(actor, tenantId, existing.id, expiresAt);
             const hostname = await bindPreviewHostname(c.var.admin, actor, baseHostname, tenantId, existing.id, opts.tag, surface);
@@ -6158,6 +7101,11 @@ export function createControlPlaneApi(options) {
         };
         let row;
         let restore;
+        /** #2009: the directory's classification of the row below, which every restore of it carries. */
+        const markCopyOfRow = () => {
+            const lineage = copyLineageOf({ kind: row.kind ?? '', forkedFrom: row.forkedFrom ?? null });
+            return lineage ? { markCopy: lineage } : {};
+        };
         if (source) {
             // A fresh fork. Export from where the prod data lives TODAY. The canonical
             // `admin.exportScope` first — it writes the K-24 audit entry (and the co-located
@@ -6188,7 +7136,9 @@ export function createControlPlaneApi(options) {
             // there; restore re-projects the vertical's roles from the dump's tuples). A one-shot
             // DO storage blip heals on the in-request retry WITHOUT burning a CI attempt (which
             // pushes a fresh version per try) — #559 (2).
-            restore = () => target.restoreScope(tenantId, previewId, tables, { sourceScopeId: source.id, exact: true });
+            // #2009: a load classifies nothing by itself, so the restore carries the directory's
+            // classification of the row below, as every restore onto a non-primary scope does.
+            restore = () => target.restoreScope(tenantId, previewId, tables, { sourceScopeId: source.id, exact: true, ...markCopyOfRow() });
         }
         else {
             // A clean-room preview (#509 (b)): an EMPTY scope, no source to export. No `forkedFrom`
@@ -6206,7 +7156,8 @@ export function createControlPlaneApi(options) {
                 jurisdiction: 'global',
                 expiresAt: expiresAt ?? undefined,
             };
-            restore = target ? () => target.restoreScope(tenantId, previewId, []) : null;
+            // #2009: marked a copy on the directory's word, as the fork above.
+            restore = target ? () => target.restoreScope(tenantId, previewId, [], markCopyOfRow()) : null;
         }
         try {
             // Inside the try: a host writes the directory row FIRST and then migrates, projects and