approval-md 0.0.1 → 0.2.0

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;