@substrat-run/contracts 0.87.0 → 0.89.0

package/dist/concurrency.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Optimistic concurrency on the operation surface (#129).
+ *
+ * Two people open the same record, both save, and the second write silently
+ * destroys the first. Nobody notices until the data is gone — there is no error,
+ * no log line, and no way to reconstruct what was lost. This is the vocabulary
+ * that lets an operation refuse the second write instead.
+ *
+ * ## What a version is, and why it is not in here
+ *
+ * The version is the ULID of the last event about the entity (`entityVersionOf`
+ * in the kernel, #901). This module holds only the WIRE half — the header names
+ * and the comparison — because contracts sits below the spine: it can say what an
+ * `ETag` is called and what makes one match, and must not know which table
+ * answers the question.
+ *
+ * ## Why an opaque token rather than a number
+ *
+ * A caller compares; it never reads. That is what lets the version be a ULID
+ * today and something else later without a client noticing, and it is also what
+ * stops a client doing arithmetic on it — `If-Match: <version + 1>` is not a
+ * thing anyone can write.
+ *
+ * ## The direction this fails
+ *
+ * ANY event about the entity moves the version, including one that changed
+ * nothing the caller read. So a precondition built on it is CONSERVATIVE: it can
+ * refuse a write that would in fact have been safe, and it cannot admit one that
+ * would not. Documented here as well as in the kernel because this is the half a
+ * client author reads when they are debugging a 412 they believe is spurious.
+ */
+/**
+ * The response header carrying an entity's current version.
+ *
+ * Strong, never weak (`W/"…"`): the comparison is exact, and a weak validator
+ * means "semantically equivalent", which is precisely the judgement no generic
+ * layer is entitled to make about a domain entity.
+ */
+export declare const ETAG_HEADER = "ETag";
+/** The request header carrying the version the caller believes it is writing over. */
+export declare const IF_MATCH_HEADER = "If-Match";
+/**
+ * The headers a cross-origin browser client cannot read unless the server says it
+ * may — the same trap already documented for `Link` and `X-Total-Count` in
+ * `PAGE_EXPOSED_HEADERS`, and worse here.
+ *
+ * A `Link` a browser cannot read looks like "there is only one page". An `ETag` a
+ * browser cannot read looks like nothing at all: `response.headers.get('ETag')` is
+ * `null`, the client sends no `If-Match`, the server has nothing to compare, and
+ * every write succeeds. The protection silently switches itself off, in the one
+ * deployment shape (an SPA on another origin) where two editors are most likely.
+ *
+ * So a vertical exposing its API cross-origin must expose these, and this constant
+ * is what it lists rather than a string it retypes.
+ */
+export declare const CONCURRENCY_EXPOSED_HEADERS: readonly ["ETag"];
+/**
+ * Format a version as an `ETag` value.
+ *
+ * Quoted, per RFC 9110 §8.8.3 — an entity-tag is a quoted string and a bare token
+ * is malformed. Intermediaries do parse this: an unquoted value is the kind of
+ * thing that works against a dev server and is stripped by a proxy in production.
+ */
+export declare function etagOf(version: string): string;
+/**
+ * Does the caller's `If-Match` admit this version?
+ *
+ * Handles the three spellings RFC 9110 §13.1.1 allows a client to send: the quoted
+ * tag, a comma-separated list of them, and `*` (meaning "any current version" —
+ * i.e. the entity must merely EXIST, which for us means it has a version at all).
+ *
+ * A weak tag (`W/"…"`) never matches. §13.1.1 requires the strong comparison
+ * function for `If-Match`, and honouring a weak one here would admit exactly the
+ * write this exists to refuse.
+ *
+ * `version` is null when the entity has no events yet. Nothing matches that except
+ * an absent header, which is not this function's call to make — a caller that sent
+ * `If-Match` against an entity with no version is asking to write over something
+ * that was never written, and gets a refusal.
+ */
+export declare function ifMatchAdmits(ifMatch: string, version: string | null): boolean;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,SAAS,CAAC;AAElC,sFAAsF;AACtF,eAAO,MAAM,eAAe,aAAa,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,mBAAyB,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAQ9E"}

package/dist/concurrency.js

@@ -0,0 +1,94 @@
+/**
+ * Optimistic concurrency on the operation surface (#129).
+ *
+ * Two people open the same record, both save, and the second write silently
+ * destroys the first. Nobody notices until the data is gone — there is no error,
+ * no log line, and no way to reconstruct what was lost. This is the vocabulary
+ * that lets an operation refuse the second write instead.
+ *
+ * ## What a version is, and why it is not in here
+ *
+ * The version is the ULID of the last event about the entity (`entityVersionOf`
+ * in the kernel, #901). This module holds only the WIRE half — the header names
+ * and the comparison — because contracts sits below the spine: it can say what an
+ * `ETag` is called and what makes one match, and must not know which table
+ * answers the question.
+ *
+ * ## Why an opaque token rather than a number
+ *
+ * A caller compares; it never reads. That is what lets the version be a ULID
+ * today and something else later without a client noticing, and it is also what
+ * stops a client doing arithmetic on it — `If-Match: <version + 1>` is not a
+ * thing anyone can write.
+ *
+ * ## The direction this fails
+ *
+ * ANY event about the entity moves the version, including one that changed
+ * nothing the caller read. So a precondition built on it is CONSERVATIVE: it can
+ * refuse a write that would in fact have been safe, and it cannot admit one that
+ * would not. Documented here as well as in the kernel because this is the half a
+ * client author reads when they are debugging a 412 they believe is spurious.
+ */
+/**
+ * The response header carrying an entity's current version.
+ *
+ * Strong, never weak (`W/"…"`): the comparison is exact, and a weak validator
+ * means "semantically equivalent", which is precisely the judgement no generic
+ * layer is entitled to make about a domain entity.
+ */
+export const ETAG_HEADER = 'ETag';
+/** The request header carrying the version the caller believes it is writing over. */
+export const IF_MATCH_HEADER = 'If-Match';
+/**
+ * The headers a cross-origin browser client cannot read unless the server says it
+ * may — the same trap already documented for `Link` and `X-Total-Count` in
+ * `PAGE_EXPOSED_HEADERS`, and worse here.
+ *
+ * A `Link` a browser cannot read looks like "there is only one page". An `ETag` a
+ * browser cannot read looks like nothing at all: `response.headers.get('ETag')` is
+ * `null`, the client sends no `If-Match`, the server has nothing to compare, and
+ * every write succeeds. The protection silently switches itself off, in the one
+ * deployment shape (an SPA on another origin) where two editors are most likely.
+ *
+ * So a vertical exposing its API cross-origin must expose these, and this constant
+ * is what it lists rather than a string it retypes.
+ */
+export const CONCURRENCY_EXPOSED_HEADERS = [ETAG_HEADER];
+/**
+ * Format a version as an `ETag` value.
+ *
+ * Quoted, per RFC 9110 §8.8.3 — an entity-tag is a quoted string and a bare token
+ * is malformed. Intermediaries do parse this: an unquoted value is the kind of
+ * thing that works against a dev server and is stripped by a proxy in production.
+ */
+export function etagOf(version) {
+    return `"${version}"`;
+}
+/**
+ * Does the caller's `If-Match` admit this version?
+ *
+ * Handles the three spellings RFC 9110 §13.1.1 allows a client to send: the quoted
+ * tag, a comma-separated list of them, and `*` (meaning "any current version" —
+ * i.e. the entity must merely EXIST, which for us means it has a version at all).
+ *
+ * A weak tag (`W/"…"`) never matches. §13.1.1 requires the strong comparison
+ * function for `If-Match`, and honouring a weak one here would admit exactly the
+ * write this exists to refuse.
+ *
+ * `version` is null when the entity has no events yet. Nothing matches that except
+ * an absent header, which is not this function's call to make — a caller that sent
+ * `If-Match` against an entity with no version is asking to write over something
+ * that was never written, and gets a refusal.
+ */
+export function ifMatchAdmits(ifMatch, version) {
+    const candidates = ifMatch
+        .split(',')
+        .map((raw) => raw.trim())
+        .filter((raw) => raw.length > 0);
+    if (candidates.includes('*'))
+        return version !== null;
+    if (version === null)
+        return false;
+    return candidates.includes(etagOf(version));
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC;AAElC,sFAAsF;AACtF,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,WAAW,CAAU,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,OAAe;IACpC,OAAO,IAAI,OAAO,GAAG,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,OAAsB;IACnE,MAAM,UAAU,GAAG,OAAO;SACvB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;SACxB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACnC,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,KAAK,IAAI,CAAC;IACtD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9C,CAAC"}

package/dist/denial.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+/**
+ * The read side of the K-35 denial log — a scope-local record of every ENFORCED
+ * permission refusal (`assertAllowed`), written on the deny path as a fresh
+ * autocommit AFTER the rollback it is evidence of.
+ *
+ * This is the *other* kind of evidence from a conformance receipt. A receipt says
+ * "we attempted the attack in CI at commit X"; these rows say "on your data, in
+ * production, here is every refusal, by whom, against which key". K-35 made the
+ * case for the row itself: a denial is the one event where an actor's intent and
+ * the permission model visibly disagree.
+ *
+ * Two properties of the log shape everything below, and both come straight from
+ * K-35's own reasoning about why denials are NOT admin-log entries:
+ *
+ * 1. **The volume is attacker-influenceable.** A probing client mints unlimited
+ *    rows, so a newest-first page of raw rows is the wrong default view — 200 rows
+ *    from one prober hide everyone else. That is why `denialSummary` exists beside
+ *    the row list, and why K-35 called rate-bucketing sanctionable up front.
+ * 2. **The window is a storage bound, not a retention policy.** Rows `drain` rather
+ *    than expire (K-24's split). Until a Tier-2 sink exists, what is here is simply
+ *    what has not been pruned — so the summary reports the window's own floor
+ *    (`windowOldestAt`) rather than letting a caller read absence as "never happened".
+ */
+/** How many denial rows an unbounded read returns — a screenful, newest-first. */
+export declare const DEFAULT_DENIAL_LIMIT = 50;
+/** The hard ceiling on one page of denial rows, and on one page of buckets. */
+export declare const DENIAL_LIMIT_MAX = 200;
+/**
+ * One recorded refusal. `scopeId` is null for a tenant-node check (one that named no
+ * scope); `operation` is null when the denial unwound something that was not an
+ * operation invocation. `drainedAt` marks a row already shipped to a Tier-2 sink and
+ * therefore eligible to be pruned — bookkeeping, not a judgement about the denial.
+ */
+export declare const permissionDenial: z.ZodObject<{
+    id: z.ZodString;
+    actor: z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">, z.ZodObject<{
+        system: z.core.$ZodBranded<z.ZodString, "ModuleId", "out">;
+    }, z.core.$strip>, z.ZodObject<{
+        connection: z.ZodString;
+    }, z.core.$strip>]>;
+    permission: z.core.$ZodBranded<z.ZodString, "PermissionKey", "out">;
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    scopeId: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "ScopeId", "out">>;
+    operation: z.ZodNullable<z.ZodString>;
+    at: z.ZodString;
+    drainedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PermissionDenial = z.infer<typeof permissionDenial>;
+/**
+ * What narrows a denial read. Every field is an exact match except the `since`/`until`
+ * bounds on `at` (inclusive lower, exclusive upper) — enough to answer "who probed
+ * this key", "what did this actor try", and "what happened during the incident window"
+ * without a SQL console.
+ *
+ * `actor` takes the LOGICAL actor — a bare principal ULID, or the object form for a
+ * system/connection actor (`{"system":"invoicing"}`). The writer persists
+ * `JSON.stringify(actor)`, so a principal is stored with its quotes; normalizing to that
+ * encoding is the reader's job (`storedActor` in the kernel's query builder), not every
+ * caller's.
+ */
+export declare const denialFilter: z.ZodObject<{
+    actor: z.ZodOptional<z.ZodString>;
+    permission: z.ZodOptional<z.ZodString>;
+    operation: z.ZodOptional<z.ZodString>;
+    since: z.ZodOptional<z.ZodString>;
+    until: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type DenialFilter = z.infer<typeof denialFilter>;
+/**
+ * One (actor, permission) bucket — K-35's "first occurrence + count per actor/key/
+ * window", which is the shape that survives a flood. `operations` is the number of
+ * DISTINCT operations the actor was refused this key on, and it is the discriminator
+ * worth the extra aggregate: one operation refused four hundred times is a broken
+ * screen or a misconfigured role, while the same count spread across a dozen
+ * operations is someone walking the surface.
+ */
+export declare const denialBucket: z.ZodObject<{
+    actor: z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">, z.ZodObject<{
+        system: z.core.$ZodBranded<z.ZodString, "ModuleId", "out">;
+    }, z.core.$strip>, z.ZodObject<{
+        connection: z.ZodString;
+    }, z.core.$strip>]>;
+    permission: z.core.$ZodBranded<z.ZodString, "PermissionKey", "out">;
+    count: z.ZodNumber;
+    operations: z.ZodNumber;
+    firstAt: z.ZodString;
+    lastAt: z.ZodString;
+}, z.core.$strip>;
+export type DenialBucket = z.infer<typeof denialBucket>;
+/**
+ * The bucketed view of a scope's denial log, plus the facts that keep it honest.
+ *
+ * `total` counts every row matching the filter, so a caller can tell a capped bucket
+ * list from a complete one. `windowOldestAt` is deliberately computed WITHOUT the
+ * filter: it is a statement about the log, not about the query — the earliest moment
+ * this scope can still speak to. An empty result older than it means "no denials";
+ * an empty result at it means "we no longer hold that far back".
+ */
+export declare const denialSummary: z.ZodObject<{
+    buckets: z.ZodArray<z.ZodObject<{
+        actor: z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">, z.ZodObject<{
+            system: z.core.$ZodBranded<z.ZodString, "ModuleId", "out">;
+        }, z.core.$strip>, z.ZodObject<{
+            connection: z.ZodString;
+        }, z.core.$strip>]>;
+        permission: z.core.$ZodBranded<z.ZodString, "PermissionKey", "out">;
+        count: z.ZodNumber;
+        operations: z.ZodNumber;
+        firstAt: z.ZodString;
+        lastAt: z.ZodString;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    actors: z.ZodNumber;
+    windowOldestAt: z.ZodNullable<z.ZodString>;
+    windowNewestAt: z.ZodNullable<z.ZodString>;
+    drained: z.ZodNumber;
+}, z.core.$strip>;
+export type DenialSummary = z.infer<typeof denialSummary>;
+//# sourceMappingURL=denial.d.ts.map

package/dist/denial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"denial.d.ts","sourceRoot":"","sources":["../src/denial.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;iBAc3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY;;;;;;;iBASvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;iBAQvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;iBAgBxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/denial.js

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { actor } from './events.js';
+import { permissionKey, scopeId, tenantId } from './ids.js';
+/**
+ * The read side of the K-35 denial log — a scope-local record of every ENFORCED
+ * permission refusal (`assertAllowed`), written on the deny path as a fresh
+ * autocommit AFTER the rollback it is evidence of.
+ *
+ * This is the *other* kind of evidence from a conformance receipt. A receipt says
+ * "we attempted the attack in CI at commit X"; these rows say "on your data, in
+ * production, here is every refusal, by whom, against which key". K-35 made the
+ * case for the row itself: a denial is the one event where an actor's intent and
+ * the permission model visibly disagree.
+ *
+ * Two properties of the log shape everything below, and both come straight from
+ * K-35's own reasoning about why denials are NOT admin-log entries:
+ *
+ * 1. **The volume is attacker-influenceable.** A probing client mints unlimited
+ *    rows, so a newest-first page of raw rows is the wrong default view — 200 rows
+ *    from one prober hide everyone else. That is why `denialSummary` exists beside
+ *    the row list, and why K-35 called rate-bucketing sanctionable up front.
+ * 2. **The window is a storage bound, not a retention policy.** Rows `drain` rather
+ *    than expire (K-24's split). Until a Tier-2 sink exists, what is here is simply
+ *    what has not been pruned — so the summary reports the window's own floor
+ *    (`windowOldestAt`) rather than letting a caller read absence as "never happened".
+ */
+/** How many denial rows an unbounded read returns — a screenful, newest-first. */
+export const DEFAULT_DENIAL_LIMIT = 50;
+/** The hard ceiling on one page of denial rows, and on one page of buckets. */
+export const DENIAL_LIMIT_MAX = 200;
+/**
+ * One recorded refusal. `scopeId` is null for a tenant-node check (one that named no
+ * scope); `operation` is null when the denial unwound something that was not an
+ * operation invocation. `drainedAt` marks a row already shipped to a Tier-2 sink and
+ * therefore eligible to be pruned — bookkeeping, not a judgement about the denial.
+ */
+export const permissionDenial = z.object({
+    /** ULID — chronological, so it is also the sort key. */
+    id: z.string().min(1),
+    /** WHO was refused: a principal, a `{ system }` module, or a `{ connection }`. */
+    actor,
+    /** The key `assertAllowed` checked and refused. */
+    permission: permissionKey,
+    tenantId,
+    scopeId: scopeId.nullable(),
+    /** The operation the denial rolled back, e.g. `workorder/complete`. */
+    operation: z.string().nullable(),
+    /** ISO 8601. */
+    at: z.string().min(1),
+    drainedAt: z.string().nullable(),
+});
+/**
+ * What narrows a denial read. Every field is an exact match except the `since`/`until`
+ * bounds on `at` (inclusive lower, exclusive upper) — enough to answer "who probed
+ * this key", "what did this actor try", and "what happened during the incident window"
+ * without a SQL console.
+ *
+ * `actor` takes the LOGICAL actor — a bare principal ULID, or the object form for a
+ * system/connection actor (`{"system":"invoicing"}`). The writer persists
+ * `JSON.stringify(actor)`, so a principal is stored with its quotes; normalizing to that
+ * encoding is the reader's job (`storedActor` in the kernel's query builder), not every
+ * caller's.
+ */
+export const denialFilter = z.object({
+    actor: z.string().min(1).optional(),
+    permission: z.string().min(1).optional(),
+    operation: z.string().min(1).optional(),
+    /** ISO 8601, inclusive. */
+    since: z.string().min(1).optional(),
+    /** ISO 8601, exclusive. */
+    until: z.string().min(1).optional(),
+    limit: z.number().int().min(1).max(DENIAL_LIMIT_MAX).optional(),
+});
+/**
+ * One (actor, permission) bucket — K-35's "first occurrence + count per actor/key/
+ * window", which is the shape that survives a flood. `operations` is the number of
+ * DISTINCT operations the actor was refused this key on, and it is the discriminator
+ * worth the extra aggregate: one operation refused four hundred times is a broken
+ * screen or a misconfigured role, while the same count spread across a dozen
+ * operations is someone walking the surface.
+ */
+export const denialBucket = z.object({
+    actor,
+    permission: permissionKey,
+    count: z.number().int().positive(),
+    operations: z.number().int().nonnegative(),
+    /** ISO 8601 — the first occurrence still in the window (see `windowOldestAt`). */
+    firstAt: z.string().min(1),
+    lastAt: z.string().min(1),
+});
+/**
+ * The bucketed view of a scope's denial log, plus the facts that keep it honest.
+ *
+ * `total` counts every row matching the filter, so a caller can tell a capped bucket
+ * list from a complete one. `windowOldestAt` is deliberately computed WITHOUT the
+ * filter: it is a statement about the log, not about the query — the earliest moment
+ * this scope can still speak to. An empty result older than it means "no denials";
+ * an empty result at it means "we no longer hold that far back".
+ */
+export const denialSummary = z.object({
+    buckets: z.array(denialBucket),
+    /** Rows matching the filter. Bucket counts sum to this when `buckets` is uncapped. */
+    total: z.number().int().nonnegative(),
+    /** Distinct actors among the matching rows. */
+    actors: z.number().int().nonnegative(),
+    /**
+     * The oldest row STILL HELD, filter ignored — the window's floor, null when the log
+     * is empty. The window is a storage bound and not a retention policy (K-35): what is
+     * absent before this instant was not necessarily never recorded.
+     */
+    windowOldestAt: z.string().nullable(),
+    /** The newest row held, filter ignored. */
+    windowNewestAt: z.string().nullable(),
+    /** Rows already shipped to a Tier-2 sink, filter ignored — prunable, not pruned. */
+    drained: z.number().int().nonnegative(),
+});
+//# sourceMappingURL=denial.js.map

package/dist/denial.js.map

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

package/dist/errors.d.ts

@@ -33,6 +33,18 @@ import { z } from 'zod';
  * decision stays a one-line change here for exactly as long as that holds.
  */
 export declare const PROBLEM_TYPE_BASE = "https://substrat.net/errors";
+/** What a problem body is served as. Never `application/json` — RFC 9457 §3. */
+export declare const PROBLEM_CONTENT_TYPE = "application/problem+json";
+/**
+ * The `type` of a failure that has a status and nothing else.
+ *
+ * RFC 9457 §4.2.1: `about:blank` means "no semantics beyond the status code", and the
+ * title is then the status phrase. That is the honest shape for the two cases a
+ * transport cannot type — an untyped throw it refuses to call the platform's fault,
+ * and a downstream status it is relaying — and it is what keeps the closed taxonomy
+ * closed while every body still parses as a problem.
+ */
+export declare const PROBLEM_TYPE_BLANK = "about:blank";
 /**
  * The taxonomy. CLOSED — an open one is a suggestion.
  *
@@ -140,7 +152,12 @@ export declare const PROBLEM_EXTENSIONS: {
             message: z.ZodString;
         }, z.core.$strip>>>;
     }, z.core.$strip>;
-    readonly precondition_failed: z.ZodObject<{}, z.core.$strict>;
+    readonly precondition_failed: z.ZodObject<{
+        entity: z.ZodOptional<z.ZodObject<{
+            entityType: z.ZodString;
+            entityId: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
     readonly rate_limited: z.ZodObject<{
         retryAfter: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
@@ -163,7 +180,7 @@ export declare const problem: z.ZodObject<{
     detail: z.ZodOptional<z.ZodString>;
     instance: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodString>;
-    code: z.ZodEnum<{
+    code: z.ZodOptional<z.ZodEnum<{
         conflict: "conflict";
         forbidden: "forbidden";
         internal: "internal";
@@ -174,7 +191,7 @@ export declare const problem: z.ZodObject<{
         unauthenticated: "unauthenticated";
         unavailable: "unavailable";
         validation_failed: "validation_failed";
-    }>;
+    }>>;
     permission: z.ZodOptional<z.ZodString>;
     entity: z.ZodOptional<z.ZodObject<{
         entityType: z.ZodString;
@@ -248,6 +265,26 @@ export declare function validationIssuesFrom(error: z.ZodError): ValidationIssue
  * quietly widening it in the name of better errors.
  */
 export declare function toProblem(err: unknown, instance?: string): Problem;
+/**
+ * A problem body for a status and nothing else — the `about:blank` form.
+ *
+ * Two callers, both transports, both relaying rather than raising:
+ *
+ * - **A throw the taxonomy does not recognise.** Every vertical answers one with the
+ *   caller's 400 and relays the message, deliberately (#559: an unrecognised throw must
+ *   not claim to be the platform's fault, because the control plane retries 5xx). That
+ *   status is a decision about blame, not a claim about what went wrong, and this is the
+ *   body that says so.
+ * - **A status raised somewhere else.** A downstream vertical's own refusal, a Durable
+ *   Object fault the runtime named (502). Inventing a code for those would put our
+ *   vocabulary on someone else's failure.
+ *
+ * `detail` is carried as the caller passes it. That is safe here and not in `toProblem`
+ * because a caller of THIS function has a status it chose or received, which means it
+ * has already looked at what it is relaying; `toProblem`'s `internal` branch is the one
+ * holding an unreviewed message, and it still refuses to disclose it.
+ */
+export declare function problemForStatus(status: number, detail?: string, instance?: string): Problem;
 /**
  * The statuses an operation can actually answer with today, for the emitted document.
  *

package/dist/errors.d.ts.map

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