@substrat-run/adapter-cloudflare 0.87.0 → 0.89.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, PermissionDenied, createAtomic, NotSearchable, isSearchIndexTable, searchIndexDdl, searchIndexMigrations, searchIndexPlans, NotListable, listIndexMigrations, listIndexPlans, listQuery, cursorOf, searchLimit, searchMatchExpression, searchQuery, } 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, 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';
@@ -211,6 +211,12 @@ const KERNEL_DDL = `
   );
   CREATE INDEX IF NOT EXISTS _substrat_attachments_entity
     ON _substrat_attachments (entity_type, entity_id);
+  -- #901: an entity's version is the ULID of the last event about it, so
+  -- 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
@@ -241,6 +247,27 @@ function toRpcError(err) {
 }
 /** The check subject for an attachment gate (#476): the connection when the connector door
  *  set one, else the principal — mirrors the invoke path's subject selection. */
+/**
+ * The entity a guarded operation's precondition is about (#129).
+ *
+ * `idFrom` is compile-checked to name an input field and the host has already
+ * parsed that input, so the field exists with its declared type. What remains
+ * possible is a field the schema lets the caller OMIT — and a precondition with no
+ * row to read is not a weaker check but an absent one, indistinguishable from one
+ * that passed. Refused rather than skipped.
+ *
+ * A module-level function rather than a method, so the pure adapter and this one
+ * are demonstrably answering with the same rule.
+ */
+function concurrencyRefOf(operation, guarded, parsed) {
+    const id = parsed?.[guarded.idFrom];
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new Error(`${operation} declares concurrency over '${guarded.entity}' keyed by ` +
+            `'${guarded.idFrom}', but the parsed input carries no such id — there is no ` +
+            'row whose version could be compared');
+    }
+    return { entityType: guarded.entity, entityId: id };
+}
 function attachSubject(principal, connectionId) {
     return connectionId ? { kind: 'connection', id: connectionId } : { kind: 'principal', id: principal };
 }
@@ -372,6 +399,16 @@ export function defineScopeDO(modules, bareOps) {
         sql;
         queue = new OperationQueue();
         operations = new Map();
+        /**
+         * #893: name → the declared input schema, parsed before guards and handler.
+         * Port of the pure adapter's map; `defineOperation` bindings with no
+         * declaration behind them stay unparsed, as they stay ungated.
+         */
+        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();
@@ -509,8 +546,45 @@ export function defineScopeDO(modules, bareOps) {
                 this.withdrawn.set(name, manifest.id);
                 this.operations.delete(name);
             }
+            // #893: a schema declared for an operation this module does not bind
+            // enforces nothing while reading as coverage — refused, as in the pure adapter.
+            const declaredInputs = registration.operationInputs ?? {};
+            const ownOps = new Set(Object.keys(registration.operations ?? {}));
+            const unbound = Object.keys(declaredInputs).filter((name) => !ownOps.has(name));
+            if (unbound.length > 0) {
+                throw new Error(`${manifest.id} declares operationInputs for unbound operation(s): ` +
+                    `${unbound.sort().join(', ')} — a schema on nothing reads as a parse that is not there`);
+            }
+            // Same rule for a declared precondition, and it matters more: a
+            // `concurrency` on an unbound name is a guarantee nothing enforces.
+            const declaredConcurrency = registration.operationConcurrency ?? {};
+            const unguarded = Object.keys(declaredConcurrency).filter((name) => !ownOps.has(name));
+            if (unguarded.length > 0) {
+                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
+                // never binds, and has nothing to parse for.
+                const schema = declaredInputs[name];
+                if (schema && this.operations.has(name))
+                    this.operationInput.set(name, schema);
+                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) {
@@ -745,19 +819,29 @@ export function defineScopeDO(modules, bareOps) {
          * an error either, because without this flag the DO throws. No flag day, and no
          * window where a failure reads as a success.
          */
-        failureEnvelope) {
+        failureEnvelope, 
+        /**
+         * #129: request preconditions, evaluated inside the operation's transaction.
+         *
+         * Unlike every other argument added to this RPC, silently ignoring this one
+         * would fail OPEN — the write commits with nothing compared. The reply
+         * therefore carries `concurrency.ifMatchChecked`, and a coordinator that
+         * 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) {
             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);
+                    return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions);
                 }
                 catch (err) {
                     throw toRpcError(err);
                 }
             }
             try {
-                return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId);
+                return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions);
             }
             catch (err) {
                 // The ONE place the error keeps its structure: flattened here, rebuilt by the
@@ -767,11 +851,14 @@ 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) {
+        async invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions) {
             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,
@@ -789,14 +876,55 @@ 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,
                     }))));
                 }
             }
+            // #893: parse, don't trust — at the scope door, from the operation's own
+            // declaration. Outside the queue and outside the transaction: a malformed
+            // call takes no turn and opens nothing. Guards read the parsed input too,
+            // so a K-17 pre-condition sees what the handler will.
+            const declaredInput = this.operationInput.get(operation);
+            const parsed = declaredInput ? declaredInput.parse(input) : input;
+            // #129. Refused rather than ignored, for the reason the coordinator refuses an
+            // unacknowledged one: a caller sending `If-Match` believes its write is
+            // conditional, and a 200 that compared nothing leaves that belief in place.
+            const guarded = this.operationConcurrency.get(operation);
+            if (invokeOptions?.ifMatch !== undefined && !guarded) {
+                throw new Error(`${operation} was called with If-Match but declares no \`concurrency\` — ` +
+                    '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
@@ -808,8 +936,51 @@ export function defineScopeDO(modules, bareOps) {
                 try {
                     await this.ctx.storage.transaction(async () => {
                         const ctx = this.operationContext(principal, tenantId, scopeId, undefined, connectionId, systemModuleId, signals);
-                        await this.runGuards(operation, ctx, input);
-                        result = await handler(ctx, input);
+                        // #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);
+                        }
                     });
                 }
                 catch (err) {
@@ -828,8 +999,32 @@ export function defineScopeDO(modules, bareOps) {
                     throw err;
                 }
                 // Post-commit: drain the outbox to consumers, each delivery its own txn.
-                await this.dispatch(tenantId, scopeId);
-                return { result, platformRequests: signals.platformRequests };
+                // 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,
+                    // 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 --------
@@ -1020,6 +1215,11 @@ export function defineScopeDO(modules, bareOps) {
                                                 last_status = excluded.last_status`, operation, at, status);
         }
         // -- guards (K-17) --------------------------------------------------------
+        /** This scope's spine, read under whatever transaction the caller already opened. */
+        versionAt(ref) {
+            const q = entityVersionQuery(ref);
+            return entityVersionOf(this.sql.exec(q.sql, ...q.params).toArray());
+        }
         async runGuards(operation, ctx, input) {
             const declared = this.guards.get(operation);
             if (!declared)
@@ -1310,6 +1510,32 @@ export function defineScopeDO(modules, bareOps) {
             }
             return result;
         }
+        // -- the denial log (K-35, #867) ------------------------------------------
+        // The refusals recorded in THIS scope's own database, read back. Authorization and
+        // the (tenantId, scopeId) K-3 cross-check happen on the coordinator before these
+        // RPCs are reached, exactly as for the introspection reads above.
+        /** A bounded page of raw denial rows, newest first. */
+        listDenials(filter) {
+            const q = denialListQuery(filter);
+            return this.sql.exec(q.sql, ...q.params).toArray().map(mapDenialRow);
+        }
+        /** The same log bucketed per (actor, permission), with the window's own facts. */
+        summarizeDenials(filter) {
+            const b = denialSummaryQuery(filter);
+            const buckets = this.sql.exec(b.sql, ...b.params).toArray().map(mapDenialBucketRow);
+            const t = denialTotalsQuery(filter);
+            const totals = this.sql.exec(t.sql, ...t.params).toArray()[0];
+            // Unfiltered on purpose — these describe the log, not the query (denial-query.ts).
+            const w = this.sql.exec(DENIAL_WINDOW_QUERY).toArray()[0];
+            return {
+                buckets,
+                total: Number(totals.total),
+                actors: Number(totals.actors),
+                windowOldestAt: w.oldest_at ?? null,
+                windowNewestAt: w.newest_at ?? null,
+                drained: Number(w.drained ?? 0),
+            };
+        }
         /**
          * A COMPLETE dump of this scope's DB (preview-and-snapshots.md §3) — every table
          * (incl. the `_substrat_*` spine), its DDL, and every row. No `.backup()` on DO
@@ -1693,6 +1919,14 @@ export function defineScopeDO(modules, bareOps) {
                     const q = platformRequestHistoryQuery(filter);
                     return sql.exec(q.sql, ...q.params).toArray().map(rowToPlatformRequest);
                 },
+                // #901. Mirror of the pure adapter, and the reason the contract suite
+                // runs on both: the query is ordinary SQL, but it is only a seek rather
+                // than a scan because of an index in spine DDL that workerd's regulator
+                // has to permit — which no amount of local green would surface.
+                versionOf: (entity) => {
+                    const q = entityVersionQuery(entity);
+                    return entityVersionOf(sql.exec(q.sql, ...q.params).toArray());
+                },
                 check: runCheck,
                 // #827. Mirror of the pure adapter: the plan comes from registration, the
                 // rows from this DO's own SQLite, and the index is maintained by triggers