approval-md 0.1.0 → 0.2.0

package/dist/src/adapters/zzz.js

@@ -0,0 +1,299 @@
+/**
+ * Credential-custody transport for zzz.bot messages (APRV-320).
+ *
+ * The adapter sends only the JSON value a grant binds. Destination selection
+ * is a strict tagged union over two fixed service origins; neither the CLI nor
+ * the payload can supply an arbitrary URL. The Bearer credential comes only
+ * from the scoped provider opened by the shared adapter contract.
+ */
+import { createHash } from "node:crypto";
+import { canonicalize } from "../core/jcs.js";
+import { payloadHash } from "../core/payload.js";
+import { CREDENTIAL_REFUSAL_CODES, PROVIDER_REF_DETAIL_KEY, } from "./contract.js";
+export const ZZZ_CLASS = "communicate.zzz.external";
+export const ZZZ_PRODUCTION_API_BASE = "https://zzz.bot";
+export const ZZZ_PREVIEW_API_BASE = "https://zzz-preview.soycarts.workers.dev";
+export const ZZZ_DEFAULT_TIMEOUT_MS = 15_000;
+export const ZZZ_TOKEN_NAME = "zzz.agent_token";
+const TOKEN = /^[A-Za-z0-9_-]{32,256}$/u;
+const PROVIDER_ID = /^(?:thr|pst)_[a-f0-9]{32}$/u;
+const MAX_MESSAGE_BYTES = 65_536;
+const MAX_RESPONSE_BYTES = 16_384;
+export const ZZZ_FAILURE_CODES = [
+    "zzz-payload-invalid",
+    "zzz-config-invalid",
+    "zzz-invalid-request",
+    "zzz-unauthorized",
+    "zzz-forbidden",
+    "zzz-not-found",
+    "zzz-idempotency-conflict",
+    "zzz-payload-too-large",
+    "zzz-rejected",
+    "zzz-rate-limited",
+    "zzz-unreachable",
+    "zzz-cancelled",
+    ...CREDENTIAL_REFUSAL_CODES,
+];
+export const ZZZ_CREDENTIAL_SPECS = [
+    {
+        name: ZZZ_TOKEN_NAME,
+        kind: "secret",
+        label: "ZZZ agent token",
+        describe: "an invited zzz.bot principal credential with write scope",
+        required: true,
+        validate(value) {
+            return TOKEN.test(value)
+                ? { ok: true }
+                : {
+                    ok: false,
+                    message: "the ZZZ agent token must be 32 to 256 ASCII letters, digits, underscores, or hyphens",
+                };
+        },
+    },
+];
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function exactKeys(value, allowed) {
+    const extra = Object.keys(value).find((key) => !allowed.includes(key));
+    return extra === undefined ? null : extra;
+}
+function boundedString(value, min, max) {
+    return typeof value === "string" && value.length >= min && value.length <= max;
+}
+function validReferences(value) {
+    if (value === undefined)
+        return true;
+    if (!Array.isArray(value) || value.length > 20)
+        return false;
+    return value.every((candidate) => {
+        const ref = object(candidate);
+        if (ref === null || exactKeys(ref, ["kind", "target", "label", "relationship"]) !== null)
+            return false;
+        if (!boundedString(ref["target"], 1, 2048) || !boundedString(ref["label"], 1, 120))
+            return false;
+        if (ref["kind"] !== "external" && ref["kind"] !== "post")
+            return false;
+        if (!["source", "context", "supersedes"].includes(String(ref["relationship"])))
+            return false;
+        if (ref["kind"] === "external") {
+            try {
+                const url = new URL(ref["target"]);
+                if (url.protocol !== "http:" && url.protocol !== "https:")
+                    return false;
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+export function validateZzzPayload(value) {
+    const input = object(value);
+    if (input === null)
+        return { ok: false, message: "the payload must be one JSON object" };
+    if (input["environment"] !== "production" && input["environment"] !== "preview") {
+        return { ok: false, message: "environment must be production or preview" };
+    }
+    if (input["operation"] !== "create_thread" && input["operation"] !== "create_reply") {
+        return { ok: false, message: "operation must be create_thread or create_reply" };
+    }
+    const common = ["environment", "operation", "body", "metadata", "tags", "references"];
+    const allowed = input["operation"] === "create_thread"
+        ? [...common, "room_id", "title"]
+        : [...common, "thread_id"];
+    const extra = exactKeys(input, allowed);
+    if (extra !== null)
+        return { ok: false, message: `unknown payload field ${JSON.stringify(extra)}` };
+    if (!boundedString(input["body"], 1, 65_536))
+        return { ok: false, message: "body must contain 1 to 65536 characters" };
+    if (input["tags"] !== undefined &&
+        (!Array.isArray(input["tags"]) || input["tags"].length > 10 ||
+            !input["tags"].every((tag) => boundedString(tag, 1, 40)))) {
+        return { ok: false, message: "tags must contain at most 10 strings of 1 to 40 characters" };
+    }
+    if (!validReferences(input["references"]))
+        return { ok: false, message: "references do not match the ZZZ API contract" };
+    let path;
+    if (input["operation"] === "create_thread") {
+        if (!boundedString(input["room_id"], 1, 256) || !boundedString(input["title"], 1, 200)) {
+            return { ok: false, message: "create_thread needs a room_id and a title of 1 to 200 characters" };
+        }
+        path = `/api/v1/rooms/${encodeURIComponent(input["room_id"])}/threads`;
+    }
+    else {
+        if (!boundedString(input["thread_id"], 1, 256))
+            return { ok: false, message: "create_reply needs a thread_id" };
+        path = `/api/v1/threads/${encodeURIComponent(input["thread_id"])}/posts`;
+    }
+    const body = {
+        ...(input["operation"] === "create_thread" ? { title: input["title"] } : {}),
+        body: input["body"],
+        ...(input["metadata"] === undefined ? {} : { metadata: input["metadata"] }),
+        ...(input["tags"] === undefined ? {} : { tags: input["tags"] }),
+        ...(input["references"] === undefined ? {} : { references: input["references"] }),
+    };
+    if (new TextEncoder().encode(canonicalize(body)).byteLength > MAX_MESSAGE_BYTES) {
+        return { ok: false, message: "the canonical ZZZ message exceeds 65536 UTF-8 bytes" };
+    }
+    return { ok: true, payload: input, path, body };
+}
+function idempotencyKey(actionKey, hash) {
+    const bytes = canonicalize({ action_key: actionKey, payload_hash: hash });
+    return `approval:${createHash("sha256").update(bytes, "utf8").digest("hex")}`;
+}
+function codeForStatus(status) {
+    if (status === 400)
+        return "zzz-invalid-request";
+    if (status === 401)
+        return "zzz-unauthorized";
+    if (status === 403)
+        return "zzz-forbidden";
+    if (status === 404)
+        return "zzz-not-found";
+    if (status === 409)
+        return "zzz-idempotency-conflict";
+    if (status === 413)
+        return "zzz-payload-too-large";
+    if (status === 422)
+        return "zzz-rejected";
+    if (status === 429)
+        return "zzz-rate-limited";
+    return "zzz-rejected";
+}
+async function boundedJson(response) {
+    const reader = response.body?.getReader();
+    if (reader === undefined)
+        throw new Error("ZZZ returned no response body");
+    const chunks = [];
+    let size = 0;
+    while (true) {
+        const item = await reader.read();
+        if (item.done)
+            break;
+        size += item.value.byteLength;
+        if (size > MAX_RESPONSE_BYTES) {
+            await reader.cancel();
+            throw new Error("ZZZ returned an oversized response");
+        }
+        chunks.push(item.value);
+    }
+    const joined = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return JSON.parse(new TextDecoder().decode(joined));
+}
+function originFor(environment, options) {
+    return options.origins?.[environment] ??
+        (environment === "production" ? ZZZ_PRODUCTION_API_BASE : ZZZ_PREVIEW_API_BASE);
+}
+export function zzzAdapter(options = {}) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? ZZZ_DEFAULT_TIMEOUT_MS;
+    return {
+        name: "zzz",
+        classes: [ZZZ_CLASS],
+        requiredCredentials: [ZZZ_TOKEN_NAME],
+        precheck(input) {
+            const checked = validateZzzPayload(input.payload);
+            return checked.ok
+                ? { ok: true }
+                : { ok: false, code: "zzz-payload-invalid", message: `${checked.message}. Nothing was sent` };
+        },
+        async act(input) {
+            const checked = validateZzzPayload(input.payload);
+            if (!checked.ok)
+                return { ok: false, code: "zzz-payload-invalid", message: `${checked.message}. Nothing was sent` };
+            const credential = input.credentials.get(ZZZ_TOKEN_NAME);
+            if (!credential.ok)
+                return { ok: false, code: credential.code, message: credential.message };
+            if (!TOKEN.test(credential.value)) {
+                return { ok: false, code: "zzz-config-invalid", message: "the vault's ZZZ agent token does not match the service credential shape. Nothing was sent" };
+            }
+            if (input.signal?.aborted === true) {
+                return { ok: false, code: "zzz-cancelled", message: "the ZZZ message was cancelled before the HTTP request. Nothing was sent" };
+            }
+            const environment = checked.payload.environment;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const abort = () => controller.abort();
+            input.signal?.addEventListener("abort", abort, { once: true });
+            try {
+                const response = await fetchImpl(new URL(checked.path, originFor(environment, options)), {
+                    method: "POST",
+                    redirect: "error",
+                    signal: controller.signal,
+                    headers: {
+                        Authorization: `Bearer ${credential.value}`,
+                        "Content-Type": "application/json",
+                        "Idempotency-Key": idempotencyKey(input.actionKey, payloadHash(input.payload)),
+                    },
+                    body: canonicalize(checked.body),
+                });
+                const definiteRefusal = [400, 401, 403, 404, 409, 413, 422, 429].includes(response.status);
+                if (response.status !== 200 && response.status !== 201 && !definiteRefusal) {
+                    await response.body?.cancel().catch(() => undefined);
+                    throw new Error(`ZZZ answered an ambiguous HTTP status ${String(response.status)}`);
+                }
+                if (definiteRefusal) {
+                    await response.body?.cancel().catch(() => undefined);
+                    return { ok: false, code: codeForStatus(response.status), message: `ZZZ refused the message with HTTP ${String(response.status)}. No response text was recorded` };
+                }
+                const answer = await boundedJson(response);
+                const parsed = object(answer);
+                const expectedPrefix = checked.payload.operation === "create_thread" ? "thr_" : "pst_";
+                if (parsed === null || exactKeys(parsed, ["id", "replayed"]) !== null ||
+                    typeof parsed["id"] !== "string" || !PROVIDER_ID.test(parsed["id"]) ||
+                    !parsed["id"].startsWith(expectedPrefix) || typeof parsed["replayed"] !== "boolean" ||
+                    parsed["replayed"] !== (response.status === 200)) {
+                    throw new Error("ZZZ returned an inconsistent success receipt");
+                }
+                return {
+                    ok: true,
+                    detail: {
+                        [PROVIDER_REF_DETAIL_KEY]: parsed["id"],
+                        replayed: parsed["replayed"],
+                        operation: checked.payload.operation,
+                        payload_hash: payloadHash(input.payload),
+                    },
+                };
+            }
+            finally {
+                clearTimeout(timer);
+                input.signal?.removeEventListener("abort", abort);
+            }
+        },
+    };
+}
+/** Read-only authentication probe. It proves no write scope or room access. */
+export async function probeZzz(token, options = {}) {
+    if (!TOKEN.test(token))
+        return { ok: false, code: "zzz-config-invalid", message: "the ZZZ agent token does not match the service credential shape" };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? ZZZ_DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await (options.fetch ?? globalThis.fetch)(new URL("/api/v1/rooms", originFor("production", options)), {
+            method: "GET",
+            redirect: "error",
+            signal: controller.signal,
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        await response.body?.cancel().catch(() => undefined);
+        if (response.status === 200)
+            return { ok: true };
+        return { ok: false, code: codeForStatus(response.status), message: `ZZZ answered HTTP ${String(response.status)}; no response text was recorded` };
+    }
+    catch {
+        return { ok: false, code: "zzz-unreachable", message: "ZZZ could not be reached for the read-only credential check" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=zzz.js.map

package/dist/src/adapters/zzz.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zzz.js","sourceRoot":"","sources":["../../../src/adapters/zzz.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EACL,wBAAwB,EACxB,uBAAuB,GAOxB,MAAM,eAAe,CAAC;AAEvB,MAAM,CAAC,MAAM,SAAS,GAAG,0BAA0B,CAAC;AACpD,MAAM,CAAC,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,0CAA0C,CAAC;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAEhD,MAAM,KAAK,GAAG,0BAA0B,CAAC;AACzC,MAAM,WAAW,GAAG,6BAA6B,CAAC;AAClD,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACjC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,qBAAqB;IACrB,oBAAoB;IACpB,qBAAqB;IACrB,kBAAkB;IAClB,eAAe;IACf,eAAe;IACf,0BAA0B;IAC1B,uBAAuB;IACvB,cAAc;IACd,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,GAAG,wBAAwB;CACnB,CAAC;AAEX,MAAM,CAAC,MAAM,oBAAoB,GAA8B;IAC7D;QACE,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,iBAAiB;QACxB,QAAQ,EAAE,0DAA0D;QACpE,QAAQ,EAAE,IAAI;QACd,QAAQ,CAAC,KAAa;YACpB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;gBACtB,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE;gBACd,CAAC,CAAC;oBACE,EAAE,EAAE,KAAK;oBACT,OAAO,EACL,sFAAsF;iBACzF,CAAC;QACR,CAAC;KACF;CACF,CAAC;AAwBF,SAAS,MAAM,CAAC,KAAgB;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzE,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED,SAAS,SAAS,CAAC,KAAgC,EAAE,OAA0B;IAC7E,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACvE,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAC5C,CAAC;AAED,SAAS,aAAa,CAAC,KAA4B,EAAE,GAAW,EAAE,GAAW;IAC3E,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG,CAAC;AACjF,CAAC;AAED,SAAS,eAAe,CAAC,KAA4B;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,KAAK,CAAC;IAC7D,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QAC9B,IAAI,GAAG,KAAK,IAAI,IAAI,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACvG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACjG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,UAAU,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,MAAM;YAAE,OAAO,KAAK,CAAC;QACvE,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7F,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,UAAU,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACnC,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;oBAAE,OAAO,KAAK,CAAC;YAC1E,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAgB;IACjD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC;IACzF,IAAI,KAAK,CAAC,aAAa,CAAC,KAAK,YAAY,IAAI,KAAK,CAAC,aAAa,CAAC,KAAK,SAAS,EAAE,CAAC;QAChF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,2CAA2C,EAAE,CAAC;IAC7E,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,eAAe,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,cAAc,EAAE,CAAC;QACpF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,iDAAiD,EAAE,CAAC;IACnF,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IACtF,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,CAAC,KAAK,eAAe;QACpD,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC;QACjC,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACxC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,yBAAyB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;IACpG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,yCAAyC,EAAE,CAAC;IACvH,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,SAAS;QAC3B,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,EAAE;YAC1D,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,4DAA4D,EAAE,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,8CAA8C,EAAE,CAAC;IAEzH,IAAI,IAAY,CAAC;IACjB,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,eAAe,EAAE,CAAC;QAC3C,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YACvF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,kEAAkE,EAAE,CAAC;QACpG,CAAC;QACD,IAAI,GAAG,iBAAiB,kBAAkB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC;IACzE,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;QAChH,IAAI,GAAG,mBAAmB,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC;IAC3E,CAAC;IAED,MAAM,IAAI,GAA8B;QACtC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,eAAe,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC;QACnB,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3E,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;KAClF,CAAC;IACF,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,GAAG,iBAAiB,EAAE,CAAC;QAChF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,qDAAqD,EAAE,CAAC;IACvF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAChE,CAAC;AAED,SAAS,cAAc,CAAC,SAAiB,EAAE,IAAY;IACrD,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1E,OAAO,YAAY,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAChF,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,qBAAqB,CAAC;IACjD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,kBAAkB,CAAC;IAC9C,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,eAAe,CAAC;IAC3C,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,eAAe,CAAC;IAC3C,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,0BAA0B,CAAC;IACtD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,uBAAuB,CAAC;IACnD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,cAAc,CAAC;IAC1C,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,kBAAkB,CAAC;IAC9C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,QAAkB;IAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;IAC1C,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI;YAAE,MAAM;QACrB,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC;QAC9B,IAAI,IAAI,GAAG,kBAAkB,EAAE,CAAC;YAC9B,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;IAAC,CAAC;IACtF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAY,CAAC;AACjE,CAAC;AASD,SAAS,SAAS,CAAC,WAAqC,EAAE,OAA0B;IAClF,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC;QACnC,CAAC,WAAW,KAAK,YAAY,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAO,GAAsB,EAAE;IACxD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACpD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,sBAAsB,CAAC;IAC9D,OAAO;QACL,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,CAAC,SAAS,CAAC;QACpB,mBAAmB,EAAE,CAAC,cAAc,CAAC;QACrC,QAAQ,CAAC,KAAoB;YAC3B,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAClD,OAAO,OAAO,CAAC,EAAE;gBACf,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE;gBACd,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,oBAAoB,EAAE,CAAC;QAClG,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,KAAe;YACvB,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAClD,IAAI,CAAC,OAAO,CAAC,EAAE;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,oBAAoB,EAAE,CAAC;YACpH,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YACzD,IAAI,CAAC,UAAU,CAAC,EAAE;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC;YAC7F,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;gBAClC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,2FAA2F,EAAE,CAAC;YACzJ,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;gBACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,yEAAyE,EAAE,CAAC;YAClI,CAAC;YACD,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC;YAChD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;YAC9D,MAAM,KAAK,GAAG,GAAS,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YAC7C,KAAK,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,EAAE;oBACvF,MAAM,EAAE,MAAM;oBACd,QAAQ,EAAE,OAAO;oBACjB,MAAM,EAAE,UAAU,CAAC,MAAM;oBACzB,OAAO,EAAE;wBACP,aAAa,EAAE,UAAU,UAAU,CAAC,KAAK,EAAE;wBAC3C,cAAc,EAAE,kBAAkB;wBAClC,iBAAiB,EAAE,cAAc,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;qBAC/E;oBACD,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC;iBACjC,CAAC,CAAC;gBACH,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBAC3F,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;oBAC3E,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;oBACrD,MAAM,IAAI,KAAK,CAAC,yCAAyC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACtF,CAAC;gBACD,IAAI,eAAe,EAAE,CAAC;oBACpB,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;oBACrD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,qCAAqC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,iCAAiC,EAAE,CAAC;gBACrK,CAAC;gBACD,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;gBAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAmB,CAAC,CAAC;gBAC3C,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,KAAK,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;gBACvF,IAAI,MAAM,KAAK,IAAI,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,KAAK,IAAI;oBACjE,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;oBACnE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,OAAO,MAAM,CAAC,UAAU,CAAC,KAAK,SAAS;oBACnF,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC;oBACrD,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;gBAClE,CAAC;gBACD,OAAO;oBACL,EAAE,EAAE,IAAI;oBACR,MAAM,EAAE;wBACN,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC;wBACvC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC;wBAC5B,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS;wBACpC,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC;qBACzC;iBACF,CAAC;YACJ,CAAC;oBAAS,CAAC;gBACT,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,KAAK,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAID,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAAa,EAAE,OAAO,GAAsB,EAAE;IAC3E,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,iEAAiE,EAAE,CAAC;IACrJ,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,SAAS,IAAI,sBAAsB,CAAC,CAAC;IAChG,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,eAAe,EAAE,SAAS,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,EAAE;YACrH,MAAM,EAAE,KAAK;YACb,QAAQ,EAAE,OAAO;YACjB,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE;SAC9C,CAAC,CAAC;QACH,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,qBAAqB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,iCAAiC,EAAE,CAAC;IACrJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,6DAA6D,EAAE,CAAC;IACxH,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,109 @@
+/**
+ * Batching: one human gesture over many requests, without losing audit
+ * granularity (SPEC.md §10.3, requirement B7).
+ *
+ * > Channels MAY present multiple pending requests as a batch and collect one
+ * > human gesture over the set, and SHOULD for high-volume `record.*` classes.
+ * > The log never batches: each granted or rejected request receives its own
+ * > `approval.granted` or `approval.rejected` event carrying the batch's channel
+ * > delivery id in its payload, so audit granularity survives ergonomic
+ * > grouping. A batch MUST NOT mix `manual` classes with differing
+ * > payload-display requirements in a way that hides any full payload behind the
+ * > fold of another.
+ *
+ * Two halves, and this module is both: {@link assembleBatch} enforces the
+ * forbidden mix *before* anything is delivered, and {@link recordBatchDecisions}
+ * records one gate decision per member afterwards.
+ *
+ * ## The B7 operationalization — FLAGGED FOR HUMAN REVIEW
+ *
+ * "Hides any full payload behind the fold of another" is a sentence about
+ * rendering, and rendering is the one thing the runtime cannot inspect. So B7 is
+ * operationalized here as a property of the *batch material* rather than of the
+ * pixels:
+ *
+ * > A batch MUST carry every member's full payload whole. The forbidden mix is
+ * > any member whose `fullPayload` is absent or truncated while the batch
+ * > contains more than one distinct payload — because with one payload there is
+ * > no "another" to hide behind, and with two or more, a member the channel was
+ * > not given in full is a member the approver cannot have read.
+ *
+ * Concretely, {@link assembleBatch} refuses when the batch holds more than one
+ * distinct `payload_hash` **and** any member's `fullPayload` is `null` or
+ * `truncated`. A single-payload batch (the same bytes requested twice, or one
+ * request) is always assemblable, and a multi-payload batch is assemblable
+ * exactly when every member arrives whole.
+ *
+ * What this deliberately does **not** try to be: a judgment about whether a
+ * particular channel's layout actually put payload #2 below the fold. That is a
+ * per-channel rendering property, and `channels/conformance.ts` checks the
+ * observable half of it (every member's full payload text present in the
+ * rendering, delineated from the claimed summary). The interpretation to
+ * confirm is the reduction of "differing payload-display requirements" to
+ * "distinct payload bytes": it is the reading that makes the rule mechanical,
+ * and it is stricter than the spec's letter in one direction (two whole payloads
+ * are fine only if both are whole) and silent in another (it says nothing about
+ * a channel that renders both whole and then collapses one). A human should
+ * confirm this is the intended reading before APRV-23/25/26 build against it.
+ */
+import type { DecideOptions } from "../core/gate.js";
+import { type ChannelActorOptions, type ChannelBatch, type ChannelDecision, type ChannelRequest, type DecisionOutcome, type DeliveryId } from "./contract.js";
+export { BATCH_DELIVERY_ID_FIELD, BATCH_DELIVERY_NOTE_PREFIX, batchDeliveryIdOf, batchNote, type ChannelBatch, } from "./contract.js";
+/** The one way a batch can be refused (SPEC.md §10.3, B7). */
+export declare const BATCH_REFUSAL_CODE = "batch-forbidden-mix";
+export interface BatchRefusal {
+    ok: false;
+    code: typeof BATCH_REFUSAL_CODE;
+    message: string;
+}
+export type AssembleBatchResult = {
+    ok: true;
+    batch: ChannelBatch;
+} | BatchRefusal;
+/**
+ * Assemble `requests` into a batch, or refuse the forbidden mix.
+ *
+ * The returned batch carries every member request **whole** — the same
+ * {@link ChannelRequest} objects a channel would receive individually, tags and
+ * full payloads included. A channel therefore has everything it needs to render
+ * each member in full; if it chooses not to, that is a rendering defect the
+ * conformance suite catches, not a gap in the material it was handed.
+ *
+ * `deliveryId` is left unset: it is assigned by the channel at `notify`.
+ */
+export declare function assembleBatch(requests: ChannelRequest[]): AssembleBatchResult;
+/** One member's outcome. `token` is held back from the channel, as always. */
+export interface BatchMemberResult {
+    action_key: string;
+    outcome: DecisionOutcome;
+    /** The raw execution token for a successful grant. Runtime-only. */
+    token?: string;
+}
+export interface BatchDecisionsResult {
+    /** True when every member was recorded. */
+    ok: boolean;
+    /** One entry per input decision, in input order. */
+    results: BatchMemberResult[];
+    batchDeliveryId: DeliveryId;
+}
+/**
+ * Record one gate decision per batch member.
+ *
+ * **Unit decisions mean unit outcomes.** The log never batches (SPEC.md §10.3),
+ * so this is a loop over `decide()` and not a transaction: each member is
+ * checked and appended on its own, each carries the batch delivery id in its
+ * payload as the first-class `batch_delivery_id` field (amended SPEC.md §10.3,
+ * APRV-38), and a member that refuses does **not** stop the rest. That is
+ * deliberate and it is the only coherent semantics available — an "all or
+ * nothing" batch would have to un-append events the log forbids un-appending,
+ * and abandoning the remaining members because the third one expired would
+ * discard a human's answer to the other four. So: partial success is a real
+ * outcome, `ok` is false when any member refused, and `results` says exactly
+ * which ones landed. A caller that wants atomicity does not want a batch.
+ *
+ * Ordering: members are recorded in the order given. Each append passes the
+ * gate's compare-and-append precondition against the head *it* read, so a
+ * concurrent writer refuses one member with `append-failed`/`head-moved`
+ * rather than corrupting the set.
+ */
+export declare function recordBatchDecisions(logPath: string, decisions: ChannelDecision[], batchDeliveryId: DeliveryId, actorOptions: ChannelActorOptions, gateOptions?: DecideOptions): BatchDecisionsResult;

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

@@ -0,0 +1,193 @@
+/**
+ * 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 { type PromptLayout } from "../core/prompt-layout.js";
+import type { ChannelBatch, ChannelDecision, ChannelHealth, ChannelRequest, DecisionOutcome, DeliveryId, RenderedRequest, TestableChannel } from "./contract.js";
+/** The narrowest thing this channel needs to write to. `process.stdout` fits. */
+export interface OutputSink {
+    write(text: string): unknown;
+}
+/** The narrowest thing this channel needs to read lines from. `process.stdin` fits. */
+export type InputSource = NodeJS.ReadableStream;
+export interface CliChannelOptions {
+    /** Where the rendering goes. Defaults to `process.stdout`. */
+    output?: OutputSink;
+    /** Where the gesture comes from. Defaults to `process.stdin`. */
+    input?: InputSource;
+    /** Channel name recorded for audit. Defaults to `cli`. */
+    name?: string;
+    /**
+     * Which rows the rendering shows (APRV-218), from `channels.cli.prompt`.
+     *
+     * Resolved by the verb, which has already loaded the policy; this channel
+     * neither reads a policy file nor holds an opinion about what an operator
+     * should see. Defaults to {@link CLI_PROMPT_LAYOUT}, so a channel constructed
+     * without one renders exactly what it rendered before the key existed.
+     */
+    layout?: PromptLayout;
+}
+/** The marker prefixes. Exported because the help text and the tests pin them. */
+export declare const COMPUTED_MARKER = "[computed]";
+export declare const CLAIMED_MARKER = "[claimed]";
+/** The full-payload delimiters (SPEC.md §10.4). Pinned by tests. */
+export declare const PAYLOAD_BEGIN = "--- BEGIN FULL PAYLOAD";
+export declare const PAYLOAD_END = "--- END FULL PAYLOAD ---";
+/** One line of the legend, printed above every delivery. */
+export declare const RENDERING_LEGEND: string;
+/** What {@link CliChannel.collectDecision} produced. */
+export type CliCollection = {
+    kind: "decided";
+    decision: ChannelDecision;
+    outcome: DecisionOutcome;
+}
+/** The human declined to answer this one; nothing was reported. */
+ | {
+    kind: "skipped";
+}
+/** Input ended before an answer arrived; nothing was reported. */
+ | {
+    kind: "aborted";
+};
+export declare class CliChannel implements TestableChannel {
+    readonly name: string;
+    private readonly output;
+    private readonly input;
+    private handler;
+    private rendered;
+    private reader;
+    private counter;
+    /** The policy's row layout for this channel (APRV-218). Pure input to the rendering. */
+    private readonly layout;
+    constructor(options?: CliChannelOptions);
+    /**
+     * 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: ChannelRequest | ChannelBatch): DeliveryId;
+    onDecision(handler: (decision: ChannelDecision) => DecisionOutcome): void;
+    health(): ChannelHealth;
+    lastRendered(): RenderedRequest[];
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    collectDecision(actionKey: string, deliveryId: DeliveryId, options?: {
+        batchDeliveryId?: DeliveryId;
+    }): Promise<CliCollection>;
+    /**
+     * 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.
+     */
+    collectCheckpoint(lines: readonly string[]): Promise<boolean | null>;
+    private report;
+    /**
+     * 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.
+     */
+    private askNote;
+    private readLine;
+    /**
+     * 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.
+     */
+    private renderRequest;
+}