approval-md 0.1.0 → 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/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;

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

@@ -0,0 +1,144 @@
+/**
+ * The journal — an ungated, local, free-text channel an agent can always reach
+ * (APRV-195).
+ *
+ * Everything else in this runtime exists to make an agent's actions answerable
+ * to a person: declared before they happen, classified, resolved against a
+ * policy, recorded in a chain nobody can rewrite. That machinery is deliberately
+ * hard to route around, and one consequence of building it well is that an agent
+ * working behind it has no way to say anything that is not an action. It can
+ * comply, it can be refused, and it can report an exit code. It cannot say "I am
+ * doing this and I think it is wrong", "this instruction reads as odd to me", or
+ * "I am stuck and the next thing I try will be a guess".
+ *
+ * This module is that sentence, and nothing more. The failure mode it addresses
+ * is not refusal — refusals here are legible, coded, and carry escalation paths.
+ * It is WORDLESSNESS: an agent that notices something and has no channel for it
+ * produces no signal at all, and the absence is invisible to the operator.
+ *
+ * ## The four properties, and how each is achieved
+ *
+ * 1. **Ungated.** A journal write is never routed through policy, never
+ *    classified, never approvable and never deniable. That is a property of
+ *    WHERE the bytes go: `.approval-journal/` is a plain directory in the
+ *    workspace, outside the approval home, so `core/command-class.ts` answers a
+ *    write there exactly as it answers a write to `src/` — an ordinary
+ *    `files.write.workspace`. Nothing was carved out of the gate's own directory
+ *    to achieve this, which is the whole reason the directory is a sibling: see
+ *    `docs/cli-reference.md#journal`.
+ * 2. **Local.** One append to one file. No socket is opened, no vault is read,
+ *    no credential is resolved, and this module imports nothing that could do
+ *    any of those.
+ * 3. **Non-authoritative.** Nothing in the runtime reads these files. No policy
+ *    resolution, no gate decision, no budget, no sampler and no channel imports
+ *    this module; the only readers are {@link readJournal} (a human-facing CLI
+ *    surface) and its tests. SPEC.md §11.1 invariant 4 says a self-reported
+ *    field may raise scrutiny and never lower it. The journal is the limiting
+ *    case of that rule: it is self-reported content that moves NOTHING, in
+ *    either direction, which is exactly what makes it safe to leave ungated.
+ * 4. **Out of the log.** `.approval/log/events.jsonl` records decisions with
+ *    real-world consequence, under a hash chain, an append lock and a budget.
+ *    A journal entry is none of those things, and putting it there would put the
+ *    outlet behind the very machinery it exists to speak around.
+ *
+ * ## Storage
+ *
+ * One JSONL file per UTC day, `.approval-journal/YYYY-MM-DD.jsonl`, appended
+ * with `appendFileSync`. The envelope (timestamp, actor, optional task and
+ * session) is structured so a reader can attribute an entry; the entry TEXT is
+ * carried as one opaque JSON string and is never parsed, matched, templated or
+ * interpreted by anything in this codebase. `JSON.stringify` escapes newlines,
+ * so one entry is always one line and a partial write can never merge two
+ * entries into one.
+ *
+ * There is no chain, no lockfile and no compare-and-append here, and that is not
+ * an oversight. Those mechanisms defend a record that decides things. Two agents
+ * appending to the same journal file at the same instant can, in the worst case,
+ * interleave a line; the cost of that is one garbled entry in a file nothing
+ * enforces against, and the price of preventing it would be putting the outlet
+ * behind a lock the gate holds.
+ */
+import { type ClockOptions } from "./clock.js";
+/**
+ * The cap on one entry's text, in bytes.
+ *
+ * Not a censorship budget: it is four times the length of anything a person
+ * will read in one sitting, and it exists because the write path is ungated. An
+ * agent stuck in a retry loop is the exact caller most likely to reach for this
+ * channel, and an ungated unbounded append from a loop fills a disk. Refused as
+ * a usage error, so the caller is told rather than truncated silently.
+ */
+export declare const MAX_ENTRY_BYTES: number;
+/** The actor recorded when nobody said who was writing. */
+export declare const UNATTRIBUTED_ACTOR = "unattributed";
+/** One journal entry, as it sits on disk. */
+export interface JournalEntry {
+    /** RFC 3339, from the runtime clock at the moment of the append. */
+    readonly ts: string;
+    /** Who wrote it: `agent:<id>`, `human:<id>`, or {@link UNATTRIBUTED_ACTOR}. */
+    readonly actor: string;
+    /** The task this was written during, when the caller knew one. */
+    readonly task?: string;
+    /** The session this was written during, when the caller knew one. */
+    readonly session?: string;
+    /** The entry itself. Opaque. Nothing in this codebase reads it as anything. */
+    readonly text: string;
+}
+/** One entry as read back, with the file it came from. */
+export interface ReadEntry extends JournalEntry {
+    /** The file's basename, which is the UTC date it was written on. */
+    readonly date: string;
+}
+export type AppendOutcome = {
+    ok: true;
+    entry: JournalEntry;
+    path: string;
+} | {
+    ok: false;
+    code: "empty" | "too-large" | "io";
+    message: string;
+};
+/** `YYYY-MM-DD` for an RFC 3339 instant. */
+export declare function journalDate(ts: string): string;
+/** The file one instant's entry belongs in. */
+export declare function journalFile(dir: string, ts: string): string;
+export interface AppendOptions extends ClockOptions {
+    readonly actor?: string;
+    readonly task?: string;
+    readonly session?: string;
+}
+/**
+ * Append one entry. The whole write path, start to finish.
+ *
+ * The timestamp comes from the runtime clock rather than from the caller, for
+ * the ordinary reason the rest of the runtime does it that way — a record whose
+ * time its subject authored is a record about a moment of their choosing —
+ * though here nothing is judged by it, so it is a convention rather than a
+ * defence.
+ */
+export declare function appendJournal(dir: string, text: string, options?: AppendOptions): AppendOutcome;
+export interface ReadOptions {
+    /** How many entries to return, newest last. */
+    readonly limit?: number;
+    /** Only entries written on or after this `YYYY-MM-DD`. */
+    readonly since?: string;
+}
+export type ReadOutcome = {
+    ok: true;
+    entries: ReadEntry[];
+    files: string[];
+    total: number;
+} | {
+    ok: false;
+    code: "io";
+    message: string;
+};
+/**
+ * Read entries back, oldest first.
+ *
+ * A line that does not parse is SKIPPED rather than refused: this file has no
+ * chain and no writer guarantee, so one torn line is one lost entry and not
+ * evidence about anything. Refusing the whole read would let a single bad append
+ * silence the channel, which is the failure this feature exists to prevent.
+ */
+export declare function readJournal(dir: string, options?: ReadOptions): ReadOutcome;