approval-md 0.0.1 → 0.2.0

package/dist/src/channels/cli.js

@@ -0,0 +1,468 @@
+/**
+ * The CLI channel (APRV-23) — the zero-config channel, written against the
+ * contract in `channels/contract.ts` and nothing else.
+ *
+ * It is the first implementation of {@link TestableChannel}, and it exists as
+ * much to prove the contract is implementable as to be useful: a terminal has no
+ * stylesheet, no buttons and no webhook, so everything the contract asks a
+ * channel to do has to be done in plain text. If SPEC.md §9's display rule
+ * cannot survive a channel this poor, it cannot survive a rich one either.
+ *
+ * ## The rendering convention (SPEC.md §9)
+ *
+ * Every line carries a marker in the first column, and the marker is the first
+ * thing a reader sees:
+ *
+ * ```
+ * [computed] class            communicate.email.external            (log)
+ * [claimed]  summary          chase invoice 41                      (agent:drafter)
+ * ```
+ *
+ * `[computed]` means the runtime derived the value — from the verified log, the
+ * attested policy, the budget evaluator, the payload bytes, or arithmetic on the
+ * display instant — and the parenthetical names *which* derivation. `[claimed]`
+ * means the party under oversight wrote it, and the parenthetical names that
+ * party. The marker is not decoration: it is the difference between "the runtime
+ * says this is a manual action" and "an agent says this costs two cents", and a
+ * channel that gave them the same weight would be a conformance failure rather
+ * than a styling preference.
+ *
+ * Claimed lines are additionally indented under a `claimed by …` heading, so the
+ * split survives a terminal that eats no colour and a reader who skims. There is
+ * no bold, no colour and no unicode box drawing anywhere in this file — a marker
+ * a `less`, a pipe, a CI log or a screen reader can lose is a marker that was
+ * never there.
+ *
+ * ## The full payload (SPEC.md §10.4)
+ *
+ * For a manual action the payload is printed verbatim inside an explicitly
+ * delimited block:
+ *
+ * ```
+ * --- BEGIN FULL PAYLOAD (bound sha256 <hash>) ---
+ * { … }
+ * --- END FULL PAYLOAD ---
+ * ```
+ *
+ * The block is never mixed with the claimed summary, and the summary is never
+ * printed inside it. `channels/tagging.ts` has already checked those bytes
+ * against the recorded binding, so what is inside the delimiters is what the
+ * execution token will spend.
+ *
+ * ## What this file does NOT do
+ *
+ * It does not read the log, write the log, decide anything, or hold a token.
+ * The decision handler is registered by the runtime (`cli/channel.ts`) and its
+ * only job is to call {@link recordChannelDecision}. The prompt loop collects a
+ * gesture and hands it over; whether that gesture becomes an event is the gate's
+ * answer, not this file's.
+ *
+ * It also does not dispatch (APRV-55). This channel is **one-shot by design**:
+ * the runtime derives the queue once, renders it, collects decisions on the
+ * requests in front of the operator, and the process ends. There is no cycle in
+ * which a newly appended request could arrive, so there is nothing to push —
+ * the operator running the verb again is the refresh. Only the long-lived push
+ * channel (Telegram) needs a per-cycle send; the long-lived pull channel (web)
+ * re-derives per page view.
+ */
+import { createInterface } from "node:readline";
+import { CLI_PROMPT_LAYOUT, isPromptRow } from "../core/prompt-layout.js";
+import { GLOSS_UNVERIFIED_SUFFIX } from "./contract.js";
+import { payloadRegionText } from "./payload-view.js";
+/** The marker prefixes. Exported because the help text and the tests pin them. */
+export const COMPUTED_MARKER = "[computed]";
+export const CLAIMED_MARKER = "[claimed]";
+/** The full-payload delimiters (SPEC.md §10.4). Pinned by tests. */
+export const PAYLOAD_BEGIN = "--- BEGIN FULL PAYLOAD";
+export const PAYLOAD_END = "--- END FULL PAYLOAD ---";
+/** One line of the legend, printed above every delivery. */
+export const RENDERING_LEGEND = [
+    `${COMPUTED_MARKER} derived by the runtime (verified log, attested policy, budget evaluator,`,
+    "           payload bytes, clock); the parenthetical names the derivation.",
+    `${CLAIMED_MARKER}  written by the party under oversight; the parenthetical names the author.`,
+    "           A claim may raise your scrutiny. It is never evidence.",
+].join("\n");
+// ---------------------------------------------------------------------------
+// Value formatting
+// ---------------------------------------------------------------------------
+function formatDuration(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0)
+        return `${hours}h ${minutes % 60}m left`;
+    if (minutes > 0)
+        return `${minutes}m ${seconds % 60}s left`;
+    return `${seconds}s left`;
+}
+function formatBudgets(verdicts) {
+    if (verdicts.length === 0)
+        return "none configured";
+    return verdicts
+        .map((verdict) => `${verdict.limit} ${verdict.pass ? "pass" : "FAIL"} (consumed ${verdict.consumed}, requested ${verdict.requested}, remaining ${verdict.remaining}, ${verdict.window})`)
+        .join("; ");
+}
+/**
+ * A field's value as one line of text.
+ *
+ * Deliberately total: an unknown shape is JSON-stringified rather than dropped,
+ * because a field the runtime tagged and the channel silently omitted is a field
+ * the approver did not see.
+ */
+function formatValue(field, value) {
+    if (value === null || value === undefined)
+        return "(none)";
+    // APRV-197. The one line in the rendering that NO party stands behind — not
+    // the runtime, not even the requesting agent — says so on the line itself,
+    // in the same words Telegram has used since APRV-144. The `(model:haiku)`
+    // attribution at the end of the line is true but small, and a reader skimming
+    // a terminal reads the sentence, not the parenthetical.
+    if (field === "gloss" && typeof value === "string") {
+        return `${value} ${GLOSS_UNVERIFIED_SUFFIX}`;
+    }
+    if (field === "ttl_remaining_ms" && typeof value === "number")
+        return formatDuration(value);
+    if (field === "budgets" && Array.isArray(value))
+        return formatBudgets(value);
+    if (field === "attestation" && typeof value === "object") {
+        const status = value.status;
+        const seq = value.seq;
+        return seq === undefined ? String(status) : `${String(status)} (policy.updated seq ${String(seq)})`;
+    }
+    if (field === "chain" && typeof value === "object") {
+        const chain = value;
+        return `seq ${String(chain.seq)} hash ${String(chain.hash)} (log head seq ${String(chain.head_seq)})`;
+    }
+    if (field === "est_cost_usd" && typeof value === "number")
+        return `$${value.toFixed(2)}`;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return JSON.stringify(value) ?? String(value);
+}
+/** The parenthetical: which derivation, or which author. */
+function attribution(field) {
+    return field.kind === "computed" ? field.source : field.author;
+}
+/**
+ * The order fields are presented in, and which of them render (APRV-218).
+ *
+ * The default is {@link CLI_PROMPT_LAYOUT}: computed identity and authority
+ * first, claimed persuasion last, every row on — a reader who stops halfway has
+ * read the runtime's answer and not the agent's pitch, and a terminal a human
+ * asked for by typing a verb is not the place to economise on lines the way a
+ * push notification is. `channels.cli.prompt` in APPROVAL.md replaces it.
+ *
+ * Two properties survive any layout. Fields absent from a request are skipped;
+ * and members the layout does not NAME are appended rather than dropped, so a
+ * widened {@link ChannelRequest} cannot silently lose one to a policy written
+ * before that field existed. `fullPayload` is one of those appended members: it
+ * is not a row, it has its own delimited region below, and no layout key
+ * reaches it.
+ */
+function orderedFields(request, layout) {
+    const members = Object.keys(request);
+    const ordered = layout.order.filter((name) => layout.visibility[name] !== "off" && members.includes(name));
+    for (const name of members) {
+        if (!ordered.includes(name) && !isPromptRow(name))
+            ordered.push(name);
+    }
+    return ordered;
+}
+// ---------------------------------------------------------------------------
+// Line reading
+// ---------------------------------------------------------------------------
+/**
+ * Sequential line reads over one `readline` interface.
+ *
+ * One interface per channel, not one per question: a fresh interface per prompt
+ * would race for buffered bytes on a piped stdin and lose lines, which on this
+ * path means losing a human's answer. `next()` resolves `null` at end of input,
+ * which every caller treats as "no gesture" — never as a default answer.
+ */
+class LineReader {
+    rl;
+    pending = [];
+    waiting = [];
+    closed = false;
+    constructor(input) {
+        this.rl = createInterface({ input, terminal: false });
+        this.rl.on("line", (line) => {
+            const waiter = this.waiting.shift();
+            if (waiter === undefined)
+                this.pending.push(line);
+            else
+                waiter(line);
+        });
+        this.rl.on("close", () => {
+            this.closed = true;
+            while (this.waiting.length > 0)
+                this.waiting.shift()?.(null);
+        });
+    }
+    next() {
+        const buffered = this.pending.shift();
+        if (buffered !== undefined)
+            return Promise.resolve(buffered);
+        if (this.closed)
+            return Promise.resolve(null);
+        return new Promise((resolve) => {
+            this.waiting.push(resolve);
+        });
+    }
+    close() {
+        this.rl.close();
+    }
+}
+export class CliChannel {
+    name;
+    output;
+    input;
+    handler = null;
+    rendered = [];
+    reader = null;
+    counter = 0;
+    /** The policy's row layout for this channel (APRV-218). Pure input to the rendering. */
+    layout;
+    constructor(options = {}) {
+        this.name = options.name ?? "cli";
+        this.output = options.output ?? process.stdout;
+        this.input = options.input ?? process.stdin;
+        this.layout = options.layout ?? CLI_PROMPT_LAYOUT;
+    }
+    /**
+     * Present a request, or a batch, and return the delivery id.
+     *
+     * Writes to the output sink and nowhere else: no log, no state, no decision.
+     * A batch is rendered member by member — each member carries its own full
+     * payload, and folding one behind another is exactly what `channels/batch.ts`
+     * refuses upstream.
+     */
+    notify(request) {
+        this.counter += 1;
+        const deliveryId = `cli-${this.counter}`;
+        const isBatch = "requests" in request;
+        const members = isBatch ? request.requests : [request];
+        this.output.write(`\n=== approval.md ${isBatch ? `batch ${deliveryId} (${members.length} request(s))` : `request ${deliveryId}`} ===\n${RENDERING_LEGEND}\n`);
+        this.rendered = members.map((member, index) => {
+            const entry = this.renderRequest(member, isBatch ? deliveryId : undefined);
+            this.output.write(textOf(member, entry, isBatch ? index + 1 : null, members.length));
+            return entry;
+        });
+        return deliveryId;
+    }
+    onDecision(handler) {
+        this.handler = handler;
+    }
+    health() {
+        return { ok: true };
+    }
+    lastRendered() {
+        return this.rendered;
+    }
+    /**
+     * Release the input interface. Safe to call when nothing was ever read.
+     *
+     * The source is paused as well as closed: a `readline` interface over
+     * `process.stdin` leaves the stream flowing, and a process that finished
+     * asking would sit there holding the event loop open.
+     */
+    close() {
+        this.reader?.close();
+        this.reader = null;
+        this.input.pause?.();
+    }
+    /**
+     * The prompt loop: `g` grants, `r` rejects, `s` skips.
+     *
+     * A reject demands a note and re-asks until it gets one — a refusal an agent
+     * cannot read is a refusal it will retry. A grant's note is optional; there is
+     * nothing to explain about "yes, do the thing I was shown".
+     *
+     * The gesture is reported to the handler registered by the runtime, and the
+     * handler's {@link DecisionOutcome} is returned unchanged, refusals included.
+     * Nothing here inspects it, and nothing here retries: a gate refusal is an
+     * answer, and re-asking a human who already answered is how double-grants get
+     * made.
+     */
+    async collectDecision(actionKey, deliveryId, options = {}) {
+        const handler = this.handler;
+        if (handler === null) {
+            throw new Error("no decision handler is registered on the cli channel; the runtime registers one before notify(), and a channel that recorded its own decision would be deciding rather than transporting (SPEC.md §10.3)");
+        }
+        for (;;) {
+            this.output.write(`\n${actionKey}\n  g) grant   r) reject   s) skip  > `);
+            const answer = (await this.readLine())?.trim().toLowerCase();
+            if (answer === undefined) {
+                this.output.write("\n(input ended; no decision was recorded)\n");
+                return { kind: "aborted" };
+            }
+            if (answer === "s" || answer === "skip" || answer === "") {
+                this.output.write("skipped; the request stays pending\n");
+                return { kind: "skipped" };
+            }
+            if (answer === "g" || answer === "grant") {
+                const note = await this.askNote("note (optional, press enter to skip) > ", false);
+                if (note === null)
+                    return { kind: "aborted" };
+                return this.report(handler, actionKey, "grant", note, deliveryId, options);
+            }
+            if (answer === "r" || answer === "reject") {
+                const note = await this.askNote("note (REQUIRED — say why) > ", true);
+                if (note === null)
+                    return { kind: "aborted" };
+                return this.report(handler, actionKey, "reject", note, deliveryId, options);
+            }
+            this.output.write(`unrecognized answer ${JSON.stringify(answer)}; expected g, r or s\n`);
+        }
+    }
+    /**
+     * The checkpoint prompt, in a terminal (APRV-257).
+     *
+     * The same question the Telegram tap asks, in the channel that has no
+     * buttons: the lines the runtime composed, then `s` to sign and `n` to
+     * decline. The text is the runtime's and identical on both surfaces, because
+     * the thing being consented to is identical and two phrasings of one gesture
+     * would be two claims about it.
+     *
+     * It collects a gesture and nothing else. What signing MEANS — the key, the
+     * head, the append — is the runtime's, exactly as a decision is: this channel
+     * can no more sign a checkpoint than it can grant a request.
+     *
+     * End of input is `null`, never a default. A closed pipe has not declined,
+     * and it certainly has not signed.
+     */
+    async collectCheckpoint(lines) {
+        for (const line of lines)
+            this.output.write(`${line}\n`);
+        for (;;) {
+            this.output.write(`  s) sign   n) not now  > `);
+            const answer = (await this.readLine())?.trim().toLowerCase();
+            if (answer === undefined) {
+                this.output.write("\n(input ended; nothing was signed)\n");
+                return null;
+            }
+            if (answer === "n" || answer === "not now" || answer === "") {
+                this.output.write("not signed; nothing was appended and nothing is refused\n");
+                return false;
+            }
+            if (answer === "s" || answer === "sign")
+                return true;
+            this.output.write(`unrecognized answer ${JSON.stringify(answer)}; expected s or n\n`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // internals
+    // -------------------------------------------------------------------------
+    report(handler, actionKey, verb, note, deliveryId, options) {
+        const decision = {
+            action_key: actionKey,
+            decision: verb,
+            deliveryId,
+            ...(note === undefined ? {} : { note }),
+            ...(options.batchDeliveryId === undefined
+                ? {}
+                : { batchDeliveryId: options.batchDeliveryId }),
+        };
+        return { kind: "decided", decision, outcome: handler(decision) };
+    }
+    /**
+     * Ask for a note. Returns `undefined` for "none given" and `null` when input
+     * ended — the two are different, and conflating them would let a closed pipe
+     * look like a human who chose to say nothing.
+     */
+    async askNote(prompt, required) {
+        for (;;) {
+            this.output.write(prompt);
+            const line = await this.readLine();
+            if (line === null) {
+                this.output.write("\n(input ended; no decision was recorded)\n");
+                return null;
+            }
+            const note = line.trim();
+            if (note.length > 0)
+                return note;
+            if (!required)
+                return undefined;
+            this.output.write("a note is required to reject: an unexplained refusal cannot be acted on\n");
+        }
+    }
+    async readLine() {
+        this.reader ??= new LineReader(this.input);
+        return await this.reader.next();
+    }
+    /**
+     * Build one request's rendering split. This is the same function whose output
+     * is written to the terminal — {@link lastRendered} is not a parallel
+     * description of the rendering, it *is* the rendering.
+     */
+    renderRequest(request, batchDeliveryId) {
+        const members = request;
+        const fields = [];
+        for (const name of orderedFields(request, this.layout)) {
+            const field = members[name];
+            if (field === undefined)
+                continue;
+            fields.push({ field: name, kind: field.kind, text: formatValue(name, field.value) });
+        }
+        const rendering = request.fullPayload.value;
+        const fullPayloadText = rendering === null
+            ? null
+            : [
+                `${PAYLOAD_BEGIN} (bound sha256 ${rendering.hash}) ---`,
+                // APRV-119. The canonical rendering, the same bytes the other two
+                // channels put in front of a human. Until now this channel printed
+                // the pretty JSON alone, which meant a terminal approver and a
+                // Telegram approver read two different texts for one payload — the
+                // exact divergence WYSIWYS exists to rule out.
+                payloadRegionText(rendering, request.class.value),
+                PAYLOAD_END,
+                ...(rendering.truncated
+                    ? ["(TRUNCATED — this is not the whole payload; do not grant on it)"]
+                    : []),
+            ].join("\n");
+        return {
+            action_key: request.action_key.value,
+            fields,
+            fullPayloadText,
+            ...(batchDeliveryId === undefined ? {} : { batchDeliveryId }),
+        };
+    }
+}
+/**
+ * The terminal text for one rendering.
+ *
+ * Computed lines first, then the claimed block under its own heading, then the
+ * delimited payload. `request` is read only for each field's attribution — the
+ * derivation that produced a computed value, the author of a claimed one.
+ */
+function textOf(request, entry, position, total) {
+    const members = request;
+    const suffix = (name) => {
+        const field = members[name];
+        return field === undefined ? "" : ` (${attribution(field)})`;
+    };
+    const lines = [
+        position === null
+            ? `\n--- ${entry.action_key} ---`
+            : `\n--- ${entry.action_key} (${position} of ${total}) ---`,
+    ];
+    for (const field of entry.fields) {
+        if (field.kind !== "computed")
+            continue;
+        lines.push(`${COMPUTED_MARKER} ${field.field.padEnd(16)} ${field.text}${suffix(field.field)}`);
+    }
+    const claimed = entry.fields.filter((field) => field.kind === "claimed");
+    if (claimed.length > 0) {
+        lines.push("claimed by the party under oversight — NOT verified by the runtime:");
+        for (const field of claimed) {
+            lines.push(`  ${CLAIMED_MARKER} ${field.field.padEnd(14)} ${field.text}${suffix(field.field)}`);
+        }
+    }
+    if (entry.fullPayloadText !== null) {
+        lines.push("");
+        lines.push(entry.fullPayloadText);
+    }
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/channels/cli.js.map

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

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

@@ -0,0 +1,92 @@
+/**
+ * The shared channel conformance suite (SPEC.md §9, §10.3, §10.4).
+ *
+ * SPEC.md §9 states the display rule and then names its consequence in the same
+ * breath: rendering claimed fields with the visual authority of computed fields
+ * "is a conformance failure for a channel". This module is what that sentence
+ * points at. It ships with the contract rather than with any one channel, so
+ * `cli`, `web` and `telegram` (APRV-23/25/26) are held to one standard written
+ * once, and a fourth channel written by someone else can import it and find out
+ * in a single test whether it is a channel or merely a message sender.
+ *
+ * ## What it checks
+ *
+ * 1. **Tagging.** Every member of the request handed to the channel is a
+ *    {@link TaggedField} ({@link assertTagged}), and every field the channel
+ *    reports rendering carries the *same* kind the request gave it. A channel
+ *    that presents a claimed summary as computed fails here.
+ * 2. **The full payload** (§10.4). A manual request's rendering contains the
+ *    payload text verbatim, in a region distinct from the claimed summary.
+ * 3. **Decision round-trip.** A gesture driven through the harness lands
+ *    exactly one correctly-shaped event in a real log, through the real gate.
+ * 4. **Batch semantics** (§10.3, B7). A batch notify plus two decisions lands
+ *    two events, each carrying the batch delivery id; and the forbidden mix is
+ *    refused at {@link assembleBatch} before anything is delivered.
+ * 5. **Terminal requests are neither pending nor armed** (APRV-113). A request
+ *    the log has settled is absent from the derivation every channel builds its
+ *    queue from, and a second gesture on it is refused and appends nothing.
+ *
+ * ## How it is run
+ *
+ * ```ts
+ * test("my channel conforms", async (t) => {
+ *   await runChannelConformance(t, () => new MyChannel(), harness);
+ * });
+ * ```
+ *
+ * `t` is a `node:test` context and is used only for `diagnostic()` labels: the
+ * checks run inline and **throw** on the first failure rather than being split
+ * into subtests. That is deliberate. A subtest's promise resolves even when the
+ * subtest fails, so a suite built from `t.test()` could not itself be tested —
+ * and a conformance suite nobody has watched fail is a suite that might pass
+ * anything. Throwing means `tests/channels-contract.test.ts` can assert the
+ * suite goes RED against deliberately broken channels.
+ *
+ * The suite writes to whatever log the harness gives it, through the real gate.
+ * It never hand-writes a log line.
+ */
+import { type DecideOptions } from "../core/gate.js";
+import { type Channel, type ChannelActorOptions, type ChannelDecision, type ChannelRequest, type DecisionOutcome } from "./contract.js";
+/** Anything with a `diagnostic` method — `node:test`'s `TestContext` qualifies. */
+export interface ConformanceContext {
+    diagnostic?(message: string): void;
+}
+/**
+ * One scenario the harness prepares: a real log with `count` live manual
+ * requests, and the identity that will decide them.
+ */
+export interface ConformanceCase {
+    /** Path to a real `events.jsonl`, built through the gate. */
+    logPath: string;
+    /** The pending requests, as `channels/tagging.ts` built them. */
+    requests: ChannelRequest[];
+    /** The approver. Must be `human:…`; the gate refuses anything else. */
+    actor: ChannelActorOptions;
+    /** Gate options for recording (policy location, injected clock). */
+    gateOptions?: DecideOptions;
+    /** Called when the suite is done with this case. */
+    cleanup?(): void;
+}
+/**
+ * What a channel's test file must provide.
+ *
+ * `setup(count)` returns a *fresh* case each call — the suite decides requests,
+ * and a decided request cannot be decided again. `setup(2)` MUST return two
+ * requests with **distinct** payload hashes; the batch checks assert that and
+ * would otherwise be vacuous.
+ *
+ * `decide` is the harness's simulation of the human gesture: press the button,
+ * answer the prompt, POST the webhook — whatever makes the channel invoke the
+ * handler it was given. It is optional; without it the suite calls the
+ * registered handler directly, which still exercises the runtime path but not
+ * the channel's own callback wiring, so a real channel should provide it.
+ */
+export interface ConformanceHarness {
+    setup(count: number): ConformanceCase | Promise<ConformanceCase>;
+    decide?(channel: Channel, decision: ChannelDecision): DecisionOutcome | Promise<DecisionOutcome>;
+}
+/**
+ * Run the suite. Resolves when every check passes; throws (an `AssertionError`)
+ * on the first failure.
+ */
+export declare function runChannelConformance(t: ConformanceContext, makeChannel: () => Channel, harness: ConformanceHarness): Promise<void>;