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

package/dist/vertical-client.js

@@ -1,6 +1,23 @@
-import { PREVIEW_CLIENT_PATH, attachmentRecord, denialFilterParams, capabilityFilterParams, capabilityPage, mintedPreviewClient, ownerSeat, ownerClaimLink, ownerTransferResult, previewClientClaim, retiredPreviewClients, peerGrantsEntry, peerSwitchOutcome, systemSwitchOutcome, systemScheduleEntry, switchedOffInUnit, exportedBatch, importResult, importCursorMoved, importState, substratError, } from '@substrat-run/contracts';
-import { CONNECTOR_ATTACHMENT_RECORD_HEADER, PLATFORM_SECRET_HEADER, undrainedEventsOf } from '@substrat-run/kernel';
+import { PREVIEW_CLIENT_PATH, attachmentRecord, denialFilterParams, capabilityFilterParams, capabilityPage, mintedPreviewClient, ownerSeat, ownerClaimLink, ownerTransferResult, previewClientClaim, retiredPreviewClients, peerGrantsEntry, peerSwitchOutcome, systemSwitchOutcome, lifecycleDelivery, systemScheduleEntry, switchedOffInUnit, exportedBatch, importResult, importCursorMoved, importState, substratError, CONNECTOR_ATTACHMENT_RECORD_HEADER, LOAD_STAMP_HEADER, PLATFORM_SECRET_HEADER, WRITE_REVISION_HEADER, } from '@substrat-run/contracts';
+import { undrainedEventsOf } from '@substrat-run/kernel';
 import { ControlPlaneError } from '@substrat-run/control-plane-client';
+/** `routeAnswer`'s word for a deployment that predates the route it was asked (#1722, #2010). */
+const PREDATES = Symbol('predates');
+/** #1722's kept-copy and fenced-wipe verbs: a host without the method answers a 501. */
+const FENCED = { legacy501: true, lost: 'it may or may not have acted' };
+/**
+ * What a 200 whose body is not JSON says, when it is an HTML page (#2010, Codex #2014 r1). An old
+ * deployment's SPA fallback answers its own app's `index.html` for a path it does not route, and a
+ * proxy or error page in between answers HTML too. Nothing the platform controls marks the first
+ * (the page is the vertical's, served by the asset layer before any platform code runs, and the
+ * deployments in question predate any marker that could be added now), so the two cannot be told
+ * apart, and an HTML page is never read as "predates the route".
+ */
+function htmlNote(res) {
+    return (res.headers.get('content-type') ?? '').toLowerCase().includes('text/html')
+        ? " (an HTML page: an old deployment's app shell cannot be told from an error page in between)"
+        : '';
+}
 /**
  * The query string for both internal denial reads. The filter's own fields come from
  * the ONE encoder in contracts (#971) — this branch answers the same two routes as
@@ -319,6 +336,30 @@ export class VerticalClient {
     async connectorGrant(input) {
         await this.postInternal('/internal/connector-grant', input, 'connector-grant');
     }
+    /**
+     * Deliver one scope's lifecycle to the deployment serving it (#1713). Throws on anything but
+     * a parsed answer, a deployment built before the route (404/501) included, so the caller
+     * records no receipt and the heal sweep asks again.
+     */
+    async setLifecycle(input) {
+        const verb = 'lifecycle';
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        const res = await this.reach(verb, () => this.options.fetch(`${base}/internal/lifecycle`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
+            body: JSON.stringify(input),
+        }));
+        if (res.status === 404) {
+            throw new ControlPlaneError(501, `the deployment serving scope ${input.scopeId} predates the lifecycle delivery (#1713) — redeploy the vertical`);
+        }
+        if (!res.ok)
+            throw await this.refusal(verb, res);
+        const parsed = lifecycleDelivery.safeParse(await res.json().catch(() => null));
+        if (!parsed.success) {
+            throw new ControlPlaneError(502, `vertical answered ${verb} for scope ${input.scopeId} with an unexpected shape`);
+        }
+        return parsed.data;
+    }
     /**
      * Move one module's schedule kill switch in the deployment serving the scope (#1666) —
      * the far end of `revokeFromSystem` / `restoreToSystem` for a hosted scope, whose
@@ -327,114 +368,83 @@ export class VerticalClient {
      * ONE shape is normalized to "redeploy the vertical", and only because it is the
      * deployment's own proof that it cannot have acted: a script built before the route
      * answers a **404** (the path does not exist — the route itself answers a module it holds
-     * nothing for with a 200 `held: false`, never a 404) or its **SPA shell** (a 200 that is
-     * not JSON). "Nothing was switched" is true of exactly those.
+     * nothing for with a 200 `held: false`, never a 404). "Nothing was switched" is true of exactly
+     * that. An HTML 200 is NOT that proof (`routeAnswer`): an old deployment's app shell cannot be
+     * told from an error page after a switch that moved.
      *
      * Everything else surfaces as the failure it is, and never claims that: a transport
-     * failure (`reach` → 502 "unreachable"), a genuine 5xx from the far end, and a 200 JSON of
-     * the wrong shape. The request may have landed and the switch may have moved before the
-     * answer was lost, so the only honest instruction is to confirm the position first.
+     * failure (`reach` → 502 "unreachable"), a genuine 5xx from the far end, a 200 whose body
+     * is truncated or fails to read (#2010), and a 200 JSON of the wrong shape. The request may
+     * have landed and the switch may have moved before the answer was lost, so the only honest
+     * instruction is to confirm the position first.
      */
     async systemSwitch(input) {
         const verb = 'system-switch';
-        const predates = () => new ControlPlaneError(501, `the deployment serving scope ${input.scopeId} predates the schedule switch (#1666) — ` +
-            `redeploy the vertical, then retry. Nothing was switched.`);
+        const lost = `the switch on scope ${input.scopeId} may or may not have moved. ` +
+            `Confirm its position (read the scope's schedule status) before retrying.`;
         const base = this.options.baseUrl ?? 'https://vertical.invalid';
-        const res = await this.reach(verb, () => this.options.fetch(`${base}/internal/system-switch`, {
+        const rule = {
+            legacy501: false,
+            lost,
+            predates: `the deployment serving scope ${input.scopeId} predates the schedule switch (#1666) — ` +
+                `redeploy the vertical, then retry. Nothing was switched.`,
+            shape: `vertical answered ${verb} with an unexpected shape — ${lost}`,
+        };
+        return this.parsedAnswer(verb, rule, systemSwitchOutcome, () => this.options.fetch(`${base}/internal/system-switch`, {
             method: 'POST',
             headers: { 'content-type': 'application/json', [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
             body: JSON.stringify(input),
         }));
-        if (res.status === 404)
-            throw predates();
-        if (!res.ok)
-            throw await this.refusal(verb, res);
-        const text = await res.text();
-        let raw;
-        try {
-            raw = JSON.parse(text);
-        }
-        catch {
-            throw predates();
-        }
-        const parsed = systemSwitchOutcome.safeParse(raw);
-        if (!parsed.success) {
-            throw new ControlPlaneError(502, `vertical answered ${verb} with an unexpected shape — the switch on scope ${input.scopeId} may ` +
-                `or may not have moved. Confirm its position (the scope's SQL console) before retrying.`);
-        }
-        return parsed.data;
     }
     /**
      * The read half of the schedule kill switch's status (#1674): every module the
      * deployment serving this scope holds or has held system authority for, and where each
-     * stands. Mirrors `systemSwitch`'s seam and its skew rule exactly (#1666's "only the
-     * explicit legacy signal reads as redeploy"): a 404 (the route does not exist) or an SPA
-     * shell (a 200 that is not JSON) are the deployment's own proof it predates this read,
-     * and become a 501 that says so. A 200 of the wrong-shaped JSON is NOT that proof — it
-     * is a failure this client cannot explain, so it surfaces as the 502 it is rather than a
-     * guess at "redeploy". The far end's own 501 (the route exists, the method doesn't)
-     * passes through `refusal` verbatim, unchanged either way.
+     * stands. Mirrors `systemSwitch`'s seam and its skew rule exactly (`routeAnswer`): a 404
+     * is the deployment's own proof it predates this read, and becomes a 501 that says so. A
+     * truncated, unreadable or HTML 200 (#2010) and a 200 of the wrong-shaped JSON are NOT that
+     * proof — they are a failed read, a 502, rather than a guess at
+     * "redeploy". The far end's own 501 (the route exists, the method doesn't) passes through
+     * `refusal` verbatim, unchanged either way.
      */
     async systemGrantsStatus(input) {
         const verb = 'system-grants';
-        const predates = () => new ControlPlaneError(501, `the deployment serving scope ${input.scopeId} predates the schedule switch's status read (#1674) — ` +
-            `redeploy the vertical, then retry.`);
+        const lost = `the status of scope ${input.scopeId} could not be read. Nothing was changed; retry the read.`;
         const base = this.options.baseUrl ?? 'https://vertical.invalid';
-        const res = await this.reach(verb, () => this.options.fetch(`${base}/internal/system-grants?scopeId=${encodeURIComponent(input.scopeId)}`, {
+        const rule = {
+            legacy501: false,
+            lost,
+            predates: `the deployment serving scope ${input.scopeId} predates the schedule switch's status read (#1674) — ` +
+                `redeploy the vertical, then retry.`,
+            shape: `vertical answered ${verb} with an unexpected shape for scope ${input.scopeId}.`,
+        };
+        return this.parsedAnswer(verb, rule, systemScheduleEntry.array(), () => this.options.fetch(`${base}/internal/system-grants?scopeId=${encodeURIComponent(input.scopeId)}`, {
             method: 'GET',
             headers: { [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
         }));
-        if (res.status === 404)
-            throw predates();
-        if (!res.ok)
-            throw await this.refusal(verb, res);
-        const text = await res.text();
-        let raw;
-        try {
-            raw = JSON.parse(text);
-        }
-        catch {
-            throw predates();
-        }
-        const parsed = systemScheduleEntry.array().safeParse(raw);
-        if (!parsed.success) {
-            throw new ControlPlaneError(502, `vertical answered ${verb} with an unexpected shape for scope ${input.scopeId}.`);
-        }
-        return parsed.data;
     }
     /**
      * The read half of the peer kill switch's status (#1706): every peer the deployment
      * serving this scope holds or has held grants for, and where each stands. Mirrors
-     * `peerSwitch`'s seam and `systemGrantsStatus`'s skew rule exactly — a 404 or an SPA
-     * shell are the deployment's own proof it predates this read and become a 501 that says
-     * to redeploy; a wrong-shaped 200 is not that proof and surfaces as the 502 it is.
+     * `peerSwitch`'s seam and `systemGrantsStatus`'s skew rule exactly — a 404 is the
+     * deployment's own proof it predates this read and becomes a 501 that says to redeploy; a
+     * truncated, unreadable, HTML or wrong-shaped 200 is not that proof and surfaces as the 502
+     * it is.
      */
     async peerGrantsStatus(input) {
         const verb = 'peer-grants';
-        const predates = () => new ControlPlaneError(501, `the deployment serving scope ${input.scopeId} predates the peer switch's status read (#1706) — ` +
-            `redeploy the vertical, then retry.`);
+        const lost = `the peer status of scope ${input.scopeId} could not be read. Nothing was changed; retry the read.`;
         const base = this.options.baseUrl ?? 'https://vertical.invalid';
-        const res = await this.reach(verb, () => this.options.fetch(`${base}/internal/peer-grants?scopeId=${encodeURIComponent(input.scopeId)}`, {
+        const rule = {
+            legacy501: false,
+            lost,
+            predates: `the deployment serving scope ${input.scopeId} predates the peer switch's status read (#1706) — ` +
+                `redeploy the vertical, then retry.`,
+            shape: `vertical answered ${verb} with an unexpected shape for scope ${input.scopeId}.`,
+        };
+        return this.parsedAnswer(verb, rule, peerGrantsEntry.array(), () => this.options.fetch(`${base}/internal/peer-grants?scopeId=${encodeURIComponent(input.scopeId)}`, {
             method: 'GET',
             headers: { [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
         }));
-        if (res.status === 404)
-            throw predates();
-        if (!res.ok)
-            throw await this.refusal(verb, res);
-        const text = await res.text();
-        let raw;
-        try {
-            raw = JSON.parse(text);
-        }
-        catch {
-            throw predates();
-        }
-        const parsed = peerGrantsEntry.array().safeParse(raw);
-        if (!parsed.success) {
-            throw new ControlPlaneError(502, `vertical answered ${verb} with an unexpected shape for scope ${input.scopeId}.`);
-        }
-        return parsed.data;
     }
     /**
      * Move one PEER's kill switch in the deployment serving the scope (#1706) — the far end
@@ -442,40 +452,30 @@ export class VerticalClient {
      * live there and nowhere the shared control plane can reach.
      *
      * The seam, the skew rule and the honesty rule are `systemSwitch`'s, for the same reasons:
-     * a **404** (no such route) or an **SPA shell** (a 200 that is not JSON) are the
-     * deployment's own proof that it predates this route and therefore cannot have switched
-     * anything — the route itself answers a peer the scope holds nothing for with a 200
-     * `held: false`, never a 404. Everything else surfaces as the failure it is, because the
-     * request may have landed and the switch may have moved before the answer was lost.
+     * a **404** (no such route) is the deployment's own proof that it
+     * predates this route and therefore cannot have switched anything — the route itself
+     * answers a peer the scope holds nothing for with a 200 `held: false`, never a 404.
+     * Everything else, a truncated or unreadable 200 included (#2010), surfaces as the failure
+     * it is, because the request may have landed and the switch may have moved before the
+     * answer was lost.
      */
     async peerSwitch(input) {
         const verb = 'peer-switch';
-        const predates = () => new ControlPlaneError(501, `the deployment serving scope ${input.scopeId} predates the peer kill switch (#1706) — ` +
-            `redeploy the vertical, then retry. Nothing was switched.`);
+        const lost = `the switch for peer '${input.vertical}' on scope ${input.scopeId} may or may not have moved. ` +
+            `Confirm its position (read the scope's peer status) before retrying.`;
         const base = this.options.baseUrl ?? 'https://vertical.invalid';
-        const res = await this.reach(verb, () => this.options.fetch(`${base}/internal/peer-switch`, {
+        const rule = {
+            legacy501: false,
+            lost,
+            predates: `the deployment serving scope ${input.scopeId} predates the peer kill switch (#1706) — ` +
+                `redeploy the vertical, then retry. Nothing was switched.`,
+            shape: `vertical answered ${verb} with an unexpected shape — ${lost}`,
+        };
+        return this.parsedAnswer(verb, rule, peerSwitchOutcome, () => this.options.fetch(`${base}/internal/peer-switch`, {
             method: 'POST',
             headers: { 'content-type': 'application/json', [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
             body: JSON.stringify(input),
         }));
-        if (res.status === 404)
-            throw predates();
-        if (!res.ok)
-            throw await this.refusal(verb, res);
-        const text = await res.text();
-        let raw;
-        try {
-            raw = JSON.parse(text);
-        }
-        catch {
-            throw predates();
-        }
-        const parsed = peerSwitchOutcome.safeParse(raw);
-        if (!parsed.success) {
-            throw new ControlPlaneError(502, `vertical answered ${verb} with an unexpected shape — the switch for peer '${input.vertical}' on ` +
-                `scope ${input.scopeId} may or may not have moved. Confirm its position before retrying.`);
-        }
-        return parsed.data;
     }
     /**
      * A preview's own client at a team auth-server (#1704, `@substrat-run/contracts`'
@@ -483,13 +483,14 @@ export class VerticalClient {
      * here, delete the preview's clients. Addressed to the ISSUER's deployment (this client),
      * never the preview's.
      *
-     * The skew rule is `systemSwitch`'s, widened by one status: a deployment built before these
+     * The skew rule is `routeAnswer`'s with `legacy501`: a deployment built before these
      * routes answers its `/internal/*` fallback — a JSON **501** on the auth-server — or a
-     * **404**, or an SPA shell (a 200 that is not JSON). All three are the deployment's own
-     * proof it cannot have acted, and become a 501 that says to redeploy the auth server. The
-     * caller must never read that as "the parent does not sign in here". A 200 of the wrong
-     * shape is not that proof and surfaces as a 502; a refusal (403 another tenant's issuer,
-     * 409 a parent it does not claim) passes through verbatim.
+     * **404**. Both are the deployment's own proof it cannot have acted,
+     * and become a 501 that says to redeploy the auth server. The caller must never read that
+     * as "the parent does not sign in here". A truncated or unreadable 200 (#2010) and a 200 of
+     * the wrong shape are not that proof and surface as a 502: a mint or a retire may have run.
+     * A refusal (403 another tenant's issuer, 409 a parent it does not claim) passes through
+     * verbatim.
      *
      * The mint's answer carries a client SECRET. It is returned to the caller and nothing here
      * keeps, logs or quotes it: no error message on this path includes a response body that
@@ -505,31 +506,19 @@ export class VerticalClient {
         return this.previewClientCall('DELETE', PREVIEW_CLIENT_PATH, input, retiredPreviewClients, 'preview-client retire', input.scopeId);
     }
     async previewClientCall(method, path, body, schema, verb, issuerScopeId) {
-        const predates = () => new ControlPlaneError(501, `the auth server serving scope ${issuerScopeId} predates preview clients (#1704) — redeploy it, ` +
-            `then re-run. Nothing was minted or deleted there.`);
         const base = this.options.baseUrl ?? 'https://vertical.invalid';
-        const res = await this.reach(verb, () => this.options.fetch(`${base}${path}`, {
+        const rule = {
+            legacy501: true,
+            lost: `the auth server serving scope ${issuerScopeId} may or may not have acted on it.`,
+            predates: `the auth server serving scope ${issuerScopeId} predates preview clients (#1704) — redeploy it, ` +
+                `then re-run. Nothing was minted or deleted there.`,
+            shape: `auth server answered ${verb} with an unexpected shape for scope ${issuerScopeId}.`,
+        };
+        return this.parsedAnswer(verb, rule, schema, () => this.options.fetch(`${base}${path}`, {
             method,
             headers: { 'content-type': 'application/json', [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
             body: JSON.stringify(body),
         }));
-        if (res.status === 404 || res.status === 501)
-            throw predates();
-        if (!res.ok)
-            throw await this.refusal(verb, res);
-        const text = await res.text();
-        let raw;
-        try {
-            raw = JSON.parse(text);
-        }
-        catch {
-            throw predates();
-        }
-        const parsed = schema.safeParse(raw);
-        if (!parsed.success) {
-            throw new ControlPlaneError(502, `auth server answered ${verb} with an unexpected shape for scope ${issuerScopeId}.`);
-        }
-        return parsed.data;
     }
     /** Journal a platform-request outcome back in the vertical after the platform ran it. */
     async settlePlatformRequest(tenantId, scopeId, id, outcome) {
@@ -562,6 +551,19 @@ export class VerticalClient {
     async exportScope(scopeId) {
         return this.getInternal(`/internal/export?scopeId=${encodeURIComponent(scopeId)}`);
     }
+    /**
+     * `exportScope` with the store's load stamp (#1722), read by the vertical in the same call as
+     * the dump and handed over in a header: what a carry's fenced wipe of the copy it leaves
+     * expects. Null from a deployment that predates the stamp, which cannot fence a wipe either.
+     * A store nothing has stamped is stamped by this read.
+     */
+    async exportScopeStamped(scopeId) {
+        const path = `/internal/export?scopeId=${encodeURIComponent(scopeId)}&stamp=1`;
+        const res = await this.getInternalResponse(path);
+        const loadStamp = res.headers.get(LOAD_STAMP_HEADER) || null;
+        const revision = res.headers.get(WRITE_REVISION_HEADER) || null;
+        return { tables: await this.parseInternal('introspection', path, res), loadStamp, revision };
+    }
     /**
      * The write half of `exportScope` — load a dump into one existing scope in this
      * deployment (drop-then-replay), for the governed restore/backout. The control-plane
@@ -576,7 +578,12 @@ export class VerticalClient {
     /** #1742: the recorded-off modules, switched off on THIS scope in the restore's own event.
      *  #1869: `sourceScopeId`, the scope the tables were captured from, so the vertical re-points
      *  exactly that scope's grants, and `exact` when the platform exported them itself. A
-     *  vertical that predates the fields ignores them. */
+     *  vertical that predates the fields ignores them. #1722: `loadStamp`, the stamp a carry
+     *  leaves on the copy it lands, which a later fenced wipe of that copy expects, and `expect`,
+     *  the marker the carry read here (`loadMarker`): the load is refused if the store moved since.
+     *  #2005: `markCopy` — the directory's classification of this scope, sent when it is not
+     *  primary, so the vertical marks it a copy in its own storage (and refuses a primary one).
+     *  A vertical that predates the field ignores it. */
     opts) {
         // `exact` vouches for a named source; the vertical refuses it without one, so say so here.
         if (opts?.exact && !opts.sourceScopeId) {
@@ -587,11 +594,194 @@ export class VerticalClient {
             scopeId,
             tables,
             ...(opts?.switchedOff ? { switchedOff: opts.switchedOff } : {}),
+            ...(opts?.tenantHeld ? { tenantHeld: opts.tenantHeld } : {}),
             ...(opts?.sourceScopeId ? { sourceScopeId: opts.sourceScopeId } : {}),
             ...(opts?.exact ? { exact: true } : {}),
+            ...(opts?.loadStamp ? { loadStamp: opts.loadStamp } : {}),
+            ...(opts?.expect ? { expect: opts.expect } : {}),
+            ...(opts?.markCopy ? { markCopy: opts.markCopy } : {}),
         }, 'restore');
         return { tables: count, ...switchedOffFrom(switchedOff) };
     }
+    /**
+     * Wipe the copy a carry left in this deployment (#1722), only if nothing was loaded into the
+     * scope since `expectLoadStamp` (null: a store no load has stamped). `wiped: false` is the
+     * vertical's refusal: something was restored there since, and it stays.
+     *
+     * `'unfenced'` is a deployment that cannot compare the stamp, and the only answer that lets
+     * the caller fall back to an unconditional wipe: a 404 (built before the route), a 501 (a host
+     * without the method) are the deployment's own proof that it wiped nothing (`routeAnswer`).
+     * Everything else, a truncated or malformed JSON answer and any HTML page included, surfaces as
+     * the failure it is: the wipe may or may not have run.
+     */
+    async wipeCarriedCopy(input) {
+        const verb = 'wipe-carried';
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        const answer = await this.routeAnswer(verb, FENCED, () => this.options.fetch(`${base}/internal/wipe-carried`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
+            body: JSON.stringify(input),
+        }));
+        if (answer === PREDATES)
+            return 'unfenced';
+        const wiped = answer?.wiped;
+        if (typeof wiped !== 'boolean') {
+            throw new ControlPlaneError(502, `vertical answered ${verb} with an unexpected shape — the copy of scope ${input.scopeId} may or may not be wiped`);
+        }
+        return { wiped };
+    }
+    /**
+     * What a carry's restore into this scope expects to find unchanged (#1722): the load stamp and
+     * the store's write revision. `'unfenced'` on `wipeCarriedCopy`'s terms: only the
+     * deployment's own answer that it predates the route; everything else is a failure.
+     */
+    async loadMarker(scopeId) {
+        const verb = 'load-marker';
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        const answer = await this.routeAnswer(verb, FENCED, () => this.options.fetch(`${base}/internal/load-marker?scopeId=${encodeURIComponent(scopeId)}`, {
+            headers: { [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
+        }));
+        if (answer === PREDATES)
+            return 'unfenced';
+        const { loadStamp, revision } = (answer ?? {});
+        const field = (v) => v === null || (typeof v === 'string' && v.length > 0);
+        if (!field(loadStamp) || !field(revision)) {
+            throw new ControlPlaneError(502, `vertical answered ${verb} for scope ${scopeId} with an unexpected shape`);
+        }
+        return { loadStamp: loadStamp, revision: revision };
+    }
+    /**
+     * The kept copy of a scope in this deployment (#1722), or null. A deployment built before the
+     * fenced wipe cannot have made one, so its "predates" answer reads as null too.
+     */
+    async keptCopy(scopeId) {
+        const verb = 'kept-copy';
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        const answer = await this.routeAnswer(verb, FENCED, () => this.options.fetch(`${base}/internal/kept-copy?scopeId=${encodeURIComponent(scopeId)}`, {
+            headers: { [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
+        }));
+        if (answer === PREDATES)
+            return null;
+        const kept = answer?.kept;
+        if (kept === null)
+            return null;
+        const k = kept;
+        if (!k || typeof k.carriedTo !== 'string' || typeof k.keptAt !== 'string' || !(k.revision === null || typeof k.revision === 'string')) {
+            throw new ControlPlaneError(502, `vertical answered ${verb} for scope ${scopeId} with an unexpected shape`);
+        }
+        return {
+            carriedTo: k.carriedTo,
+            keptAt: k.keptAt,
+            revision: k.revision,
+            ...(k.leftAgain && typeof k.leftAgain.to === 'string' && typeof k.leftAgain.at === 'string'
+                ? { leftAgain: { to: k.leftAgain.to, at: k.leftAgain.at } }
+                : {}),
+            ...(k.clearedOnly && (k.clearedOnly.revision === null || typeof k.clearedOnly.revision === 'string')
+                ? { clearedOnly: { revision: k.clearedOnly.revision } }
+                : {}),
+        };
+    }
+    /** Release the marker of a kept copy that is the live store after all (#1722), at the revision read. */
+    async releaseKeptCopy(input) {
+        const verb = 'kept-copy-release';
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        const answer = await this.routeAnswer(verb, FENCED, () => this.options.fetch(`${base}/internal/kept-copy/release`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
+            body: JSON.stringify(input),
+        }));
+        if (answer === PREDATES) {
+            throw new ControlPlaneError(501, `the deployment holding scope ${input.scopeId} keeps no copies (#1722)`);
+        }
+        const a = answer;
+        if (a?.released === true)
+            return { released: true };
+        if (a?.refused === 'changed' || a?.refused === 'not-kept')
+            return { refused: a.refused };
+        throw new ControlPlaneError(502, `vertical answered ${verb} with an unexpected shape — the marker may or may not be cleared`);
+    }
+    /** Discard the kept copy of a scope in this deployment (#1722), at the revision the operator read. */
+    async discardKeptCopy(input) {
+        const verb = 'kept-copy-discard';
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        const answer = await this.routeAnswer(verb, FENCED, () => this.options.fetch(`${base}/internal/kept-copy/discard`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
+            body: JSON.stringify(input),
+        }));
+        if (answer === PREDATES) {
+            throw new ControlPlaneError(501, `the deployment holding scope ${input.scopeId} keeps no copies (#1722)`);
+        }
+        const a = answer;
+        if (a?.discarded === true)
+            return { discarded: true };
+        if (a?.refused === 'changed' || a?.refused === 'not-kept')
+            return { refused: a.refused };
+        throw new ControlPlaneError(502, `vertical answered ${verb} with an unexpected shape — the copy may or may not be discarded`);
+    }
+    /**
+     * The ONE skew rule for a route a deployment may predate (#1722, #2010): `PREDATES` only for a
+     * status that says the route is not there — a 404, and a 501 where `rule.legacy501` says the far
+     * end's own fallback answers one. No body is that proof. Everything else is a failure, never
+     * `PREDATES`, because the request may have landed: a transport failure, a refusal, a body that
+     * fails to read, and a body that is not valid JSON — a truncated `{"held":` from a deployment
+     * that DID act, or an HTML page (`htmlNote`), which an old deployment's app shell and an error
+     * page after a switch that moved both are. Those last ones are a 502 that ends with
+     * `rule.lost`, the verb's own sentence for what a lost answer leaves unknown.
+     */
+    async routeAnswer(verb, rule, request) {
+        const res = await this.reach(verb, request);
+        if (res.status === 404 || (rule.legacy501 && res.status === 501))
+            return PREDATES;
+        if (!res.ok)
+            throw await this.refusal(verb, res);
+        return this.readAnswer(verb, res, rule.lost);
+    }
+    /**
+     * `routeAnswer` for a verb whose "predates" is always a 501 and whose answer has a schema:
+     * the parsed answer, or the 501 `rule.predates`, or the 502 `rule.shape` for a wrong shape.
+     */
+    async parsedAnswer(verb, rule, schema, request) {
+        const answer = await this.routeAnswer(verb, rule, request);
+        if (answer === PREDATES)
+            throw new ControlPlaneError(501, rule.predates);
+        const parsed = schema.safeParse(answer);
+        if (!parsed.success)
+            throw new ControlPlaneError(502, rule.shape);
+        return parsed.data;
+    }
+    /**
+     * A 200's body, read under #2010's rule: the JSON it carries. A body that fails to read, or is
+     * not JSON (an HTML page included, `htmlNote`), is a 502 that names `subject` and ends with
+     * `lost`, because the deployment that answered may have acted.
+     */
+    async readAnswer(subject, res, lost) {
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (e) {
+            throw new ControlPlaneError(502, `reading the vertical's answer to ${subject} failed (${e instanceof Error ? e.message : String(e)}) — ${lost}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new ControlPlaneError(502, `vertical answered ${subject} with a body that is not JSON${htmlNote(res)} — ${lost}`);
+        }
+    }
+    /** Mark one scope a copy in the vertical's own storage (#2005), given the directory's
+     *  classification of it; whether this call stamped it. */
+    async markCopy(scopeId, lineage) {
+        return this.postInternal('/internal/mark-copy', { scopeId, lineage }, 'mark-copy');
+    }
+    /** Remove a mistaken copy marker (#2005), given the directory's classification; whether it did. */
+    async clearCopyMark(scopeId, lineage, 
+    /** #1722 (Codex #2008 r12–r13): clear only the store with this load stamp and revision; 412
+     *  otherwise. */
+    opts = {}) {
+        return this.postInternal('/internal/clear-copy-mark', { scopeId, lineage, ...(opts.expect ? { expect: opts.expect } : {}) }, 'clear-copy-mark');
+    }
     /** Facets over one scope's outbox (#1239) — through the vertical that holds the data. */
     async facetEvents(scopeId, input) {
         const q = new URLSearchParams({ scopeId });
@@ -787,21 +977,16 @@ export class VerticalClient {
             : `vertical refused ${verb}: ${res.status} ${res.statusText}`);
     }
     /**
-     * A 200 whose body is not JSON is a script that does not SERVE this route: an old
-     * worker build falls through to its SPA fallback and answers the app shell (200,
-     * `<!doctype …`) for any `/internal/*` path it predates. Surface that as the
-     * diagnosis instead of an unhandled SyntaxError → 500 (#389: a pre-#236 script has
-     * no `/internal/export`, so a carried rebind cannot dump it).
+     * A 200 that is not JSON is a 502 that names the verb, instead of an unhandled SyntaxError →
+     * 500 (#389: a pre-#236 script has no `/internal/export`, and its SPA fallback answered the app
+     * shell). That shell cannot be told from an error page in between (`htmlNote`), and a truncated
+     * answer from a deployment that has the route may follow a write that ran (#2010), so the
+     * message says the call may or may not have acted, and names redeploying only as the remedy
+     * for the case it cannot prove.
      */
     async parseInternal(verb, path, res) {
-        const text = await res.text();
-        try {
-            return JSON.parse(text);
-        }
-        catch {
-            throw new ControlPlaneError(502, `vertical answered ${verb} (${path}) with non-JSON — its deployed script predates this ` +
-                `surface. Redeploy the vertical (or, for a rebind, use abandonData).`);
-        }
+        return (await this.readAnswer(`${verb} (${path})`, res, 'it may or may not have acted. If this deployment answers its app for /internal/*, it predates ' +
+            'this surface: redeploy the vertical (or, for a rebind, use abandonData).'));
     }
     /** A platform-authenticated POST to the vertical's `/internal/*` surface. */
     /**
@@ -827,10 +1012,11 @@ export class VerticalClient {
      *
      * The skew rule is `systemSwitch`'s, and here it is the whole point: an EMPTY batch is a
      * real answer (nothing new), so a deployment that cannot answer must never produce one. A
-     * 404 (the route does not exist) or a 200 that is not JSON (the SPA shell of a script that
-     * predates the route) is that deployment's own proof, and becomes a 501 saying to redeploy.
+     * 404 (the route does not exist) is that deployment's own proof (`routeAnswer`), and becomes a
+     * 501 saying to redeploy.
      * The far end's own 501 (the route exists, the host method does not) passes through
-     * verbatim. A JSON 200 of the wrong shape is a 502, never a guess.
+     * verbatim. A truncated or unreadable 200 (#2010) and a JSON 200 of the wrong shape are a
+     * 502, never a guess.
      */
     async exportedEvents(input) {
         return this.crossVerticalCall('exported-events', '/internal/exported-events', input.scopeId, exportedBatch, input);
@@ -856,8 +1042,8 @@ export class VerticalClient {
     /**
      * The replay lever's far end (#1705 PR 3): move the watermark of the consumer scope this
      * deployment serves. The same skew rule, plus the write's one difference: a JSON 200 of the
-     * wrong shape may follow a move that happened, so the 502 says to read the edge before
-     * pulling the lever again. A 404 or an SPA shell proves the route is absent, so nothing moved.
+     * wrong shape, or one truncated or unreadable (#2010), may follow a move that happened, so the
+     * 502 says to read the edge before pulling the lever again. A 404 proves the route is absent, so nothing moved.
      */
     async importCursorMove(input) {
         return this.crossVerticalCall('import-cursor', '/internal/import-cursor', input.scopeId, importCursorMoved, input, {
@@ -869,31 +1055,21 @@ export class VerticalClient {
      * of `body` when there is one, a GET otherwise.
      */
     async crossVerticalCall(verb, path, scopeId, schema, body, opts = {}) {
-        const predates = () => new ControlPlaneError(501, `the deployment serving scope ${scopeId} predates cross-vertical events (#1705) — redeploy the vertical. ` +
-            `Nothing was read or delivered; the edge's watermark holds.`);
+        const lost = opts.write
+            ? 'the write may have taken effect: read the edge before retrying.'
+            : 'it may or may not have acted; repeating it is safe.';
         const base = this.options.baseUrl ?? 'https://vertical.invalid';
         const secret = { [PLATFORM_SECRET_HEADER]: this.options.platformSecret };
-        const res = await this.reach(verb, () => this.options.fetch(`${base}${path}`, body === undefined
+        const rule = {
+            legacy501: false,
+            lost,
+            predates: `the deployment serving scope ${scopeId} predates cross-vertical events (#1705) — redeploy the vertical. ` +
+                `Nothing was read or delivered; the edge's watermark holds.`,
+            shape: `vertical answered ${verb} with an unexpected shape for scope ${scopeId}` + (opts.write ? ` — ${lost}` : '.'),
+        };
+        return this.parsedAnswer(verb, rule, schema, () => this.options.fetch(`${base}${path}`, body === undefined
             ? { method: 'GET', headers: secret }
             : { method: 'POST', headers: { ...secret, 'content-type': 'application/json' }, body: JSON.stringify(body) }));
-        if (res.status === 404)
-            throw predates();
-        if (!res.ok)
-            throw await this.refusal(verb, res);
-        const text = await res.text();
-        let raw;
-        try {
-            raw = JSON.parse(text);
-        }
-        catch {
-            throw predates();
-        }
-        const parsed = schema.safeParse(raw);
-        if (!parsed.success) {
-            throw new ControlPlaneError(502, `vertical answered ${verb} with an unexpected shape for scope ${scopeId}.` +
-                (opts.write ? ' The write may have taken effect: read the edge before retrying.' : ''));
-        }
-        return parsed.data;
     }
     async postInternal(path, body, verb) {
         const base = this.options.baseUrl ?? 'https://vertical.invalid';
@@ -911,13 +1087,17 @@ export class VerticalClient {
     }
     /** A platform-authenticated GET to the vertical's `/internal/*` surface. */
     async getInternal(path) {
+        return this.parseInternal('introspection', path, await this.getInternalResponse(path));
+    }
+    /** `getInternal`'s request, answering the response itself, for a caller that reads a header too. */
+    async getInternalResponse(path) {
         const base = this.options.baseUrl ?? 'https://vertical.invalid';
         const res = await this.reach('introspection', () => this.options.fetch(`${base}${path}`, {
             headers: { [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
         }));
         if (!res.ok)
             throw await this.refusal('introspection', res);
-        return this.parseInternal('introspection', path, res);
+        return res;
     }
 }
 //# sourceMappingURL=vertical-client.js.map