approval-md 0.0.1 → 0.2.0

package/dist/src/core/intake-limits.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Request-volume limits at intake (SPEC.md §5.2, APRV-173).
+ *
+ * > **Request-volume limits.** `limits.max_pending` (per class or global):
+ * > maximum simultaneously pending requests; further requests are refused at
+ * > intake with reason `queue-full`. `limits.requests_per_hour` (per origin):
+ * > rolling-window ceiling on request creation; excess is refused with reason
+ * > `rate-limited`.
+ *
+ * This module is that computation. It was policy vocabulary that no runtime
+ * read until this task: a policy could declare either key, the schema would
+ * accept it, and nothing enforced it.
+ *
+ * ## What these limits protect
+ *
+ * Budgets meter money and action counts, which is the world's exposure to the
+ * agent. These meter the QUEUE, which is the human's exposure to the agent. An
+ * agent that floods the queue with cheap, in-budget requests spends nothing and
+ * still defeats the gate, because an approver facing two hundred prompts stops
+ * reading them and starts clearing them. So the ceiling here is on attention,
+ * and a refusal costs the requester one exit code and the approver nothing.
+ *
+ * That difference is why a refusal on this path appends NOTHING (Carter's
+ * approved reading, 2026-08-31). `budget.exceeded` exists because a budget
+ * refusal is a fact about a commitment that audit must be able to reconstruct;
+ * a queue-flood refusal is a fact about a flood, and writing one log record per
+ * refused request would hand the flooder the log growth it was refused the
+ * queue for. The refusals are machine-readable and distinct (§11.1 invariant
+ * 6), which is what an agent and an auditor each need, and the events that WERE
+ * admitted are still all in the log to count from.
+ *
+ * ## Pure, deterministic, injected time
+ *
+ * Same discipline as `core/budgets.ts`: no I/O, no clock, no randomness. The
+ * evaluation instant and the TTL are parameters, so a verdict is replayable
+ * from the log alone. Nothing here re-runs class matching; the gate hands in
+ * the limits the matcher already resolved and the pattern that produced them.
+ *
+ * ## What "pending" means
+ *
+ * A request is pending when {@link requestState} derives `requested` for its
+ * action key at the evaluation instant: no grant, rejection, revocation,
+ * withdrawal, expiry event or lapsed TTL, and no execution. That derivation is
+ * `core/state.ts`'s and is the same one the gate refuses `duplicate-request`
+ * from and the channels build the queue from. Counting pending requests with a
+ * second, private definition is the one thing this module must not do — the
+ * cap a policy writes is a cap on the queue a human is shown, so it counts the
+ * queue a human is shown.
+ *
+ * ## What "per origin" means at v0.1
+ *
+ * **Origin is the record's `actor`.** The approved reading (Carter,
+ * 2026-08-31): the actor on `approval.requested` is assigned by the runtime
+ * from its own configuration rather than from the request, and under MCP the
+ * `--as` argument is appended last, so a caller cannot choose the identity its
+ * requests are counted under. Per-guest actors therefore make the ceiling
+ * per-client, which is the useful shape. This is a v0.1 reading of the spec's
+ * word "origin" rather than a claim that actor and origin are the same thing
+ * forever: an origin richer than the actor (a session, a remote address) would
+ * be a spec amendment, and it would only ever partition the count further.
+ *
+ * ## The rolling window
+ *
+ * `requests_per_hour` is measured over the hour preceding the evaluation
+ * instant, tiled exactly as `core/budgets.ts` tiles its 24 hours: a request
+ * consumes iff
+ *
+ *     evaluationTs - 1h  <  record.ts  <=  evaluationTs
+ *
+ * half-open at the bottom, closed at the top, so consecutive windows tile the
+ * timeline and no request is counted in two of them. A request stamped exactly
+ * one hour before the evaluation instant has aged out; one stamped at the
+ * instant itself is in.
+ *
+ * ## Fail-closed, and what "unset" means
+ *
+ * A limit that is DECLARED and cannot be evaluated fails: a value that is not a
+ * positive finite integer, or an evaluation timestamp no window can be computed
+ * from, yields `pass: false` with a note. Silence is never a grant.
+ *
+ * A limit that is NOT declared enforces nothing, and that is the conservative
+ * answer rather than an exception to it. SPEC.md §5.2 says these ceilings are a
+ * tripwire whose "defaults are generous"; a runtime that invented one would
+ * refuse requests under a policy the human attested and read, and the refusal
+ * would name a number that appears nowhere in the file they signed. The
+ * fail-closed direction for an ABSENT request-volume limit is the same one the
+ * rest of the runtime takes for an absent `approval_ttl`: the policy declares
+ * no ceiling, so no ceiling binds, and the manual gate that binds every request
+ * on this path is what stands between the queue and the flood in the meantime.
+ * Where an operator wants a tripwire, one line of policy arms it.
+ *
+ * ## Division of labour with `core/budgets.ts`
+ *
+ * These two names are evaluated HERE and nowhere else. `core/budgets.ts` skips
+ * them by name rather than refusing them as unknown limits, and this module
+ * ignores every limit name that is not one of them. The two skip lists are
+ * complements, and each module's comment names the other: a limit that both
+ * skipped would be a ceiling in the policy file that no code enforces, which is
+ * the exact defect this task exists to close.
+ */
+import type { EventRecord } from "./log.js";
+import type { Policy } from "./policy-load.js";
+/** Length of the `requests_per_hour` window: one hour, in milliseconds. */
+export declare const REQUEST_WINDOW_MS: number;
+/** The limit name capping simultaneously pending requests (SPEC.md §5.2). */
+export declare const MAX_PENDING = "max_pending";
+/** The limit name capping request creation per origin (SPEC.md §5.2). */
+export declare const REQUESTS_PER_HOUR = "requests_per_hour";
+/**
+ * The two names this module owns.
+ *
+ * Exported so `core/budgets.ts` skips exactly these and no others: one array,
+ * read by both modules, so the two skip lists cannot drift apart into a limit
+ * nobody evaluates.
+ */
+export declare const INTAKE_LIMIT_NAMES: readonly ["max_pending", "requests_per_hour"];
+/** Is `name` a request-volume limit (and therefore not a budget's business)? */
+export declare function isIntakeLimitName(name: string): boolean;
+/** The refusal a failing limit produces at intake. Mirrors SPEC.md §5.2. */
+export type IntakeRefusal = "queue-full" | "rate-limited";
+/**
+ * Which limits apply, as resolved by the policy matcher — this module does not
+ * re-run matching. Shaped like `BudgetScope` deliberately.
+ *
+ * - `classLimits` is `Resolution.limits`: the winning rule's `limits` map.
+ * - `classPattern` is that rule's pattern. Class-scoped counting attributes a
+ *   record by matching its `payload.class` against this pattern, exactly as
+ *   budgets attribute, so one `financial.*` rule is one queue ceiling shared by
+ *   every class it governs rather than a separate invisible queue per class.
+ * - `globalBudgets` is `policy.budgets`: named scopes, each conjunctive, each
+ *   counting every live request whatever its class. That is what makes it
+ *   global, and it is the same reading `core/budgets.ts` gives `daily_actions`.
+ */
+export interface IntakeScope {
+    classLimits: Record<string, number> | null;
+    classPattern: string | null;
+    globalBudgets: Policy["budgets"] | null;
+}
+/** The request being admitted: its class, and the origin it is counted under. */
+export interface IntakeAction {
+    class: string;
+    /** The requesting actor. See "What per origin means" in the header. */
+    origin: string;
+}
+/**
+ * One limit's outcome.
+ *
+ * `observed` is what the log already holds (pending requests, or requests in
+ * the window), `requested` is always `1` — the request being admitted — and
+ * `remaining` is the headroom left after admitting it, so a failing verdict
+ * shows how far over the line the queue is.
+ *
+ * Plain integers rather than the decimal strings `BudgetVerdict` carries. Those
+ * are strings because a failing budget verdict is copied into `budget.exceeded`
+ * and becomes hashed material; these verdicts are never appended anywhere, and
+ * a count has no fractional part to serialize differently in another language.
+ */
+export interface IntakeVerdict {
+    /** `max_pending`, `requests_per_hour`, or `<scope>.max_pending`. */
+    limit: string;
+    scope: "class" | "global";
+    window: "simultaneous" | "rolling-1h";
+    /** The refusal code this verdict produces when it fails. */
+    refusal: IntakeRefusal;
+    observed: number;
+    requested: number;
+    remaining: number;
+    /** The declared ceiling, or `null` when it could not be read as one. */
+    ceiling: number | null;
+    pass: boolean;
+    /** Present only when the verdict needs explaining (fail-closed refusals). */
+    note?: string;
+}
+/** Outcome of {@link evaluateIntakeLimits}. Conjunctive: all must pass. */
+export interface IntakeVerdicts {
+    pass: boolean;
+    verdicts: IntakeVerdict[];
+}
+/**
+ * How many requests are simultaneously pending at `evaluationTs`.
+ *
+ * Derived through {@link requestState}, one action key at a time, so every
+ * exit from the queue is honoured by the definition that owns it: a decision,
+ * a revocation, a withdrawal (APRV-106), an `approval.expired` record, a TTL
+ * lapsed by arithmetic with no record at all, and an execution. Nothing here
+ * re-implements any of that.
+ *
+ * `pattern` scopes the count: `null` counts the whole queue (the global
+ * scopes), a pattern counts the requests attributed to the winning rule.
+ * Attribution reads the class off the `approval.requested` record rather than
+ * off the derivation, because the pending set is the set of requests, and the
+ * class a request was routed under is the class it was recorded with.
+ *
+ * Cost is one derivation per requested key, which is what
+ * `channels/tagging.ts` already pays to build the same queue. Sharing that
+ * cost is the point: a faster private walk would be a second definition of
+ * pending, and the two would agree until the day they did not.
+ */
+export declare function pendingCount(records: EventRecord[], pattern: string | null, evaluationTs: string, ttlMs: number | null): number;
+/**
+ * How many `approval.requested` records `origin` created inside the window.
+ *
+ * Counts records, not live requests: the ceiling is on request CREATION, so a
+ * request that was granted, rejected or withdrawn a minute after it was made
+ * still consumed the origin's share of the hour. A ceiling that forgot a
+ * request the moment it was answered would be no ceiling at all — an agent
+ * could withdraw each request as it made it and create them without bound.
+ *
+ * A record whose `ts` cannot be parsed is COUNTED: it cannot be shown to lie
+ * outside the window, and the fail-closed reading of an unplaceable request is
+ * that it is inside. Same rule, and the same reason, as `core/budgets.ts`.
+ *
+ * Returns `null` when `evaluationTs` is not a parseable instant: no window can
+ * be computed, so nothing can be counted, and the caller fails the limit closed
+ * rather than reporting a zero that reads as headroom.
+ */
+export declare function requestsInWindow(records: EventRecord[], origin: string, pattern: string | null, evaluationTs: string): number | null;
+/**
+ * Evaluate every applicable request-volume limit against the log.
+ *
+ * Conjunctive, exactly as budgets are: `pass` is true only when every verdict
+ * passes. Verdicts are emitted class limits first (limit names ascending, which
+ * puts `max_pending` before `requests_per_hour`), then global scopes (scope
+ * name ascending), so the list is byte-stable regardless of policy key order.
+ *
+ * **The refusal code is the first failing verdict's**, in exactly that order,
+ * and the order is normative: a caller told `queue-full` learns that the
+ * approver's queue is at its ceiling, which is a standing condition it must
+ * wait out or escalate; a caller told `rate-limited` learns that its own recent
+ * volume is the problem, which is a condition that clears on its own. Where
+ * both are true the standing condition is the one worth reporting, because an
+ * agent that backs off for a minute on a `rate-limited` and retries into a full
+ * queue has been told the smaller of the two facts.
+ *
+ * `records` may be the whole log; the caller is never asked to pre-filter, for
+ * the reason `core/budgets.ts` gives: a caller that filtered wrongly would
+ * silently widen the ceiling.
+ */
+export declare function evaluateIntakeLimits(records: EventRecord[], scope: IntakeScope, action: IntakeAction, evaluationTs: string, ttlMs: number | null): IntakeVerdicts;
+/**
+ * The refusal code a failing evaluation produces, or `null` when it passed.
+ *
+ * One place, so the gate and any later surface answer with the same code for
+ * the same verdict list. See {@link evaluateIntakeLimits} for why the first
+ * failing verdict in verdict order is the one that speaks.
+ */
+export declare function intakeRefusalOf(verdicts: IntakeVerdicts): IntakeRefusal | null;

package/dist/src/core/intake-limits.js

@@ -0,0 +1,350 @@
+/**
+ * Request-volume limits at intake (SPEC.md §5.2, APRV-173).
+ *
+ * > **Request-volume limits.** `limits.max_pending` (per class or global):
+ * > maximum simultaneously pending requests; further requests are refused at
+ * > intake with reason `queue-full`. `limits.requests_per_hour` (per origin):
+ * > rolling-window ceiling on request creation; excess is refused with reason
+ * > `rate-limited`.
+ *
+ * This module is that computation. It was policy vocabulary that no runtime
+ * read until this task: a policy could declare either key, the schema would
+ * accept it, and nothing enforced it.
+ *
+ * ## What these limits protect
+ *
+ * Budgets meter money and action counts, which is the world's exposure to the
+ * agent. These meter the QUEUE, which is the human's exposure to the agent. An
+ * agent that floods the queue with cheap, in-budget requests spends nothing and
+ * still defeats the gate, because an approver facing two hundred prompts stops
+ * reading them and starts clearing them. So the ceiling here is on attention,
+ * and a refusal costs the requester one exit code and the approver nothing.
+ *
+ * That difference is why a refusal on this path appends NOTHING (Carter's
+ * approved reading, 2026-08-31). `budget.exceeded` exists because a budget
+ * refusal is a fact about a commitment that audit must be able to reconstruct;
+ * a queue-flood refusal is a fact about a flood, and writing one log record per
+ * refused request would hand the flooder the log growth it was refused the
+ * queue for. The refusals are machine-readable and distinct (§11.1 invariant
+ * 6), which is what an agent and an auditor each need, and the events that WERE
+ * admitted are still all in the log to count from.
+ *
+ * ## Pure, deterministic, injected time
+ *
+ * Same discipline as `core/budgets.ts`: no I/O, no clock, no randomness. The
+ * evaluation instant and the TTL are parameters, so a verdict is replayable
+ * from the log alone. Nothing here re-runs class matching; the gate hands in
+ * the limits the matcher already resolved and the pattern that produced them.
+ *
+ * ## What "pending" means
+ *
+ * A request is pending when {@link requestState} derives `requested` for its
+ * action key at the evaluation instant: no grant, rejection, revocation,
+ * withdrawal, expiry event or lapsed TTL, and no execution. That derivation is
+ * `core/state.ts`'s and is the same one the gate refuses `duplicate-request`
+ * from and the channels build the queue from. Counting pending requests with a
+ * second, private definition is the one thing this module must not do — the
+ * cap a policy writes is a cap on the queue a human is shown, so it counts the
+ * queue a human is shown.
+ *
+ * ## What "per origin" means at v0.1
+ *
+ * **Origin is the record's `actor`.** The approved reading (Carter,
+ * 2026-08-31): the actor on `approval.requested` is assigned by the runtime
+ * from its own configuration rather than from the request, and under MCP the
+ * `--as` argument is appended last, so a caller cannot choose the identity its
+ * requests are counted under. Per-guest actors therefore make the ceiling
+ * per-client, which is the useful shape. This is a v0.1 reading of the spec's
+ * word "origin" rather than a claim that actor and origin are the same thing
+ * forever: an origin richer than the actor (a session, a remote address) would
+ * be a spec amendment, and it would only ever partition the count further.
+ *
+ * ## The rolling window
+ *
+ * `requests_per_hour` is measured over the hour preceding the evaluation
+ * instant, tiled exactly as `core/budgets.ts` tiles its 24 hours: a request
+ * consumes iff
+ *
+ *     evaluationTs - 1h  <  record.ts  <=  evaluationTs
+ *
+ * half-open at the bottom, closed at the top, so consecutive windows tile the
+ * timeline and no request is counted in two of them. A request stamped exactly
+ * one hour before the evaluation instant has aged out; one stamped at the
+ * instant itself is in.
+ *
+ * ## Fail-closed, and what "unset" means
+ *
+ * A limit that is DECLARED and cannot be evaluated fails: a value that is not a
+ * positive finite integer, or an evaluation timestamp no window can be computed
+ * from, yields `pass: false` with a note. Silence is never a grant.
+ *
+ * A limit that is NOT declared enforces nothing, and that is the conservative
+ * answer rather than an exception to it. SPEC.md §5.2 says these ceilings are a
+ * tripwire whose "defaults are generous"; a runtime that invented one would
+ * refuse requests under a policy the human attested and read, and the refusal
+ * would name a number that appears nowhere in the file they signed. The
+ * fail-closed direction for an ABSENT request-volume limit is the same one the
+ * rest of the runtime takes for an absent `approval_ttl`: the policy declares
+ * no ceiling, so no ceiling binds, and the manual gate that binds every request
+ * on this path is what stands between the queue and the flood in the meantime.
+ * Where an operator wants a tripwire, one line of policy arms it.
+ *
+ * ## Division of labour with `core/budgets.ts`
+ *
+ * These two names are evaluated HERE and nowhere else. `core/budgets.ts` skips
+ * them by name rather than refusing them as unknown limits, and this module
+ * ignores every limit name that is not one of them. The two skip lists are
+ * complements, and each module's comment names the other: a limit that both
+ * skipped would be a ceiling in the policy file that no code enforces, which is
+ * the exact defect this task exists to close.
+ */
+import { matchesPattern } from "./policy-match.js";
+import { payloadOf, requestState } from "./state.js";
+/** Length of the `requests_per_hour` window: one hour, in milliseconds. */
+export const REQUEST_WINDOW_MS = 60 * 60 * 1000;
+/** The limit name capping simultaneously pending requests (SPEC.md §5.2). */
+export const MAX_PENDING = "max_pending";
+/** The limit name capping request creation per origin (SPEC.md §5.2). */
+export const REQUESTS_PER_HOUR = "requests_per_hour";
+/**
+ * The two names this module owns.
+ *
+ * Exported so `core/budgets.ts` skips exactly these and no others: one array,
+ * read by both modules, so the two skip lists cannot drift apart into a limit
+ * nobody evaluates.
+ */
+export const INTAKE_LIMIT_NAMES = [MAX_PENDING, REQUESTS_PER_HOUR];
+/** Is `name` a request-volume limit (and therefore not a budget's business)? */
+export function isIntakeLimitName(name) {
+    return INTAKE_LIMIT_NAMES.includes(name);
+}
+/** `payload.class` when it is a string, else `null`. */
+function classOf(record) {
+    const value = payloadOf(record)["class"];
+    return typeof value === "string" ? value : null;
+}
+/**
+ * Does this record belong to the scope being counted?
+ *
+ * `pattern === null` is the global scope: everything belongs. Otherwise the
+ * record's own declared class must match the winning rule's pattern. A record
+ * carrying no usable class is invisible to a class-scoped count for the reason
+ * `core/budgets.ts` gives: it cannot be SHOWN to belong to the class. It is
+ * still counted by every global scope.
+ */
+function inScope(record, pattern) {
+    if (pattern === null)
+        return true;
+    const cls = classOf(record);
+    return cls !== null && matchesPattern(pattern, cls);
+}
+/** Every action key with an `approval.requested`, in log order, deduplicated. */
+function requestedKeys(records) {
+    const keys = [];
+    for (const record of records) {
+        if (record.event !== "approval.requested")
+            continue;
+        const key = record.action_key;
+        if (key === undefined || keys.includes(key))
+            continue;
+        keys.push(key);
+    }
+    return keys;
+}
+/**
+ * How many requests are simultaneously pending at `evaluationTs`.
+ *
+ * Derived through {@link requestState}, one action key at a time, so every
+ * exit from the queue is honoured by the definition that owns it: a decision,
+ * a revocation, a withdrawal (APRV-106), an `approval.expired` record, a TTL
+ * lapsed by arithmetic with no record at all, and an execution. Nothing here
+ * re-implements any of that.
+ *
+ * `pattern` scopes the count: `null` counts the whole queue (the global
+ * scopes), a pattern counts the requests attributed to the winning rule.
+ * Attribution reads the class off the `approval.requested` record rather than
+ * off the derivation, because the pending set is the set of requests, and the
+ * class a request was routed under is the class it was recorded with.
+ *
+ * Cost is one derivation per requested key, which is what
+ * `channels/tagging.ts` already pays to build the same queue. Sharing that
+ * cost is the point: a faster private walk would be a second definition of
+ * pending, and the two would agree until the day they did not.
+ */
+export function pendingCount(records, pattern, evaluationTs, ttlMs) {
+    let count = 0;
+    for (const key of requestedKeys(records)) {
+        const derivation = requestState(records, key, evaluationTs, ttlMs);
+        if (derivation.state !== "requested")
+            continue;
+        if (derivation.requestSeq === null)
+            continue;
+        const record = records.find((candidate) => candidate.seq === derivation.requestSeq);
+        if (record === undefined)
+            continue;
+        if (!inScope(record, pattern))
+            continue;
+        count += 1;
+    }
+    return count;
+}
+/**
+ * How many `approval.requested` records `origin` created inside the window.
+ *
+ * Counts records, not live requests: the ceiling is on request CREATION, so a
+ * request that was granted, rejected or withdrawn a minute after it was made
+ * still consumed the origin's share of the hour. A ceiling that forgot a
+ * request the moment it was answered would be no ceiling at all — an agent
+ * could withdraw each request as it made it and create them without bound.
+ *
+ * A record whose `ts` cannot be parsed is COUNTED: it cannot be shown to lie
+ * outside the window, and the fail-closed reading of an unplaceable request is
+ * that it is inside. Same rule, and the same reason, as `core/budgets.ts`.
+ *
+ * Returns `null` when `evaluationTs` is not a parseable instant: no window can
+ * be computed, so nothing can be counted, and the caller fails the limit closed
+ * rather than reporting a zero that reads as headroom.
+ */
+export function requestsInWindow(records, origin, pattern, evaluationTs) {
+    const evaluationMs = Date.parse(evaluationTs);
+    if (Number.isNaN(evaluationMs))
+        return null;
+    const floor = evaluationMs - REQUEST_WINDOW_MS;
+    let count = 0;
+    for (const record of records) {
+        if (record.event !== "approval.requested")
+            continue;
+        if (record.actor !== origin)
+            continue;
+        if (!inScope(record, pattern))
+            continue;
+        const ms = Date.parse(record.ts);
+        if (!Number.isNaN(ms) && !(ms > floor && ms <= evaluationMs))
+            continue;
+        count += 1;
+    }
+    return count;
+}
+/** A declared ceiling as an exact positive integer, or `null`. */
+function ceilingOf(value) {
+    if (typeof value !== "number")
+        return null;
+    if (!Number.isInteger(value) || value <= 0)
+        return null;
+    return value;
+}
+function verdict(limit, scope, window, refusal, observed, ceiling) {
+    const remaining = ceiling - observed - 1;
+    return {
+        limit,
+        scope,
+        window,
+        refusal,
+        observed,
+        requested: 1,
+        remaining,
+        ceiling,
+        pass: remaining >= 0,
+    };
+}
+/** A fail-closed refusal: nothing measured, nothing admitted, reason attached. */
+function refuse(limit, scope, window, refusal, note) {
+    return {
+        limit,
+        scope,
+        window,
+        refusal,
+        observed: 0,
+        requested: 1,
+        remaining: -1,
+        ceiling: null,
+        pass: false,
+        note,
+    };
+}
+/**
+ * Evaluate every applicable request-volume limit against the log.
+ *
+ * Conjunctive, exactly as budgets are: `pass` is true only when every verdict
+ * passes. Verdicts are emitted class limits first (limit names ascending, which
+ * puts `max_pending` before `requests_per_hour`), then global scopes (scope
+ * name ascending), so the list is byte-stable regardless of policy key order.
+ *
+ * **The refusal code is the first failing verdict's**, in exactly that order,
+ * and the order is normative: a caller told `queue-full` learns that the
+ * approver's queue is at its ceiling, which is a standing condition it must
+ * wait out or escalate; a caller told `rate-limited` learns that its own recent
+ * volume is the problem, which is a condition that clears on its own. Where
+ * both are true the standing condition is the one worth reporting, because an
+ * agent that backs off for a minute on a `rate-limited` and retries into a full
+ * queue has been told the smaller of the two facts.
+ *
+ * `records` may be the whole log; the caller is never asked to pre-filter, for
+ * the reason `core/budgets.ts` gives: a caller that filtered wrongly would
+ * silently widen the ceiling.
+ */
+export function evaluateIntakeLimits(records, scope, action, evaluationTs, ttlMs) {
+    const classLimits = scope.classLimits ?? {};
+    const globalBudgets = scope.globalBudgets ?? {};
+    const verdicts = [];
+    // --- Class limits (the winning rule's `limits`) --------------------------
+    for (const name of Object.keys(classLimits).sort()) {
+        if (!isIntakeLimitName(name))
+            continue; // `core/budgets.ts` owns the rest.
+        const declared = classLimits[name];
+        const isPending = name === MAX_PENDING;
+        const window = isPending ? "simultaneous" : "rolling-1h";
+        const refusal = isPending ? "queue-full" : "rate-limited";
+        const ceiling = ceilingOf(declared);
+        if (ceiling === null) {
+            verdicts.push(refuse(name, "class", window, refusal, `class limit "${name}" is not a positive whole number; a ceiling that cannot be compared cannot be proven satisfied, so the request is refused rather than admitted against a limit nobody can evaluate`));
+            continue;
+        }
+        if (scope.classPattern === null) {
+            verdicts.push(refuse(name, "class", window, refusal, `class limit "${name}" was supplied without the class pattern that scopes its count; the queue cannot be attributed, so the limit cannot be proven satisfied`));
+            continue;
+        }
+        if (isPending) {
+            verdicts.push(verdict(name, "class", window, refusal, pendingCount(records, scope.classPattern, evaluationTs, ttlMs), ceiling));
+            continue;
+        }
+        const observed = requestsInWindow(records, action.origin, scope.classPattern, evaluationTs);
+        if (observed === null) {
+            verdicts.push(refuse(name, "class", window, refusal, `evaluation timestamp "${evaluationTs}" is not a parseable RFC 3339 instant; the rolling window cannot be computed, so no request-volume limit can be proven satisfied`));
+            continue;
+        }
+        verdicts.push(verdict(name, "class", window, refusal, observed, ceiling));
+    }
+    // --- Global scopes (`policy.budgets`) -----------------------------------
+    // Only `max_pending` lives here: `policy.schema.json` gives a budget scope
+    // `daily_usd`, `daily_actions` and `max_pending`, and a rate limit has no
+    // global spelling because it is measured per origin and a scope names none.
+    for (const scopeName of Object.keys(globalBudgets).sort()) {
+        const budget = globalBudgets[scopeName];
+        if (budget === undefined)
+            continue;
+        const declared = budget[MAX_PENDING];
+        if (declared === undefined)
+            continue;
+        const label = `${scopeName}.${MAX_PENDING}`;
+        const ceiling = ceilingOf(declared);
+        if (ceiling === null) {
+            verdicts.push(refuse(label, "global", "simultaneous", "queue-full", `budget "${label}" is not a positive whole number; a ceiling that cannot be compared cannot be proven satisfied`));
+            continue;
+        }
+        verdicts.push(verdict(label, "global", "simultaneous", "queue-full", pendingCount(records, null, evaluationTs, ttlMs), ceiling));
+    }
+    return { pass: verdicts.every((entry) => entry.pass), verdicts };
+}
+/**
+ * The refusal code a failing evaluation produces, or `null` when it passed.
+ *
+ * One place, so the gate and any later surface answer with the same code for
+ * the same verdict list. See {@link evaluateIntakeLimits} for why the first
+ * failing verdict in verdict order is the one that speaks.
+ */
+export function intakeRefusalOf(verdicts) {
+    const failed = verdicts.verdicts.find((entry) => !entry.pass);
+    return failed === undefined ? null : failed.refusal;
+}
+//# sourceMappingURL=intake-limits.js.map

package/dist/src/core/intake-limits.js.map

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

package/dist/src/core/jcs.d.ts

@@ -0,0 +1,52 @@
+/**
+ * RFC 8785 — JSON Canonicalization Scheme (JCS).
+ *
+ * SPEC.md §8 fixes the hash scheme at `sha256/jcs`: SHA-256 over the RFC 8785
+ * canonical serialization of an event record with `prev` included. The digest
+ * is a permanent wire commitment, so this module is part of the deterministic
+ * core: same input, same bytes, forever. No clock, no locale, no randomness,
+ * no configuration knobs.
+ *
+ * Implemented by hand — zero dependencies (CLAUDE.md: minimal dependencies,
+ * and a canonicalizer is exactly the kind of code that must not drift beneath
+ * us). Three rules do all the work:
+ *
+ * 1. **Object keys** are sorted by their UTF-16 code units (RFC 8785 §3.2.3).
+ *    That is JavaScript's own `<` on strings, which is why a naive code-point
+ *    sort is *wrong*: a key starting U+10000 (surrogate pair D800 DC00) sorts
+ *    *before* a key starting U+FFFF under code units and *after* it under code
+ *    points. The comparator below is deliberately code-unit based.
+ * 2. **Numbers** use ECMAScript `Number::toString` (RFC 8785 §3.2.2.3), which
+ *    is precisely what `JSON.stringify` emits for a finite number — including
+ *    `1e+21`, `1e-7`, and `-0` collapsing to `0`. Delegating is not a shortcut
+ *    around the RFC; the RFC's normative reference *is* the ECMAScript
+ *    algorithm.
+ * 3. **Strings** use the ECMAScript `QuoteJSONString` escaping (RFC 8785
+ *    §3.2.2.2): shortest form for `\b \t \n \f \r \" \\`, `\u00xx` with
+ *    lowercase hex for the remaining C0 controls, and every other code point
+ *    literal. `JSON.stringify` on a string implements exactly this, including
+ *    the well-formed-stringify escaping of lone surrogates (ES2019+).
+ *
+ * Everything JCS cannot represent is rejected loudly rather than coerced:
+ * `undefined`, functions, symbols, `BigInt`, `NaN`, `±Infinity`, and non-plain
+ * objects (a `Date` or `Map` would silently canonicalize to `{}`). Silent
+ * coercion in a hash input is a tamper-evidence hole, so this module fails
+ * closed by throwing {@link JcsError}.
+ */
+/** Reason a value could not be canonicalized. */
+export type JcsErrorCode = "undefined" | "function" | "symbol" | "bigint" | "non-finite-number" | "unsupported-object" | "cycle";
+/** Thrown when a value has no RFC 8785 canonical form. */
+export declare class JcsError extends Error {
+    /** Machine-readable reason. */
+    readonly code: JcsErrorCode;
+    /** JSON Pointer-ish location of the offending value ("" for the root). */
+    readonly path: string;
+    constructor(code: JcsErrorCode, path: string, message: string);
+}
+/**
+ * Canonicalize `value` to its RFC 8785 (JCS) serialization: sorted object
+ * keys, no whitespace, ECMAScript number and string formatting.
+ *
+ * @throws {JcsError} if the value contains anything JCS cannot represent.
+ */
+export declare function canonicalize(value: unknown): string;