@substrat-run/adapter-cloudflare 0.112.0 → 0.114.0

package/dist/scope-do.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-do.d.ts","sourceRoot":"","sources":["../src/scope-do.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAgDnD,OAAO,EA0BL,KAAK,kBAAkB,EAEvB,KAAK,gBAAgB,EAsCtB,MAAM,sBAAsB,CAAC;AAiB9B;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAyZD;uEACuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA6DD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAwDxD;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,kBAAkB,EAAE,EAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,GACxD,KAAK,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,UAAU,KAAK,aAAa,CAy2FjE"}
+{"version":3,"file":"scope-do.d.ts","sourceRoot":"","sources":["../src/scope-do.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAiDnD,OAAO,EA0BL,KAAK,kBAAkB,EAEvB,KAAK,gBAAgB,EAsCtB,MAAM,sBAAsB,CAAC;AAmB9B;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAiaD;uEACuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA6DD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAwDxD;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,kBAAkB,EAAE,EAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,GACxD,KAAK,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,UAAU,KAAK,aAAa,CA88FjE"}

package/dist/scope-do.js

@@ -1,9 +1,9 @@
 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, MAX_PENDING_SWEEP_RUNS, SWEEP_RUNS_KIND, platformRequest, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, listLimitOf, requestFingerprint, substratError, assertReplayableDump, } from '@substrat-run/contracts';
+import { ATTACHMENT_ADDED, ATTACHMENT_REMOVED, attachmentRecord, domainEvent, domainEventInput, eventId, instant, objectRef, toWireFailure, grantRefFromProof, principalId, platformRequestInput, platformRequestId, MAX_PENDING_PLATFORM_REQUESTS, MAX_PENDING_SWEEP_RUNS, SWEEP_RUNS_KIND, platformRequest, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, listLimitOf, requestFingerprint, substratError, assertReplayableDump, REDRAIN_BATCH, } from '@substrat-run/contracts';
 import { ulid, createUlid, assertAllowed, ConnectionSealingKeyUnavailableError, noSealingKeyMessage, sealTo, assertReadOnlyQuery, entitlementDenial, platformRequestHistoryQuery, PLATFORM_REQUEST_COLUMNS, denialListQuery, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialSummaryBuckets, PermissionDenied, assertImpersonationWrites, assertModuleEnqueueableKind, 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 { facetEvents, readHistory, walkEventCause, walkEventEffects } from '@substrat-run/kernel';
+import { facetEvents, readDeadLetters, readHistory, readInvocation, walkEventCause, walkEventEffects } from '@substrat-run/kernel';
 import { createDoTupleChecker, createLocalControlPlaneReader } from './checker.js';
 /**
  * The key marking a scope DO whose storage was destroyed (`destroyStorage`).
@@ -71,6 +71,12 @@ const KERNEL_DDL = `
     -- nothing was being delivered (an operation emitted it directly), or the row
     -- predates the column.
     caused_by TEXT,
+    -- #1237: the INVOCATION this event belongs to, minted by the transport and carried
+    -- on InvokeOptions. The spine could say what caused an event and which operation
+    -- emitted it, and still not say which two events came from the same call — the
+    -- runtime's request id is stamped by the log platform at ingestion, so no vertical
+    -- code can read it. NULL = the transport minted none, or the row predates the column.
+    invocation_id TEXT,
     drained_at TEXT
   );
   -- #1232: the freshness evaluator's read - MAX(occurred_at) per type, every pass,
@@ -771,6 +777,10 @@ export function defineScopeDO(modules, bareOps) {
                 // exists on the outbox but not on the envelope `parseOutboxRow` returns,
                 // whose `domainEvent.parse` strips anything it does not declare.
                 causedBy: r.caused_by ?? null,
+                // …and the invocation, for the same reason again: a lake that kept cause and
+                // dropped the call could say what set an event off and never which request did
+                // it, which is the grouping a trace is built on.
+                invocationId: r.invocation_id ?? null,
             }));
         }
         /**
@@ -802,6 +812,37 @@ export function defineScopeDO(modules, bareOps) {
                 return drained;
             });
         }
+        /**
+         * Reopen rows stamped strictly before `drainedBefore`, so the drain ships them again
+         * (#1334). The kernel contract says why the instant is required; this is the mechanism.
+         *
+         * Counted BEFORE the update, on `markEventsDrained`'s reasoning: `rowsWritten` includes
+         * index entries, and `_substrat_outbox_drained` leads with `drained_at`, so clearing N
+         * rows reports more than N writes. The queue has this scope to itself, so the count
+         * taken here is the count the update goes on to change.
+         *
+         * BOUNDED at `REDRAIN_BATCH`, and the caller loops until this returns 0. The outbox is
+         * never pruned, so "every stamped row before an instant" grows with the scope's whole
+         * lifetime — and this runs inside ONE Durable Object request, against a fixed budget.
+         * Unbounded, a big enough scope would exceed it, and exceed it again on every retry, so
+         * the one scope that most needs reopening could never make progress. Oldest first, so a
+         * partial run leaves a prefix of the window rather than holes scattered through it.
+         */
+        async redrainEvents(drainedBefore) {
+            return await this.queue.enqueue(() => {
+                const ids = this.sql
+                    .exec(`SELECT id FROM _substrat_outbox
+              WHERE drained_at IS NOT NULL AND drained_at < ?
+              ORDER BY id LIMIT ?`, drainedBefore, REDRAIN_BATCH)
+                    .toArray();
+                if (ids.length === 0)
+                    return 0;
+                // By id, not by the window again: the rows just chosen are exactly the rows
+                // cleared, so the count returned cannot drift from what the statement touched.
+                this.sql.exec(`UPDATE _substrat_outbox SET drained_at = NULL WHERE id IN (${ids.map(() => '?').join(',')})`, ...ids.map((r) => r.id));
+                return ids.length;
+            });
+        }
         /**
          * Facet this scope's own outbox (#1239) — `facetEvents`, which is the
          * sanctioned read: an erased payload yields the same NULL a missing field
@@ -834,6 +875,14 @@ export function defineScopeDO(modules, bareOps) {
         eventEffects(input) {
             return walkEventEffects({ sql: doScopedSql(this.sql) }, input.eventId, input.maxNodes);
         }
+        /** #1237: everything one call emitted, inside the DO where the outbox lives. */
+        invocationEvents(input) {
+            return readInvocation({ sql: doScopedSql(this.sql) }, input.invocationId, input.limit);
+        }
+        /** #1525: every delivery in this scope that gave up, inside the DO where both tables live. */
+        deadLetters(input) {
+            return readDeadLetters({ sql: doScopedSql(this.sql) }, { limit: input.limit, cursor: input.cursor });
+        }
         migrationBookmarks(limit = 20) {
             return this.sql
                 .exec(`SELECT bookmark, taken_at, pending FROM _substrat_migration_bookmarks
@@ -1098,153 +1147,176 @@ export function defineScopeDO(modules, bareOps) {
             // 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.
+            // `return await`, not a bare return: the work is QUEUED, and `try { return p }`
+            // runs its `finally` when the RETURN executes rather than when `p` settles — so
+            // the invocation id was cleared before the queued body had emitted anything.
+            return await this.queue.enqueue(async () => {
+                // #1237: the invocation this call belongs to, for the duration of it.
+                //
+                // Set INSIDE the queued body, which is the only region where one call holds the
+                // DO to itself. The input gate reopens around every await, and there are two
+                // before this point (`ensureMigrations`, `requestFingerprint`) — so assigning at
+                // the top of the RPC let a second call overwrite the field while the first was
+                // suspended, and the first would then emit under the second's id and clear it on
+                // the way out. `OperationQueue` is what makes this a plain field rather than a
+                // stack: the bodies do not interleave, so set-and-clear here brackets exactly
+                // one call. Same placement as the SQLite adapter's actor task, for this reason.
+                this.invocationId = invokeOptions?.invocationId ?? null;
                 try {
-                    await this.ctx.storage.transaction(async () => {
-                        const ctx = this.operationContext(principal, tenantId, scopeId, undefined, connectionId, systemModuleId, signals, impersonation, operation);
-                        // #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;
+                    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, impersonation, operation);
+                            // #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
+                            // precondition evaluated ahead of it turns the operation into a version
+                            // oracle for a principal who may not read the entity at all. The full
+                            // reasoning is on the pure adapter, which does the identical thing.
+                            const seen = guardedRef && invokeOptions?.ifMatch !== undefined
+                                ? this.versionAt(guardedRef)
+                                : undefined;
+                            await this.runGuards(operation, ctx, parsed);
+                            result = await handler(ctx, parsed);
+                            if (guardedRef && invokeOptions?.ifMatch !== undefined) {
+                                assertIfMatch(guardedRef, invokeOptions.ifMatch, seen ?? null);
+                            }
+                            // The tag describes the row as THIS write left it, so it is read after
+                            // 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,
+                                        },
+                                    }
+                                    : {}),
+                            };
                         }
-                        // #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
-                        // precondition evaluated ahead of it turns the operation into a version
-                        // oracle for a principal who may not read the entity at all. The full
-                        // reasoning is on the pure adapter, which does the identical thing.
-                        const seen = guardedRef && invokeOptions?.ifMatch !== undefined
-                            ? this.versionAt(guardedRef)
-                            : undefined;
-                        await this.runGuards(operation, ctx, parsed);
-                        result = await handler(ctx, parsed);
-                        if (guardedRef && invokeOptions?.ifMatch !== undefined) {
-                            assertIfMatch(guardedRef, invokeOptions.ifMatch, seen ?? null);
-                        }
-                        // The tag describes the row as THIS write left it, so it is read after
-                        // 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);
+                        // 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) {
+                            this.recordDenial(systemModuleId
+                                ? { kind: 'system', id: systemModuleId }
+                                : connectionId
+                                    ? { kind: 'connection', id: connectionId }
+                                    : { kind: 'principal', id: principal }, tenantId, operation, err, impersonation);
                         }
-                        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) {
-                        this.recordDenial(systemModuleId
-                            ? { kind: 'system', id: systemModuleId }
-                            : connectionId
-                                ? { kind: 'connection', id: connectionId }
-                                : { 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
+                        // path. Collapsing it here would lose the structure before either can look.
+                        throw err;
                     }
-                    // The ORIGINAL error, deliberately: `invoke` flattens it for the envelope
-                    // (which keeps its code and extensions) or rewraps it for the legacy throw
-                    // path. Collapsing it here would lose the structure before either can look.
-                    throw err;
+                    // Post-commit: drain the outbox to consumers, each delivery its own txn.
+                    // 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
+                            ? {
+                                concurrency: {
+                                    version: committedVersion,
+                                    ifMatchChecked: invokeOptions?.ifMatch !== undefined,
+                                },
+                            }
+                            : {}),
+                    };
+                }
+                finally {
+                    // Cleared on BOTH paths. The DO outlives the request, so a value left set here
+                    // is read by whatever runs next — an alarm-driven drain, a consumer retry —
+                    // and stamps its events with a call they had nothing to do with. A wrong
+                    // recorded fact, which is worse than the honest NULL this column uses.
+                    this.invocationId = null;
                 }
-                // Post-commit: drain the outbox to consumers, each delivery its own txn.
-                // 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
-                        ? {
-                            concurrency: {
-                                version: committedVersion,
-                                ifMatchChecked: invokeOptions?.ifMatch !== undefined,
-                            },
-                        }
-                        : {}),
-                };
             });
         }
         // -- attachments (#473): the metadata half of the attachment surface --------
@@ -1904,6 +1976,9 @@ export function defineScopeDO(modules, bareOps) {
                 // null is honestly "unrecorded" for every legacy row — nothing can go back and
                 // decide what a past consumer was reacting to.
                 'ALTER TABLE _substrat_outbox ADD COLUMN caused_by TEXT',
+                // #1237: the invocation column on a DO created before it. Nullable, and the
+                // null is honestly "none was carried" for every legacy row.
+                'ALTER TABLE _substrat_outbox ADD COLUMN invocation_id TEXT',
             ]) {
                 try {
                     this.sql.exec(alter);
@@ -1913,6 +1988,19 @@ export function defineScopeDO(modules, bareOps) {
                         throw err;
                 }
             }
+            // #1237: `readInvocation`'s lookup — WHERE invocation_id = ? ORDER BY id — over an outbox
+            // that is never pruned. No index leads with invocation_id, so without this one SQLite
+            // walks the PRIMARY KEY from the oldest event until it reaches the call, and reading a
+            // recent invocation costs the scope's lifetime event count. The trailing id gives the
+            // ORDER BY for free, as it does on `_substrat_outbox_drained`.
+            //
+            // HERE, after the column is ensured, and deliberately NOT in KERNEL_DDL beside the
+            // other outbox indexes. KERNEL_DDL runs FIRST on every wake, and on a scope created
+            // before #1237 its `CREATE TABLE IF NOT EXISTS` does not add the column — so an index
+            // naming invocation_id there throws "no such column" and every existing scope fails to
+            // boot. `lint:spine-ddl` compares KERNEL_DDL's indexes only, so this one is held to
+            // both adapters by the query-plan test rather than by that gate.
+            this.sql.exec('CREATE INDEX IF NOT EXISTS _substrat_outbox_invocation ON _substrat_outbox (invocation_id, id)');
         }
         async importDump(tables, destScopeId) {
             // The WHOLE drop-then-replay runs under deferred foreign keys, in one transaction.
@@ -2103,6 +2191,15 @@ export function defineScopeDO(modules, bareOps) {
          * another scope's emit the moment a consumer awaits.
          */
         causedBy = null;
+        /**
+         * #1237: the invocation currently running in this DO, or null.
+         *
+         * DO-local, like `causedBy` and for a simpler reason: a Durable Object IS one
+         * scope, so there is no other scope's call to confuse it with. It still has to be
+         * cleared, because the DO outlives the request and a value left set would stamp a
+         * later alarm-driven drain with a call it had nothing to do with.
+         */
+        invocationId = null;
         async dispatch(tenantId, scopeId) {
             for (let round = 0; round < 50; round++) {
                 let deliveredAny = false;
@@ -2335,8 +2432,8 @@ export function defineScopeDO(modules, bareOps) {
                     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,
-                impersonation, operation, version, caused_by, 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.operation ?? null, 
+                impersonation, operation, version, caused_by, invocation_id, 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.operation ?? null, 
                     // #1242: script configuration, not envelope data — the version is a fact
                     // about the deploy, so it never rides `DomainEvent` for module code to
                     // branch on; it exists for the observability joins the column serves.
@@ -2344,7 +2441,9 @@ export function defineScopeDO(modules, bareOps) {
                     // #1237: whatever delivery is in flight, if any — read off the DO the same
                     // way the version is read off its env. A fact about the surrounding
                     // dispatch, never envelope data module code could set or branch on.
-                    this.causedBy, full.payload === undefined ? null : JSON.stringify(full.payload));
+                    this.causedBy, 
+                    // #1237: a fact about the surrounding CALL, like the version above.
+                    this.invocationId, full.payload === undefined ? null : JSON.stringify(full.payload));
                 },
                 requestPlatform: (request) => {
                     assertImpersonationWrites(impersonation, 'ctx.requestPlatform');