approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,370 @@
+/**
+ * WYSIWYS: the canonical rendering of a payload (APRV-119), and the structural
+ * views it is built from (APRV-100, APRV-124, APRV-126, APRV-144).
+ *
+ * ## What you see is what you sign
+ *
+ * The prompt a human approves is a deterministic function of the payload bytes
+ * and the action class, and of nothing else. {@link canonicalRender} is that
+ * function. Two channels, two runtimes, or two versions of this one cannot show
+ * two humans two different readings of the same payload without the difference
+ * being detectable: the rendering carries its own `display_hash`, the gate
+ * records that hash on `approval.requested`, and a rendering that disagrees is a
+ * rendering whose hash disagrees.
+ *
+ * The threat this closes is signoff social engineering. An approval surface that
+ * renders benign text while the hashed payload is malicious leaves the human
+ * signing blind. `payload_hash` binds the bytes; `display_hash` binds the
+ * reading of them.
+ *
+ * Four properties, and they are the whole module:
+ *
+ * 1. **Pure.** No clock, no locale, no environment, no randomness, no IO. The
+ *    only inputs are the payload value and the class string, and
+ *    `tests/wysiwys.test.ts` reads this file's own source and fails on a
+ *    reference to any of them.
+ * 2. **Closed field set per kind.** A payload is recognised as one of four kinds
+ *    (`command`, `file-change`, `email`, `opaque`) by its STRUCTURE, and each
+ *    kind renders a fixed list of fields. A shape carrying one key its kind does
+ *    not render is not that kind: it falls through to `opaque`, where the
+ *    canonical JSON is shown whole. Nothing is hidden by being unrecognised.
+ * 3. **Absent renders explicitly.** A field the payload does not carry is
+ *    printed as {@link ABSENT}, never omitted. An omitted line and a line whose
+ *    value happens to be empty are different facts, and a reader who cannot tell
+ *    them apart is reading a rendering that lost information.
+ * 4. **Claimed material stays outside.** Everything inside the canonical block
+ *    is derived from the bound bytes. Summaries, cost estimates, rationale,
+ *    confidence, and model-written glosses are rendered OUTSIDE it, under the
+ *    channel's own claimed heading (SPEC.md §9).
+ *
+ * ## Why this lives in `src/core/`, not `src/channels/`
+ *
+ * It is deterministic core in the sense CLAUDE.md means: pure, exhaustively
+ * tested, and consulted by the gate. `core/gate.ts` computes `display_hash` at
+ * the write boundary from the same function every channel renders with, so the
+ * log states what rendering the approver was shown. A renderer under
+ * `src/channels/` would have to be imported BY core to do that, inverting the
+ * direction the codebase is built on. `channels/payload-view.ts` is the
+ * channel-side facade over this module and holds the one function that needs a
+ * channel type.
+ *
+ * ## The reading aids this absorbed (APRV-100, APRV-124, APRV-126)
+ *
+ * SPEC.md §10.4 requires a channel to present, for a `manual` action, "the full
+ * payload or a faithful rendering of it". Until now every channel used the one
+ * rendering `channels/tagging.ts` builds: pretty-printed JSON. That is faithful
+ * and it is exact, and for an email it is close to unreadable — the observed
+ * failure (2026-08-18, examples/email-demo.md) is a body arriving on a phone as
+ * a single line carrying literal `\n` sequences, which is precisely the text a
+ * human is being asked to take responsibility for.
+ *
+ * So this module adds a second rendering *on top of* the first, never instead
+ * of it:
+ *
+ * - A payload whose **structure** matches the email adapter's payload shape
+ *   ({@link ../adapters/email.js}) is rendered field by field, with the body as
+ *   the human will read it: real line breaks, no JSON escapes.
+ * - A payload whose structure is a **shell command** (APRV-126: the shape
+ *   `cli/hook.ts` builds for a `Bash` tool call) is rendered as the command a
+ *   shell would receive, over as many lines as it really has, with `cwd` on its
+ *   own line beneath it. Same reason again: `"command": "gh pr create --body
+ *   'a\nb'"` on a phone is one paragraph of escaped JSON, and the observed
+ *   failure (2026-08-20) is a human being asked to take responsibility for it.
+ * - A payload whose structure is a **file change** (APRV-124: the shape
+ *   `cli/hook.ts` builds for an `Edit` or a `Write` tool call) is rendered as a
+ *   diff, so the approver reads the change rather than the fact that a file was
+ *   touched. Same reason as the email case: `"before": "a\nb"` on a phone is
+ *   bytes nobody can check.
+ * - Every other shape falls to `opaque`, whose view IS the canonical JSON: the
+ *   bytes whole, pretty-printed, exactly the rendering every payload had before
+ *   the structural views existed.
+ *
+ * Three properties this file is careful about:
+ *
+ * 1. **Detection is structural.** Nothing here reads a self-declared "kind" or
+ *    "type" field, because that field would be authored by the party under
+ *    oversight, and a channel that lets an agent choose its own presentation
+ *    has handed the agent the display. A payload is email-shaped when its keys
+ *    and its value types say so, and for no other reason.
+ * 2. **Nothing is hidden.** The shape is accepted only when *every* key is one
+ *    this module renders, so the field-by-field view never omits a byte of the
+ *    payload — a `bcc` or a `content_type` that the reader could not see would
+ *    be the same failure as a truncated payload, wearing a friendlier face.
+ * 3. **This is claimed content.** The payload is authored by the requesting
+ *    agent. The block says so in its first line, and the computed binding (the
+ *    `sha256` label each channel already prints around this region) stays where
+ *    it is. Making the payload *legible* must not make it look *verified*.
+ *    A `tool` or a `rule` value inside a file-change payload is rendered for
+ *    the reader and is never what selects the rendering: the shape is, exactly
+ *    as for an email.
+ * 4. **Two different byte strings never look the same.** A reading aid that
+ *    interprets escape sequences has to answer the question it creates: if a
+ *    real line break becomes a line break, what does the two-byte sequence
+ *    backslash-`n` become? Rendering both as a line break would let an agent
+ *    write one payload and have the approver read another. So the rendering is
+ *    INJECTIVE by construction ({@link markEscapes}), and the property is
+ *    tested by generating pairs of distinct byte strings.
+ * 5. **The view is the whole reading (APRV-162, `approval.md/wysiwys/2`).** A
+ *    structured kind's view is the canonical rendering entire; no canonical-JSON
+ *    appendix follows it. The completeness argument is property 2 above: kind
+ *    detection is a closed field set, one unrecognised key sends the payload to
+ *    `opaque` whose view is the whole JSON, so a structural view that renders at
+ *    all renders every byte. The views therefore do not fold. A fold was
+ *    survivable only while the appendix restated the hidden lines underneath it;
+ *    with the appendix gone it would hide bytes from the only reading a human
+ *    gets, which is the failure this module exists to remove.
+ *
+ * The output is plain text with real newlines. Escaping belongs to the channel:
+ * `telegram.ts` and `web.ts` each pass this through their own `escapeHtml` and
+ * their own `<pre>`, so the injection surface is exactly what it was before.
+ */
+import { type ProtectedPathEntry } from "./command-class.js";
+/**
+ * How a field the payload does not carry is rendered.
+ *
+ * Never an omission. A closed field set that silently drops its absent members
+ * is not a closed field set: the reader cannot tell "no `cc`" from "a `cc` this
+ * renderer does not know how to show", and those are the two cases the whole
+ * design exists to keep apart.
+ */
+export declare const ABSENT = "(absent)";
+/** The heading and delimiters. Exported because the tests pin them. */
+export declare const EMAIL_VIEW_HEADING = "email \u2014 rendered field by field; every value below is CLAIMED, authored by the requesting party";
+export declare const BODY_BEGIN = "--- body begins ---";
+export declare const BODY_END = "--- body ends ---";
+export declare const CANONICAL_JSON_HEADING = "--- the same bytes, canonical JSON ---";
+/** One labelled line of the field-by-field view. */
+export interface EmailViewField {
+    label: string;
+    /** The value as text. For `body`, this may contain newlines. */
+    text: string;
+}
+/**
+ * Recognise an email-shaped payload, structurally.
+ *
+ * Returns the fields in display order, or `null` when the value is any other
+ * shape — including an email-ish object carrying one key this module does not
+ * know how to show, which falls back to JSON rather than hiding it.
+ */
+export declare function emailPayloadFields(value: unknown): EmailViewField[] | null;
+/** The heading and delimiters of the diff view. Exported because tests pin them. */
+export declare const EDIT_VIEW_HEADING = "file change \u2014 the change itself, not the touch; every value below is CLAIMED, authored by the requesting party";
+export declare const DIFF_BEGIN = "--- change begins ---";
+export declare const DIFF_END = "--- change ends ---";
+/** The qualifier a proposal-tier touch renders (APRV-124). */
+export declare const PROPOSAL_QUALIFIER = "this edit targets a file inside an AGENT WORKTREE: it is a branch PROPOSAL, not the live file. Merging it to the live checkout is a separate gated action.";
+export declare const LIVE_QUALIFIER = "this edit targets the LIVE checkout, not a branch proposal.";
+/** The qualifier a protected-name touch outside the gated checkout renders (APRV-161). */
+export declare const ELSEWHERE_QUALIFIER = "this edit targets a file NAMED like a policy file, OUTSIDE the gated checkout: it is not the live policy. It gates because the name is protected wherever it sits.";
+/** A file change, recognised structurally. */
+export interface ChangeView {
+    /** Labelled single-line fields, in display order. */
+    labels: EmailViewField[];
+    /** The removed side, or `null` for a whole-file write. */
+    before: string | null;
+    /** The added side: the new text, or the whole new content. */
+    after: string;
+}
+/**
+ * Recognise a file-change payload, structurally.
+ *
+ * Accepted when the payload names a `file` and carries either both sides of an
+ * edit (`before` and `after`) or a whole-file `content`, and every other key is
+ * one this module renders. Anything else — including a payload that carries
+ * only `before`, where the reader would be shown half a change — is `null` and
+ * falls back to JSON.
+ */
+export declare function changePayloadView(value: unknown): ChangeView | null;
+/** The heading and delimiters of the command view. Exported because tests pin them. */
+export declare const COMMAND_VIEW_HEADING = "command \u2014 rendered; the hash binds the RAW BYTES, not this view. Every value below is CLAIMED, authored by the requesting party";
+export declare const COMMAND_BEGIN = "--- command begins ---";
+export declare const COMMAND_END = "--- command ends ---";
+/**
+ * The delimiters around a marked escape sequence.
+ *
+ * Guillemets rather than brackets: `[` and `]` are ordinary shell and regex
+ * characters, so a marker built from them would be indistinguishable from the
+ * command's own text at a glance, which is the failure this marker exists to
+ * prevent.
+ */
+export declare const ESCAPE_OPEN = "\u00AB";
+export declare const ESCAPE_CLOSE = "\u00BB";
+/** The legend printed above every command block, so the marker needs no lore. */
+export declare const ESCAPE_LEGEND = "escapes: \u00AB\\n\u00BB is the two LITERAL bytes backslash-n; a real line break is a line break";
+/**
+ * One line of a command, with literal escape sequences marked.
+ *
+ * INJECTIVE, and the proof is short enough to keep here. The rendering is a
+ * left-to-right tokenizer over two tokens: a backslash followed by a letter in
+ * {@link MARKED_ESCAPES} becomes `«\c»`, and every other character is itself.
+ * A `«\c»` in the OUTPUT can therefore only have come from that first token,
+ * because a backslash followed by such a letter in the input is never emitted
+ * bare — so reading the output back left to right recovers the input exactly,
+ * and a left inverse is all injectivity needs.
+ *
+ * Real newlines are handled by the caller, which splits on them before calling
+ * this: a line break in the output comes from a line break in the input, and
+ * from nothing else.
+ */
+export declare function markEscapes(line: string): string;
+/** A shell command, recognised structurally. */
+export interface CommandView {
+    /** The command, exactly as the payload carries it. */
+    command: string;
+    /** The working directory, or `null` when the payload names none. */
+    cwd: string | null;
+}
+/**
+ * Recognise a command payload, structurally.
+ *
+ * Accepted when the payload carries a string `command` and nothing this module
+ * cannot show. `cwd` is optional here even though `cli/hook.ts` always sets it:
+ * the question this answers is "will a human read this better as a command?",
+ * and a payload missing its directory reads better either way.
+ */
+export declare function commandPayloadView(value: unknown): CommandView | null;
+/**
+ * Where the exact bytes live, and how to get them back (APRV-126, APRV-162).
+ *
+ * Carried by every structural view, not the command view alone: with no
+ * canonical-JSON appendix underneath, this line is the reader's only route from
+ * a rendering back to the bytes it was derived from.
+ *
+ * The store is content-addressed by this very hash and re-verified on every
+ * read (`core/payload-store.ts`), so the line is an instruction, never a claim:
+ * following it produces the bytes or produces a refusal, and never something
+ * else wearing the same name.
+ */
+export declare function rawBytesLine(hash: string): string;
+/** What separates two segments of the breakdown. Exported: the tests pin it. */
+export declare const BREAKDOWN_SEPARATOR = " \u00B7 ";
+/** Characters one segment of the breakdown may take before it folds. */
+export declare const BREAKDOWN_SEGMENT_BUDGET = 40;
+/** Segments the breakdown shows before it says how many it did not. */
+export declare const BREAKDOWN_MAX_SEGMENTS = 8;
+/**
+ * What a compound command does, segment by segment (APRV-144).
+ *
+ * `git add … · git commit · git push origin main:records-… · gh pr create`.
+ *
+ * The observed complaint (Carter, 2026-08-25) is that the claimed summary of a
+ * shell action is `truncate(command, 160)`, which for a chained command is the
+ * first clause and a path prefix: the approver reads where the command starts
+ * and never what it ends by doing. This is the deterministic half of the
+ * answer. It is derived from {@link commandSegmentWords} — the classifier's own
+ * tokenizer, never a second one — so a channel showing it cannot describe a
+ * command differently from the module that chose its class.
+ *
+ * `null` for a string the tokenizer refuses (the same input the classifier
+ * answers `unparseable` for) and for one with no segment carrying a binary: an
+ * aid that cannot be derived is absent, never guessed.
+ */
+export declare function commandBreakdown(command: string): string | null;
+/** The path that made an action `policy.edit`, and the rule that matched it. */
+export interface ProtectedPathView {
+    path: string;
+    rule: string;
+}
+/**
+ * Which protected path selected this payload's class, when one did (APRV-143).
+ *
+ * A prompt that says `class: policy.edit` and stops there tells the approver
+ * that *some* rule fired and leaves them to find the file. Both gated shapes
+ * can say which:
+ *
+ * - a shell payload is re-classified here, by the same
+ *   {@link classifyCommand} the hook decided with, and the segment that took
+ *   `policy.edit` carries the word it matched (`ClassifiedSegment.path`);
+ * - a file-tool payload names its target in `file`, and
+ *   {@link isProtectedPath} is re-run over it rather than trusted: the answer
+ *   is recomputed from the bound bytes, so this stays a computed field. The
+ *   payload's own `rule` is used as the label only when it is one of the three
+ *   the hook writes, which is what keeps the worktree-proposal and
+ *   protected-name-elsewhere tiers legible (APRV-124, APRV-161).
+ *
+ * `extra` is `policy.protected_paths`, passed exactly as every enforcement path
+ * passes it; omitting it narrows the answer and never widens it.
+ */
+export declare function protectedPathView(value: unknown, extra?: readonly ProtectedPathEntry[]): ProtectedPathView | null;
+/**
+ * The renderer's identity, printed inside every canonical block.
+ *
+ * Inside the text, and therefore inside {@link CanonicalRendering.display_hash}:
+ * a version that rode alongside the hash rather than inside it would let two
+ * renderer versions produce the same digest for two different readings, which is
+ * the one thing the digest exists to make impossible. Any change to the bytes
+ * this module emits — a new field, a reworded heading, a line that used to be
+ * folded away — is a new version, and a reader comparing a stored
+ * `display_hash` against a re-render can see which renderer wrote it. A record
+ * written under an earlier version re-derives under the renderer its own hashed
+ * text names, never under this one.
+ *
+ * `/2` (APRV-162): the structural views render whole and carry no canonical-JSON
+ * appendix; `opaque` is unchanged, its view being that JSON.
+ */
+export declare const CANONICAL_RENDERER_VERSION = "approval.md/wysiwys/2";
+/**
+ * The `approval.requested` payload field carrying {@link
+ * CanonicalRendering.display_hash} (APRV-119).
+ *
+ * Written by the gate at the write boundary, exactly as `ts` and `policy_sha256`
+ * are, and for the same reason: the requesting party must not be able to name
+ * the rendering it claims a human was shown. {@link RequestInput} carries no
+ * field for it.
+ */
+export declare const DISPLAY_HASH_FIELD = "display_hash";
+/** The delimiters of the canonical block. Exported because the tests pin them. */
+export declare const CANONICAL_BEGIN = "--- canonical rendering begins ---";
+export declare const CANONICAL_END = "--- canonical rendering ends ---";
+/** The heading of the `opaque` kind: no structural view, the bytes whole. */
+export declare const OPAQUE_VIEW_HEADING = "payload \u2014 no structural view applies to this shape; every byte of it is in the canonical JSON below, and every value is CLAIMED, authored by the requesting party";
+/**
+ * The kinds a payload can be rendered as.
+ *
+ * Closed, and decided by structure alone. `opaque` is not a failure: it is the
+ * kind whose closed field set is "the whole canonical JSON", which is the
+ * rendering every payload had before the structural views existed.
+ */
+export declare const CANONICAL_KINDS: readonly ["command", "file-change", "email", "opaque"];
+export type CanonicalKind = (typeof CANONICAL_KINDS)[number];
+/** One canonical rendering: what the human reads, and the digest of it. */
+export interface CanonicalRendering {
+    /** {@link CANONICAL_RENDERER_VERSION}, for a caller that wants it separately. */
+    version: string;
+    /** Which structural view was applied. */
+    kind: CanonicalKind;
+    /** The text, with real newlines. Escaping belongs to the channel. */
+    text: string;
+    /** SHA-256 (lowercase hex) over `text` as UTF-8. */
+    display_hash: string;
+}
+/**
+ * Render a payload the way every channel MUST present it (APRV-119).
+ *
+ * A pure function of `(payload, actionClass)`. Same arguments, byte-identical
+ * `text` and `display_hash`, in this process or another, today or next year
+ * under the same {@link CANONICAL_RENDERER_VERSION}.
+ *
+ * The block states its own renderer, class, kind and payload digest before it
+ * shows anything, so a reader who is handed the text alone can tell what
+ * produced it and what it binds to. Then the view for the kind, which is the
+ * whole reading: it renders every byte of the payload or the payload is
+ * `opaque` and the view is its JSON (APRV-162).
+ *
+ * Throws `JcsError` for a payload RFC 8785 cannot serialize (a cycle, a NaN).
+ * That is {@link payloadHash}'s contract and it is the right one here too: a
+ * payload that cannot be bound to must not acquire a plausible-looking rendering
+ * of itself. Every caller in this repository renders material that has already
+ * been hash-checked against the log's binding, so the throw is unreachable on
+ * the paths a human ever sees.
+ */
+export declare function canonicalRender(payload: unknown, actionClass: string): CanonicalRendering;
+/**
+ * The `display_hash` of a payload, or `null` when there is none to compute.
+ *
+ * The gate's entry point (`core/gate.ts`), where a payload that cannot be
+ * canonicalized must not abort a request that has already passed every check
+ * that matters. A missing `display_hash` costs a reader one cross-check; a
+ * throw here would cost them the request.
+ */
+export declare function displayHashOf(payload: unknown, actionClass: string): string | null;

package/dist/src/daemon/advance-child.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The daemon's advance, run in a child process (APRV-211).
+ *
+ * ## Why this file exists
+ *
+ * `approval up` runs the daemon loop and the Telegram listener in one process,
+ * and `cli/log-advance.ts` is `spawnSync` from end to end. So an advance run on
+ * the daemon's own stack blocks the loop for as long as `git fetch`, the
+ * scratch-index commit, `git push` and `gh pr create` take, and every callback
+ * that arrived meanwhile was answered past Telegram's window: the
+ * `answerCallbackQuery: HTTP 400`s Carter saw on 2026-09-02. Nothing that runs
+ * on that loop can fix it, because synchronous work does not yield. Another
+ * process can.
+ *
+ * ## What it is allowed to do, and what it is not
+ *
+ * It runs the verb. That is the entire remit.
+ *
+ * It does NOT touch the gate, and it could not if it tried: `core/child-env.ts`
+ * strips `APPROVAL_*` from a child's environment (APRV-205), which is where the
+ * `supervised-live` draw's secret lives, so a child that asked the gate would
+ * fail closed on every tick. The register/request/start half happens in the
+ * daemon before this is spawned and the `execution.completed`/`failed` is
+ * appended by the daemon after it exits. This process appends nothing, decides
+ * nothing, and holds no authority: if it were replaced wholesale by something
+ * hostile, the worst it could do is refuse to advance the log or report a
+ * failure that did not happen — it cannot authorise anything, because by the
+ * time it runs the authorisation is already in the log and already spent.
+ *
+ * ## The protocol
+ *
+ * One argument: the JSON `LogAdvanceOptions` subset the daemon chose. One line
+ * on stdout: the `LogAdvanceResult` verbatim, `{ok:true,report}` or
+ * `{ok:false,code,message}`. The parent VALIDATES that line rather than
+ * trusting it, and treats anything else as a failed advance with a
+ * machine-readable reason. Nothing is written to stdout but that line, which is
+ * why the verb is given no progress reporter.
+ */
+export {};