approval-md 0.1.0 → 0.2.0

package/dist/src/channels/render-queue.d.ts

@@ -0,0 +1,149 @@
+/**
+ * `.approval/QUEUE.md` — the queue projection of SPEC.md §9.1.
+ *
+ * > **The queue** (`.approval/QUEUE.md`): a rendered, read-only markdown view of
+ * > pending requests (task, actions, declared effects, cost, TTL countdown) plus
+ * > the sampled-audit backlog. Regenerated on every relevant event. This is the
+ * > screenshot; it is never the truth.
+ *
+ * Three properties are the whole point of this module.
+ *
+ * **It is a pure function of (verified log, policy, `now`).** No ambient clock,
+ * no locale, no hostname, no environment, no random temp name in the bytes. The
+ * evaluation instant is a parameter — the same discipline `channels/tagging.ts`
+ * already keeps — so an identical log rendered at an identical `now` produces
+ * identical bytes, and a rendering can be reproduced later from the log alone.
+ * Every number here is formatted by hand with integer arithmetic for the same
+ * reason: `toLocaleString` would make the output depend on the machine.
+ *
+ * **It re-derives nothing.** Entries come from
+ * {@link buildPendingQueue}, which is the one place a {@link ChannelRequest} is
+ * built. So the class, the autonomy, the provenance, the budgets, the
+ * attestation and the TTL a reader sees in QUEUE.md are the same answers the
+ * gate itself would give — not a second implementation that could drift. This
+ * module's entire job is text.
+ *
+ * **It never writes the log.** {@link writeQueue} writes exactly one file, and
+ * it is `QUEUE.md`.
+ *
+ * ## Why this lives in `src/channels/`, not `src/core/`
+ *
+ * It consumes `channels/contract.ts`'s tagged requests through
+ * `channels/tagging.ts`. Putting it in `core/` would make core import channels,
+ * inverting the dependency the codebase is built on: core decides, channels
+ * display, and this file is display — a read-only markdown surface that collects
+ * no gesture and holds no authority. It sits beside `tagging.ts` and `batch.ts`
+ * because it is the third consumer of the same tagged data, and it deliberately
+ * does not implement {@link ../channels/contract.js Channel}: QUEUE.md notifies
+ * nobody and answers nothing.
+ *
+ * ## B3: computed vs claimed
+ *
+ * SPEC.md §9: "Every displayed field is one of two kinds and MUST be visibly
+ * distinguished". Here that is structural, not typographic: computed fields are
+ * rendered as `computed · <source>` lines under **Computed by the runtime**, and
+ * claimed fields under a separate **Claimed by `<actor>` (not verified)** block
+ * that names its author. A reader skimming the file cannot mistake an agent's
+ * cost estimate for a budget verdict, because they are not in the same list.
+ *
+ * ## The full payload is NOT in this file — flagged for human review
+ *
+ * SPEC.md §10.4 requires channels to present the full payload before collecting
+ * a decision. QUEUE.md collects no decision: it is a read-only summary, and the
+ * decision surfaces are the channels (`approval grant`, the web page, Telegram),
+ * each of which presents the bytes at decision time. Inlining payloads here
+ * would put every pending payload — recipients, bodies, argv — into a file that
+ * is regenerated on every event, checked into nothing, and read by anyone with
+ * the working directory, with no gesture ever collected from it. So the queue
+ * carries the **binding** (`payload_hash`) and points at the channels for the
+ * bytes, and the rendered header says exactly that to the human reading it.
+ *
+ * Which is a different statement from "the renderer cannot see the payload".
+ * Since APRV-28 it can: `channels/tagging.ts` reads the payload store beside the
+ * log (SPEC.md §6.2's "the payload itself is stored or referenced by the request
+ * so channels can display it"), so a request whose bytes were supplied at intake
+ * is *summarizable* here and appears in the pending section — which is why this
+ * file's pending count now agrees with the queue every channel shows, where
+ * before it silently disagreed. The bytes still do not appear in this file.
+ * Requests whose material nobody holds remain in {@link QueueRender.skipped},
+ * rendered in their own section with the reason, never silently dropped.
+ */
+import type { LogHead } from "../core/log.js";
+import { type TagOptions } from "./tagging.js";
+/**
+ * Rendering options. A superset of {@link TagOptions} with nothing added: the
+ * renderer's inputs are exactly the tagger's inputs, plus `now`, because it
+ * derives nothing the tagger does not already derive.
+ */
+export type RenderQueueOptions = TagOptions;
+/**
+ * Why the renderer refused.
+ *
+ * The three log codes are `channels/tagging.ts`'s and `core/state.ts`'s,
+ * verbatim, so a corrupt log is reported as corruption by every layer with one
+ * vocabulary. `write-failed` is {@link writeQueue}'s alone — the renderer itself
+ * cannot fail for any other reason, because it is a pure function.
+ */
+export declare const RENDER_QUEUE_REFUSAL_CODES: readonly ["log-unreadable", "log-torn-tail", "log-corrupt", "write-failed"];
+export type RenderQueueRefusalCode = (typeof RENDER_QUEUE_REFUSAL_CODES)[number];
+export interface RenderQueueRefusal {
+    ok: false;
+    code: RenderQueueRefusalCode;
+    message: string;
+}
+/** A successful render: the bytes, plus what went into them. */
+export interface QueueRender {
+    ok: true;
+    /** The complete file contents. Deterministic for a given (log, policy, now). */
+    markdown: string;
+    /** The chain head the render derives from; `null` for an empty log. */
+    head: LogHead | null;
+    /** Pending requests rendered, in log order. */
+    pending: number;
+    /** Live requests that could not be tagged, listed with their reason. */
+    skipped: number;
+    /** `audit.sampled` events with no later `audit.reviewed`. */
+    auditBacklog: number;
+}
+export type RenderQueueResult = QueueRender | RenderQueueRefusal;
+export interface QueueWrite extends Omit<QueueRender, "markdown"> {
+    /** Where the file was written. */
+    path: string;
+    /** Bytes written (UTF-8). */
+    bytes: number;
+}
+export type WriteQueueResult = QueueWrite | RenderQueueRefusal;
+/**
+ * Render the queue.
+ *
+ * Deterministic in the strong sense: for a fixed log, policy and `now`, the
+ * returned string is byte-identical across processes and machines. Nothing here
+ * reads a clock, a locale, an environment variable, or a hostname.
+ *
+ * Expiry is not this module's judgment: `channels/tagging.ts` derives state
+ * through `core/state.ts` with the policy TTL and the same `now`, so a request
+ * whose TTL has elapsed is `expired`, not `requested`, and never reaches the
+ * pending section. The countdown a reader sees therefore never reaches zero on
+ * a listed entry.
+ *
+ * The verified read happens twice — once here for the head and the audit
+ * records, once inside {@link buildPendingQueue} — which is a deliberate trade:
+ * a second walk of the chain costs a few milliseconds on a rendering path, and
+ * the alternative is widening the tagger's public result to carry records it
+ * has no other reason to expose.
+ */
+export declare function renderQueue(logPath: string, options: RenderQueueOptions, now: string): RenderQueueResult;
+/**
+ * Render and write `.approval/QUEUE.md` atomically.
+ *
+ * Temp file in the destination directory, `fsync`, then `rename` — a reader
+ * either sees the previous complete rendering or the new one, never a half-
+ * written queue. The temp name is the only non-deterministic byte anywhere in
+ * this module and it never reaches the file's contents; it is removed on every
+ * failure path, so a failed render leaves no debris beside the queue.
+ *
+ * Writes this one file and nothing else. In particular it does not touch the
+ * log: the log is opened read-only by the verified read and is not reopened
+ * here.
+ */
+export declare function writeQueue(logPath: string, queuePath: string, options: RenderQueueOptions, now: string): WriteQueueResult;

package/dist/src/channels/tagging.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The runtime-side tagger: log + policy in, render-ready request out
+ * (SPEC.md §9, §10.3, §10.4).
+ *
+ * This is the only place a {@link ChannelRequest} is built, and it is on the
+ * runtime side of the boundary on purpose. Every `computed` field here is
+ * derived by the same modules the gate itself uses — `core/state.ts` for the
+ * verified read and the approval derivation, `core/policy-match.ts` /
+ * `policy-explain.ts` for autonomy, `core/budgets.ts` for the verdicts,
+ * `core/attest.ts` for the attestation status, `core/payload.ts` for the
+ * content binding — so what a channel displays as "computed" is the same answer
+ * the gate would give, not a second implementation that could disagree with it.
+ * Every `claimed` field is copied out of a log record and stamped with the actor
+ * who authored that record.
+ *
+ * ## Why this takes a log *path*, not records
+ *
+ * SPEC.md §11.1(1): enforcement paths read only verified records. A channel
+ * request is what a human's decision is made from, so it is an enforcement
+ * surface in the sense that matters — a request built from a spliced log would
+ * put a fabricated action in front of an approver. Accepting an
+ * `EventRecord[]` would let a caller hand over anything; taking the path and
+ * calling {@link readVerifiedRecords} here means the chain is walked, the hashes
+ * recomputed and the schemas checked before a single field is tagged, and a log
+ * that does not verify produces a refusal rather than a queue entry.
+ *
+ * ## Where the full payload comes from — flagged for human review
+ *
+ * v0.1's log records a `payload_hash`, never the payload bytes: the binding is
+ * a commitment, and putting the bytes in an append-only log would make every
+ * approved payload permanent and world-readable to anyone with the log. So the
+ * material to render comes from the payload store beside the log
+ * (`core/payload-store.ts`, APRV-28), or from a caller-supplied override
+ * ({@link TagOptions.payload}) where an operator holds the bytes somewhere else,
+ * and this module **verifies it against the recorded hash** before tagging it
+ * `computed` — material that does not hash to the bound value is refused
+ * `payload-mismatch` and never reaches a channel. That verification is what
+ * makes `fullPayload` a computed field rather than one more agent claim, and it
+ * is the same check `core/token.ts` makes at spend time.
+ *
+ * Determinism: no clock. `now` is a parameter, so a queue rendering is
+ * replayable exactly as it was rendered.
+ */
+import { type ChannelRequest } from "./contract.js";
+/**
+ * Where the payload material for an action comes from.
+ *
+ * Returns `undefined` when the caller holds no material for that key — which
+ * falls back to the payload store, and then, if that holds nothing either, is a
+ * refusal for a manual request (§10.4) and merely a missing field otherwise.
+ * Never throws: an adapter that cannot produce material says so by returning
+ * `undefined`.
+ *
+ * The bound `payload_hash` is passed as a second argument for sources that are
+ * addressed by content rather than by key; sources that key on the action alone
+ * ignore it.
+ */
+export type PayloadSource = (actionKey: string, payloadHash: string) => unknown;
+export interface TagOptions {
+    /** Where `APPROVAL.md` lives. Same semantics as `core/gate.ts`'s option. */
+    policy?: {
+        dir?: string;
+        file?: string;
+    };
+    /** Schema directory, passed to the verified read and the policy load. */
+    schemaDir?: string;
+    /**
+     * The payload bytes to render, checked against the recorded binding.
+     *
+     * An **override**: when it is absent, or returns `undefined` for a key, the
+     * payload store beside the log answers instead (APRV-28). An operator with a
+     * `--payload-dir` therefore still wins for the keys it covers, and gets the
+     * store for the rest.
+     */
+    payload?: PayloadSource;
+    /**
+     * Where the payload store lives. Defaults to `.approval/payloads/` beside the
+     * log, resolved by `core/payload-store.ts` from the log path the caller
+     * already passed. `null` disables the fallback entirely, which is what a
+     * caller that wants to prove the store is not answering asks for.
+     */
+    payloadStoreDir?: string | null;
+    /**
+     * Truncate the rendered payload text at this many characters. Unset means no
+     * truncation. A truncated rendering is legal for a unit request and is what
+     * `channels/batch.ts` refuses to fold into a batch (SPEC.md §10.3, B7).
+     */
+    maxPayloadChars?: number;
+}
+/** Why the tagger refused. Frozen per SPEC.md §11.1(6). */
+export declare const CHANNEL_TAG_REFUSAL_CODES: readonly [
+/** The log could not be opened. */
+"log-unreadable", 
+/** The log's final line is unterminated (a crashed write). */
+"log-torn-tail", 
+/** The chain does not verify; nothing may be rendered from it. */
+"log-corrupt", 
+/** No `approval.requested` record for this action key. */
+"not-requested", 
+/** There is a request, but it is decided or expired — nothing to approve. */
+"not-awaiting", 
+/** The request carries no usable `payload.class`; policy cannot be resolved. */
+"class-missing", 
+/** The request carries no `payload_hash`; there is no binding to display. */
+"payload-hash-missing", 
+/** No payload material was supplied for a manual request (§10.4). */
+"payload-unavailable", 
+/** The supplied material does not hash to the bound `payload_hash`. */
+"payload-mismatch", 
+/** The supplied material cannot be canonicalized (a cycle, a NaN, …). */
+"payload-unrenderable", 
+/** {@link createChannelRequest} refused the assembled request. */
+"request-invalid", 
+/**
+ * An attestation prompt's policy bytes are no longer the bytes on disk
+ * (APRV-109).
+ *
+ * Skipped rather than rendered: the hash, the diff and the advisory the
+ * proposal recorded all describe a file that has since changed, and a prompt
+ * showing them would ask a human to sign for bytes nobody is holding. The
+ * repair is to propose the amendment again, which re-derives all three from
+ * the file as it now stands.
+ */
+"proposal-stale"];
+export type ChannelTagRefusalCode = (typeof CHANNEL_TAG_REFUSAL_CODES)[number];
+export interface ChannelTagRefusal {
+    ok: false;
+    code: ChannelTagRefusalCode;
+    message: string;
+}
+export type BuildChannelRequestResult = {
+    ok: true;
+    request: ChannelRequest;
+} | ChannelTagRefusal;
+/**
+ * Build the render-ready request for one action key.
+ *
+ * Computed, and what derives each:
+ *
+ * | field | derivation | `source` |
+ * | --- | --- | --- |
+ * | `class`, `task`, `payload_hash`, `requested_ts`, `chain`, `state` | the verified log | `log` |
+ * | `autonomy`, `provenance` | `explain()` over the attested policy | `policy-match` |
+ * | `budgets` | `evaluateBudgetsWithTask()` at `now` | `budgets` |
+ * | `attestation` | `checkAttestation()` against the live policy file | `attestation` |
+ * | `fullPayload` | supplied material, hash-checked | `payload-binding` |
+ * | `command_breakdown`, `protected_path` | the classifier, re-run over the hash-checked material | `classifier` |
+ * | `ttl_remaining_ms`, `waiting` | arithmetic on `now` | `clock` |
+ *
+ * Claimed, and who authored each: `summary` and `est_cost_usd` carry the actor
+ * of the `approval.requested` record — the party that submitted the declaration
+ * — and `rationale` / `confidence` carry the registering actor.
+ *
+ * Refuses an unknown or undecidable key rather than rendering a partial one:
+ * `not-requested` (no such request), `not-awaiting` (already granted, rejected,
+ * revoked or expired), and the payload codes above. An unverifiable log refuses
+ * `log-corrupt` before anything is derived.
+ */
+export declare function buildChannelRequest(logPath: string, actionKey: string, options: TagOptions, now: string): BuildChannelRequestResult;
+/**
+ * `just now`, `4 min ago`, `2h 05m ago` — how long the question has waited.
+ *
+ * Exported since APRV-216 so the Telegram queue summary states a request's age
+ * in the same words the request's own prompt does. One phrasing and one
+ * rounding: a summary calling a question `2h 05m` old beside a prompt that
+ * calls it something else leaves a reader deciding which of the two the
+ * runtime meant.
+ */
+export declare function ageText(ms: number): string;
+/** One key the queue could not render, and why. */
+export interface SkippedRequest {
+    action_key: string;
+    code: ChannelTagRefusalCode;
+    message: string;
+}
+export type PendingQueueResult = {
+    ok: true;
+    /** Every live request awaiting a human decision, in log order. */
+    requests: ChannelRequest[];
+    /**
+     * Keys that are live but could not be rendered — most often a manual
+     * request whose payload material the caller does not hold. Surfaced
+     * rather than silently dropped: a request missing from a queue is a
+     * request nobody will approve, and an operator must be able to see why.
+     */
+    skipped: SkippedRequest[];
+} | ChannelTagRefusal;
+/**
+ * Build the pending queue: every action key with a live `approval.requested`.
+ *
+ * Order is log order (oldest request first), which is the order SPEC.md §9's
+ * queue projection asks for. One verified read serves the whole queue, and one
+ * policy load serves every entry, so an entry cannot disagree with its
+ * neighbour about what the policy says.
+ */
+export declare function buildPendingQueue(logPath: string, options: TagOptions, now: string): PendingQueueResult;