@substrat-run/kernel 0.134.0 → 0.136.0

package/dist/scope-copy.js

@@ -0,0 +1,187 @@
+import { CAPABILITY_TABLE_NAMES } from './capability.js';
+/**
+ * What a dump leaves behind when it lands in a scope other than the one it was captured from
+ * (#1686). One definition for both adapters' loaders, so the DO and the pure host agree.
+ *
+ * A load is a **copy** when the destination is not the source: a fork, a snapshot, a preview, or
+ * one scope's backup restored onto another. It is a **return** when the dump goes back into the
+ * scope it came from: a backup restore, a carry onto a new version, adopt, rebind. A copy runs as
+ * a scope of its own, so whatever in the dump is bound to being the source (a live link's secret,
+ * a side effect the source asked for) must not work in the copy. A return keeps all of it, because
+ * restoring a backup must not end live links or lose requests that were waiting.
+ *
+ * An unknown source (`sourceScopeId` or `destScopeId` absent) counts as a copy: a load that cannot
+ * say where the dump came from cannot show it is a return. Only a control plane that predates the
+ * field sends a restore with no source.
+ */
+export const isCopyLoad = (destScopeId, sourceScopeId) => destScopeId === undefined || sourceScopeId !== destScopeId;
+/** The capability tables, as `capabilitiesForLoad` matches a dump's (lowercased) names. */
+const CAPABILITY_TABLES = new Set(CAPABILITY_TABLE_NAMES);
+/**
+ * A dump's tables as a load into `destScopeId` takes them: **capability rows never cross a scope
+ * id.** A copy loads both capability tables empty, so a live link share opens the scope it was
+ * minted in and never a copy of it; a return keeps them.
+ *
+ * Dropped, not loaded as revoked: the copy never minted those links, so a revocation recorded
+ * there would be evidence of something that did not happen in it. Names are matched without
+ * case, as SQLite resolves a table name.
+ */
+export function capabilitiesForLoad(tables, destScopeId, sourceScopeId) {
+    if (!isCopyLoad(destScopeId, sourceScopeId))
+        return tables;
+    return tables.map((t) => (CAPABILITY_TABLES.has(t.name.toLowerCase()) ? { ...t, rows: [] } : t));
+}
+/** The reason copied work is settled with. Names the source, so the journal says where it runs. */
+const notCarried = (sourceScopeId) => `not carried: copied from ${sourceScopeId ? `scope ${sourceScopeId}` : 'another scope'} before it ran; ` +
+    'it runs in the scope that asked for it, never in a copy';
+/** A copied intent's failure: the platform's own refusal, never the provider's answer. */
+const NOT_CARRIED_FAILURE = JSON.stringify({
+    origin: 'platform',
+    code: 'precondition_failed',
+    permission: null,
+});
+/**
+ * Where a scope's data came from, and whether it is a copy: at most one row, which holds two
+ * facts that are set and corrected apart (#2009).
+ *
+ * - **`events_through`, the copied-events mark.** The highest event id a load brought in from
+ *   another scope, or `''` when it brought none. Every event at or below it was emitted in another
+ *   scope; every event the scope emits itself sorts above it, because a loader re-seeds the
+ *   scope's event-id floor from `MAX(id)` (#1335) once the rows are in. Written by a load into a
+ *   scope id other than the dump's (`settleCopiedWork`), and by nothing else.
+ * - **`is_copy`, the classification.** Whether the scope is a copy (a fork, a snapshot, a
+ *   preview), which a host with no control-plane directory reads for primacy and holds inert
+ *   (#2005). Written on the directory's word only (`markCopyOrigin`), never inferred from a load:
+ *   one install's backup restored onto another install is a cross-scope load, so it carries the
+ *   source's events mark, yet the directory still says primary, and its own effects must run.
+ *   Cleared by staff's correction (`clearCopyMarker`) without touching the events mark.
+ *
+ * A scope that was never loaded from another scope and never marked holds no row. A row written
+ * before the column existed holds `is_copy` NULL, and NULL reads as a copy: such a row meant both
+ * facts at once, so every legacy store keeps exactly the behaviour it had (`IS_COPY_SQL`). The
+ * column is nullable with no DEFAULT for the reason every additive spine column is (#1883,
+ * `lint:spine-ddl`), so its "default" lives in that read. Kernel-owned and shared by both
+ * adapters' `KERNEL_DDL`, so the two cannot part company.
+ */
+export const COPY_ORIGIN_DDL = `
+  CREATE TABLE IF NOT EXISTS _substrat_copy_origin (
+    -- Always 1: one origin per scope. No CHECK, because lint:spine-ddl compares none.
+    id INTEGER PRIMARY KEY,
+    source_scope_id TEXT,
+    events_through TEXT NOT NULL,
+    copied_at TEXT NOT NULL,
+    -- #2009: 1 a copy, 0 not one (a load's events mark only, or a cleared marker), NULL a row
+    -- from before the column, which read as a copy and still does.
+    is_copy INTEGER
+  );
+`;
+/**
+ * The predicate every read that turns an outbox row into WORK carries (consumer dispatch, executor
+ * dispatch, the Tier-2 drain): the event was emitted in this scope, not copied into it. `alias` is
+ * the outbox's alias in the caller's query (`'o.'`), or empty. A scope that was never a copy has no
+ * key, and every id compares above the empty string.
+ */
+export const emittedHere = (alias = '') => `${alias}id > COALESCE((SELECT events_through FROM _substrat_copy_origin WHERE id = 1), '')`;
+/**
+ * On a copy, nothing that originated in the source produces an effect in the destination. Run
+ * inside the load's transaction, after the rows are in and BEFORE the loader queues any work of
+ * its own (the attachment-text re-extraction is a job run), or that work is settled with the
+ * source's. The history stays: every row is still
+ * there and reads as what happened at the source; only its power to cause something here goes.
+ *
+ * The platform's drain walks every active scope, and a fork, a snapshot or a preview is one, so
+ * each of these would otherwise run a second time from the copy (an email sent twice, a connector
+ * delivery repeated, a usage line billed twice):
+ *
+ * - **Pending intents** settle `failed`, "not carried", attributed to the platform.
+ * - **Executor retries** (`_substrat_deliveries` rows with a `next_attempt_at`) become terminal,
+ *   with "not carried" as their error, as a dead letter reads.
+ * - **Running job runs** settle `failed`, "not carried"; their step ledger stays as evidence.
+ * - **Events no consumer or executor has reached yet** cannot be settled row by row: an executor is
+ *   registered on the coordinator, not in the scope, so the loader cannot know who still owes one.
+ *   Instead the copy records the highest id it brought in (`_substrat_copy_origin`), and every
+ *   read that dispatches work carries `emittedHere()`. That also keeps the copy from shipping the
+ *   source's events to Tier 2 a second time.
+ *
+ * A return leaves all of it as it was, because the scope that asked for the work is the one it is
+ * back in. Settled rather than dropped: a journal row saying "not carried" explains why the event
+ * that raised it caused nothing here, where a missing row would leave a gap.
+ */
+export function settleCopiedWork(sql, destScopeId, sourceScopeId, now) {
+    if (!isCopyLoad(destScopeId, sourceScopeId))
+        return;
+    const reason = notCarried(sourceScopeId);
+    sql.run(`UPDATE _substrat_platform_requests
+        SET status = 'failed', last_error = ?, last_failure = ?, settled_at = ?
+      WHERE status = 'pending'`, reason, NOT_CARRIED_FAILURE, now);
+    sql.run(`UPDATE _substrat_deliveries SET next_attempt_at = NULL, error = ?, delivered_at = ?
+      WHERE next_attempt_at IS NOT NULL`, reason, now);
+    sql.run(`UPDATE _substrat_job_runs
+        SET status = 'failed', last_error = ?, next_attempt_at = NULL, updated_at = ?, ended_at = ?
+      WHERE status = 'running'`, reason, now, now);
+    const highest = sql.all('SELECT MAX(id) AS id FROM _substrat_outbox')[0]?.id;
+    // Written for an empty copy too: `''` is below every id, so `emittedHere()` passes all of the
+    // scope's own events exactly as no row would. An origin the dump already carried with the same
+    // source and mark is kept as it was, its `copied_at` included, so re-loading the same export
+    // changes nothing in it.
+    //
+    // `is_copy` is 0 (#2009): the load moves the events mark and does not classify. Whatever the
+    // dump's row said described the scope it came FROM; whether THIS scope is a copy is the
+    // directory's to say, through `markCopyOrigin`, which the loader runs after this when the
+    // directory says so.
+    sql.run(`INSERT INTO _substrat_copy_origin (id, source_scope_id, events_through, copied_at, is_copy) VALUES (1, ?, ?, ?, 0)
+       ON CONFLICT (id) DO UPDATE SET
+         source_scope_id = excluded.source_scope_id,
+         events_through = excluded.events_through,
+         copied_at = excluded.copied_at,
+         is_copy = excluded.is_copy
+       WHERE _substrat_copy_origin.source_scope_id IS NOT excluded.source_scope_id
+          OR _substrat_copy_origin.events_through IS NOT excluded.events_through
+          OR _substrat_copy_origin.is_copy IS NOT excluded.is_copy`, sourceScopeId ?? null, typeof highest === 'string' ? highest : '', now);
+}
+/**
+ * Mark this scope a copy (#2005), on the directory's word that it is not primary: a load the
+ * platform flags, the `mark-copies` repair, a reactivation, a carry's wipe or release. Sets the
+ * classification and nothing else (#2009): an origin row a load wrote keeps its events mark and
+ * source, and a scope with no row gets one whose events mark is `''`, which passes every event
+ * exactly as no row does, so dispatch is unchanged. Idempotent: answers whether this call changed
+ * anything, and a store that already reads as a copy (a legacy row included) is left as it is.
+ */
+export function markCopyOrigin(sql, now) {
+    if (sql.all(IS_COPY_SQL).length > 0)
+        return false;
+    sql.run(MARK_COPY_ORIGIN_SQL, now);
+    return true;
+}
+/**
+ * The one statement that marks a store a copy (#2005, #2009): the origin row with no events mark
+ * where none exists, or the classification set on the row that does. It only ever makes a store
+ * MORE restricted — a copy's executors are held inert — and changes no data and no events mark,
+ * which is why the scope DO lets this statement, and no other, through without advancing the
+ * write revision a carry fences on (#1722, `isCopyMarkInsert`). Clearing a marker is the opposite
+ * and is a write like any other.
+ */
+export const MARK_COPY_ORIGIN_SQL = "INSERT INTO _substrat_copy_origin (id, source_scope_id, events_through, copied_at, is_copy) VALUES (1, NULL, '', ?, 1) " +
+    'ON CONFLICT (id) DO UPDATE SET is_copy = 1';
+/**
+ * Correct a MISTAKEN copy classification (#2005, #2009): for a scope the directory says is
+ * primary, marked by a misclassification, a race, an operator, or a row from before #2009 that
+ * a cross-scope load wrote (one install's backup restored onto another). Clears the
+ * classification only: the events mark stays, so the source's queued work is still never run
+ * here (`emittedHere()`), and the scope's own effects run again. `absent` when the store does not
+ * read as a copy.
+ */
+export function clearCopyMarker(sql) {
+    if (sql.all(IS_COPY_SQL).length === 0)
+        return 'absent';
+    sql.run('UPDATE _substrat_copy_origin SET is_copy = 0 WHERE id = 1');
+    return 'cleared';
+}
+/**
+ * Whether this scope is a copy (#2005, #2009): the classification on its copy-origin row, with
+ * a row from before the column (NULL) read as one. The one primacy fact a host with no
+ * control-plane directory can read from the scope's own storage — a CP-less hosted vertical's
+ * coordinator asks it before it runs an executor.
+ */
+export const IS_COPY_SQL = 'SELECT 1 AS copy FROM _substrat_copy_origin WHERE id = 1 AND COALESCE(is_copy, 1) = 1';
+//# sourceMappingURL=scope-copy.js.map

package/dist/scope-copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-copy.js","sourceRoot":"","sources":["../src/scope-copy.ts"],"names":[],"mappings":"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"}

package/dist/scope-host.d.ts

@@ -1,5 +1,5 @@
 import type { ModuleLog } from './module-log.js';
-import type { OnBehalfOf, ExportReadInput, ExportedBatch, ImportBatch, ImportedEvent, ImportResult, ImportState, ImportCursorMove, ImportCursorMoved, AdminAction, BecomeCapabilityInput, CapabilityExchange, CapabilityId, MintedCapability, ListPage, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, DelegatedReadRecord, OwnerTransferAudit, BindHostnameInput, AdminLogEntry, OpsFailureEntry, PlatformRequestDrainTotalsEntry, SweepRunEntry, SweepRunKind, SweepRunOutcome, ModelUsageEntry, ModelUsageSummary, CapabilityGrant, CreateTenantInput, Decision, Instant, DomainEvent, DomainEventInput, PlatformRequestInput, PlatformRequestId, PlatformRequest, PlatformRequestFilter, PlatformRequestStatus, PlatformRequestFailure, EntitlementGrant, EntitlementGrantInput, EntitlementView, MeterReading, EntityRef, IdentityLink, IdentityPool, Jurisdiction, ModuleId, ModuleManifest, ScheduleSpec, SystemGrant, PeerGrantsStatusEntry, SystemGrantsStatusEntry, SystemSwitchRecord, SystemSwitch, SystemSwitchResult, PeerCoverage, PeerSwitch, PeerSwitchResult, VerticalCaller, VerticalResolution, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ExportBreak, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, BindAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, RouteTarget, DirectoryDump, IdentityMembership, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, DenialFilter, DenialSummary, PermissionDenial, Coverage, BeginImpersonationInput, ImpersonationFilter, ImpersonationSession, ImpersonationSessionId, ScopeTablePage, StorageShape, Tenant, TenantId, TenantRole, TenantStoreHandle, AttachmentRecord, BlobStoreHandle, Visibility, Vertical, VerticalChannel, VerticalVersion, TenantStatus, Page, CountedPage, FreshnessSpec, EntityHistoryInput, EventFacetInput, EventCauseInput, EventEffectsInput, EffectsTree, InvocationEventsInput, InvocationEvents, DeadLettersInput, DeadLetter, LifecycleFlowInput, LifecycleFlowResult, CauseChain, EventFacetResult, HistoryEntry, ErrorCode, PlatformRequestFailureOrigin, IssueEntry, IssueStatus, IssueStatusInput, DeclaredMigration, CheckSubject } from '@substrat-run/contracts';
+import type { OnBehalfOf, ExportReadInput, ExportedBatch, ImportBatch, ImportedEvent, ImportResult, ImportState, ImportCursorMove, ImportCursorMoved, AdminAction, BecomeCapabilityInput, CapabilityExchange, CapabilityFilter, CapabilityId, CapabilityPage, MintedCapability, ListPage, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, DelegatedReadRecord, OwnerTransferAudit, CopyMarkAudit, BindHostnameInput, AdminLogEntry, OpsFailureEntry, PlatformRequestDrainTotalsEntry, SweepRunEntry, SweepRunKind, SweepRunOutcome, ModelUsageEntry, ModelUsageSummary, CapabilityGrant, CreateTenantInput, Decision, Instant, DomainEvent, DomainEventInput, PlatformRequestInput, PlatformRequestId, PlatformRequest, PlatformRequestFilter, PlatformRequestStatus, PlatformRequestFailure, EntitlementGrant, EntitlementGrantInput, EntitlementView, MeterReading, EntityRef, IdentityLink, IdentityPool, Jurisdiction, ModuleId, ModuleManifest, ScheduleSpec, SystemGrant, PeerGrantsStatusEntry, SystemGrantsStatusEntry, SystemSwitchRecord, SystemSwitch, SystemSwitchResult, PeerCoverage, PeerSwitch, PeerSwitchResult, VerticalCaller, VerticalResolution, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ExportBreak, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, BindAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, RouteTarget, DirectoryDump, IdentityMembership, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, DenialFilter, DenialSummary, RefusalFilter, RefusalRecord, PermissionDenial, Coverage, BeginImpersonationInput, ImpersonationFilter, ImpersonationSession, ImpersonationSessionId, ScopeTablePage, StorageShape, Tenant, TenantId, TenantRole, TenantStoreHandle, AttachmentRecord, BlobStoreHandle, Visibility, Vertical, VerticalChannel, VerticalVersion, TenantStatus, Page, CountedPage, FreshnessSpec, EntityHistoryInput, EventFacetInput, EventCauseInput, EventEffectsInput, EffectsTree, InvocationEventsInput, InvocationEvents, DeadLettersInput, DeadLetter, LifecycleFlowInput, LifecycleFlowResult, CauseChain, EventFacetResult, HistoryEntry, ErrorCode, PlatformRequestFailureOrigin, IssueEntry, IssueStatus, IssueStatusInput, DeclaredMigration, CheckSubject } from '@substrat-run/contracts';
 import type { ConnectionUseOutcome } from './connector-calls.js';
 import type { CapabilityVerbs } from './capability.js';
 import type { ModelUsageFilter, ModelUsageInput, ModelUsageWindow } from './model-usage.js';
@@ -264,6 +264,10 @@ export interface OperationContext {
      * `SortNotDeclared` for a `?sort=` outside the vocabulary, and
      * `FilterNotDeclared` for a filter outside it — never a silently-ignored
      * parameter, which is how a caller comes to believe a filter is applied.
+     *
+     * `params.order` unset walks ascending; an operation's declared order arrives
+     * already applied by `operationInputsOf`. A cursor replayed under another sort
+     * or order throws `CursorMismatch` (`reason: 'cursor_restart'`) — #2001, K-44.
      */
     page<T>(entityType: string, params: PageParams): Page<T> | CountedPage<T>;
     /**
@@ -775,6 +779,19 @@ export interface ExecutorDrainReport {
      * the response so the router kicks an immediate drain.
      */
     routedToPlatform?: number;
+    /**
+     * Deliveries journaled as not executed because the scope is not primary — a fork, a
+     * snapshot or a preview, which cause no outbound effects (#2005, `INERT_SCOPE_REASON`).
+     * Terminal and counted apart from `deadLettered`: nothing failed, the platform declined.
+     */
+    inert?: number;
+    /**
+     * The scope's lifecycle holds its work (#1713): a suspended or archived scope, or one under a
+     * suspended or deleting tenant, as a CP-less host reads it from the scope's own storage.
+     * Nothing was attempted and every due delivery is still due, so the first pass after the scope
+     * is live again delivers it. Absent otherwise.
+     */
+    lifecycleHeld?: true;
 }
 /**
  * A module's recurring-work declarations, as `registeredSchedules` reports them
@@ -832,6 +849,12 @@ export interface ScheduleRunReport {
      * scope (#1819, Cloudflare only) reports the same.
      */
     switchedOff?: true;
+    /**
+     * The scope's lifecycle holds its work (#1713, a CP-less host reading the scope's own
+     * storage): every schedule is `skipped` and no cadence row moved, so a schedule that came
+     * due meanwhile fires once on the first pass after the scope is live again. Absent otherwise.
+     */
+    lifecycleHeld?: true;
     /**
      * Per-schedule failures on this scope: the operation name and the error. One entry is
      * not a schedule's: `operation: 'switch-hold'` says the rewind hold (#1819) could not be
@@ -1900,6 +1923,14 @@ export interface HostAdmin {
      * deliberately deleted (the "absent = pinned" the snapshot body already models). Audited.
      */
     setScopeExpiresAt(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, expiresAt: string | null): Promise<void>;
+    /**
+     * Record a staff resolution of a kept copy (#1722, Codex #2008 r7) in the admin log. A kept
+     * copy is one a carry's wipe refused because it took a write the carry never copied; the
+     * vertical's store holds it, so the resolution itself (a discard, or a restore forward over the
+     * live store) runs there, and this is its record: which script held it, what was done, and the
+     * write revision before and after. The directory changes nothing else. Refuses an unknown scope.
+     */
+    recordKeptCopyResolution(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, resolution: KeptCopyResolution): Promise<void>;
     /**
      * When each of a CO-LOCATED scope's migrations actually ran (#1236), newest
      * first. `_substrat_migrations.applied_at` has been written since the table
@@ -2350,6 +2381,36 @@ export interface HostAdmin {
      * getting refused" — and the answer says which grouping it carries.
      */
     summarizeDenials(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, filter?: DenialFilter): Promise<DenialSummary>;
+    /**
+     * #1745: the refusal log — every lifecycle move `assertTransition` refused and the
+     * operation failed with, recorded after the rollback exactly as a denial is. A bounded
+     * page of raw rows, newest first; narrow with `entityType`/`entityId` (which record),
+     * `actor`, `operation`, `invocationId` (which call) and a `since`/`until` window.
+     *
+     * The row read beneath `lifecycleFlow`'s `refused` counts, read like the denial log:
+     * a `PlatformActorId`, a K-24 access-log entry and the K-3 (tenantId, scopeId)
+     * cross-check. Unlike a denial row it names a record and the state it was in — a key
+     * and a status value, never the record's fields.
+     */
+    listRefusals(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, filter?: RefusalFilter): Promise<RefusalRecord[]>;
+    /**
+     * The operator's read of a scope's capabilities (#1686): the directory `ctx.capabilities.list`
+     * reads from inside a module, for someone who has no operation to stand in. Newest first,
+     * live (unrevoked) ones only unless `includeRevoked`, narrowable to one `entity`, and
+     * keyset-paged: `limit` 1..200 (default 50) and a `cursor`, the previous page's `nextCursor`.
+     * `nextCursor` is set only when more records follow, so a walk never truncates silently and
+     * a full last page ends it. A malformed cursor is refused.
+     *
+     * **Never a secret, never a hash.** A record carries what the capability may do (mode, entity,
+     * keys, operation allowlist, or the principal a `become` yields), who minted and revoked it,
+     * its expiry, use limit and use count. The kernel's one query (`capabilityListQuery`) does not
+     * select `token_hash`, and the record schema has no field to hold one.
+     *
+     * Read like the denial log: a `PlatformActorId`, a K-24 access-log entry and the K-3
+     * (tenantId, scopeId) cross-check. Pull-only — it changes nothing, so it is not in the admin
+     * log; `mintCapability` and `revokeCapability` are.
+     */
+    listCapabilities(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, filter?: CapabilityFilter): Promise<CapabilityPage>;
     /**
      * A COMPLETE dump of the directory itself: tenants, scopes, hostnames, verticals,
      * entitlements, identities, and the audit spine. The platform-level analogue of
@@ -2889,6 +2950,14 @@ export interface HostAdmin {
      * `id` and `at`. Throws when the row cannot be written.
      */
     recordOwnerTransfer(actor: PlatformActorId, entry: OwnerTransferAudit): Promise<void>;
+    /**
+     * Record one change to a scope's copy marker (#2005) on the admin log — `markScopeCopy` for a
+     * `mark`, `clearScopeCopyMark` for a `clear`. The marker lives in the vertical's deployment, so
+     * the control plane writes this around its call there — `recordOwnerTransfer`'s shape: fixed
+     * actions, parsed entry, request actor, adapter-stamped `id` and `at`. Throws when the row
+     * cannot be written.
+     */
+    recordCopyMark(actor: PlatformActorId, entry: CopyMarkAudit): Promise<void>;
     /**
      * Stamp `drainedAt` on every not-yet-drained access row up to and including
      * `upToId`, marking them shipped to Tier 2. Returns how many rows moved.
@@ -3055,6 +3124,53 @@ export declare function attachmentBlobKey(scopeId: string, attachmentId: string)
  * both adapters' `open`, and the extraction job (#1575).
  */
 export declare function attachmentSha256(body: Uint8Array): Promise<string>;
+/**
+ * Who binds an operation, as the §4.3 entitlement gate needs to know it: the owning
+ * module, the SKU flag its manifest declares, and the operations that module declares
+ * as its own recurring schedules (#383). Each adapter records one per bound operation
+ * at `registerModule`, and hands it to {@link requiredEntitlementFor} at every invoke.
+ */
+export interface OperationEntitlement {
+    moduleId: string;
+    entitlementKey: string;
+    scheduledOperations: ReadonlySet<string>;
+}
+/**
+ * The SKU flag the §4.3 gate demands for ONE invoke — `undefined` when it demands none.
+ * One predicate, run by every place the gate lives (the Cloudflare coordinator, the
+ * ScopeDO it hands the key to, the SQLite stub), so no adapter can be the lenient one.
+ *
+ * **The rule:** a module loads for a tenant only if the tenant holds its SKU flag. An
+ * operation with no recorded binding (a bare `defineOperation`, tests and glue) is ungated.
+ *
+ * **The one exception (#1654): a module's own declared schedule, fired through the
+ * system door.** All three must hold:
+ *   1. the invoke came through the system door (`getSystemScope`, so `systemModuleId`
+ *      is set) — a door with no route; no HTTP request, principal, connection or peer
+ *      reaches it;
+ *   2. the operation is bound by THAT module (`moduleId === systemModuleId`) — the system
+ *      principal of one module never borrows the exception for another module's operation;
+ *   3. the module declares that operation in its own `schedules` — a system-door invoke of
+ *      any other operation is still gated, so a job run or a direct `getSystemScope` call
+ *      is not widened.
+ *
+ * Why the SKU is not the switch there: a composed engine's schedule runs in the engine's
+ * name, but the engine is loaded into the scope by the VERTICAL that composes it, and a
+ * standard install grants the vertical's keys, not the engine's (meridian composes
+ * `engine-absence` by call; its `absence/expire-stale` was refused on every install).
+ * The schedule's authority is already the `system:<moduleId>` grant — seated only by
+ * provisioning a scope with that module registered, holding exactly the permissions the
+ * schedules declare, and pulled by the kill switch (#1666). "The grant IS the switch"
+ * (#383) now holds for loading as well as for permissions. What does NOT change: every
+ * user-reachable door — `getScope`, connector, capability, peer, impersonation — still
+ * demands the operation's own key, so the engine's operations stay unreachable on an
+ * install that does not hold the engine's SKU.
+ *
+ * The cost, stated: on a tenant whose SKU for a module lapses, that module's own declared
+ * schedules keep running on scopes that still hold the system grant. Stopping them is the
+ * schedule switch (`revokeFromSystem`, #1666), or archiving the scope.
+ */
+export declare function requiredEntitlementFor(operation: string, binding: OperationEntitlement | undefined, systemModuleId: string | undefined): string | undefined;
 /**
  * The §4.3 entitlement-gate denial, worded identically wherever the gate lives — the
  * coordinator against the shared CP, a scope DO against its projection, the SQLite
@@ -3401,6 +3517,22 @@ export interface OpsFailureInput {
     /** The upstream provider's trace reference, when the message carried one. */
     reference?: string | null;
 }
+/** One staff resolution of a kept copy (#1722), as `recordKeptCopyResolution` logs it. */
+export interface KeptCopyResolution {
+    /** `discard` wiped the kept copy; `restore-forward` restored it over the live store, then wiped it;
+     *  `release` cleared the marker of a kept copy that is the live store after all. */
+    action: 'discard' | 'restore-forward' | 'release';
+    /** The script that held the kept copy. */
+    script: string;
+    /** The script the scope routes to, which a restore forward replaced; null for a discard. */
+    liveScript: string | null;
+    /** When the copy was kept, from its marker. */
+    keptAt: string;
+    /** The kept copy's write revision the operator acted on. */
+    revisionBefore: string | null;
+    /** The write revision of the store the resolution changed, after it. */
+    revisionAfter: string | null;
+}
 /** Filter for `listOpsFailures` — cursor/order/limit exactly as `AuditLogFilter`. */
 export interface OpsFailureFilter {
     tenantId?: TenantId;
@@ -3640,6 +3772,10 @@ export interface ScopeHost {
      * not. A failure is retried with backoff, dead-lettered at `maxAttempts`, and
      * surfaced through `drainDue`/`executorDeadLetters` — never thrown at whoever happened
      * to be holding the request.
+     *
+     * **Never on a scope that is not primary** (#2005). A fork, a snapshot or a preview causes
+     * no outbound effects, so its deliveries are journaled terminal with `INERT_SCOPE_REASON`
+     * (counted in `ExecutorDrainReport.inert`) and no handler — executor or connector — runs.
      */
     registerExecutor(id: string, eventType: string, handler: ExecutorHandler, retry?: ExecutorRetryPolicy): void;
     /**
@@ -4217,29 +4353,14 @@ export interface LiveReadSurface<Req extends LiveUpgradeRequest = LiveUpgradeReq
         request: Req;
     }): Promise<Res>;
 }
-/**
- * Set on every refusal a live-read door returns, so a client can tell "no push here,
- * poll" from "your request was wrong" without parsing a body or guessing from a status.
- *
- * Here rather than in the hosted adapter because both ends of a refusal need to spell it
- * the same way: the hosted adapter sets it on its own refusals, and a vertical's mount
- * sets it on the pure host's `501` (the ask-don't-assume recipe on `ScopeHost.liveReads`).
- * A dev server should not have to import the Cloudflare adapter to say "poll".
- */
-export declare const LIVE_MODE_HEADER = "x-substrat-live";
-/** Why a subscription was refused — the value of `LIVE_MODE_HEADER` on a refusal. */
-export type LiveRefusal = 
-/** This host or connection cannot carry a WebSocket; the client should keep polling. */
-'poll'
-/** The request was not an upgrade at all — a programming error at the caller. */
- | 'not-an-upgrade';
 /**
  * Is this request asking to be upgraded to a WebSocket?
  *
- * Here beside `LIVE_MODE_HEADER` because a vertical's live route asks it first, before
- * anything else it decides: only a WebSocket handshake is a live read, and a browser
- * always sends `Origin` on one, so everything past this check can trust that a missing
- * `Origin` did not come from a browser page. A plain GET with a cookie on it cannot.
+ * Paired with `LIVE_MODE_HEADER` (`@substrat-run/contracts`) because a vertical's live
+ * route asks it first, before anything else it decides: only a WebSocket handshake is a
+ * live read, and a browser always sends `Origin` on one, so everything past this check
+ * can trust that a missing `Origin` did not come from a browser page. A plain GET with a
+ * cookie on it cannot.
  */
 export declare function isUpgradeRequest(request: LiveUpgradeRequest): boolean;
 /**