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