@substrat-run/adapter-cloudflare 0.88.0 → 0.90.0

package/dist/scope-do.js

@@ -1,6 +1,6 @@
 import { DurableObject } from 'cloudflare:workers';
-import { ATTACHMENT_ADDED, ATTACHMENT_REMOVED, attachmentRecord, domainEvent, domainEventInput, eventId, instant, objectRef, toWireFailure, grantRefFromProof, principalId, platformRequestInput, platformRequestId, MAX_PENDING_PLATFORM_REQUESTS, platformRequest, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, listLimitOf, } from '@substrat-run/contracts';
-import { ulid, assertAllowed, ConnectionSealingKeyUnavailableError, noSealingKeyMessage, sealTo, assertReadOnlyQuery, entitlementDenial, platformRequestHistoryQuery, PLATFORM_REQUEST_COLUMNS, denialListQuery, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialBucketRow, PermissionDenied, createAtomic, NotSearchable, isSearchIndexTable, searchIndexDdl, searchIndexMigrations, searchIndexPlans, NotListable, listIndexMigrations, listIndexPlans, listQuery, cursorOf, searchLimit, searchMatchExpression, searchQuery, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, } from '@substrat-run/kernel';
+import { ATTACHMENT_ADDED, ATTACHMENT_REMOVED, attachmentRecord, domainEvent, domainEventInput, eventId, instant, objectRef, toWireFailure, grantRefFromProof, principalId, platformRequestInput, platformRequestId, MAX_PENDING_PLATFORM_REQUESTS, platformRequest, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, listLimitOf, requestFingerprint, substratError, } from '@substrat-run/contracts';
+import { ulid, assertAllowed, ConnectionSealingKeyUnavailableError, noSealingKeyMessage, sealTo, assertReadOnlyQuery, entitlementDenial, platformRequestHistoryQuery, PLATFORM_REQUEST_COLUMNS, denialListQuery, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialBucketRow, PermissionDenied, assertImpersonationWrites, impersonationStampOf, createAtomic, NotSearchable, isSearchIndexTable, searchIndexDdl, searchIndexMigrations, searchIndexPlans, NotListable, listIndexMigrations, listIndexPlans, listQuery, cursorOf, searchLimit, searchMatchExpression, searchQuery, IDEMPOTENCY_DDL, assertIdempotencyKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencyOptedOutMessage, replayFor, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, } from '@substrat-run/kernel';
 import { OperationQueue } from './serialization.js';
 import { doScopedSql } from './sql.js';
 import { createDoTupleChecker, createLocalControlPlaneReader } from './checker.js';
@@ -23,6 +23,10 @@ const KERNEL_DDL = `
     -- K-34: the checks the emitting operation passed (JSON [{permission, grant?}]).
     -- NULL on rows written before the field existed -- honestly unrecorded, not empty.
     authorization TEXT,
+    -- K-42: the staff actor + session an impersonated operation ran under (JSON
+    -- session/by). NULL is the ordinary case -- nobody was impersonating -- and the
+    -- actor column above stays the principal the permission model answered about.
+    impersonation TEXT,
     drained_at TEXT
   );
   -- platform-intents.md: durable intents a vertical enqueues (ctx.requestPlatform) for the platform
@@ -33,6 +37,8 @@ const KERNEL_DDL = `
     kind TEXT NOT NULL,
     payload TEXT NOT NULL,
     requested_by TEXT NOT NULL,
+    -- K-42: the staff actor + session, when the intent was raised under one.
+    impersonation TEXT,
     status TEXT NOT NULL DEFAULT 'pending',
     attempts INTEGER NOT NULL DEFAULT 0,
     last_error TEXT,
@@ -57,6 +63,8 @@ const KERNEL_DDL = `
     tenant_id TEXT NOT NULL,
     scope_id TEXT,
     operation TEXT,
+    -- K-42: WHICH of the two actors was refused is exactly what this log is for.
+    impersonation TEXT,
     at TEXT NOT NULL,
     drained_at TEXT
   );
@@ -215,6 +223,8 @@ const KERNEL_DDL = `
   -- MAX(id) per (entity_type, entity_id) is the read. The id column sits last so
   -- SQLite walks to the end of the matched range instead of aggregating over it.
   ${OUTBOX_ENTITY_INDEX}
+  -- #116: the request-dedupe table, kernel-owned so no vertical migrates for it.
+  ${IDEMPOTENCY_DDL}
 `;
 /**
  * Workers RPC carries a plain `Error`'s MESSAGE faithfully and nothing else. A custom
@@ -284,6 +294,7 @@ function rowToPlatformRequest(r) {
         kind: r.kind,
         payload: JSON.parse(r.payload),
         requestedBy: JSON.parse(r.requested_by),
+        impersonation: r.impersonation == null ? null : JSON.parse(r.impersonation),
         status: r.status,
         attempts: r.attempts,
         lastError: r.last_error,
@@ -405,6 +416,8 @@ export function defineScopeDO(modules, bareOps) {
         operationInput = new Map();
         /** #129: name → the entity whose version an `If-Match` is compared against. */
         operationConcurrency = new Map();
+        /** #116: the operations that declared `idempotency: false` — refusals, not participants. */
+        operationIdempotencyOptOut = new Set();
         modules = new Map();
         guards = new Map();
         predicates = new Map();
@@ -451,6 +464,13 @@ export function defineScopeDO(modules, bareOps) {
                 // intent settled before this column reads as "nobody classified this" rather
                 // than claiming an origin the drain never decided.
                 'ALTER TABLE _substrat_platform_requests ADD COLUMN last_failure TEXT',
+                // K-42: the two-actor stamp on the three spine tables that record who did
+                // what, for a scope DO created before impersonation existed. Nullable
+                // everywhere, and the null means "nobody was impersonating" rather than
+                // "unrecorded" — every one of those rows predates the possibility.
+                'ALTER TABLE _substrat_outbox ADD COLUMN impersonation TEXT',
+                'ALTER TABLE _substrat_platform_requests ADD COLUMN impersonation TEXT',
+                'ALTER TABLE _substrat_denials ADD COLUMN impersonation TEXT',
             ]) {
                 try {
                     this.sql.exec(alter);
@@ -559,6 +579,15 @@ export function defineScopeDO(modules, bareOps) {
                 throw new Error(`${manifest.id} declares operationConcurrency for unbound operation(s): ` +
                     `${unguarded.sort().join(', ')} — a precondition on nothing reads as a guard that is not there`);
             }
+            // #116: same rule again for an opt-out — one on an unbound name reads as a
+            // deliberate exclusion of an operation that is not there.
+            const declaredOptOuts = registration.operationIdempotencyOptOuts ?? [];
+            const unboundOptOuts = declaredOptOuts.filter((name) => !ownOps.has(name));
+            if (unboundOptOuts.length > 0) {
+                throw new Error(`${manifest.id} declares idempotency: false for unbound operation(s): ` +
+                    `${[...unboundOptOuts].sort().join(', ')} — an opt-out on nothing reads as an ` +
+                    'exclusion someone decided, of an operation that does not exist');
+            }
             for (const [name, handler] of Object.entries(registration.operations ?? {})) {
                 this.defineOperation(name, handler);
                 // The schema follows the HANDLER, not the name: a withdrawn operation
@@ -569,6 +598,9 @@ export function defineScopeDO(modules, bareOps) {
                 const guarded = declaredConcurrency[name];
                 if (guarded && this.operations.has(name))
                     this.operationConcurrency.set(name, guarded);
+                if (declaredOptOuts.includes(name) && this.operations.has(name)) {
+                    this.operationIdempotencyOptOut.add(name);
+                }
             }
         }
         defineOperation(name, handler) {
@@ -813,19 +845,27 @@ export function defineScopeDO(modules, bareOps) {
          * sent an `If-Match` and does not see it refuses the success. An old DO
          * cannot set the acknowledgement, which is exactly how the skew is caught.
          */
-        invokeOptions) {
+        invokeOptions, 
+        /**
+         * K-42: the session this call runs under, resolved by the coordinator from
+         * the directory (which this DO cannot read) and passed WHOLE rather than as
+         * an id. The coordinator has already checked it is live, unexpired and for
+         * this scope; the DO uses it for the two-actor stamp and for the read-only
+         * bound, and nothing here can be reached without it having been minted.
+         */
+        impersonation) {
             if (!failureEnvelope) {
                 // Legacy path, byte-for-byte what it was: rewrapped so a non-plain error (a
                 // ZodError, whose `message` is a getter) still arrives with its message.
                 try {
-                    return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions);
+                    return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions, impersonation);
                 }
                 catch (err) {
                     throw toRpcError(err);
                 }
             }
             try {
-                return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions);
+                return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions, impersonation);
             }
             catch (err) {
                 // The ONE place the error keeps its structure: flattened here, rebuilt by the
@@ -835,11 +875,16 @@ export function defineScopeDO(modules, bareOps) {
             }
         }
         /** The operation path itself. Throws; `invoke` decides how that reaches the caller. */
-        async invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions) {
+        async invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions, 
+        /** K-42: the session, resolved coordinator-side. See `invoke` above. */
+        impersonation) {
             await this.ensureMigrations();
             const handler = this.operations.get(operation);
+            // `not_found`, not a bare throw (#113): every vertical hand-matched this message
+            // to reach a 404, because the platform's own refusals were as untyped as anything
+            // else. Naming the code once here is what lets those patterns go.
             if (!handler)
-                throw new Error(`unknown operation: ${operation}`);
+                throw substratError('not_found', `unknown operation: ${operation}`);
             // #304 entitlement gate, scope-local path: fail closed on the projected view exactly as
             // the coordinator fails closed against the CP. Only active once entitlements have been
             // projected (the `entitlements_enforced` marker) — before that the scope trusts upstream,
@@ -857,7 +902,7 @@ export function defineScopeDO(modules, bareOps) {
                         .exec(`SELECT entitlement_key, expires_at FROM _substrat_entitlements
                WHERE tenant_id = ? ORDER BY entitlement_key`, tenantId)
                         .toArray();
-                    throw new Error(entitlementDenial(operation, requiredEntitlement, all.map((r) => ({
+                    throw substratError('not_found', entitlementDenial(operation, requiredEntitlement, all.map((r) => ({
                         key: r.entitlement_key,
                         expired: r.expires_at !== null && r.expires_at <= now,
                     }))));
@@ -878,20 +923,73 @@ export function defineScopeDO(modules, bareOps) {
                     'nothing would have been compared. Declare it, or drop the header');
             }
             const guardedRef = guarded ? concurrencyRefOf(operation, guarded, parsed) : undefined;
+            // #116. Refused rather than ignored, for the reason two paragraphs up: an
+            // operation that opted out never records its response, so a caller who sent
+            // a key and got a 200 believes a retry is safe when it would execute again.
+            const idempotencyKey = invokeOptions?.idempotencyKey;
+            if (idempotencyKey !== undefined) {
+                if (this.operationIdempotencyOptOut.has(operation)) {
+                    throw new Error(idempotencyOptedOutMessage(operation));
+                }
+                assertIdempotencyKey(idempotencyKey);
+            }
+            // The subject a key is scoped to — the same three-way read `recordDenial`
+            // makes below, hoisted because both need it. A key belongs to whoever sent
+            // it: two principals choosing `1` must not reach each other's response.
+            const idempotencySubjectRef = systemModuleId
+                ? { kind: 'system', id: systemModuleId }
+                : connectionId
+                    ? { kind: 'connection', id: connectionId }
+                    : { kind: 'principal', id: principal };
+            // Fingerprinted from the PARSED input (defaults applied), before the queue:
+            // a pure hash of what the caller sent has no business inside a transaction.
+            const fingerprint = idempotencyKey === undefined ? undefined : await requestFingerprint(operation, parsed);
             return this.queue.enqueue(async () => {
                 let result;
                 let committedVersion = null;
+                // #116: set when this invocation was answered from a recording rather
+                // than run. Read after the transaction, where it decides both the
+                // envelope's acknowledgement and whether there is anything to dispatch.
+                let replayed = false;
                 // #458: how many platform intents THIS invoke enqueued. Counted inside the
                 // transaction, reported only after commit — a rolled-back intent is no signal.
                 // The envelope return (below) is the DO↔coordinator wire for it; both sides
                 // live in this package and deploy as one script, so the shape never skews.
                 const signals = { platformRequests: 0 };
+                /**
+                 * K-42: how a read-only session is made to BE read-only.
+                 *
+                 * Thrown on success, so the transaction never commits — the same
+                 * mechanism `queryScope`'s console uses, for the same reason: the DO's
+                 * `exec` exposes no read-only flag, so refusing to commit is the only
+                 * enforcement that survives a handler writing rows with plain SQL.
+                 * `ctx.emit` and the other effecting verbs refuse outright as well; that
+                 * is the half a support engineer sees, this is the half that holds.
+                 */
+                const rollback = new Error('read-only impersonation rollback');
                 // The async transaction is the K-4 boundary: guards + handler + emits
                 // commit together, or a throw (from either) rolls domain writes AND
                 // emitted events back as one — verified across `await` in workerd.
                 try {
                     await this.ctx.storage.transaction(async () => {
-                        const ctx = this.operationContext(principal, tenantId, scopeId, undefined, connectionId, systemModuleId, signals);
+                        const ctx = this.operationContext(principal, tenantId, scopeId, undefined, connectionId, systemModuleId, signals, impersonation);
+                        // #116: a retry is answered from the recording, and nothing else runs
+                        // — not the guards, not the handler, not the permission check inside
+                        // it. Keyed by SUBJECT, so a caller only ever reaches its own
+                        // responses; `idempotency.ts` states what that does not promise.
+                        if (idempotencyKey !== undefined && fingerprint !== undefined) {
+                            const lookup = idempotencyLookupQuery(idempotencySubjectRef, idempotencyKey);
+                            const prior = this.sql.exec(lookup.sql, ...lookup.params).toArray()[0];
+                            if (prior) {
+                                const replay = replayFor(idempotencyKey, fingerprint, prior);
+                                result = replay.result;
+                                // Only a guarded operation may report a tag (#129).
+                                if (guardedRef)
+                                    committedVersion = replay.entityVersion;
+                                replayed = true;
+                                return;
+                            }
+                        }
                         // #129: snapshot the version BEFORE the handler, compare AFTER it.
                         // Before, because the handler's own `emit` moves it; after, because the
                         // permission check lives inside the handler and must answer first — a
@@ -910,9 +1008,47 @@ export function defineScopeDO(modules, bareOps) {
                         // the handler and still inside the transaction.
                         if (guardedRef)
                             committedVersion = this.versionAt(guardedRef);
+                        // #116: recorded INSIDE the transaction, which is what makes a failed
+                        // request retried rather than replayed — it rolls back with the writes
+                        // it describes. The prune rides along, on the only path that adds a row.
+                        if (idempotencyKey !== undefined && fingerprint !== undefined) {
+                            const at = new Date().toISOString();
+                            const record = idempotencyRecordStatement(idempotencySubjectRef, idempotencyKey, operation, fingerprint, result, committedVersion, at);
+                            this.sql.exec(record.sql, ...record.params);
+                            const prune = idempotencyPruneStatement(at);
+                            this.sql.exec(prune.sql, ...prune.params);
+                        }
+                        if (impersonation?.mode === 'read-only')
+                            throw rollback;
                     });
                 }
                 catch (err) {
+                    // The read-only unwind, not a failure: `result` was assigned before the
+                    // throw and is the answer, while every row the handler wrote is gone.
+                    //
+                    // The acknowledgements ride along unchanged, because they are about
+                    // whether this DO UNDERSTOOD the arguments, not about what committed —
+                    // and a coordinator that sent `If-Match` to a read-only session must not
+                    // be told the host is too old to have evaluated it. The version reported
+                    // is the rolled-back one, which is the honest answer: nothing moved.
+                    if (err === rollback) {
+                        return {
+                            result,
+                            platformRequests: 0,
+                            impersonation: { honoured: true },
+                            ...(idempotencyKey !== undefined
+                                ? { idempotency: { keyHonoured: true, replayed } }
+                                : {}),
+                            ...(guardedRef
+                                ? {
+                                    concurrency: {
+                                        version: committedVersion,
+                                        ifMatchChecked: invokeOptions?.ifMatch !== undefined,
+                                    },
+                                }
+                                : {}),
+                        };
+                    }
                     // K-35: the transaction has rolled back; record a refused check now, as its own
                     // write (outside that transaction), so the denial survives the rollback.
                     if (err instanceof PermissionDenied) {
@@ -920,7 +1056,7 @@ export function defineScopeDO(modules, bareOps) {
                             ? { kind: 'system', id: systemModuleId }
                             : connectionId
                                 ? { kind: 'connection', id: connectionId }
-                                : { kind: 'principal', id: principal }, tenantId, operation, err);
+                                : { kind: 'principal', id: principal }, tenantId, operation, err, impersonation);
                     }
                     // The ORIGINAL error, deliberately: `invoke` flattens it for the envelope
                     // (which keeps its code and extensions) or rewraps it for the legacy throw
@@ -928,10 +1064,22 @@ export function defineScopeDO(modules, bareOps) {
                     throw err;
                 }
                 // Post-commit: drain the outbox to consumers, each delivery its own txn.
-                await this.dispatch(tenantId, scopeId);
+                // Skipped on a replay: nothing was written, so there is nothing this
+                // invocation added to drain. Anything the ORIGINAL left undrained is the
+                // outbox's own retry backstop, which is what that backstop is for.
+                if (!replayed)
+                    await this.dispatch(tenantId, scopeId);
                 return {
                     result,
                     platformRequests: signals.platformRequests,
+                    ...(impersonation ? { impersonation: { honoured: true } } : {}),
+                    // The acknowledgement the coordinator's skew check reads (#116), on the
+                    // same reasoning as `ifMatchChecked` below and with a sharper failure: a
+                    // DO too old to know about keys would EXECUTE THE OPERATION AGAIN and
+                    // return 200, which is the duplicate the header was sent to prevent.
+                    ...(idempotencyKey !== undefined
+                        ? { idempotency: { keyHonoured: true, replayed } }
+                        : {}),
                     // The acknowledgement the coordinator's skew check reads. Present only
                     // for a guarded operation, so an unguarded one costs nothing.
                     ...(guardedRef
@@ -1333,9 +1481,18 @@ export function defineScopeDO(modules, bareOps) {
                 throw new Error(`too many pending platform requests (${pending}); the delivery retries once some have drained`);
             }
             const id = platformRequestId.parse(ulid());
+            // K-42: the intent inherits the SOURCE EVENT's stamp rather than being written
+            // unstamped. Nobody is impersonating at this moment — the drain runs long after
+            // the session's invoke returned — but the intent exists BECAUSE of an event that
+            // was raised under one, and the platform drain is where an operator asks who
+            // caused an outbound effect. Read here rather than passed over the RPC: the DO
+            // owns the outbox, so a coordinator cannot claim a stamp or drop one.
+            const source = this.sql
+                .exec('SELECT impersonation FROM _substrat_outbox WHERE id = ?', eventId)
+                .toArray()[0];
             this.sql.exec(`INSERT INTO _substrat_platform_requests
-           (id, kind, payload, requested_by, status, attempts, requested_at)
-         VALUES (?, ?, ?, ?, 'pending', 0, ?)`, id, kind, payload, requestedBy, instant.parse(new Date().toISOString()));
+           (id, kind, payload, requested_by, impersonation, status, attempts, requested_at)
+         VALUES (?, ?, ?, ?, ?, 'pending', 0, ?)`, id, kind, payload, requestedBy, source?.impersonation ?? null, instant.parse(new Date().toISOString()));
             this.recordExecutorAttempt(eventId, deliveryId, null, null);
             return id;
         }
@@ -1682,7 +1839,8 @@ export function defineScopeDO(modules, bareOps) {
          * catch after the storage transaction has rolled back, so this write is its own and
          * survives — the whole point, since the denial is the write the operation could not make.
          */
-        recordDenial(subject, tenantId, operation, err) {
+        /** K-42: the session a refused call ran under travels with the denial row. */
+        recordDenial(subject, tenantId, operation, err, impersonation) {
             // Only an ENFORCED denial (assertAllowed, which attaches the checked permission +
             // node) is recorded. A module's own hand-thrown `new PermissionDenied('…')` carries
             // no permission key and is left to the module.
@@ -1694,8 +1852,8 @@ export function defineScopeDO(modules, bareOps) {
                     ? { connection: subject.id }
                     : subject.id;
             this.sql.exec(`INSERT INTO _substrat_denials
-           (id, actor, permission, tenant_id, scope_id, operation, at)
-         VALUES (?, ?, ?, ?, ?, ?, ?)`, ulid(), JSON.stringify(actor), err.permission, err.node.tenantId, err.node.scopeId ?? null, operation, new Date().toISOString());
+           (id, actor, permission, tenant_id, scope_id, operation, impersonation, at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, ulid(), JSON.stringify(actor), err.permission, err.node.tenantId, err.node.scopeId ?? null, operation, impersonation ? JSON.stringify(impersonationStampOf(impersonation)) : null, new Date().toISOString());
         }
         parseOutboxRow(row) {
             return domainEvent.parse({
@@ -1710,13 +1868,26 @@ export function defineScopeDO(modules, bareOps) {
                 piiClass: row.pii_class,
                 ...(row.subject_id ? { subjectId: row.subject_id } : {}),
                 ...(row.authorization ? { authorization: JSON.parse(row.authorization) } : {}),
+                // K-42: the stamp survives the read, so a consumer's event and an executor's
+                // are the same fact the stored row is. Absent rather than null when nobody
+                // was impersonating, because `DomainEvent.impersonation` is optional — the
+                // shape module code never sees is also the shape it cannot branch on.
+                ...(row.impersonation ? { impersonation: JSON.parse(row.impersonation) } : {}),
                 payload: row.payload === null ? undefined : JSON.parse(row.payload),
             });
         }
         // -- operation context (port of operationContext) -------------------------
         operationContext(principal, tenantId, scopeId, systemActor, connectionId, systemModuleId, 
         /** #458: per-invoke tally of `ctx.requestPlatform` calls; absent for consumer dispatch. */
-        signals) {
+        signals, 
+        /**
+         * K-42: the session this operation runs under, resolved by the coordinator
+         * from the directory and handed down. Read here and nowhere module code can
+         * reach — a vertical that could see it could branch on it, and "hide this row
+         * when support is looking" is the one behaviour this feature must make
+         * impossible.
+         */
+        impersonation) {
             const checker = this.checker;
             const relations = this.relations;
             const searchPlans = this.searchPlans;
@@ -1751,6 +1922,10 @@ export function defineScopeDO(modules, bareOps) {
             // invoke, so this does not leak across operations). `emit` snapshots it; a
             // system/override actor is unconditionally allowed, so its checks are not recorded.
             const passed = [];
+            // K-42: the two-actor stamp, computed once per operation. Every record this
+            // operation writes about who did what carries it, and module code can
+            // neither add it nor drop it.
+            const stamp = impersonation ? impersonationStampOf(impersonation) : undefined;
             /**
              * The scope host's half of `ctx.atomic` (#770) — everything else is the
              * kernel's (`createAtomic`).
@@ -1797,6 +1972,7 @@ export function defineScopeDO(modules, bareOps) {
                 sql: doScopedSql(sql),
                 now: () => at,
                 emit: (event) => {
+                    assertImpersonationWrites(impersonation, 'ctx.emit');
                     const parsed = domainEventInput.parse(event);
                     const full = domainEvent.parse({
                         ...parsed,
@@ -1806,13 +1982,16 @@ export function defineScopeDO(modules, bareOps) {
                         scopeId,
                         actor: systemActor ?? derivedActor,
                         ...(passed.length ? { authorization: passed.map((p) => ({ ...p })) } : {}),
+                        ...(stamp ? { impersonation: stamp } : {}),
                     });
                     sql.exec(`INSERT INTO _substrat_outbox
                (id, type, schema_version, occurred_at, tenant_id, scope_id, actor,
-                entity_type, entity_id, pii_class, subject_id, authorization, payload)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, full.id, full.type, full.schemaVersion, full.occurredAt, full.tenantId, full.scopeId, JSON.stringify(full.actor), full.entity.entityType, full.entity.entityId, full.piiClass, full.subjectId ?? null, full.authorization ? JSON.stringify(full.authorization) : null, full.payload === undefined ? null : JSON.stringify(full.payload));
+                entity_type, entity_id, pii_class, subject_id, authorization,
+                impersonation, payload)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, full.id, full.type, full.schemaVersion, full.occurredAt, full.tenantId, full.scopeId, JSON.stringify(full.actor), full.entity.entityType, full.entity.entityId, full.piiClass, full.subjectId ?? null, full.authorization ? JSON.stringify(full.authorization) : null, full.impersonation ? JSON.stringify(full.impersonation) : null, full.payload === undefined ? null : JSON.stringify(full.payload));
                 },
                 requestPlatform: (request) => {
+                    assertImpersonationWrites(impersonation, 'ctx.requestPlatform');
                     const input = platformRequestInput.parse(request);
                     // Backpressure (platform-intents.md): refuse when the scope already holds too many pending
                     // intents, so a stuck or runaway vertical cannot flood the platform drain.
@@ -1825,8 +2004,8 @@ export function defineScopeDO(modules, bareOps) {
                     const id = platformRequestId.parse(ulid());
                     const requestedBy = systemActor ?? derivedActor;
                     sql.exec(`INSERT INTO _substrat_platform_requests
-               (id, kind, payload, requested_by, status, attempts, requested_at)
-             VALUES (?, ?, ?, ?, 'pending', 0, ?)`, id, input.kind, JSON.stringify(input.payload ?? null), JSON.stringify(requestedBy), at);
+               (id, kind, payload, requested_by, impersonation, status, attempts, requested_at)
+             VALUES (?, ?, ?, ?, ?, 'pending', 0, ?)`, id, input.kind, JSON.stringify(input.payload ?? null), JSON.stringify(requestedBy), stamp ? JSON.stringify(stamp) : null, at);
                     if (signals)
                         signals.platformRequests += 1;
                     return id;
@@ -1895,6 +2074,7 @@ export function defineScopeDO(modules, bareOps) {
                  * than elevates.
                  */
                 grant: async (principal, permission, entity) => {
+                    assertImpersonationWrites(impersonation, 'ctx.grant');
                     const held = await runCheck(permission, entity);
                     if (!held.allowed) {
                         throw new PermissionDenied(`cannot grant '${permission}' on ${entity.entityType}:${entity.entityId} — ` +
@@ -1903,6 +2083,7 @@ export function defineScopeDO(modules, bareOps) {
                     sql.exec(`INSERT OR IGNORE INTO _substrat_tuples (subject, relation, object) VALUES (?, ?, ?)`, `principal:${principal}`, `granted:${permission}`, `${entity.entityType}:${entity.entityId}`);
                 },
                 revoke: async (principal, permission, entity) => {
+                    assertImpersonationWrites(impersonation, 'ctx.revoke');
                     const held = await runCheck(permission, entity);
                     if (!held.allowed) {
                         throw new PermissionDenied(`cannot revoke '${permission}' on ${entity.entityType}:${entity.entityId} — ` +
@@ -1912,6 +2093,7 @@ export function defineScopeDO(modules, bareOps) {
                 },
                 atomic: createAtomic(runSub, { passed, signals }),
                 link: (child, parent) => {
+                    assertImpersonationWrites(impersonation, 'ctx.link');
                     const allowed = relations.get(child.entityType);
                     if (!allowed?.has(parent.entityType)) {
                         throw new Error(`undeclared entity relation: ${child.entityType} → ${parent.entityType} ` +