@substrat-run/adapter-cloudflare 0.119.0 → 0.121.0

package/dist/host.js

@@ -1,6 +1,6 @@
-import { fromWireFailure, exportReadInput, exportedBatch, importBatch, importResult, importState, accessLogEntry, adminLogEntry, opsFailureEntry, opsFailureFingerprint, issueEntry, sweepRunEntry, FRESHNESS_HEARTBEAT_MINUTES, sweepRunsPayload, modelUsageEntry, attachmentRecord, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalServingState, verticalChannel, verticalVersion, connection, capabilityExchange, capabilityGrant, principalId, connectionGrant, connectionGrantRecord, connectionSecret, systemGrant, systemSwitch, systemSwitchOutcome, systemScheduleEntry, entitlementGrant, entitlementGrantInput, instant, meterReading, subjectRef, createConnectionInput, projectedConnectionGrant, projectedConnectionKey, moduleManifest, org as orgSchema, orgMembership, resolvedIdentity, identityMembership, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, delegatedReadRecord, subjectShredReceipt, connectorDispatchKind, callsOfManifestJson, outboundOfManifestJson, substratError, redrainEventsInput, peerCoverage, peerGrantsEntry, peerSwitch, peerSwitchOutcome, verticalCaller, verticalResolution, verticalSlug, } from '@substrat-run/contracts';
+import { fromWireFailure, exportReadInput, exportedBatch, importBatch, importResult, importState, importsOfManifestJson, exportsOfManifestJson, importCursorMove, importCursorMoveAt, importCursorMoved, accessLogEntry, adminLogEntry, opsFailureEntry, opsFailureFingerprint, issueEntry, sweepRunEntry, FRESHNESS_HEARTBEAT_MINUTES, sweepRunsPayload, modelUsageEntry, attachmentRecord, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalServingState, verticalChannel, verticalVersion, connection, capabilityExchange, capabilityGrant, principalId, connectionGrant, connectionGrantRecord, connectionSecret, systemGrant, systemSwitch, systemSwitchOutcome, systemScheduleEntry, systemSwitchRecord, entitlementGrant, entitlementGrantInput, instant, meterReading, subjectRef, createConnectionInput, projectedConnectionGrant, projectedConnectionKey, moduleManifest, org as orgSchema, orgMembership, resolvedIdentity, identityMembership, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, delegatedReadRecord, subjectShredReceipt, connectorDispatchKind, callsOfManifestJson, outboundOfManifestJson, substratError, redrainEventsInput, peerCoverage, peerGrantsEntry, peerSwitch, peerSwitchOutcome, verticalCaller, verticalResolution, verticalSlug, } from '@substrat-run/contracts';
 import { normalizeHostname, toRouteTarget } from './route-resolver.js';
-import { attachmentBlobKey, entitlementDenial, foldMeterReading, parseValidationRecords, resolveScopeRecord, ulid, capabilityTokenHash, checkBecomeInput, plausibleSessionToken, foldModelUsage, backoffAt, resolveRetryPolicy, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, openSealed, ImpersonationRefused, assertSessionUsable, impersonationRowValues, mapImpersonationRow, newImpersonationSession, jobRunOf, runDueJobRuns, startJobRun, globalFetch, assertRedrainWindow, platformRequestOf, undrainedEventsOf, systemSwitchedOffMessage, CrossVerticalRegistry, collectPeers, peerSeats, connectorCallRecord, noopConnectorCallRecorder, recordConnectorCall, settleConnectionUse, } from '@substrat-run/kernel';
+import { attachmentBlobKey, entitlementDenial, foldMeterReading, parseValidationRecords, resolveScopeRecord, ulid, capabilityTokenHash, checkBecomeInput, plausibleSessionToken, foldModelUsage, backoffAt, resolveRetryPolicy, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, openSealed, ImpersonationRefused, assertSessionUsable, impersonationRowValues, mapImpersonationRow, newImpersonationSession, jobRunOf, runDueJobRuns, startJobRun, globalFetch, assertRedrainWindow, platformRequestOf, undrainedEventsOf, withRecorded, systemSwitchedOffMessage, CrossVerticalRegistry, importCursorSourceOf, exportBreaksOf, exportBreakRefusal, collectPeers, peerSeats, connectorCallRecord, noopConnectorCallRecorder, recordConnectorCall, settleConnectionUse, } from '@substrat-run/kernel';
 import { isOrangeToOrange, isUpgradeRequest, LIVE_MODE_HEADER, LIVE_PRINCIPAL_HEADER, LIVE_SCOPE_HEADER, LIVE_SUBSCRIBE_PATH, LIVE_TENANT_HEADER, } from './live-reads.js';
 import { tenantStoreDatabaseName } from './d1.js';
 import { blobStoreBucketName, r2TenantBlobStore } from './r2.js';
@@ -31,7 +31,7 @@ function unwrapCapabilityReply(reply) {
 /**
  * A control-plane stand-in for a CP-less vertical (scope-local-permissions.md Phase 3).
  * The hot path a served scope actually touches becomes trust-the-upstream:
- *   - `validateScopeAccess` / `setMigrationState` → no-op: the router already gated the
+ *   - `scopeAccessRefusal` / `setMigrationState` → no-op: the router already gated the
  *     scope's lifecycle + tenancy from the shared directory, so the vertical trusts the
  *     asserted node rather than re-reading a directory it does not have.
  *   - `tenantHoldsEntitlement` → true: the SKU was enforced on the shared control plane
@@ -43,11 +43,20 @@ function unwrapCapabilityReply(reply) {
 function nullControlPlane() {
     const noop = async () => undefined;
     const passthrough = {
-        validateScopeAccess: noop,
+        scopeAccessRefusal: noop,
         setMigrationState: noop,
         recordAdmin: noop,
         recordAccess: noop,
         tenantHoldsEntitlement: async () => true,
+        // #1674: the schedule switch's record is a DIRECTORY store, and a CP-less host has no
+        // directory — the shared control plane that delegates here keeps it. Same posture as
+        // `recordAdmin`: nothing to write, nothing recorded to read back.
+        recordSystemSwitchedOff: noop,
+        recordSystemSwitchedOn: async () => null,
+        restoreSystemSwitchRecord: noop,
+        listSystemSwitches: async () => [],
+        systemSwitchRecordsOf: async () => [],
+        switchedOffModulesOf: async () => [],
     };
     return new Proxy({}, {
         get: (_t, prop) => typeof prop === 'string' && prop in passthrough
@@ -124,6 +133,8 @@ export class CloudflareScopeHost {
     systemSwitchDelegation;
     /** #1706: the peer kill switch's reach into the deployment serving a scope. */
     peerSwitchDelegation;
+    /** #1705 PR 3: the replay lever's reach into the deployment serving a consumer scope. */
+    importCursorDelegation;
     /**
      * MUST be constructed per request. Never cache an instance across requests.
      *
@@ -152,6 +163,7 @@ export class CloudflareScopeHost {
         this.eventDrainDelegation = options.eventDrainDelegation;
         this.systemSwitchDelegation = options.systemSwitchDelegation;
         this.peerSwitchDelegation = options.peerSwitchDelegation;
+        this.importCursorDelegation = options.importCursorDelegation;
         this.admin = this.buildAdmin();
     }
     // -- registration mechanics (validation only) -----------------------------
@@ -341,7 +353,7 @@ export class CloudflareScopeHost {
     async drainDue(tenantId, scopeId) {
         // Same lifecycle gate `getScope` applies (K-3): a suspended or archived scope
         // does not get its effects driven either.
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         // #1525: null, and honestly so — a sweep is not a call. An attempt this pass makes
         // records no invocation, which is what distinguishes it from the first attempt the
@@ -380,14 +392,14 @@ export class CloudflareScopeHost {
         };
     }
     async startJobRun(tenantId, scopeId, input) {
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         return jobRunOf(await startJobRun(this.jobStore(scopeId), input, ulid, () => new Date().toISOString()));
     }
     async runDueJobs(tenantId, scopeId, options) {
         // Same lifecycle gate as `drainDue`: a suspended scope's runs wait rather than
         // advance, and an archived one's never move again.
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         return runDueJobRuns({
             store: this.jobStore(scopeId),
@@ -399,7 +411,7 @@ export class CloudflareScopeHost {
         });
     }
     async jobRuns(tenantId, scopeId, filter) {
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         return (await this.jobStore(scopeId).list(filter ?? {})).map(jobRunOf);
     }
@@ -409,7 +421,7 @@ export class CloudflareScopeHost {
         // same context build as the in-process path, so the handler cannot tell which host
         // ran it. On a CP-less host `connectorContext` throws from the null control plane:
         // fail closed, exactly the hole routing exists to avoid.
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         this.causedBy = event.id;
         try {
             await handler(await this.connectorContext(tenantId, scopeId, options?.timeoutMs ?? 30_000, event.id), event);
@@ -419,7 +431,7 @@ export class CloudflareScopeHost {
         }
     }
     async executorDeadLetters(tenantId, scopeId) {
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         return this.scopeStub(scopeId).executorDeadLetters();
     }
@@ -432,18 +444,18 @@ export class CloudflareScopeHost {
         return this.scopeStub(scopeId).enqueueSweepRuns(JSON.stringify(sweepRunsPayload.parse(payload)), JSON.stringify({ system: 'scope-sweeper' }));
     }
     async listPlatformRequests(tenantId, scopeId) {
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         // Tolerant (#1588): one undecodable row comes back naming why, never throws for the list.
         return (await this.scopeStub(scopeId).pendingPlatformRequests()).map(platformRequestOf);
     }
     async listPlatformRequestHistory(tenantId, scopeId, filter) {
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         return (await this.scopeStub(scopeId).platformRequestHistory(filter)).map(platformRequestOf);
     }
     async settlePlatformRequest(tenantId, scopeId, id, outcome) {
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         await this.scopeStub(scopeId).settlePlatformRequest(id, outcome.status, outcome.result === undefined ? null : JSON.stringify(outcome.result), outcome.lastError ?? null, outcome.failure == null ? null : JSON.stringify(outcome.failure));
     }
@@ -473,7 +485,7 @@ export class CloudflareScopeHost {
         const rec = await this.cp.getScopeRecord(tenantId, scopeId);
         // K-3: a scope under another tenant is indistinguishable from one that does not exist.
         if (!rec)
-            throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
+            throw substratError('not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         if (rec.status !== 'active' && rec.status !== 'provisioning') {
             throw new Error(`scope not migratable (status: ${rec.status}): ${scopeId}`);
         }
@@ -783,6 +795,13 @@ export class CloudflareScopeHost {
         for (const seat of peerSeats(collectPeers(this.peerSources), input.scopeId)) {
             await this.scopeStub(input.scopeId).seatTuple(seat.subject, seat.relation, seat.object, null);
         }
+        // #1674: re-assert the recorded OFF positions after the seat (`system-switch-record.ts`).
+        // Only where this seat landed in the scope's real store — a CP-less host, or a scope
+        // bound to no vertical. A scope a vertical's deployment serves is seated there, later,
+        // and re-asserted after that deployment's reconcile instead.
+        if (this.cpLess || record.vertical === null) {
+            await this.admin.reassertSystemSwitches(actor, { tenantId: input.tenantId, scopeId: input.scopeId });
+        }
         // Audit a real provision only; an idempotent re-provision changed nothing.
         if (created) {
             await this.recordAdmin(actor, 'provisionScope', { tenantId: input.tenantId, scopeId: input.scopeId, vertical: record.vertical }, null, record);
@@ -918,7 +937,7 @@ export class CloudflareScopeHost {
         // gates and metadata facts live in the ScopeDO (per-scope serialization, spine event
         // in the same transaction); bytes go straight to the per-tenant R2 bucket through the
         // binding the vertical's worker resolved — never through the DO.
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         const store = await this.resolveAttachmentStore(tenantId);
         return this.buildAttachmentSurface({ principal }, tenantId, scopeId, store);
@@ -934,12 +953,12 @@ export class CloudflareScopeHost {
             throw new Error(`connection ${connectionId} is revoked`);
         const scope = await this.cp.getScopeRecord(conn.tenant_id, scopeId);
         if (!scope)
-            throw new Error(`unknown scope for connection: ${scopeId}`);
+            throw substratError('not_found', `unknown scope for connection: ${scopeId}`);
         if (scope.vertical !== conn.vertical) {
             throw new Error(`connection ${connectionId} is for vertical '${conn.vertical}' and scope ${scopeId} ` +
                 `runs '${scope.vertical ?? 'none'}'`);
         }
-        await this.cp.validateScopeAccess(conn.tenant_id, scopeId);
+        await this.validateScopeAccess(conn.tenant_id, scopeId);
         // #574: same delegation as getConnectorScope. `upload` is the verb the reconcile
         // path needs (landing the sealed PDF) and `open` the one the outbound path needs
         // (sending the vertical's own document, #711). `list` and `remove` still fail
@@ -1100,14 +1119,14 @@ export class CloudflareScopeHost {
         // Restore never creates a scope (that is importScope) — an unknown target fails closed.
         const existing = await this.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!existing)
-            throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+            throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
         await this.scopeStub(scopeId).importDump(dump.tables, scopeId);
         await this.recordAdmin(actor, 'restoreScope', { tenantId, scopeId }, null, { sourceScopeId: dump.scopeId, tables: dump.tables.length, capturedAt: dump.capturedAt });
     }
     async snapshotScope(actor, tenantId, scopeId, opts) {
         const source = await this.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!source)
-            throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+            throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
         const dump = await this.admin.exportScope(actor, tenantId, scopeId);
         const snapshotId = ulid();
         await this.importScope(actor, {
@@ -1132,7 +1151,7 @@ export class CloudflareScopeHost {
         // #509 ask (b)). A PRIMARY scope keeps the platform's tombstone-only rule (archive it).
         const rec = await this.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!rec)
-            throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+            throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
         if (!rec.forkedFrom && rec.kind !== 'preview') {
             throw new Error(`scope ${scopeId} is not a fork or preview — only previews may be deleted; ` +
                 `archive a primary scope instead`);
@@ -1188,7 +1207,7 @@ export class CloudflareScopeHost {
     async getScope(principal, tenantId, scopeId, options) {
         // Lifecycle gates (control-plane.md §4.1/§4.2), the K-3 fail-closed path,
         // evaluated durably in the ControlPlaneDO. A throw propagates here.
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         return this.buildStub(tenantId, scopeId, principal, undefined, undefined, options);
     }
@@ -1211,12 +1230,12 @@ export class CloudflareScopeHost {
             throw new Error(`connection ${connectionId} is revoked`);
         const scope = await this.cp.getScopeRecord(conn.tenant_id, scopeId);
         if (!scope)
-            throw new Error(`unknown scope for connection: ${scopeId}`);
+            throw substratError('not_found', `unknown scope for connection: ${scopeId}`);
         if (scope.vertical !== conn.vertical) {
             throw new Error(`connection ${connectionId} is for vertical '${conn.vertical}' and scope ${scopeId} ` +
                 `runs '${scope.vertical ?? 'none'}'`);
         }
-        await this.cp.validateScopeAccess(conn.tenant_id, scopeId);
+        await this.validateScopeAccess(conn.tenant_id, scopeId);
         // #574: a scope served by ANOTHER deployment (the shared control plane running the
         // connector pass for a dispatch vertical) — the write-back rides the delegation
         // seam; migration is the serving deployment's business, exactly like provision.
@@ -1263,7 +1282,7 @@ export class CloudflareScopeHost {
         const record = await this.resolveImpersonation(session, tenantId, scopeId);
         // The same lifecycle gate the principal door applies: a suspended tenant
         // refuses a support session exactly as it refuses a user.
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         return this.buildStub(tenantId, scopeId, record.principal, undefined, undefined, options, record.id);
     }
@@ -1277,7 +1296,7 @@ export class CloudflareScopeHost {
         if (!this.moduleIds.has(moduleId)) {
             throw new Error(`module not registered on this host: ${moduleId}`);
         }
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         return this.buildStub(tenantId, scopeId, undefined, undefined, moduleId);
     }
@@ -1310,7 +1329,7 @@ export class CloudflareScopeHost {
      * capability row lives. The answer is re-parsed on this side of the RPC.
      */
     async exchangeCapability(tenantId, scopeId, secret, options) {
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         const outcome = await this.scopeStub(scopeId).exchangeCapability(secret, tenantId, scopeId, options?.mode);
         return capabilityExchange.nullable().parse(outcome);
@@ -1324,7 +1343,7 @@ export class CloudflareScopeHost {
         if (!plausibleSessionToken(sessionToken)) {
             throw substratError('unauthenticated', 'not a capability session token');
         }
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         const hash = await capabilityTokenHash(sessionToken);
         return this.buildStub(tenantId, scopeId, undefined, undefined, undefined, options, undefined, hash);
@@ -1370,7 +1389,7 @@ export class CloudflareScopeHost {
             }
             this.assertServedHere(record, scopeId, verb);
         }
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
     }
     /**
@@ -1383,7 +1402,7 @@ export class CloudflareScopeHost {
         if (!plausibleSessionToken(sessionToken)) {
             throw substratError('unauthenticated', 'not a capability session token');
         }
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         const store = await this.resolveAttachmentStore(tenantId);
         const capabilitySession = await capabilityTokenHash(sessionToken);
@@ -1407,13 +1426,21 @@ export class CloudflareScopeHost {
      * and by the verbs that read a record of their own, so a caller never meets two of them.
      */
     assertServedHere(record, scopeId, verb) {
-        if (this.servesScopesElsewhere && record.vertical !== null) {
+        if (this.servesScopesElsewhereNow && record.vertical !== null) {
             throw substratError('unavailable', `${verb} cannot reach scope ${scopeId}: it is served by the '${record.vertical}' deployment, ` +
                 'which a peer reaches through the platform, not through the shared control plane');
         }
     }
-    get servesScopesElsewhere() {
-        return Boolean(this.connectorDelegation || this.systemSwitchDelegation || this.peerSwitchDelegation || this.eventDrainDelegation);
+    /** `ScopeHost.servesScopesElsewhere` (#1705 PR 3): any delegation set means the shared control plane. */
+    servesScopesElsewhere() {
+        return this.servesScopesElsewhereNow;
+    }
+    get servesScopesElsewhereNow() {
+        return Boolean(this.connectorDelegation ||
+            this.systemSwitchDelegation ||
+            this.peerSwitchDelegation ||
+            this.eventDrainDelegation ||
+            this.importCursorDelegation);
     }
     /**
      * Where a platform capability verb (#1672) may write: this host's own ScopeDO — refused,
@@ -1427,7 +1454,7 @@ export class CloudflareScopeHost {
         const rec = await this.cp.getScopeRecord(tenantId, scopeId);
         if (!rec)
             throw substratError('not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
-        if (this.servesScopesElsewhere && rec.vertical !== null) {
+        if (this.servesScopesElsewhereNow && rec.vertical !== null) {
             throw substratError('unavailable', `${verb} cannot reach scope ${scopeId}: it is served by the '${rec.vertical}' ` +
                 'deployment, and platform capability verbs are not delegated there yet');
         }
@@ -1696,6 +1723,8 @@ export class CloudflareScopeHost {
                 const enqueued = envelope.platformRequests + (drained.routedToPlatform ?? 0);
                 if (enqueued > 0)
                     options?.onPlatformRequests?.(enqueued);
+                if ((envelope.exported ?? 0) > 0)
+                    options?.onExportedEvents?.(envelope.exported);
                 if (envelope.concurrency)
                     invokeOptions?.onEntityVersion?.(envelope.concurrency.version);
                 if (envelope.idempotency?.replayed)
@@ -1744,7 +1773,22 @@ export class CloudflareScopeHost {
             ...(r.serving_version_id ? { servingVersionId: r.serving_version_id } : {}),
             createdAt: r.created_at,
         });
-        const mapVersion = (r) => verticalVersion.parse({
+        // A listed version carries its surfaces as lifted JSON text, not its manifest (#1677):
+        // read on exactly `outboundOfManifestJson`'s terms, so the two reads agree.
+        const stringListOfJson = (json) => {
+            if (!json)
+                return null;
+            try {
+                const v = JSON.parse(json);
+                return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        const mapVersion = (r) => versionRecord(r, outboundOfManifestJson(r.manifest_json), callsOfManifestJson(r.manifest_json));
+        const mapListedVersion = (r) => versionRecord(r, stringListOfJson(r.outbound_json), stringListOfJson(r.calls_json));
+        const versionRecord = (r, outbound, calls) => verticalVersion.parse({
             id: r.id,
             verticalSlug: r.vertical_slug,
             version: r.version,
@@ -1755,8 +1799,8 @@ export class CloudflareScopeHost {
             admission: r.admission,
             admissionNote: r.admission_note,
             origin: r.origin_json ? JSON.parse(r.origin_json) : null,
-            outbound: outboundOfManifestJson(r.manifest_json),
-            calls: callsOfManifestJson(r.manifest_json),
+            outbound,
+            calls,
             createdAt: r.created_at,
         });
         const mapOrg = (r) => orgSchema.parse({
@@ -1812,7 +1856,13 @@ export class CloudflareScopeHost {
         // reap's `backupRef` (#493) is the first. Kept out of `before` deliberately: it
         // describes what the transition DID, not the state it left.
         afterExtra) => {
-            const before = await this.cp.transitionScope(tenantId, scopeId, from, to, action);
+            // The DO answers a refusal as data (#1718): a throw from there would arrive here
+            // flattened, its code gone. The pair check stays in the DO, in the same read as the
+            // write, so a row deleted concurrently is still refused `not_found`.
+            const before = await this.cp.transitionScopeOrRefusal(tenantId, scopeId, from, to, action);
+            if (!before.ok) {
+                throw before.code ? substratError(before.code, before.message) : new Error(before.message);
+            }
             // The audit target carries the scope's vertical (control-plane.md §4.4:
             // "vertical stays null until §4.2 lifecycle actions that name one"). The DO
             // returns it with the previous status, so the trail cannot disagree with
@@ -1869,7 +1919,7 @@ export class CloudflareScopeHost {
             if (delegation) {
                 // The gate's lifecycle half still runs (a suspended tenant or scope cannot be
                 // switched); its `scopeStub` half is what the delegation replaces.
-                await this.cp.validateScopeAccess(tenantId, scopeId);
+                await this.validateScopeAccess(tenantId, scopeId);
             }
             else {
                 await this.peerScopeGate(tenantId, scopeId, action);
@@ -1910,9 +1960,15 @@ export class CloudflareScopeHost {
                 permissions: outcome.permissions,
             };
         };
-        const switchSystem = async (actor, raw, to) => {
-            const input = systemSwitch.parse(raw);
-            const { tenantId, scopeId } = input.node;
+        /**
+         * Where one scope's schedule switch lands — the ONE rule `switchSystem` and the #1674
+         * re-assert share, so a re-assert moves exactly the switch an operator's OFF would have.
+         * A scope bound to no vertical (#1666 review) has no deployment to delegate to: its store
+         * is the DO here, so the switch moves (or answers `held: false`) here too. Delegating it
+         * would throw "no deployment serving scope" instead. A scope WITH a vertical still
+         * delegates, and still fails loudly when none serves it.
+         */
+        const systemSwitchTarget = async (tenantId, scopeId) => {
             let vertical = null;
             if (!this.cpLess) {
                 const rec = await this.cp.getScopeRecord(tenantId, scopeId);
@@ -1920,6 +1976,16 @@ export class CloudflareScopeHost {
                     throw substratError('not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
                 vertical = rec.vertical;
             }
+            const delegation = this.cpLess || vertical !== null ? this.systemSwitchDelegation : undefined;
+            const move = (moduleId, to, at) => delegation
+                ? delegation.switch({ tenantId, scopeId, moduleId, to })
+                : this.scopeStub(scopeId).switchSystemSchedules(moduleId, scopeId, to, at);
+            return { vertical, move };
+        };
+        const switchSystem = async (actor, raw, to) => {
+            const input = systemSwitch.parse(raw);
+            const { tenantId, scopeId } = input.node;
+            const { vertical, move } = await systemSwitchTarget(tenantId, scopeId);
             // AUDIT FIRST (#1666 review): the intent row lands before anything moves, and the
             // outcome row after — every attempt, a repeat included. The scope's store and the
             // admin log are separate, so no order makes the pair atomic; this one fails toward
@@ -1930,36 +1996,84 @@ export class CloudflareScopeHost {
             const target = { tenantId, scopeId, vertical };
             const base = { operationId, moduleId: input.moduleId, schedules: to };
             await this.recordAdmin(actor, action, target, null, { ...base, phase: 'intent', reason: input.reason });
-            // A scope bound to no vertical (#1666 review) has no deployment to delegate to: its
-            // store is the DO here, so the switch moves (or answers `held: false`) here too.
-            // Delegating it would throw "no deployment serving scope" instead. A scope WITH a
-            // vertical still delegates, and still fails loudly when none serves it.
-            const delegation = this.cpLess || vertical !== null ? this.systemSwitchDelegation : undefined;
+            // The directory's record (#1674): ON before the scope moves, OFF after it held — see
+            // `recordSystemSwitchedOn` for why that order is the safe one.
+            const at = new Date().toISOString();
+            const record = { tenantId, scopeId, moduleId: input.moduleId, actor, reason: input.reason, operationId, at };
+            const errorOf = (err) => (err instanceof Error ? err.message : String(err));
+            let prior = null;
+            if (to === 'on') {
+                try {
+                    prior = await this.cp.recordSystemSwitchedOn(record);
+                }
+                catch (err) {
+                    // Nothing has moved: fail the call here, audited, rather than switch a scope on
+                    // whose record still says off (the next reconcile would switch it back off).
+                    await this.recordAdmin(actor, action, target, null, { ...base, phase: 'failed', error: errorOf(err) }).catch(() => undefined);
+                    throw err;
+                }
+            }
+            /**
+             * A record write AFTER the scope moved (review #5): retried once, and a failure of both
+             * is answered rather than swallowed — it lands on the outcome row as `recordError`, and
+             * the call does not report plain success. A lost OFF record is exactly what a wipe then
+             * turns into a module running again.
+             */
+            const recordWrite = async (write) => {
+                try {
+                    await write();
+                    return null;
+                }
+                catch {
+                    try {
+                        await write();
+                        return null;
+                    }
+                    catch (err) {
+                        return errorOf(err);
+                    }
+                }
+            };
             let outcome;
             try {
-                outcome = delegation
-                    ? await delegation.switch({ tenantId, scopeId, moduleId: input.moduleId, to })
-                    : await this.scopeStub(scopeId).switchSystemSchedules(input.moduleId, scopeId, to, new Date().toISOString());
+                outcome = await move(input.moduleId, to, at);
             }
             catch (err) {
+                const recordError = prior ? await recordWrite(() => this.cp.restoreSystemSwitchRecord(record, prior)) : null;
                 // Best effort: the original error is what the caller must see, and the intent row
                 // already says an attempt was made.
                 await this.recordAdmin(actor, action, target, null, {
                     ...base,
                     phase: 'failed',
-                    error: err instanceof Error ? err.message : String(err),
+                    error: errorOf(err),
+                    ...(recordError ? { recordError } : {}),
                 }).catch(() => undefined);
                 throw err;
             }
+            // OFF is recorded once the scope held it. A refused ON moved nothing, so its record
+            // write is undone: left `on`, the next reconcile of a wiped scope would leave the
+            // module running.
+            const recordError = to === 'off' && outcome.held
+                ? await recordWrite(() => this.cp.recordSystemSwitchedOff(record))
+                : to === 'on' && !outcome.held && prior
+                    ? await recordWrite(() => this.cp.restoreSystemSwitchRecord(record, prior))
+                    : null;
             await this.recordAdmin(actor, action, target, null, {
                 ...base,
                 phase: outcome.held ? 'applied' : 'refused',
                 changed: outcome.changed,
                 permissions: outcome.permissions,
+                ...(recordError ? { recordError } : {}),
             });
             if (!outcome.held) {
                 throw substratError('not_found', `scope ${scopeId} holds no system grant for module '${input.moduleId}' — nothing to switch ${to} ` +
-                    `(check the module id: it is the module's manifest id, e.g. '@substrat-run/engine-absence')`);
+                    `(check the module id: it is the module's manifest id, e.g. '@substrat-run/engine-absence')` +
+                    (recordError ? `; and its directory record could not be put back (${recordError})` : ''));
+            }
+            if (recordError) {
+                throw substratError('unavailable', `module '${input.moduleId}' is switched ${to} on scope ${scopeId}, but the directory's record of it ` +
+                    `could not be written (${recordError}) — repeat the call to record it; a wipe of this scope would ` +
+                    `otherwise lose the switch`);
             }
             return {
                 operationId,
@@ -2036,23 +2150,65 @@ export class CloudflareScopeHost {
                 throw substratError('unavailable', `no delegation configured for hosted scope ${scopeId} (vertical '${vertical}') — cannot read its schedule switches`);
             }
             const delegation = this.cpLess || vertical !== null ? this.systemSwitchDelegation : undefined;
-            const states = delegation
-                ? await delegation.status({ tenantId, scopeId })
-                : systemScheduleEntry.array().parse(await this.scopeStub(scopeId).systemGrantsStatus());
+            // The scope's own position and the directory's record are independent reads.
+            const [states, recordedRows] = await Promise.all([
+                delegation
+                    ? delegation.status({ tenantId, scopeId })
+                    : this.scopeStub(scopeId).systemGrantsStatus().then((rows) => systemScheduleEntry.array().parse(rows)),
+                this.cp.systemSwitchRecordsOf(tenantId, scopeId),
+            ]);
             const offModules = new Set(states.filter((s) => s.schedules === 'off').map((s) => s.moduleId));
             const explanations = offModules.size > 0
                 ? await lastSwitchedOff(tenantId, scopeId, offModules)
                 : new Map();
-            const result = states.map((s) => ({
+            const result = withRecorded(states, new Map(recordedRows)).map((s) => ({
                 moduleId: s.moduleId,
                 schedules: s.schedules,
                 switchedOff: explanations.get(s.moduleId) ?? null,
+                recorded: s.recorded,
             }));
             // K-24: reading the switch's position and any live incident reason is itself
             // access-logged, the same as every other HostAdmin read.
             await this.recordAccess(actor, 'systemGrantsStatus', { tenantId, scopeId }, null, result.length);
             return result;
         };
+        /**
+         * #1674: put the directory's OFF positions back into one scope — see
+         * `HostAdmin.reassertSystemSwitches`. It moves the switch through `systemSwitchTarget`,
+         * so it lands wherever an operator's OFF would have — for a hosted scope, over the
+         * `/internal/system-switch` route every deployment since #1666 answers.
+         */
+        const reassertSystemSwitchesOf = async (actor, node) => {
+            const { tenantId, scopeId } = node;
+            const { vertical, move } = await systemSwitchTarget(tenantId, scopeId);
+            const modules = await this.cp.switchedOffModulesOf(tenantId, scopeId);
+            // A hosted scope with no delegation configured (Copilot review): this host's own
+            // namespace is the module-less placeholder, where the switch would answer `held: false`
+            // quietly — a re-assert reported done, and a receipt written, while the deployment
+            // serving the scope keeps its schedules running. Refused loudly instead, as the status
+            // read is, and only when a re-assert is owed: nothing recorded, nothing to refuse.
+            if (modules.length > 0 && !this.cpLess && vertical !== null && !this.systemSwitchDelegation) {
+                throw substratError('unavailable', `no delegation configured for hosted scope ${scopeId} (vertical '${vertical}') — cannot re-assert ` +
+                    `its switched-off schedules in the deployment serving it`);
+            }
+            const at = new Date().toISOString();
+            const results = [];
+            for (const moduleId of modules) {
+                const outcome = await move(moduleId, 'off', at);
+                if (outcome.changed) {
+                    await this.recordAdmin(actor, 'reassertSystemSwitch', { tenantId, scopeId, vertical }, null, {
+                        operationId: ulid(),
+                        moduleId,
+                        schedules: 'off',
+                        phase: 'applied',
+                        changed: true,
+                        permissions: outcome.permissions,
+                    });
+                }
+                results.push({ moduleId, held: outcome.held, changed: outcome.changed });
+            }
+            return results;
+        };
         /**
          * The peer switch's status read (#1706) — `systemGrantsStatusOf` with the subject
          * swapped, and delegated for the same reason the write is: a hosted scope's
@@ -2179,7 +2335,7 @@ export class CloudflareScopeHost {
                 if (grant.node.scopeId) {
                     const scope = await this.cp.getScopeRecord(grant.node.tenantId, grant.node.scopeId);
                     if (!scope) {
-                        throw new Error(`unknown scope ${grant.node.scopeId} in tenant ${grant.node.tenantId}`);
+                        throw substratError('not_found', `unknown scope ${grant.node.scopeId} in tenant ${grant.node.tenantId}`);
                     }
                     if (scope.vertical !== conn.vertical) {
                         throw new Error(`connection ${grant.connectionId} is for vertical '${conn.vertical}' and scope ` +
@@ -2255,6 +2411,14 @@ export class CloudflareScopeHost {
             // #1674: the switch's status read — same gate, same delegation, and (unlike the
             // deployment it may delegate to) the admin log to explain an `off` entry.
             systemGrantsStatus: systemGrantsStatusOf,
+            // #1674: the directory's record of the switch — the fleet read, and the re-assert a
+            // scope that lost its marker gets after a wipe or a restore.
+            listSystemSwitches: async (actor, filter) => {
+                const rows = await this.cp.listSystemSwitches(filter);
+                await this.recordAccess(actor, 'listSystemSwitches', { tenantId: filter?.tenantId ?? null }, filter ?? null, rows.length);
+                return rows.map((r) => systemSwitchRecord.parse(r));
+            },
+            reassertSystemSwitches: reassertSystemSwitchesOf,
             // #1672 — the platform's two capability verbs. Audited AFTER the write, on both, and
             // the failure each leaves is the safe one: a mint whose audit row did not land never
             // returned its secret, so nobody can ever exchange it; a revoke whose row did not land
@@ -2264,7 +2428,7 @@ export class CloudflareScopeHost {
                 // a bare message, and the caller would lose `validation_failed`. One function, so the
                 // two sides cannot disagree about what a valid mint is.
                 checkBecomeInput(input, new Date().toISOString());
-                await this.cp.validateScopeAccess(tenantId, scopeId);
+                await this.validateScopeAccess(tenantId, scopeId);
                 const { stub, vertical } = await this.capabilityScopeStub(tenantId, scopeId, 'mintCapability');
                 const minted = await stub.mintBecomeCapability(input, actor);
                 await this.recordAdmin(actor, 'mintCapability', { tenantId, scopeId, vertical }, null, {
@@ -2303,7 +2467,7 @@ export class CloudflareScopeHost {
                 const parsed = bindHostnameInput.parse(input);
                 const scope = await this.cp.getScopeRecord(parsed.tenantId, parsed.scopeId);
                 if (!scope) {
-                    throw new Error(`unknown scope ${parsed.scopeId} in tenant ${parsed.tenantId}`);
+                    throw substratError('not_found', `unknown scope ${parsed.scopeId} in tenant ${parsed.tenantId}`);
                 }
                 const existing = await this.cp.readHostname(parsed.hostname);
                 // The holder's own status decides whether the name is reclaimable. Read it from
@@ -2477,7 +2641,7 @@ export class CloudflareScopeHost {
             listVersions: async (actor, verticalSlug, page) => {
                 const rows = await this.cp.listVersions(verticalSlug, page);
                 await this.recordAccess(actor, 'listVersions', {}, { verticalSlug }, rows.length);
-                return rows.map(mapVersion);
+                return rows.map(mapListedVersion);
             },
             getVersion: async (actor, versionId, verticalSlug) => {
                 const row = await this.cp.readVersion(versionId);
@@ -2571,6 +2735,19 @@ export class CloudflareScopeHost {
                 await this.cp.setAdmission(versionId, 'admitted', null);
                 await this.recordAdmin(actor, 'admitVersion', { tenantId: null }, { admission: v.admission }, { admission: 'admitted' });
             },
+            promotionImpact: async (actor, verticalSlug, channel, versionId) => {
+                const incoming = await this.cp.readVersion(versionId);
+                if (!incoming || incoming.vertical_slug !== verticalSlug) {
+                    throw substratError('not_found', `unknown version ${versionId} for vertical '${verticalSlug}'`);
+                }
+                const current = await this.cp.readChannel(verticalSlug, channel);
+                const outgoing = current ? await this.cp.readVersion(current.version_id) : undefined;
+                const breaks = outgoing
+                    ? await this.exportBreaksBetween(actor, verticalSlug, outgoing.manifest_json, incoming.manifest_json)
+                    : [];
+                await this.recordAccess(actor, 'promotionImpact', { tenantId: null }, { verticalSlug, channel, versionId }, breaks.length);
+                return breaks;
+            },
             rejectVersion: async (actor, versionId, note) => {
                 const v = await this.cp.readVersion(versionId);
                 if (!v)
@@ -2607,6 +2784,12 @@ export class CloudflareScopeHost {
                         throw new Error(`promotion changes migrations (${outgoing.migration_digest} → ` +
                             `${incoming.migration_digest}) — acknowledge it explicitly to promote`);
                     }
+                    // #1705 PR 3: an export an installed consumer imports, dropped or re-versioned.
+                    if (!ack.exportBreak) {
+                        const breaks = await this.exportBreaksBetween(actor, verticalSlug, outgoing.manifest_json, incoming.manifest_json);
+                        if (breaks.length > 0)
+                            throw substratError('precondition_failed', exportBreakRefusal(breaks));
+                    }
                 }
                 const promotedAt = new Date().toISOString();
                 await this.cp.setChannel(verticalSlug, channel, versionId, promotedAt);
@@ -2626,8 +2809,8 @@ export class CloudflareScopeHost {
                 // promote) is a complete deploy and a rollback promote reaches the running
                 // app. D-30's lockstep concern is a SHARED vertical's many tenants, which a
                 // private vertical cannot have — this fires for no one else. Snapshots and
-                // forks (forked_from set) keep their frontier untouched, and a rebind that
-                // crosses a migration digest snapshots first (fork-before-promote, §4).
+                // forks (forked_from set) and all previews keep their frontier untouched. A rebind
+                // that crosses a migration digest snapshots first (fork-before-promote, §4).
                 //
                 // EXCEPTION (#321): a DISPATCH-BACKED vertical (its version has a
                 // `deployment_ref`) serves in place off a stable script. Rebinding a legacy
@@ -2642,7 +2825,7 @@ export class CloudflareScopeHost {
                 if (channel === 'prod' && !incoming.deployment_ref) {
                     const owning = await this.cp.readVertical(verticalSlug);
                     if (owning && owning.owner_tenant !== null && !owning.listed) {
-                        const bound = (await this.cp.listScopes({ tenantId: owning.owner_tenant, vertical: verticalSlug, status: ['active'] })).filter((s) => !s.forked_from);
+                        const bound = (await this.cp.listScopes({ tenantId: owning.owner_tenant, vertical: verticalSlug, status: ['active'] })).filter((s) => !s.forked_from && s.kind !== 'preview');
                         for (const s of bound) {
                             if (s.vertical_version_id === versionId)
                                 continue;
@@ -2694,7 +2877,7 @@ export class CloudflareScopeHost {
                     throw substratError('not_found', `unknown version ${versionId}`);
                 const scope = await this.cp.getScopeRecord(tenantId, scopeId);
                 if (!scope)
-                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                    throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
                 // The refusal the registry exists for — but scoped to a SERVING bind. Admission
                 // gates code reaching an install; a PREVIEW fork is the builder's own tenant's data
                 // at a non-canonical URL, serving no install, so it may run pending PR code — the
@@ -2728,7 +2911,7 @@ export class CloudflareScopeHost {
             markScopeProvisioned: async (actor, tenantId, scopeId, versionId) => {
                 const scope = await this.cp.getScopeRecord(tenantId, scopeId);
                 if (!scope)
-                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                    throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
                 await this.cp.markScopeProvisioned(scopeId, versionId);
                 await this.recordAdmin(actor, 'markScopeProvisioned', { tenantId, scopeId }, null, {
                     versionId,
@@ -2774,21 +2957,21 @@ export class CloudflareScopeHost {
             setScopeServingRef: async (actor, tenantId, scopeId, servingRef) => {
                 const scope = await this.cp.getScopeRecord(tenantId, scopeId);
                 if (!scope)
-                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                    throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
                 await this.cp.setScopeServingRef(scopeId, servingRef);
                 await this.recordAdmin(actor, 'setScopeServingRef', { tenantId, scopeId }, { servingRef: scope.serving_ref ?? null }, { servingRef });
             },
             setScopeExpiresAt: async (actor, tenantId, scopeId, expiresAt) => {
                 const scope = await this.cp.getScopeRecord(tenantId, scopeId);
                 if (!scope)
-                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                    throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
                 await this.cp.setScopeExpiresAt(scopeId, expiresAt);
                 await this.recordAdmin(actor, 'setScopeExpiresAt', { tenantId, scopeId }, { expiresAt: scope.expires_at ?? null }, { expiresAt });
             },
             scopeAppliedMigrations: async (actor, tenantId, scopeId) => {
                 const scope = await this.cp.getScopeRecord(tenantId, scopeId);
                 if (!scope)
-                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                    throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
                 const applied = await this.scopeStub(scopeId).appliedMigrations();
                 await this.recordAccess(actor, 'scopeAppliedMigrations', { tenantId, scopeId }, null, applied.length);
                 return applied;
@@ -2796,7 +2979,7 @@ export class CloudflareScopeHost {
             scopeMigrationBookmarks: async (actor, tenantId, scopeId) => {
                 const scope = await this.cp.getScopeRecord(tenantId, scopeId);
                 if (!scope)
-                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                    throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
                 const bookmarks = await this.scopeStub(scopeId).migrationBookmarks();
                 await this.recordAccess(actor, 'scopeMigrationBookmarks', { tenantId, scopeId }, null, bookmarks.length);
                 return bookmarks;
@@ -2811,7 +2994,7 @@ export class CloudflareScopeHost {
             rewindScope: async (actor, tenantId, scopeId, bookmark, opts) => {
                 const scope = await this.cp.getScopeRecord(tenantId, scopeId);
                 if (!scope)
-                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                    throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
                 // Audit FIRST: a destructive rewind that fails halfway must still be on the
                 // record — the entry names the intent; the DO's refusals name the outcome.
                 await this.recordAdmin(actor, 'rewindScope', { tenantId, scopeId }, null, {
@@ -2995,6 +3178,7 @@ export class CloudflareScopeHost {
                 await this.recordAccess(actor, 'importState', { tenantId, scopeId }, null, state.cursors.length);
                 return state;
             },
+            moveImportCursor: async (actor, tenantId, scopeId, raw) => this.moveImportCursorAt(actor, tenantId, scopeId, raw),
             readUndrainedEvents: async (actor, tenantId, scopeId, limit) => {
                 const record = await this.scopeRecordForRead(tenantId, scopeId);
                 const bounded = Math.min(Math.max(limit ?? 200, 1), 1000);
@@ -3264,7 +3448,7 @@ export class CloudflareScopeHost {
                 // no-op when the bytes lived remotely.
                 const rec = await this.cp.getScopeRecord(tenantId, scopeId);
                 if (!rec)
-                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                    throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
                 if (rec.status !== 'archived') {
                     throw new Error(`scope ${scopeId} is ${rec.status}, not archived — only an archived scope may be reaped`);
                 }
@@ -3906,9 +4090,18 @@ export class CloudflareScopeHost {
     }
     // -- helpers --------------------------------------------------------------
     /**
-     * Record a staff read (K-24). `params` is a bounded summary, capped so one query
-     * cannot write an unbounded row.
+     * The getScope gate (control-plane.md §4.1/§4.2) — the pair check, then the tenant's and
+     * the scope's lifecycle — thrown on THIS side of the RPC (#1718). The ControlPlaneDO
+     * answers its refusal as data, because an error thrown there arrives here flattened, with
+     * no code; a record crosses intact. A CP-less host's null control plane answers nothing,
+     * so the gate passes: the router already made it from the shared directory.
      */
+    async validateScopeAccess(tenantId, scopeId) {
+        const refusal = await this.cp.scopeAccessRefusal(tenantId, scopeId);
+        if (!refusal)
+            return;
+        throw refusal.code ? substratError(refusal.code, refusal.message) : new Error(refusal.message);
+    }
     /**
      * K-3's cross-check on its own: the (tenant, scope) pair must exist and agree before a
      * subject-key operation touches anything. Without it a caller could reach another
@@ -3917,7 +4110,7 @@ export class CloudflareScopeHost {
     async assertScope(tenantId, scopeId) {
         const rec = await this.cp.getScopeRecord(tenantId, scopeId);
         if (!rec)
-            throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
+            throw substratError('not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
     }
     /**
      * The same K-3 cross-check, for a read that then opens the scope's STORAGE — every
@@ -3932,7 +4125,7 @@ export class CloudflareScopeHost {
     async scopeRecordForRead(tenantId, scopeId) {
         const row = await this.cp.getScopeRecord(tenantId, scopeId);
         if (!row)
-            throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
+            throw substratError('not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         if (row.status === 'reaped') {
             throw new Error(`scope ${scopeId} is reaped — its storage is gone and cannot be read`);
         }
@@ -3950,6 +4143,10 @@ export class CloudflareScopeHost {
             tombstone: (subjectId, at) => this.cp.tombstoneSubjectKey({ scopeId, subjectId, tenantId, at }),
         });
     }
+    /**
+     * Record a staff read (K-24). `params` is a bounded summary, capped so one query
+     * cannot write an unbounded row.
+     */
     async recordAccess(actor, method, target, params, resultCount) {
         await this.cp.recordAccess({
             id: ulid(),
@@ -3985,7 +4182,7 @@ export class CloudflareScopeHost {
      * directory's view stays on `HostAdmin.listConnectionGrants`.
      */
     async connectionGrantsInScope(tenantId, scopeId) {
-        await this.cp.validateScopeAccess(tenantId, scopeId);
+        await this.validateScopeAccess(tenantId, scopeId);
         await this.migrateAndRecord(scopeId);
         const now = new Date().toISOString();
         // Both stores again, but the CF split is not the pure adapter's. The DO holds the
@@ -4161,7 +4358,7 @@ export class CloudflareScopeHost {
              * count to the directory — so a scope whose first contact after a deploy is a
              * subscription does not go dark in the migration fleet view.
              */
-            await this.cp.validateScopeAccess(tenantId, scopeId);
+            await this.validateScopeAccess(tenantId, scopeId);
             await this.migrateAndRecord(scopeId);
             // Asserted, not carried through from the client: the principal is the
             // vertical's own resolution of its session, and the tenant and scope are the
@@ -4576,6 +4773,164 @@ export class CloudflareScopeHost {
     async peerSwitchLocal(scopeId, vertical, to) {
         return peerSwitchOutcome.parse(await this.scopeStub(scopeId).switchPeer(verticalSlug.parse(vertical), scopeId, to, new Date().toISOString()));
     }
+    // -- the cross-vertical far ends (#1705 PR 2) --------------------------------
+    // The shared control plane runs the cross-vertical phase for every hosted edge and reaches the
+    // scopes over `/internal/exported-events`, `/internal/import-state` and `/internal/import-events`,
+    // which land here. The platform resolved the pair and the tenant; what runs HERE is what only
+    // this deployment can decide: what its own code exports and to whom, and what its own code
+    // imports and runs. Each verb first proves the scope is one this deployment serves
+    // (`assertServesLocally`), because a CP-less host has no directory and an unprovisioned DO
+    // answers every read with a plausible empty result.
+    /** The producer's release after a watermark (#1705), for a scope served HERE. */
+    async exportedEventsLocal(tenantId, scopeId, raw) {
+        const input = exportReadInput.parse(raw);
+        await this.assertServesLocally(tenantId, scopeId, 'readExportedEvents');
+        return exportedBatch.parse(await this.scopeStub(scopeId).exportedEventsRead(input, tenantId, scopeId));
+    }
+    /**
+     * The consumer's imports and watermarks (#1705), for a scope served HERE. The served-here
+     * check comes FIRST, before the "this deployment imports nothing" answer. That answer is a
+     * fact about this code, but given for a scope this deployment does not serve, it would tell the
+     * platform the scope imports nothing, when the truth is that the platform asked the wrong
+     * deployment. The platform reads the former as a disagreement with its registry, and must
+     * hear the latter as a refusal.
+     */
+    async importStateLocal(tenantId, scopeId) {
+        await this.assertServesLocally(tenantId, scopeId, 'importState');
+        if (this.crossVertical.consumes().length === 0)
+            return { consumes: [], cursors: [] };
+        return importState.parse(await this.scopeStub(scopeId).importStateRead());
+    }
+    /** Apply a producer's batch (#1705) to a scope served HERE, through the peer door's gate. */
+    async importEventsLocal(tenantId, scopeId, batch) {
+        await this.assertServesLocally(tenantId, scopeId, 'deliverToPeer');
+        return this.deliverToPeer(tenantId, scopeId, batch);
+    }
+    /**
+     * The replay lever's far end (#1705 PR 3), for a consumer scope served HERE. The platform
+     * resolved the producer and wrote the intent row. What runs here is the move itself, in this
+     * deployment's own store, under the platform's `replayId`. Nothing is audited here, as for the
+     * switches: the admin rows are the platform's.
+     */
+    async importCursorLocal(tenantId, scopeId, raw) {
+        const input = importCursorMoveAt.parse(raw);
+        await this.assertServesLocally(tenantId, scopeId, 'moveImportCursor');
+        return this.moveInScope(scopeId, input);
+    }
+    /** The move in this host's own scope DO, on the real clock (host code may read it). */
+    async moveInScope(scopeId, at) {
+        return importCursorMoved.parse(await this.scopeStub(scopeId).importCursorMove({ ...at, now: Date.now() }));
+    }
+    /**
+     * `HostAdmin.moveImportCursor` (#1705 PR 3): the peer switch's shape. Resolve, audit the
+     * intent, move where the scope's storage is (the delegation for a hosted scope, this host's
+     * own DO otherwise), and audit the outcome. Every attempt leaves a row, and a failed one
+     * says why.
+     */
+    async moveImportCursorAt(actor, tenantId, scopeId, raw) {
+        const move = importCursorMove.parse(raw);
+        if (this.cpLess) {
+            throw substratError('unavailable', 'moveImportCursor needs the directory to resolve the producer — the platform moves a watermark, ' +
+                'and reaches this deployment through /internal/import-cursor');
+        }
+        const rec = await this.cp.getScopeRecord(tenantId, scopeId);
+        if (!rec)
+            throw substratError('not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
+        const source = await importCursorSourceOf((t, v) => this.admin.resolveVerticalInstance(t, v), { tenantId, scopeId, vertical: rec.vertical }, move.from);
+        // Where the write lands is the peer switch's rule: a scope bound to a vertical is served by
+        // that vertical's deployment, and its watermark lives there. Without a delegation that
+        // refusal stands (`assertServedHere`) rather than a move in the placeholder namespace.
+        const delegation = rec.vertical !== null ? this.importCursorDelegation : undefined;
+        if (!delegation)
+            this.assertServedHere(rec, scopeId, 'moveImportCursor');
+        await this.validateScopeAccess(tenantId, scopeId);
+        const replayId = ulid();
+        const target = { tenantId, scopeId, vertical: rec.vertical };
+        const base = { replayId, mode: move.mode, from: move.from, source: source.scopeId };
+        await this.recordAdmin(actor, 'moveImportCursor', target, null, { ...base, phase: 'intent', reason: move.reason });
+        const at = { move, source: source, replayId };
+        let moved;
+        try {
+            moved = delegation
+                ? importCursorMoved.parse(await delegation.move({ tenantId, scopeId, at }))
+                : await this.moveInScope(scopeId, at);
+        }
+        catch (err) {
+            await this.recordAdmin(actor, 'moveImportCursor', target, null, {
+                ...base,
+                phase: 'failed',
+                error: err instanceof Error ? err.message : String(err),
+            }).catch(() => undefined);
+            throw err;
+        }
+        await this.recordAdmin(actor, 'moveImportCursor', target, null, {
+            ...base,
+            phase: 'applied',
+            previous: moved.previous,
+            cursor: moved.cursor,
+            archived: moved.archived,
+        });
+        return moved;
+    }
+    /** #1705 PR 3: the promote gate's question, over two stored manifests (`exportBreaksOf`). */
+    exportBreaksBetween(actor, producer, outgoingManifest, incomingManifest) {
+        return exportBreaksOf({
+            admin: this.admin,
+            actor,
+            producer,
+            outgoing: exportsOfManifestJson(outgoingManifest),
+            incoming: exportsOfManifestJson(incomingManifest),
+            readImports: (slug, versionId) => this.versionImports(slug, versionId),
+        });
+    }
+    /**
+     * The served-here gate (#1705 PR 2), from whichever source of truth this host has.
+     *
+     * With a directory, the directory decides: the record must exist for this (tenant, scope), and
+     * the shared control plane refuses a scope bound to a vertical (`assertServedHere`). Role rows
+     * are not consulted, because a directory-backed host provisions without projecting them.
+     *
+     * CP-less, which is every pushed vertical, there is no directory. The scope must have been
+     * provisioned in THIS deployment's namespace, for THIS tenant (`ScopeDO.servesTenant`).
+     *
+     * A scope this host does not hold is refused `conflict`, not `not_found`: over `/internal` a
+     * 404 means "this deployment predates the route", and the platform reads it as exactly that.
+     * One exception: the SHARED control plane (a directory host with delegations) refuses a scope
+     * bound to a vertical `unavailable`, through `assertServedHere`, the same answer its peer door
+     * gives. It never mounts these routes, so no `/internal` caller meets that answer.
+     */
+    async assertServesLocally(tenantId, scopeId, verb) {
+        if (!this.cpLess) {
+            const record = await this.cp.getScopeRecord(tenantId, scopeId);
+            if (!record) {
+                throw substratError('conflict', `${verb} cannot answer for scope ${scopeId}: the directory has no such scope for tenant ${tenantId}`);
+            }
+            this.assertServedHere(record, scopeId, verb);
+            return;
+        }
+        if (!(await this.scopeStub(scopeId).servesTenant(tenantId))) {
+            throw substratError('conflict', `${verb} cannot answer for scope ${scopeId}: this deployment holds no scope provisioned for tenant ` +
+                `${tenantId} under that id — the platform resolved the scope to a deployment that does not serve it`);
+        }
+    }
+    /**
+     * What one pushed version imports from other verticals (#1705 PR 2), from its stored manifest:
+     * the control plane's cross-vertical narrowing reads this to decide which scopes it calls.
+     *
+     * Deliberately NOT through `admin.versionManifest`, which writes an access-log row per read.
+     * The narrowing asks once per distinct running version on every pass and every kick. Audited,
+     * the log would grow with fleet × tick rate + request rate, for a read of the platform's own
+     * code metadata (a version's declared edges, which a push put there), not of a tenant's data.
+     * Throws `not_found` for a version the registry does not know under that vertical, which the
+     * narrowing reports and treats as "cannot say" rather than "imports nothing".
+     */
+    async versionImports(verticalSlug, versionId) {
+        const v = await this.cp.readVersion(versionId);
+        if (!v || v.vertical_slug !== verticalSlug) {
+            throw substratError('not_found', `unknown version ${versionId} for vertical '${verticalSlug}'`);
+        }
+        return importsOfManifestJson(v.manifest_json);
+    }
 }
 /** SHA-256 hex of an attachment's bytes — what `AttachmentRecord.sha256` holds. */
 async function sha256Hex(body) {