@substrat-run/kernel 0.88.0 → 0.90.0

package/dist/denial-query.d.ts

@@ -12,7 +12,7 @@ import { type DenialBucket, type DenialFilter, type PermissionDenial } from '@su
  * arrive from an HTTP query string. Values are bound, never interpolated.
  */
 /** Every column of `_substrat_denials`, in the order `mapDenialRow` expects. */
-export declare const DENIAL_COLUMNS = "id, actor, permission, tenant_id, scope_id, operation, at, drained_at";
+export declare const DENIAL_COLUMNS = "id, actor, permission, tenant_id, scope_id, operation, impersonation, at, drained_at";
 /** The raw row shape, as either adapter hands it back. */
 export interface DenialRow {
     id: string;
@@ -21,6 +21,8 @@ export interface DenialRow {
     tenant_id: string;
     scope_id: string | null;
     operation: string | null;
+    /** K-42: the staff actor + session, as JSON, when the refusal was under one. */
+    impersonation: string | null;
     at: string;
     drained_at: string | null;
 }

package/dist/denial-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"denial-query.d.ts","sourceRoot":"","sources":["../src/denial-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAItB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;GAWG;AAEH,gFAAgF;AAChF,eAAO,MAAM,cAAc,0EAA0E,CAAC;AAEtG,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED,iDAAiD;AACjD,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,gBAAgB,CAW7D;AAgCD,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;CAAE,CAOnG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC7B,CAYA;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,YAAY,CASrE;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC7B,CAOA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAGL,CAAC;AAE5B,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB"}
+{"version":3,"file":"denial-query.d.ts","sourceRoot":"","sources":["../src/denial-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,YAAY,EAEjB,KAAK,gBAAgB,EAItB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;GAWG;AAEH,gFAAgF;AAChF,eAAO,MAAM,cAAc,yFAC6D,CAAC;AAEzF,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gFAAgF;IAChF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED,iDAAiD;AACjD,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,gBAAgB,CAa7D;AAgCD,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;CAAE,CAOnG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC7B,CAYA;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,YAAY,CASrE;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC7B,CAOA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAGL,CAAC;AAE5B,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB"}

package/dist/denial-query.js

@@ -12,7 +12,7 @@ import { DEFAULT_DENIAL_LIMIT, denialFilter, } from '@substrat-run/contracts';
  * arrive from an HTTP query string. Values are bound, never interpolated.
  */
 /** Every column of `_substrat_denials`, in the order `mapDenialRow` expects. */
-export const DENIAL_COLUMNS = 'id, actor, permission, tenant_id, scope_id, operation, at, drained_at';
+export const DENIAL_COLUMNS = 'id, actor, permission, tenant_id, scope_id, operation, impersonation, at, drained_at';
 /**
  * The stored spelling of an actor. The writer persists `JSON.stringify(actor)`, so a
  * principal is stored WITH its quotes (`"01J…"`) while a system or connection actor is
@@ -39,6 +39,7 @@ export function mapDenialRow(row) {
         tenantId: row.tenant_id,
         scopeId: (row.scope_id ?? null),
         operation: row.operation ?? null,
+        impersonation: row.impersonation == null ? null : JSON.parse(row.impersonation),
         at: row.at,
         drainedAt: row.drained_at ?? null,
     };

package/dist/denial-query.js.map

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

package/dist/idempotency.d.ts

@@ -0,0 +1,143 @@
+import { type CheckSubject } 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 declare const IDEMPOTENCY_DDL = "\n  CREATE TABLE IF NOT EXISTS _substrat_idempotency (\n    subject TEXT NOT NULL,\n    key TEXT NOT NULL,\n    operation TEXT NOT NULL,\n    -- SHA-256 over (operation, parsed input). A second request under this key\n    -- whose fingerprint differs is a REUSE, refused with 409 \u2014 never served the\n    -- first request's response, which is a different request's answer.\n    fingerprint TEXT NOT NULL,\n    -- The operation's return value as JSON. NULL means one of two things, which\n    -- `oversized` separates: the operation returned nothing, or the result was\n    -- too large to record and a replay must be refused rather than re-executed.\n    result TEXT,\n    oversized INTEGER NOT NULL DEFAULT 0,\n    -- #129's tag, replayed with the body so a retry hands the client the same\n    -- ETag the original did. Without it a replayed response has no validator and\n    -- the client's next conditional write has nothing to send.\n    entity_version TEXT,\n    recorded_at TEXT NOT NULL,\n    PRIMARY KEY (subject, key)\n  );\n  CREATE INDEX IF NOT EXISTS _substrat_idempotency_recorded\n    ON _substrat_idempotency (recorded_at);\n";
+/** The stored row, as both adapters' SQL returns it. */
+export interface IdempotencyRow {
+    readonly operation: string;
+    readonly fingerprint: string;
+    readonly result: string | null;
+    readonly oversized: number;
+    readonly entity_version: string | null;
+}
+/** What a replay answers with: the recorded return value and the recorded tag. */
+export interface IdempotentReplay {
+    readonly result: unknown;
+    readonly entityVersion: string | null;
+}
+/** The subject a key is scoped to, in the form the column stores. */
+export declare function idempotencySubject(subject: CheckSubject): string;
+/**
+ * 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 declare function assertIdempotencyKey(key: string): void;
+/** The lookup a retry is answered from. */
+export declare function idempotencyLookupQuery(subject: CheckSubject, key: string): {
+    sql: string;
+    params: [string, string];
+};
+/**
+ * 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 declare function replayFor(key: string, fingerprint: string, row: IdempotencyRow): IdempotentReplay;
+/**
+ * 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 declare function idempotencyRecordStatement(subject: CheckSubject, key: string, operation: string, fingerprint: string, result: unknown, entityVersion: string | null, at: string): {
+    sql: string;
+    params: [string, string, string, string, string | null, number, string | null, string];
+};
+/**
+ * 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 declare function idempotencyPruneStatement(now: string): {
+    sql: string;
+    params: [string];
+};
+/**
+ * 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 declare function idempotencyOptedOutMessage(operation: string): string;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,+nCAuB3B,CAAC;AAEF,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAEhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAMtD;AAED,2CAA2C;AAC3C,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,MAAM,GACV;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAO3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,cAAc,GAClB,gBAAgB,CAsBlB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,EAAE,EAAE,MAAM,GACT;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,CAAA;CAAE,CAmBzG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAA;CAAE,CAMxF;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKpE"}

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/impersonation.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The rules an impersonated session is held to (K-42, #868) — kernel-side, so
+ * both adapters enforce the same ones.
+ *
+ * An adapter supplies storage and a clock. Everything that decides whether a
+ * session may be opened, whether it may still be used, and what it may do lives
+ * here: a rule implemented twice is a rule that will eventually be two rules,
+ * and this is not a surface where the two versions may drift.
+ *
+ * What is deliberately NOT here: the permission evaluation. An impersonated
+ * operation checks as the impersonated principal through the ordinary
+ * `PermissionChecker`, with no override branch anywhere — the same discipline
+ * that made `system:<moduleId>` a subject rather than a bypass (#383). A door
+ * that grants authority by opening is a door nobody can audit.
+ */
+import { SubstratError, type BeginImpersonationInput, type ImpersonationFilter, type ImpersonationSession, type ImpersonationSessionId, type ImpersonationStamp, type Instant, type PlatformActorId, type ScopeId, type TenantId } from '@substrat-run/contracts';
+/**
+ * A session refused: expired, ended, pointed at the wrong scope, or asked to do
+ * something a `read-only` session may not.
+ *
+ * `forbidden` rather than `permission_denied`, and the distinction is worth the
+ * separate class: the principal being impersonated may well hold the permission,
+ * and the check may well have passed. What refused is the SESSION. Recording
+ * this in the denial log would put a row there about a permission nobody was
+ * actually denied.
+ */
+export declare class ImpersonationRefused extends SubstratError {
+    constructor(message: string);
+}
+/**
+ * Mint a session from a staff request. Pure: the caller supplies the id and the
+ * instant, so a frozen clock produces a deterministic session (#812) and the
+ * adapter keeps its one source of ULIDs.
+ *
+ * `minutes` is CAPPED BY THE SCHEMA rather than clamped here — a caller asking
+ * for a day is refused with a parse error naming the ceiling, because silently
+ * handing back a shorter session than was asked for is how somebody comes to
+ * believe they have one that is still open.
+ */
+export declare function newImpersonationSession(id: string, actor: PlatformActorId, input: BeginImpersonationInput, now: Instant): ImpersonationSession;
+/**
+ * Is this session usable, right now, for this scope?
+ *
+ * Called at the DOOR and again on EVERY INVOKE. Twice deliberately: a stub is a
+ * capability and nothing forces a caller to drop it, so a session checked only
+ * when the stub was minted would be a session whose expiry meant nothing to the
+ * one caller holding it — the exact shape of a time-box that is not one.
+ *
+ * Expiry is compared as ISO text, which sorts lexicographically, so neither
+ * adapter parses a date to answer it.
+ */
+export declare function assertSessionUsable(session: ImpersonationSession, now: Instant, at?: {
+    tenantId: TenantId;
+    scopeId: ScopeId;
+}): void;
+/**
+ * The effecting verbs a `read-only` session refuses, by name.
+ *
+ * Refusing at the verb is the half a person notices; the transaction being
+ * rolled back rather than committed is the half that is actually load-bearing,
+ * since `ctx.sql.exec` can write a row without going through any of these. Both
+ * are needed: without the rollback the guarantee is a promise about which
+ * functions module code happens to call, and without the refusal a support
+ * engineer watches a save appear to succeed and silently vanish.
+ */
+export declare function assertImpersonationWrites(session: ImpersonationSession | undefined, verb: string): void;
+/** What the kernel stamps on a record raised under this session. */
+export declare function impersonationStampOf(session: ImpersonationSession): ImpersonationStamp;
+/** Every column of `_substrat_impersonations`, in the order `mapImpersonationRow` expects. */
+export declare const IMPERSONATION_COLUMNS = "id, actor, principal, tenant_id, scope_id, reason, mode, started_at, expires_at, ended_at";
+/** The raw row shape, as either adapter hands it back. */
+export interface ImpersonationRow {
+    id: string;
+    actor: string;
+    principal: string;
+    tenant_id: string;
+    scope_id: string;
+    reason: string;
+    mode: string;
+    started_at: string;
+    expires_at: string;
+    ended_at: string | null;
+}
+export declare function mapImpersonationRow(row: ImpersonationRow): ImpersonationSession;
+export declare function impersonationRowValues(session: ImpersonationSession): (string | null)[];
+/** Read one session by id — the door's own lookup, shared so both adapters spell it once. */
+export declare function impersonationByIdQuery(id: ImpersonationSessionId | string): {
+    sql: string;
+    params: string[];
+};
+/**
+ * A bounded page of sessions, newest first. `active` is resolved against the
+ * caller's `now` rather than a stored flag: a session becomes inactive by the
+ * clock moving, and a flag would need somebody to come and set it.
+ */
+export declare function impersonationListQuery(filter: ImpersonationFilter | undefined, now: Instant): {
+    sql: string;
+    params: (string | number)[];
+};
+/** The DDL both adapters create the session store from — one spelling, one shape. */
+export declare const IMPERSONATION_DDL = "\n  CREATE TABLE IF NOT EXISTS _substrat_impersonations (\n    id          TEXT PRIMARY KEY,\n    -- The REAL actor. Never a principal: a platform actor is branded apart from\n    -- one precisely so a staff member can never read as a person in a trail.\n    actor       TEXT NOT NULL,\n    principal   TEXT NOT NULL,\n    tenant_id   TEXT NOT NULL,\n    scope_id    TEXT NOT NULL,\n    reason      TEXT NOT NULL,\n    mode        TEXT NOT NULL,\n    started_at  TEXT NOT NULL,\n    expires_at  TEXT NOT NULL,\n    -- Explicitly closed, as distinct from expired. Never deleted (K-21): a\n    -- session that once existed is why some rows carry the stamp they do.\n    ended_at    TEXT\n  );\n  CREATE INDEX IF NOT EXISTS _substrat_impersonations_tenant ON _substrat_impersonations (tenant_id, id);\n  CREATE INDEX IF NOT EXISTS _substrat_impersonations_actor ON _substrat_impersonations (actor, id);\n";
+//# sourceMappingURL=impersonation.d.ts.map

package/dist/impersonation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impersonation.d.ts","sourceRoot":"","sources":["../src/impersonation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAOL,aAAa,EACb,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,aAAa;IACrD,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,uBAAuB,EAC9B,GAAG,EAAE,OAAO,GACX,oBAAoB,CAgBtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,OAAO,EACZ,EAAE,CAAC,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC5C,IAAI,CAmBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,IAAI,EAAE,MAAM,GACX,IAAI,CAMN;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,GAAG,kBAAkB,CAEtF;AAED,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,8FAC2D,CAAC;AAE9F,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,GAAG,oBAAoB,CAa/E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAavF;AAED,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,sBAAsB,GAAG,MAAM,GAAG;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAKA;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,mBAAmB,GAAG,SAAS,EACvC,GAAG,EAAE,OAAO,GACX;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;CAAE,CAgC9C;AAED,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,04BAmB7B,CAAC"}