@substrat-run/kernel 0.87.0 → 0.89.0

package/dist/denial-query.d.ts

@@ -0,0 +1,84 @@
+import { type DenialBucket, type DenialFilter, type PermissionDenial } from '@substrat-run/contracts';
+/**
+ * The SELECTs behind every read of a scope's denial log (#867, K-35's stated tail).
+ *
+ * Four surfaces answer questions from `_substrat_denials` — the pure adapter's
+ * `HostAdmin`, the Durable Object's RPC, the vertical's `/internal/denials` seam and
+ * the control-plane route above them — and they must not drift on what "newest"
+ * means, what a bucket groups by, or which rows a window bound includes. Ids are
+ * ULIDs, so `ORDER BY id DESC` IS newest-first with no second index.
+ *
+ * Filters are re-parsed here rather than trusted: this builds SQL and every field can
+ * 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";
+/** The raw row shape, as either adapter hands it back. */
+export interface DenialRow {
+    id: string;
+    actor: string;
+    permission: string;
+    tenant_id: string;
+    scope_id: string | null;
+    operation: string | null;
+    at: string;
+    drained_at: string | null;
+}
+/**
+ * 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
+ * stored as an object (`{"system":"invoicing"}`). A caller filtering by actor holds the
+ * logical form, not that encoding, so normalize rather than making every call site know:
+ * text that already parses as JSON is passed through, anything else is a bare id and is
+ * stringified. Round-trips exactly what `recordDenial` wrote in both adapters.
+ */
+export declare function storedActor(input: string): string;
+/** Turn a stored row into the contract shape. */
+export declare function mapDenialRow(row: DenialRow): PermissionDenial;
+/** A bounded page of raw denial rows, newest first. */
+export declare function denialListQuery(filter?: DenialFilter): {
+    sql: string;
+    params: (string | number)[];
+};
+/**
+ * K-35's rate-buckets: one row per (actor, permission), busiest first.
+ *
+ * Busiest-first rather than newest-first on purpose — this view exists BECAUSE the
+ * volume is attacker-influenceable, and ordering by recency would let whoever wrote
+ * the last hundred rows push everyone else off the page, which is the exact failure
+ * the bucketing is there to prevent. Ties break on `MAX(id)` so the order is total.
+ */
+export declare function denialSummaryQuery(filter?: DenialFilter): {
+    sql: string;
+    params: (string | number)[];
+};
+export interface DenialBucketRow {
+    actor: string;
+    permission: string;
+    count: number;
+    operations: number;
+    first_at: string;
+    last_at: string;
+}
+export declare function mapDenialBucketRow(row: DenialBucketRow): DenialBucket;
+/** Totals for the FILTERED set — what the capped bucket list is a page of. */
+export declare function denialTotalsQuery(filter?: DenialFilter): {
+    sql: string;
+    params: (string | number)[];
+};
+/**
+ * Facts about the WINDOW, filter ignored — deliberately.
+ *
+ * These describe the log, not the query. A caller reading an empty filtered result
+ * needs to know whether the log reaches back past the interval it asked about, because
+ * rows here drain rather than expire (K-24's split) and until a Tier-2 sink exists the
+ * window simply IS the retention. Reporting the floor is what stops absence being read
+ * as "this never happened" — K-35 calls that a stated limitation, so the surface states it.
+ */
+export declare const DENIAL_WINDOW_QUERY: string;
+export interface DenialWindowRow {
+    oldest_at: string | null;
+    newest_at: string | null;
+    drained: number | null;
+}
+//# sourceMappingURL=denial-query.d.ts.map

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

@@ -0,0 +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"}

package/dist/denial-query.js

@@ -0,0 +1,135 @@
+import { DEFAULT_DENIAL_LIMIT, denialFilter, } from '@substrat-run/contracts';
+/**
+ * The SELECTs behind every read of a scope's denial log (#867, K-35's stated tail).
+ *
+ * Four surfaces answer questions from `_substrat_denials` — the pure adapter's
+ * `HostAdmin`, the Durable Object's RPC, the vertical's `/internal/denials` seam and
+ * the control-plane route above them — and they must not drift on what "newest"
+ * means, what a bucket groups by, or which rows a window bound includes. Ids are
+ * ULIDs, so `ORDER BY id DESC` IS newest-first with no second index.
+ *
+ * Filters are re-parsed here rather than trusted: this builds SQL and every field can
+ * 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';
+/**
+ * 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
+ * stored as an object (`{"system":"invoicing"}`). A caller filtering by actor holds the
+ * logical form, not that encoding, so normalize rather than making every call site know:
+ * text that already parses as JSON is passed through, anything else is a bare id and is
+ * stringified. Round-trips exactly what `recordDenial` wrote in both adapters.
+ */
+export function storedActor(input) {
+    try {
+        JSON.parse(input);
+        return input;
+    }
+    catch {
+        return JSON.stringify(input);
+    }
+}
+/** Turn a stored row into the contract shape. */
+export function mapDenialRow(row) {
+    return {
+        id: row.id,
+        actor: JSON.parse(row.actor),
+        permission: row.permission,
+        tenantId: row.tenant_id,
+        scopeId: (row.scope_id ?? null),
+        operation: row.operation ?? null,
+        at: row.at,
+        drainedAt: row.drained_at ?? null,
+    };
+}
+/** The WHERE fragment shared by the row read and the summary. */
+function where(f) {
+    const parts = [];
+    const params = [];
+    if (f.actor !== undefined) {
+        parts.push('actor = ?');
+        params.push(storedActor(f.actor));
+    }
+    if (f.permission !== undefined) {
+        parts.push('permission = ?');
+        params.push(f.permission);
+    }
+    if (f.operation !== undefined) {
+        parts.push('operation = ?');
+        params.push(f.operation);
+    }
+    // `at` is ISO 8601 text, which sorts lexicographically — the comparison is the
+    // ordering, no date parsing on either adapter. Inclusive lower, exclusive upper, so
+    // adjacent windows tile without double-counting a row on the boundary.
+    if (f.since !== undefined) {
+        parts.push('at >= ?');
+        params.push(f.since);
+    }
+    if (f.until !== undefined) {
+        parts.push('at < ?');
+        params.push(f.until);
+    }
+    return { clause: parts.length ? ` WHERE ${parts.join(' AND ')}` : '', params };
+}
+/** A bounded page of raw denial rows, newest first. */
+export function denialListQuery(filter) {
+    const f = denialFilter.parse(filter ?? {});
+    const w = where(f);
+    return {
+        sql: `SELECT ${DENIAL_COLUMNS} FROM _substrat_denials${w.clause} ORDER BY id DESC LIMIT ?`,
+        params: [...w.params, f.limit ?? DEFAULT_DENIAL_LIMIT],
+    };
+}
+/**
+ * K-35's rate-buckets: one row per (actor, permission), busiest first.
+ *
+ * Busiest-first rather than newest-first on purpose — this view exists BECAUSE the
+ * volume is attacker-influenceable, and ordering by recency would let whoever wrote
+ * the last hundred rows push everyone else off the page, which is the exact failure
+ * the bucketing is there to prevent. Ties break on `MAX(id)` so the order is total.
+ */
+export function denialSummaryQuery(filter) {
+    const f = denialFilter.parse(filter ?? {});
+    const w = where(f);
+    return {
+        sql: `SELECT actor, permission, COUNT(*) AS count,` +
+            ` COUNT(DISTINCT operation) AS operations,` +
+            ` MIN(at) AS first_at, MAX(at) AS last_at, MAX(id) AS last_id` +
+            ` FROM _substrat_denials${w.clause}` +
+            ` GROUP BY actor, permission ORDER BY count DESC, last_id DESC LIMIT ?`,
+        params: [...w.params, f.limit ?? DEFAULT_DENIAL_LIMIT],
+    };
+}
+export function mapDenialBucketRow(row) {
+    return {
+        actor: JSON.parse(row.actor),
+        permission: row.permission,
+        count: Number(row.count),
+        operations: Number(row.operations),
+        firstAt: row.first_at,
+        lastAt: row.last_at,
+    };
+}
+/** Totals for the FILTERED set — what the capped bucket list is a page of. */
+export function denialTotalsQuery(filter) {
+    const f = denialFilter.parse(filter ?? {});
+    const w = where(f);
+    return {
+        sql: `SELECT COUNT(*) AS total, COUNT(DISTINCT actor) AS actors FROM _substrat_denials${w.clause}`,
+        params: w.params,
+    };
+}
+/**
+ * Facts about the WINDOW, filter ignored — deliberately.
+ *
+ * These describe the log, not the query. A caller reading an empty filtered result
+ * needs to know whether the log reaches back past the interval it asked about, because
+ * rows here drain rather than expire (K-24's split) and until a Tier-2 sink exists the
+ * window simply IS the retention. Reporting the floor is what stops absence being read
+ * as "this never happened" — K-35 calls that a stated limitation, so the surface states it.
+ */
+export const DENIAL_WINDOW_QUERY = 'SELECT MIN(at) AS oldest_at, MAX(at) AS newest_at,' +
+    ' SUM(CASE WHEN drained_at IS NOT NULL THEN 1 ELSE 0 END) AS drained' +
+    ' FROM _substrat_denials';
+//# sourceMappingURL=denial-query.js.map

package/dist/denial-query.js.map

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

package/dist/entity-version.d.ts

@@ -0,0 +1,115 @@
+import { type EntityRef } from '@substrat-run/contracts';
+/**
+ * An entity's version — the ULID of the last event about it (#901).
+ *
+ * ## There is no version column, and there should not be one
+ *
+ * This began as a `_version INTEGER` on every entity table, bumped by a trigger
+ * the DDL emitter would ship per table. That design works, and it was rejected
+ * for two reasons that are not about cost.
+ *
+ * It would have put a platform guarantee into per-vertical DDL. The only way to
+ * make a column unforgettable is a trigger, and a trigger is SQLite — replicated
+ * into every table, re-derived for every vertical authored afterwards, and
+ * unavailable to any adapter that is not SQLite. The scope-host contract is not
+ * a SQL contract; `query`/`exec` are how *these* adapters happen to serve it.
+ *
+ * And the version already existed. `_substrat_outbox` has recorded `entity_type`
+ * and `entity_id` against a monotonic ULID `id` since it was written, on every
+ * event, for every module. Nothing needed to be added to a row.
+ *
+ * ## Why the ULID is a sound version
+ *
+ * - **Monotonic and exactly comparable.** `ulid()` uses the spec's monotonic
+ *   factory, and its header names that load-bearing precisely because this table
+ *   orders by id: two events in one millisecond still sort in creation order.
+ * - **Never pruned.** The outbox DRAINS, it does not expire (K-24's split) —
+ *   `drained_at` marks a shipped row and nothing deletes it.
+ * - **Survives erasure.** A shred nulls `payload` and keeps the row, so an
+ *   erased entity can still refuse a stale write. A version that vanished with
+ *   the data would fail open at exactly the wrong moment.
+ * - **Unforgeable.** Module code cannot write `_substrat_*` (rule 3). A column
+ *   would have had to earn that property with a trigger clever enough to reset a
+ *   forged value; the spine has it by construction.
+ *
+ * ## What it is sensitive to
+ *
+ * ANY event about the entity moves the version, including one that changed
+ * nothing the caller read. A precondition built on this is therefore
+ * conservative: it can refuse a write that would in fact have been safe, and 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 — documented here rather than
+ * discovered by someone debugging a 412 they think is spurious.
+ *
+ * The converse is the one hole worth naming: a mutation that emits no event does
+ * not move the version. "Every mutation emits a fat event" is a rule that review
+ * enforces and `boundary-lint` does not, so the answer is not here — it is that
+ * a declared `concurrency` must be compile-checked against the operation's
+ * declared `emits` (#129), which is strictly more than a trigger would have
+ * given: a trigger guarantees the column moved, never that the operation
+ * announced what it did.
+ */
+/** The opaque version token. A ULID, but callers compare it — they do not read it. */
+export type EntityVersion = string;
+/**
+ * The one SELECT behind every read of an entity's version.
+ *
+ * Both adapters call this rather than writing the query twice, for the same
+ * reason `platformRequestHistoryQuery` exists: two surfaces answering one
+ * question from one table must not drift on what the answer means.
+ *
+ * `MAX(id)` with no `GROUP BY` always returns exactly one row — the value is
+ * NULL when the entity has no events. So absence is a null column, never a
+ * missing row, and the caller distinguishes "never touched" from "touched" on
+ * the value alone.
+ */
+export declare function entityVersionQuery(ref: EntityRef): {
+    sql: string;
+    params: [string, string];
+};
+/**
+ * The index that makes the query a seek instead of a scan.
+ *
+ * Column order matters and is not arbitrary: the two equality predicates come
+ * first, and `id` last so SQLite answers `MAX(id)` by walking to the end of the
+ * matched range rather than aggregating over it. Emitted into both adapters'
+ * spine DDL — kernel-owned, so no vertical carries a migration for it.
+ *
+ * The outbox had no index at all before this. Every other spine table with a
+ * filtered read has one (`_substrat_access_log_actor`, `_substrat_admin_log_scope`,
+ * and the rest); the outbox was only ever read by drain order, which is its
+ * primary key.
+ */
+export declare const OUTBOX_ENTITY_INDEX = "CREATE INDEX IF NOT EXISTS _substrat_outbox_entity ON _substrat_outbox (entity_type, entity_id, id);";
+/** The row `entityVersionQuery` returns — one row, `version` null when there are no events. */
+export interface EntityVersionRow {
+    readonly version: string | null;
+}
+/** Normalise the single row into the contract's answer. */
+export declare function entityVersionOf(rows: readonly EntityVersionRow[]): EntityVersion | null;
+/**
+ * Refuse a write whose caller is holding a stale version (#129).
+ *
+ * Both adapters call this rather than comparing twice, for the reason
+ * `entityVersionQuery` exists one screen up: two surfaces answering one question
+ * must not drift on what the answer means. Here the answer decides whether a
+ * write lands, so drifting would mean one host silently admitting what the other
+ * refuses.
+ *
+ * ## This must be called INSIDE the operation's transaction
+ *
+ * A precondition read outside the write's transaction is a time-of-check /
+ * time-of-use bug wearing a safety mechanism's clothes: the version is read, a
+ * concurrent writer commits, and then the guarded write commits over it having
+ * "passed". Serialising the read with the write is the entire guarantee, so this
+ * takes a version the CALLER has already read under `BEGIN`, and cannot do the
+ * read itself without inviting the mistake.
+ *
+ * ## The refusal deliberately carries no version
+ *
+ * See `PROBLEM_EXTENSIONS.precondition_failed`. Handing the current tag back
+ * turns the obvious client fix into a blind retry that overwrites the change
+ * which caused the refusal.
+ */
+export declare function assertIfMatch(ref: EntityRef, ifMatch: string, version: EntityVersion | null): void;
+//# sourceMappingURL=entity-version.d.ts.map

package/dist/entity-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-version.d.ts","sourceRoot":"","sources":["../src/entity-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,sFAAsF;AACtF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1B,CAKA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,yGACwE,CAAC;AAEzG,+FAA+F;AAC/F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,GAAG,aAAa,GAAG,IAAI,CAEvF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAUlG"}

package/dist/entity-version.js

@@ -0,0 +1,70 @@
+import { ifMatchAdmits, substratError } from '@substrat-run/contracts';
+/**
+ * The one SELECT behind every read of an entity's version.
+ *
+ * Both adapters call this rather than writing the query twice, for the same
+ * reason `platformRequestHistoryQuery` exists: two surfaces answering one
+ * question from one table must not drift on what the answer means.
+ *
+ * `MAX(id)` with no `GROUP BY` always returns exactly one row — the value is
+ * NULL when the entity has no events. So absence is a null column, never a
+ * missing row, and the caller distinguishes "never touched" from "touched" on
+ * the value alone.
+ */
+export function entityVersionQuery(ref) {
+    return {
+        sql: 'SELECT MAX(id) AS version FROM _substrat_outbox WHERE entity_type = ? AND entity_id = ?',
+        params: [ref.entityType, ref.entityId],
+    };
+}
+/**
+ * The index that makes the query a seek instead of a scan.
+ *
+ * Column order matters and is not arbitrary: the two equality predicates come
+ * first, and `id` last so SQLite answers `MAX(id)` by walking to the end of the
+ * matched range rather than aggregating over it. Emitted into both adapters'
+ * spine DDL — kernel-owned, so no vertical carries a migration for it.
+ *
+ * The outbox had no index at all before this. Every other spine table with a
+ * filtered read has one (`_substrat_access_log_actor`, `_substrat_admin_log_scope`,
+ * and the rest); the outbox was only ever read by drain order, which is its
+ * primary key.
+ */
+export const OUTBOX_ENTITY_INDEX = 'CREATE INDEX IF NOT EXISTS _substrat_outbox_entity ON _substrat_outbox (entity_type, entity_id, id);';
+/** Normalise the single row into the contract's answer. */
+export function entityVersionOf(rows) {
+    return rows[0]?.version ?? null;
+}
+/**
+ * Refuse a write whose caller is holding a stale version (#129).
+ *
+ * Both adapters call this rather than comparing twice, for the reason
+ * `entityVersionQuery` exists one screen up: two surfaces answering one question
+ * must not drift on what the answer means. Here the answer decides whether a
+ * write lands, so drifting would mean one host silently admitting what the other
+ * refuses.
+ *
+ * ## This must be called INSIDE the operation's transaction
+ *
+ * A precondition read outside the write's transaction is a time-of-check /
+ * time-of-use bug wearing a safety mechanism's clothes: the version is read, a
+ * concurrent writer commits, and then the guarded write commits over it having
+ * "passed". Serialising the read with the write is the entire guarantee, so this
+ * takes a version the CALLER has already read under `BEGIN`, and cannot do the
+ * read itself without inviting the mistake.
+ *
+ * ## The refusal deliberately carries no version
+ *
+ * See `PROBLEM_EXTENSIONS.precondition_failed`. Handing the current tag back
+ * turns the obvious client fix into a blind retry that overwrites the change
+ * which caused the refusal.
+ */
+export function assertIfMatch(ref, ifMatch, version) {
+    if (ifMatchAdmits(ifMatch, version))
+        return;
+    throw substratError('precondition_failed', version === null
+        ? `${ref.entityType} ${ref.entityId} has no recorded version — it may never have existed, ` +
+            'or the write you are holding a tag for was rolled back'
+        : `${ref.entityType} ${ref.entityId} changed since you read it`, { entity: ref });
+}
+//# sourceMappingURL=entity-version.js.map

package/dist/entity-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-version.js","sourceRoot":"","sources":["../src/entity-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAkB,MAAM,yBAAyB,CAAC;AAwDvF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAc;IAI/C,OAAO;QACL,GAAG,EAAE,yFAAyF;QAC9F,MAAM,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC;KACvC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,sGAAsG,CAAC;AAOzG,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,IAAiC;IAC/D,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAAC,GAAc,EAAE,OAAe,EAAE,OAA6B;IAC1F,IAAI,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC;QAAE,OAAO;IAC5C,MAAM,aAAa,CACjB,qBAAqB,EACrB,OAAO,KAAK,IAAI;QACd,CAAC,CAAC,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,QAAQ,wDAAwD;YACzF,wDAAwD;QAC1D,CAAC,CAAC,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,QAAQ,4BAA4B,EACjE,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAC;AACJ,CAAC"}

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"}