@substrat-run/kernel 0.87.0 → 0.89.0

package/dist/idempotency.js

@@ -0,0 +1,197 @@
+import { IDEMPOTENCY_REPLAY_UNAVAILABLE, IDEMPOTENCY_RESULT_LIMIT, IDEMPOTENCY_RETENTION_MS, IDEMPOTENCY_REUSED, isValidIdempotencyKey, subjectRef, substratError, } from '@substrat-run/contracts';
+/**
+ * The spine half of request idempotency (#116) — what remembers a key, and what
+ * a second request carrying it is answered with.
+ *
+ * `@substrat-run/contracts` owns the wire (the header names, what makes a key
+ * well-formed, what makes two requests the same request); this owns the table
+ * and the decisions read off it. Both adapters call these rather than writing
+ * the SQL twice, for the reason `entityVersionQuery` gives one file over: two
+ * surfaces answering one question must not drift on what the answer means. Here
+ * the answer decides whether work happens at all.
+ *
+ * ## Recorded INSIDE the operation's transaction, which is the whole design
+ *
+ * The row is written in the same transaction as the work it describes, after the
+ * handler and before `COMMIT`. Three properties fall out of that one placement,
+ * and none of them needed a mechanism of its own:
+ *
+ * - **A failed request is retried, not replayed.** The operation threw, the
+ *   transaction rolled back, and the row went with it. There is nothing to find,
+ *   so the retry executes — which is correct, because nothing happened the first
+ *   time. Recording failures would have meant deciding which of them are
+ *   permanent, and that is a judgement no generic layer can make.
+ * - **A replayed response describes work that actually committed.** The row and
+ *   the rows it is about are the same transaction; there is no window in which
+ *   one exists without the other.
+ * - **The dedupe cannot be defeated by a concurrent retry.** Invokes serialise
+ *   per scope in both adapters, so the second request takes its turn after the
+ *   first has committed — no in-flight state, no "still processing" 409.
+ *
+ * ## What a replay is NOT
+ *
+ * It is not a fresh authorization. The recorded response is returned without
+ * running the handler, and the permission check lives inside the handler — so a
+ * caller whose access was revoked in the last 24 hours can still replay their own
+ * response. This is bounded by the two things that make it defensible: the row is
+ * keyed by the SUBJECT, so a caller can only ever reach responses they themselves
+ * received, and the window is a day. It is stated here rather than discovered,
+ * because the alternative — re-running the operation to re-check the permission —
+ * is the duplicate execution this feature exists to prevent.
+ */
+/**
+ * The dedupe table, kernel-owned so that no vertical carries a migration for it.
+ *
+ * Keyed `(subject, key)` rather than `(key)`, and that is a safety property, not
+ * a namespacing convenience: a key is a string a client chose, two clients will
+ * choose `1`, and a lookup that found the other one's row would replay a response
+ * across a principal boundary. With the subject in the primary key that is not a
+ * check that could be forgotten — it is a row that cannot be reached.
+ *
+ * `operation` is stored as well as hashed into `fingerprint`. The hash is what
+ * decides a mismatch; the column is what makes the table readable when someone is
+ * working out why a client is getting 409s.
+ */
+export const IDEMPOTENCY_DDL = `
+  CREATE TABLE IF NOT EXISTS _substrat_idempotency (
+    subject TEXT NOT NULL,
+    key TEXT NOT NULL,
+    operation TEXT NOT NULL,
+    -- SHA-256 over (operation, parsed input). A second request under this key
+    -- whose fingerprint differs is a REUSE, refused with 409 — never served the
+    -- first request's response, which is a different request's answer.
+    fingerprint TEXT NOT NULL,
+    -- The operation's return value as JSON. NULL means one of two things, which
+    -- \`oversized\` separates: the operation returned nothing, or the result was
+    -- too large to record and a replay must be refused rather than re-executed.
+    result TEXT,
+    oversized INTEGER NOT NULL DEFAULT 0,
+    -- #129's tag, replayed with the body so a retry hands the client the same
+    -- ETag the original did. Without it a replayed response has no validator and
+    -- the client's next conditional write has nothing to send.
+    entity_version TEXT,
+    recorded_at TEXT NOT NULL,
+    PRIMARY KEY (subject, key)
+  );
+  CREATE INDEX IF NOT EXISTS _substrat_idempotency_recorded
+    ON _substrat_idempotency (recorded_at);
+`;
+/** The subject a key is scoped to, in the form the column stores. */
+export function idempotencySubject(subject) {
+    return subjectRef(subject);
+}
+/**
+ * Refuse a malformed key at the door.
+ *
+ * `validation_failed` rather than `conflict`: nothing is in conflict, the caller
+ * sent a header we cannot store. Refused rather than ignored, for the reason the
+ * `If-Match` path gives — a caller who believes their retry is safe and whose
+ * key was silently dropped is in exactly the position this feature exists to
+ * prevent, arrived at through the feature itself.
+ */
+export function assertIdempotencyKey(key) {
+    if (isValidIdempotencyKey(key))
+        return;
+    throw substratError('validation_failed', 'Idempotency-Key must be 1-255 visible ASCII characters with no spaces');
+}
+/** The lookup a retry is answered from. */
+export function idempotencyLookupQuery(subject, key) {
+    return {
+        sql: 'SELECT operation, fingerprint, result, oversized, entity_version ' +
+            'FROM _substrat_idempotency WHERE subject = ? AND key = ?',
+        params: [idempotencySubject(subject), key],
+    };
+}
+/**
+ * Decide what a second request under this key gets.
+ *
+ * Two refusals and one replay, both refusals `conflict` (409) with a reason slug
+ * this feature owns:
+ *
+ * - **Reuse.** Same key, different request. The client's assertion that this is
+ *   the request it sent before is false, and the one thing that must not happen
+ *   is serving the earlier request's response to it.
+ * - **Unavailable.** The original response was too large to record. Refused
+ *   rather than re-executed, which is the fail-closed direction: an error the
+ *   caller can act on, instead of the duplicate work the key was sent to avoid.
+ */
+export function replayFor(key, fingerprint, row) {
+    if (row.fingerprint !== fingerprint) {
+        throw substratError('conflict', `Idempotency-Key '${key}' was already used for a different request ` +
+            `(${row.operation}). A key identifies one request; use a fresh one`, { reason: IDEMPOTENCY_REUSED });
+    }
+    if (row.oversized !== 0) {
+        throw substratError('conflict', `the original response for Idempotency-Key '${key}' was too large to record, ` +
+            'so this retry cannot be answered from it — the original request did complete, ' +
+            'and re-running it would duplicate the work the key exists to prevent', { reason: IDEMPOTENCY_REPLAY_UNAVAILABLE });
+    }
+    return {
+        result: row.result === null ? undefined : JSON.parse(row.result),
+        entityVersion: row.entity_version,
+    };
+}
+/**
+ * The row a completed operation leaves behind.
+ *
+ * Serialisation happens here rather than at each call site so the size decision
+ * has one home: over `IDEMPOTENCY_RESULT_LIMIT` the body is dropped and the key
+ * is recorded as oversized, which is what makes a later replay a refusal instead
+ * of a silent re-execution.
+ *
+ * `undefined` and `null` results are both stored as a NULL body with
+ * `oversized = 0`; a replay returns `undefined` for either. An operation whose
+ * return value a caller distinguishes on that difference has a bigger problem
+ * than this table.
+ */
+export function idempotencyRecordStatement(subject, key, operation, fingerprint, result, entityVersion, at) {
+    const serialised = result === undefined ? null : JSON.stringify(result) ?? null;
+    const oversized = serialised !== null && serialised.length > IDEMPOTENCY_RESULT_LIMIT;
+    return {
+        sql: 'INSERT INTO _substrat_idempotency ' +
+            '(subject, key, operation, fingerprint, result, oversized, entity_version, recorded_at) ' +
+            'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+        params: [
+            idempotencySubject(subject),
+            key,
+            operation,
+            fingerprint,
+            oversized ? null : serialised,
+            oversized ? 1 : 0,
+            entityVersion,
+            at,
+        ],
+    };
+}
+/**
+ * Age rows out, in the same transaction as the write that added one.
+ *
+ * Opportunistic rather than swept, deliberately. A sweeper would be a second
+ * schedule, a second failure mode and a second thing to deploy, for a table whose
+ * only writer is already here holding a transaction open. Bounded work: the
+ * `recorded_at` index makes it a range delete, and it runs only on an invocation
+ * that carried a key — so a fleet that never uses the feature never pays for it.
+ *
+ * The consequence worth stating: a scope that stops receiving keyed requests
+ * keeps its last rows past the window. They are inert (nothing reads a row
+ * without a key that matches it) and the next keyed request clears them.
+ */
+export function idempotencyPruneStatement(now) {
+    const cutoff = new Date(Date.parse(now) - IDEMPOTENCY_RETENTION_MS).toISOString();
+    return {
+        sql: 'DELETE FROM _substrat_idempotency WHERE recorded_at < ?',
+        params: [cutoff],
+    };
+}
+/**
+ * The refusal an operation that declared `idempotency: false` answers a key with.
+ *
+ * Not a `conflict` — nothing conflicts — and not silence, which is the failure
+ * mode every branch of this feature is written to avoid. The operation opted out
+ * because its response must not be recorded; a caller who sent a key and got a
+ * 200 would believe a retry is safe when the second one will execute again.
+ */
+export function idempotencyOptedOutMessage(operation) {
+    return (`${operation} declares \`idempotency: false\` and cannot honour an Idempotency-Key — ` +
+        'its response is not recorded, so a retry would execute it a second time');
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.js.map

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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { AccessLogFilter, AttachmentUploadInput, AuditLogFilter, BlobStoreProvisionInput, BlobStoreRecord, ConsumerHandler, ExecutorDeadLetter, ExecutorDrainReport, ExecutorHandler, ExecutorRetryPolicy, ConnectorConnection, ScopedConnectorConnection, ConnectorContext, ConnectorHandler, ConnectorOptions, ConnectorRequestInit, ConnectorResponse, Clock, FetchLike, GuardPredicate, HostAdmin, MigrateScopeOutcome, MigrationFrontier, ModuleRegistration, ConsumersOf, EventContract, EventPayloadOf, EventTypeOf, TypedConsumerHandler, TypedConsumers, OpenedAttachment, OperationContext, PageParams, OperationHandler, OpsFailureFilter, OpsFailureInput, ProvisionScopeInput, RoleFilter, ScheduleRegistration, ScheduleRunReport, ScopeAttachments, ScopedSql, ScopeFilter, ScopeHost, ScopeStub, ScopeStubOptions, SqlMigration, SqlValue, TenantBlobStore, TenantRelationalStore, TenantStoreProvisionInput, TenantStoreRecord, } from './scope-host.js';
+export type { AccessLogFilter, AttachmentUploadInput, AuditLogFilter, BlobStoreProvisionInput, BlobStoreRecord, ConsumerHandler, ExecutorDeadLetter, ExecutorDrainReport, ExecutorHandler, ExecutorRetryPolicy, ConnectorConnection, ScopedConnectorConnection, ConnectorContext, ConnectorHandler, ConnectorOptions, ConnectorRequestInit, ConnectorResponse, Clock, FetchLike, GuardPredicate, HostAdmin, MigrateScopeOutcome, MigrationFrontier, ModuleRegistration, ConsumersOf, EventContract, EventPayloadOf, EventTypeOf, TypedConsumerHandler, TypedConsumers, OpenedAttachment, OperationContext, PageParams, OperationHandler, OpsFailureFilter, OpsFailureInput, ProvisionScopeInput, RoleFilter, ScheduleRegistration, ScheduleRunReport, ScopeAttachments, ScopedSql, ScopeFilter, ScopeHost, ScopeStub, ScopeStubOptions, InvokeOptions, SqlMigration, SqlValue, TenantBlobStore, TenantRelationalStore, TenantStoreProvisionInput, TenantStoreRecord, } from './scope-host.js';
 export { attachmentBlobKey, consumersFor, entitlementDenial, backoffAt, parseValidationRecords, resolveRetryPolicy, OPS_FAILURE_RETENTION_DAYS, } from './scope-host.js';
 export { isSecretBoxConfigured, SecretBoxUnconfiguredError, unconfiguredSecretBox, webCryptoSecretBox, } from './secret-box.js';
 export type { SealedSecret, SecretBox } from './secret-box.js';
@@ -25,6 +25,11 @@ export { readRoutedNode, RouterAssertionError } from './routed-node.js';
 export type { RoutedNode, HeaderReader } from './routed-node.js';
 export { assertPlatformCall, PlatformCallError, PLATFORM_SECRET_HEADER, PLATFORM_REQUEST_HEADER, CONNECTOR_ATTACHMENT_RECORD_HEADER, } from './platform-call.js';
 export { PLATFORM_REQUEST_COLUMNS, platformRequestHistoryQuery, } from './platform-request-query.js';
+export { DENIAL_COLUMNS, DENIAL_WINDOW_QUERY, denialListQuery, denialSummaryQuery, denialTotalsQuery, mapDenialRow, mapDenialBucketRow, storedActor, type DenialRow, type DenialBucketRow, type DenialWindowRow, } from './denial-query.js';
+export { entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, type EntityVersion, type EntityVersionRow, } from './entity-version.js';
+export { readTimeline, readHistory } from './timeline.js';
+export type { TimelineReader } from './timeline.js';
+export { IDEMPOTENCY_DDL, assertIdempotencyKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencySubject, idempotencyOptedOutMessage, replayFor, type IdempotencyRow, type IdempotentReplay, } from './idempotency.js';
 export { isTerminalDispatchFailure, isTerminalProviderError, providerErrorStatus, RETRYABLE_CLIENT_STATUSES, } from './provider-error.js';
 export { runPlatformSweep, startPlatformSweeper } from './platform-sweep.js';
 export type { AccessLogSink, AccessLogSweepReport, ConnectorSweeper, MigrationSweepReport, PlatformSweepOptions, PlatformSweepReport, PlatformSweeperHandle, ScheduleSweepReport, StartPlatformSweeperOptions, } from './platform-sweep.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -14,6 +14,10 @@ export { assertReadOnlyQuery } from './read-only-sql.js';
 export { readRoutedNode, RouterAssertionError } from './routed-node.js';
 export { assertPlatformCall, PlatformCallError, PLATFORM_SECRET_HEADER, PLATFORM_REQUEST_HEADER, CONNECTOR_ATTACHMENT_RECORD_HEADER, } from './platform-call.js';
 export { PLATFORM_REQUEST_COLUMNS, platformRequestHistoryQuery, } from './platform-request-query.js';
+export { DENIAL_COLUMNS, DENIAL_WINDOW_QUERY, denialListQuery, denialSummaryQuery, denialTotalsQuery, mapDenialRow, mapDenialBucketRow, storedActor, } from './denial-query.js';
+export { entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, } from './entity-version.js';
+export { readTimeline, readHistory } from './timeline.js';
+export { IDEMPOTENCY_DDL, assertIdempotencyKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencySubject, idempotencyOptedOutMessage, replayFor, } from './idempotency.js';
 export { isTerminalDispatchFailure, isTerminalProviderError, providerErrorStatus, RETRYABLE_CLIENT_STATUSES, } from './provider-error.js';
 export { runPlatformSweep, startPlatformSweeper } from './platform-sweep.js';
 export { MIGRATION_FLAG_THRESHOLD, migrationFleet, migrationProgress, migrationSummary, scopeMigrationState, } from './migration-progress.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsDA,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,sBAAsB,EACtB,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,oCAAoC,EACpC,sBAAsB,EACtB,mBAAmB,EACnB,UAAU,EACV,MAAM,EACN,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EACL,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,SAAS,EACT,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAOzB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExE,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,kCAAkC,GACnC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAY7E,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuDA,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,sBAAsB,EACtB,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,oCAAoC,EACpC,sBAAsB,EACtB,mBAAmB,EACnB,UAAU,EACV,MAAM,EACN,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EACL,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,SAAS,EACT,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAOzB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExE,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,kCAAkC,GACnC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,WAAW,GAIZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,kBAAkB,EAClB,0BAA0B,EAC1B,SAAS,GAGV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAY7E,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/scope-host.d.ts

@@ -1,6 +1,7 @@
-import type { AdminAction, ListPage, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, BindHostnameInput, AdminLogEntry, OpsFailureEntry, CapabilityGrant, CreateTenantInput, Decision, Instant, DomainEvent, DomainEventInput, PlatformRequestInput, PlatformRequestId, PlatformRequest, PlatformRequestFilter, PlatformRequestStatus, PlatformRequestFailure, EntitlementGrant, EntitlementGrantInput, EntitlementView, MeterReading, EntityRef, IdentityLink, IdentityPool, Jurisdiction, ModuleId, ModuleManifest, ScheduleSpec, SystemGrant, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, RouteTarget, DirectoryDump, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, ScopeTablePage, StorageShape, Tenant, TenantId, TenantRole, TenantStoreHandle, AttachmentRecord, BlobStoreHandle, Visibility, Vertical, VerticalChannel, VerticalVersion, TenantStatus, Page, CountedPage } from '@substrat-run/contracts';
+import type { AdminAction, ListPage, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, BindHostnameInput, AdminLogEntry, OpsFailureEntry, CapabilityGrant, CreateTenantInput, Decision, Instant, DomainEvent, DomainEventInput, PlatformRequestInput, PlatformRequestId, PlatformRequest, PlatformRequestFilter, PlatformRequestStatus, PlatformRequestFailure, EntitlementGrant, EntitlementGrantInput, EntitlementView, MeterReading, EntityRef, IdentityLink, IdentityPool, Jurisdiction, ModuleId, ModuleManifest, ScheduleSpec, SystemGrant, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, RouteTarget, DirectoryDump, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, DenialFilter, DenialSummary, PermissionDenial, ScopeTablePage, StorageShape, Tenant, TenantId, TenantRole, TenantStoreHandle, AttachmentRecord, BlobStoreHandle, Visibility, Vertical, VerticalChannel, VerticalVersion, TenantStatus, Page, CountedPage } from '@substrat-run/contracts';
 import type { SealedSecret } from './secret-box.js';
 import type { SearchHit, SearchOptions } from './search-index.js';
+import type { EntityVersion } from './entity-version.js';
 /**
  * What a caller asks a paged read for (#811).
  *
@@ -107,6 +108,39 @@ export interface OperationContext {
      * code writing `_substrat_*`), so an intent's status is only ever the platform's answer.
      */
     platformRequests(filter?: PlatformRequestFilter): PlatformRequest[];
+    /**
+     * This entity's version (#901) — the ULID of the last event about it, or
+     * `null` if nothing has ever been emitted about it.
+     *
+     * There is no version column anywhere, and there is deliberately not going to
+     * be one: `_substrat_outbox` has recorded `entity_type` and `entity_id`
+     * against a monotonic ULID since it was written, so every mutation that
+     * followed the fat-event rule already versioned the thing it touched. See
+     * `entity-version.ts` for why the alternative — a `_version` column bumped by
+     * an emitted trigger — was rejected despite working.
+     *
+     * ```ts
+     * const before = ctx.versionOf({ entityType: 'customer', entityId: id });
+     * // …mutate, emit…
+     * ctx.versionOf({ entityType: 'customer', entityId: id }) !== before  // true
+     * ```
+     *
+     * **Conservative, by construction.** ANY event about the entity moves this,
+     * including one that changed nothing the caller read. A precondition built on
+     * it can refuse a write that would have been safe; it cannot admit one that
+     * would not. That is the correct direction to fail, and it is a real
+     * difference from a per-row counter.
+     *
+     * Rule 3 permits a projection read of `_substrat_*`, so a vertical *could*
+     * hand-roll this `SELECT`. It should not: the spine's schema is private and a
+     * vertical pinned to it is pinned to a table the kernel may re-shape. Same
+     * reasoning as `platformRequests`.
+     *
+     * **Checks no permission** — nothing on `ctx` does. A version is not a read of
+     * the entity, but it is evidence the entity exists, so an operation that hands
+     * one to an untrusted caller does its own `assertAllowed` first.
+     */
+    versionOf(entity: EntityRef): EntityVersion | null;
     /** Node-level check; pass `entity` for per-entity checks (portal access, §4.2 rule 3). */
     check(permission: PermissionKey, entity?: EntityRef): Promise<Decision>;
     /**
@@ -284,11 +318,85 @@ export interface OperationContext {
     atomic<T>(fn: () => T | Promise<T>): Promise<T>;
 }
 export type OperationHandler<I = unknown, O = unknown> = (ctx: OperationContext, input: I) => O | Promise<O>;
+/**
+ * The per-invocation transport channel: what the caller requires to be true
+ * before the operation runs, and the transport facts it needs back (#129, #116).
+ *
+ * A separate parameter rather than fields on the input, because these are facts
+ * about the REQUEST and not about the domain. A handler's declared input is what
+ * the operation MEANS, and threading a retry token or an entity tag through it
+ * would make every in-process caller state something it does not have.
+ * `mountOperations` reads them off headers; a test, a seed or a schedule omits
+ * them entirely.
+ *
+ * Per INVOCATION rather than on `ScopeStubOptions`, where `onPlatformRequests`
+ * lives, and the difference is not stylistic. A stub is minted by the vertical's
+ * own `resolveStub`, so anything hung off it requires that vertical to cooperate;
+ * `If-Match` and the `ETag` are wholly the mount's business and must work with no
+ * change to a vertical at all. They are also genuinely per-call — one stub serves
+ * one request, but nothing in the contract says so.
+ *
+ * Deliberately one bag rather than a parameter per concern. `If-Match` and
+ * `Idempotency-Key` are ONE precondition pass at one point in the invoke — before
+ * the guards, inside the transaction — which is what #116's note asked of
+ * whichever landed first. #129 built the bag; #116 declared into it and added no
+ * second interception point.
+ */
+export interface InvokeOptions {
+    /**
+     * The version the caller believes it is writing over, verbatim from `If-Match`
+     * (quoted, and possibly a list — `ifMatchAdmits` owns the parsing).
+     *
+     * Honoured only by an operation that DECLARES `concurrency`. Sending it to one
+     * that does not is an error rather than a no-op: a caller who believes it is
+     * protected and is not is the failure this whole mechanism exists to prevent,
+     * and silence is exactly how that belief survives.
+     */
+    readonly ifMatch?: string;
+    /**
+     * Called after a guarded operation COMMITS, with the entity's version as it
+     * stands at commit — the `ETag` the transport hands back.
+     *
+     * Read after the handler and inside the same transaction, so the tag describes
+     * the row as the caller's own write left it rather than as the caller found it.
+     * A client that echoed back what it sent would loop on its own stale value.
+     *
+     * Never called for a rolled-back operation, and never for an operation that
+     * declares no `concurrency`: a version that did not survive its transaction is
+     * not a tag anyone may hold, and an operation that opted out must not pay for a
+     * spine read on every invocation.
+     */
+    readonly onEntityVersion?: (version: string | null) => void;
+    /**
+     * The client's retry token, verbatim from `Idempotency-Key` (#116).
+     *
+     * Honoured by every operation on an unsafe method — there is no declaration to
+     * make, because a retried write creating a second entity is a hazard on all of
+     * them. The exception is an operation that declared `idempotency: false`, whose
+     * response must not be recorded; sending a key to one is an error rather than a
+     * no-op, for the same reason an unhonoured `If-Match` is.
+     *
+     * A first request under a key runs, and its return value is recorded inside the
+     * operation's own transaction. A second request under the same key returns that
+     * recording without running the handler. A second request under the same key
+     * with a DIFFERENT input is refused — a key names one request, and serving the
+     * first one's response to a second one would be a lie a client acts on.
+     */
+    readonly idempotencyKey?: string;
+    /**
+     * Called when this invocation was answered from a recording rather than run.
+     *
+     * The transport sets `Idempotency-Replayed` from it. Advisory: a caller that
+     * ignores this is not wrong about anything, it simply cannot tell a retry from
+     * a first request — which is enough of a debugging cost to be worth a callback.
+     */
+    readonly onIdempotentReplay?: () => void;
+}
 /** The capability stub — the ONLY way code outside the scope reaches it. */
 export interface ScopeStub {
     readonly tenantId: TenantId;
     readonly scopeId: ScopeId;
-    invoke<O = unknown, I = unknown>(operation: string, input?: I): Promise<O>;
+    invoke<O = unknown, I = unknown>(operation: string, input?: I, options?: InvokeOptions): Promise<O>;
 }
 /**
  * Observers a caller may attach when minting a stub (#458). Harness-level, not
@@ -801,6 +909,80 @@ export interface ModuleRegistration<C extends readonly EventContract[] = []> {
     manifest: ModuleManifest;
     migrations?: SqlMigration[];
     operations?: Record<string, OperationHandler<never, unknown>>;
+    /**
+     * name → the schema the host parses an invocation's input against, BEFORE the
+     * guards and the handler see it (#893).
+     *
+     * Derived from the declared operation surface — `operationInputsOf(ops)` — and
+     * never written a second time. A module that declares its operations gets the
+     * parse by handing the same object over:
+     *
+     * ```ts
+     * operations: { 'rally/book': bookOp, … },
+     * operationInputs: operationInputsOf(rallyOperations),
+     * ```
+     *
+     * **This is where "parse, don't trust" is kept, rather than in 85 handlers.**
+     * `OperationShape.input` calls itself *"the SAME Zod object the handler
+     * parses"* and across the fleet it mostly was not — rally declared 32 inputs
+     * and parsed 2. One place that cannot be forgotten beats a rule every new
+     * operation has to remember, which is the same argument `mountOperations`
+     * already makes for the page trio.
+     *
+     * A name here that no operation binds is an error: it is a schema enforcing
+     * nothing, and it reads as coverage. A bound operation with no entry is
+     * allowed and means what it always meant — nothing was declared to parse.
+     *
+     * Typed structurally rather than as `z.ZodType` so the kernel keeps its single
+     * dependency and no zod version is pinned by the scope-host contract. The
+     * shape is the whole surface the host uses: throw to refuse, return the value
+     * to accept.
+     */
+    operationInputs?: Record<string, {
+        parse(value: unknown): unknown;
+    }>;
+    /**
+     * name → the entity whose version this operation's `If-Match` is compared
+     * against, and the input field carrying its id (#129).
+     *
+     * Derived from the declared operation surface — `operationConcurrencyOf(ops)` —
+     * and never written a second time, exactly as `operationInputs` is:
+     *
+     * ```ts
+     * operations: { 'callout/update-customer': updateCustomerOp, … },
+     * operationInputs: operationInputsOf(calloutOperations),
+     * operationConcurrency: operationConcurrencyOf(calloutOperations),
+     * ```
+     *
+     * **The host compares, not the handler.** A precondition a handler evaluates is
+     * a precondition a handler can forget, and the one that is forgotten is
+     * indistinguishable from one that passed. Here the comparison happens between
+     * `BEGIN` and the guards for every caller and every transport, or the operation
+     * does not claim to have it.
+     *
+     * A name here that no operation binds is an error, for the same reason it is on
+     * `operationInputs`: it reads as coverage while enforcing nothing.
+     */
+    operationConcurrency?: Record<string, {
+        entity: string;
+        idFrom: string;
+    }>;
+    /**
+     * The operations that declared `idempotency: false` (#116) — the ones whose
+     * response must not be recorded, and which therefore refuse an
+     * `Idempotency-Key` instead of honouring it.
+     *
+     * Derived like the two above, and never written a second time:
+     *
+     * ```ts
+     * operationIdempotencyOptOuts: operationIdempotencyOptOutsOf(calloutOperations),
+     * ```
+     *
+     * A list of refusals rather than a list of participants, because that is what
+     * the declaration is. Absent means every operation honours a key, which is the
+     * default and the reason there is nothing to remember.
+     */
+    operationIdempotencyOptOuts?: readonly string[];
     /**
      * eventType → handler; the types must appear in manifest.events.consumes.
      *
@@ -1322,6 +1504,18 @@ export interface HostAdmin {
      * the spine is kept because a fork must carry the event/migration state to be faithful.
      */
     exportScope(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId): Promise<ScopeDump>;
+    /**
+     * A bounded page of raw denial rows, newest first. Narrow with `actor` (who was
+     * refused), `permission` (which key), `operation`, and a `since`/`until` window.
+     */
+    listDenials(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, filter?: DenialFilter): Promise<PermissionDenial[]>;
+    /**
+     * The same log bucketed per (actor, permission) — K-35's "first occurrence + count
+     * per actor/key/window" — busiest first, with the filtered totals and the unfiltered
+     * window facts beside them. This is the view an operator opens first: "who has been
+     * probing for access they don't hold" is a question about counts, not about rows.
+     */
+    summarizeDenials(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, filter?: DenialFilter): Promise<DenialSummary>;
     /**
      * A COMPLETE dump of the directory itself: tenants, scopes, hostnames, verticals,
      * entitlements, identities, and the audit spine. The platform-level analogue of
@@ -1909,6 +2103,13 @@ export declare function attachmentBlobKey(scopeId: string, attachmentId: string)
  * `held` is every key projected for the tenant, expired ones included and marked: a lapsed
  * grant denies exactly like an absent one, and "you have it, it ran out" is a different fix
  * from "you never had it".
+ *
+ * **Its code is `not_found`** at all three throw sites (#113). Not an oversight and not
+ * `forbidden`: the taxonomy's `not_found` row already covers "exists, and must read as
+ * absent" for K-3's cross-tenant case, and every vertical had independently arrived at a
+ * 404 here for the same reason — *"a 403 would confirm the feature exists"*
+ * ([`todo/routes.ts`](../../../demos/todo/src/routes.ts)). Naming the code once is what
+ * retires those hand-written patterns.
  */
 export declare function entitlementDenial(operation: string, requiredKey: string, held: readonly {
     key: string;