approval-md 0.0.1 → 0.2.0

package/dist/src/core/payload-store.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The payload store: one source of bytes for the gate, the render, and every
+ * channel (SPEC.md §6.2, §9, §10.4; APRV-28).
+ *
+ * SPEC.md §6.2 already asks for this in one clause — "The payload itself is
+ * stored or referenced by the request so channels can display it; the hash is
+ * what approval binds to" — and until now nothing implemented it. The bytes a
+ * human had to see before deciding were carried around the runtime by hand:
+ * `--payload-dir` for the CLI and web channels, `--payloads` for Telegram, and
+ * nothing at all for `approval render`, which is why QUEUE.md's pending count
+ * disagreed with the queue every channel showed (the APRV-27 friction case).
+ *
+ * ## What this is
+ *
+ * A content-addressed directory, `.approval/payloads/` beside the log, holding
+ * one file per bound payload: `<payload_hash>.json`, whose contents are the
+ * exact material whose RFC 8785 canonical serialization hashes to the filename.
+ * The name *is* the checksum, so the store needs no index, no manifest and no
+ * lock: two writers writing the same payload write the same bytes to the same
+ * path, and a file either verifies or it is refused.
+ *
+ * ## Verified on every read, without exception
+ *
+ * {@link loadPayload} re-canonicalizes and re-hashes what it read and compares
+ * that against the filename before returning anything. A file whose contents
+ * were edited after it was written refuses `hash-mismatch` and its value is
+ * **never returned**, so tampering with the store cannot put different bytes in
+ * front of an approver than the ones the request bound to. The recorded binding
+ * on `approval.requested` stays authoritative in both directions: the store is a
+ * cache of bytes that the log already committed to, and when the two disagree
+ * the log is right and the store is refused.
+ *
+ * This is the same rule the rest of the codebase keeps — files are the
+ * interface, the log is the truth, the database (and now the store) is a cache.
+ *
+ * ## External references
+ *
+ * A request may name material this runtime cannot hold: a message body in a
+ * vault, an object in a bucket. The store records that as `{"$ref": "<uri>"}` in
+ * the same `<hash>.json` file, and {@link loadPayload} reports it as a
+ * `reference` — deliberately **not** resolved. Resolving a URI would mean
+ * fetching bytes at render time from a source this module cannot verify, and a
+ * channel that displayed them would be showing an approver something no hash
+ * ever bound. So a reference renders as a reference: the channel says where the
+ * payload lives and refuses to pretend it has seen it.
+ *
+ * ## Writes never touch the log
+ *
+ * Nothing here opens `events.jsonl`. {@link storePayload} writes exactly one
+ * file, atomically (temp + rename in the destination directory), and the store
+ * directory is a sibling of the log directory rather than a child, so no
+ * conceivable store path collides with the log's.
+ */
+/** The directory name, beside the log's home: `.approval/payloads/`. */
+export declare const PAYLOAD_STORE_DIRNAME = "payloads";
+/**
+ * The store directory for a given log path — the convention every caller uses
+ * when no explicit directory is supplied.
+ *
+ * SPEC.md §9 fixes the log at `<home>/log/events.jsonl`, so the store is
+ * `<home>/payloads/`: a sibling of the log directory, never inside it. When a
+ * caller points `--log` at some other layout the store lands beside that file
+ * instead, which keeps the two together for the ad-hoc case without ever
+ * placing payload files in the directory the log is walked from.
+ */
+export declare function payloadStoreDirFor(logPath: string): string;
+/** The file one payload hash addresses. */
+export declare function payloadPath(storeDir: string, hash: string): string;
+export type StorePayloadResult = {
+    ok: true;
+    hash: string;
+    path: string;
+} | {
+    ok: false;
+    code: "unserializable" | "write-failed";
+    message: string;
+};
+/**
+ * Store payload material and return the hash it is addressed by.
+ *
+ * The bytes written are the RFC 8785 canonical serialization itself — not
+ * `JSON.stringify` of the value — so the file's own bytes hash to its own name
+ * and the store is verifiable byte for byte as well as semantically.
+ *
+ * **Idempotent.** Writing the same value twice writes the same bytes to the same
+ * path and reports the same hash. The write is unconditional rather than
+ * skipped-if-present, which also means a corrupted file is repaired by the next
+ * store of the same payload: content addressing makes "overwrite" and "leave
+ * alone" the same operation for anything that was ever valid.
+ *
+ * Refuses `unserializable` for material RFC 8785 cannot serialize (a cycle, a
+ * NaN, a function). A payload that cannot be canonicalized cannot be bound to,
+ * so it must not be stored under a hash that would then name something else.
+ */
+export declare function storePayload(storeDir: string, value: unknown): StorePayloadResult;
+/**
+ * Record an external reference for a payload this runtime does not hold.
+ *
+ * The hash is supplied by the caller because a reference does not determine one:
+ * the binding is a fact about the *payload*, which lives elsewhere, and the
+ * reference is only a pointer to it. {@link loadPayload} reports the pointer and
+ * resolves nothing — see the module header.
+ */
+export declare function storeReference(storeDir: string, hash: string, reference: string): StorePayloadResult;
+/**
+ * Every payload hash the store currently holds, sorted.
+ *
+ * Only `<hash>.json` names whose stem is a well-formed `payload_hash` are
+ * reported. A directory, a dotfile (the temp name an interrupted
+ * {@link writeAtomic} leaves behind), and anything else a human dropped in the
+ * directory are not payloads the store addresses, so no caller — the daemon's
+ * pruner least of all — is ever handed one as if it were.
+ *
+ * An unreadable or absent directory yields the empty list rather than throwing:
+ * a store that cannot be listed holds nothing this process can act on, which is
+ * the fail-closed reading for every caller here (reporting counts, deciding what
+ * to prune).
+ */
+export declare function listStoredPayloadHashes(storeDir: string): string[];
+/** Why a removal did not happen. `absent` is a success for every caller here. */
+export type RemovePayloadResult = {
+    ok: true;
+    path: string;
+    existed: boolean;
+} | {
+    ok: false;
+    code: "unlink-failed";
+    message: string;
+    path: string;
+};
+/**
+ * Delete the bytes stored under `hash`.
+ *
+ * **Daemon-only.** SPEC.md §5.2: "Pruning is performed by the daemon and by
+ * nothing else." Nothing in the CLI calls this, and the retention rule that
+ * decides *which* hash reaches it lives in `daemon/prune.ts`, which appends the
+ * `payload.pruned` event before the file goes. This function is the unlink and
+ * nothing more: it judges no retention, reads no policy, and touches no log.
+ *
+ * A file that is already gone reports `existed: false` and `ok`. The caller's
+ * intent is that the bytes not be there, and a removal that raced another
+ * removal (or completed a crash-interrupted one) achieved exactly that.
+ */
+export declare function removeStoredPayload(storeDir: string, hash: string): RemovePayloadResult;
+/** Why a read did not produce material. */
+export type LoadPayloadRefusalCode = 
+/** No file is stored under this hash. */
+"absent"
+/** A file exists but its contents do not hash to its name. */
+ | "hash-mismatch"
+/** The file could not be read, or is not JSON. */
+ | "unreadable"
+/** The file holds a `{"$ref": …}` pointer, which is not resolved here. */
+ | "reference";
+export type LoadPayloadResult = {
+    ok: true;
+    value: unknown;
+    path: string;
+} | {
+    ok: false;
+    code: LoadPayloadRefusalCode;
+    message: string;
+    path: string;
+    /** The pointer, when `code` is `reference`. */
+    reference?: string;
+};
+/**
+ * Load the material stored under `hash`, verifying it against `hash`.
+ *
+ * The verification is unconditional and the value is withheld when it fails:
+ * `hash-mismatch` says the file on disk is not the payload the request bound to,
+ * and returning it "so the caller can decide" would hand a channel exactly the
+ * bytes the binding exists to keep away from an approver.
+ */
+export declare function loadPayload(storeDir: string, hash: string): LoadPayloadResult;

package/dist/src/core/payload-store.js

@@ -0,0 +1,340 @@
+/**
+ * The payload store: one source of bytes for the gate, the render, and every
+ * channel (SPEC.md §6.2, §9, §10.4; APRV-28).
+ *
+ * SPEC.md §6.2 already asks for this in one clause — "The payload itself is
+ * stored or referenced by the request so channels can display it; the hash is
+ * what approval binds to" — and until now nothing implemented it. The bytes a
+ * human had to see before deciding were carried around the runtime by hand:
+ * `--payload-dir` for the CLI and web channels, `--payloads` for Telegram, and
+ * nothing at all for `approval render`, which is why QUEUE.md's pending count
+ * disagreed with the queue every channel showed (the APRV-27 friction case).
+ *
+ * ## What this is
+ *
+ * A content-addressed directory, `.approval/payloads/` beside the log, holding
+ * one file per bound payload: `<payload_hash>.json`, whose contents are the
+ * exact material whose RFC 8785 canonical serialization hashes to the filename.
+ * The name *is* the checksum, so the store needs no index, no manifest and no
+ * lock: two writers writing the same payload write the same bytes to the same
+ * path, and a file either verifies or it is refused.
+ *
+ * ## Verified on every read, without exception
+ *
+ * {@link loadPayload} re-canonicalizes and re-hashes what it read and compares
+ * that against the filename before returning anything. A file whose contents
+ * were edited after it was written refuses `hash-mismatch` and its value is
+ * **never returned**, so tampering with the store cannot put different bytes in
+ * front of an approver than the ones the request bound to. The recorded binding
+ * on `approval.requested` stays authoritative in both directions: the store is a
+ * cache of bytes that the log already committed to, and when the two disagree
+ * the log is right and the store is refused.
+ *
+ * This is the same rule the rest of the codebase keeps — files are the
+ * interface, the log is the truth, the database (and now the store) is a cache.
+ *
+ * ## External references
+ *
+ * A request may name material this runtime cannot hold: a message body in a
+ * vault, an object in a bucket. The store records that as `{"$ref": "<uri>"}` in
+ * the same `<hash>.json` file, and {@link loadPayload} reports it as a
+ * `reference` — deliberately **not** resolved. Resolving a URI would mean
+ * fetching bytes at render time from a source this module cannot verify, and a
+ * channel that displayed them would be showing an approver something no hash
+ * ever bound. So a reference renders as a reference: the channel says where the
+ * payload lives and refuses to pretend it has seen it.
+ *
+ * ## Writes never touch the log
+ *
+ * Nothing here opens `events.jsonl`. {@link storePayload} writes exactly one
+ * file, atomically (temp + rename in the destination directory), and the store
+ * directory is a sibling of the log directory rather than a child, so no
+ * conceivable store path collides with the log's.
+ */
+import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { canonicalize } from "./jcs.js";
+import { isPayloadHash, payloadHash } from "./payload.js";
+/** The directory name, beside the log's home: `.approval/payloads/`. */
+export const PAYLOAD_STORE_DIRNAME = "payloads";
+/**
+ * The store directory for a given log path — the convention every caller uses
+ * when no explicit directory is supplied.
+ *
+ * SPEC.md §9 fixes the log at `<home>/log/events.jsonl`, so the store is
+ * `<home>/payloads/`: a sibling of the log directory, never inside it. When a
+ * caller points `--log` at some other layout the store lands beside that file
+ * instead, which keeps the two together for the ad-hoc case without ever
+ * placing payload files in the directory the log is walked from.
+ */
+export function payloadStoreDirFor(logPath) {
+    const logDir = dirname(logPath);
+    const home = basename(logDir) === "log" ? dirname(logDir) : logDir;
+    return join(home, PAYLOAD_STORE_DIRNAME);
+}
+/** The file one payload hash addresses. */
+export function payloadPath(storeDir, hash) {
+    return join(storeDir, `${hash}.json`);
+}
+function detail(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/** Distinguishes concurrent writers' temp files within one process. */
+let tempCounter = 0;
+function writeAtomic(path, bytes) {
+    const directory = dirname(path);
+    tempCounter += 1;
+    const temp = join(directory, `.${basename(path)}.tmp-${String(process.pid)}-${String(tempCounter)}`);
+    try {
+        mkdirSync(directory, { recursive: true });
+        const handle = openSync(temp, "wx");
+        try {
+            writeSync(handle, bytes, 0, "utf8");
+        }
+        finally {
+            closeSync(handle);
+        }
+        renameSync(temp, path);
+    }
+    catch (cause) {
+        try {
+            unlinkSync(temp);
+        }
+        catch {
+            // The temp file may never have been created; nothing to clean up.
+        }
+        return { ok: false, message: detail(cause) };
+    }
+    return { ok: true };
+}
+/**
+ * Store payload material and return the hash it is addressed by.
+ *
+ * The bytes written are the RFC 8785 canonical serialization itself — not
+ * `JSON.stringify` of the value — so the file's own bytes hash to its own name
+ * and the store is verifiable byte for byte as well as semantically.
+ *
+ * **Idempotent.** Writing the same value twice writes the same bytes to the same
+ * path and reports the same hash. The write is unconditional rather than
+ * skipped-if-present, which also means a corrupted file is repaired by the next
+ * store of the same payload: content addressing makes "overwrite" and "leave
+ * alone" the same operation for anything that was ever valid.
+ *
+ * Refuses `unserializable` for material RFC 8785 cannot serialize (a cycle, a
+ * NaN, a function). A payload that cannot be canonicalized cannot be bound to,
+ * so it must not be stored under a hash that would then name something else.
+ */
+export function storePayload(storeDir, value) {
+    let hash;
+    let bytes;
+    try {
+        bytes = canonicalize(value);
+        hash = payloadHash(value);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            code: "unserializable",
+            message: `the payload material could not be canonicalized: ${detail(cause)}. A payload that cannot be serialized cannot be bound to, so nothing was stored.`,
+        };
+    }
+    const path = payloadPath(storeDir, hash);
+    const written = writeAtomic(path, bytes);
+    if (!written.ok) {
+        return {
+            ok: false,
+            code: "write-failed",
+            message: `payload ${hash} could not be written to ${path}: ${written.message}. Nothing was stored and the log was not touched.`,
+        };
+    }
+    return { ok: true, hash, path };
+}
+/**
+ * Record an external reference for a payload this runtime does not hold.
+ *
+ * The hash is supplied by the caller because a reference does not determine one:
+ * the binding is a fact about the *payload*, which lives elsewhere, and the
+ * reference is only a pointer to it. {@link loadPayload} reports the pointer and
+ * resolves nothing — see the module header.
+ */
+export function storeReference(storeDir, hash, reference) {
+    if (!isPayloadHash(hash)) {
+        return {
+            ok: false,
+            code: "unserializable",
+            message: `${JSON.stringify(hash)} is not a payload hash (SHA-256, lowercase hex); a reference must be filed under the hash the request bound to`,
+        };
+    }
+    const path = payloadPath(storeDir, hash);
+    const written = writeAtomic(path, canonicalize({ $ref: reference }));
+    if (!written.ok) {
+        return {
+            ok: false,
+            code: "write-failed",
+            message: `reference for ${hash} could not be written to ${path}: ${written.message}`,
+        };
+    }
+    return { ok: true, hash, path };
+}
+// ---------------------------------------------------------------------------
+// Enumeration and removal
+// ---------------------------------------------------------------------------
+/**
+ * Every payload hash the store currently holds, sorted.
+ *
+ * Only `<hash>.json` names whose stem is a well-formed `payload_hash` are
+ * reported. A directory, a dotfile (the temp name an interrupted
+ * {@link writeAtomic} leaves behind), and anything else a human dropped in the
+ * directory are not payloads the store addresses, so no caller — the daemon's
+ * pruner least of all — is ever handed one as if it were.
+ *
+ * An unreadable or absent directory yields the empty list rather than throwing:
+ * a store that cannot be listed holds nothing this process can act on, which is
+ * the fail-closed reading for every caller here (reporting counts, deciding what
+ * to prune).
+ */
+export function listStoredPayloadHashes(storeDir) {
+    let entries;
+    try {
+        entries = readdirSync(storeDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const hashes = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || entry.name.startsWith(".") || !entry.name.endsWith(".json"))
+            continue;
+        const stem = entry.name.slice(0, -".json".length);
+        if (isPayloadHash(stem))
+            hashes.push(stem);
+    }
+    return hashes.sort();
+}
+/**
+ * Delete the bytes stored under `hash`.
+ *
+ * **Daemon-only.** SPEC.md §5.2: "Pruning is performed by the daemon and by
+ * nothing else." Nothing in the CLI calls this, and the retention rule that
+ * decides *which* hash reaches it lives in `daemon/prune.ts`, which appends the
+ * `payload.pruned` event before the file goes. This function is the unlink and
+ * nothing more: it judges no retention, reads no policy, and touches no log.
+ *
+ * A file that is already gone reports `existed: false` and `ok`. The caller's
+ * intent is that the bytes not be there, and a removal that raced another
+ * removal (or completed a crash-interrupted one) achieved exactly that.
+ */
+export function removeStoredPayload(storeDir, hash) {
+    const path = payloadPath(storeDir, hash);
+    if (!isPayloadHash(hash)) {
+        return {
+            ok: false,
+            code: "unlink-failed",
+            message: `${JSON.stringify(hash)} is not a payload hash; the store is addressed by hash and nothing else, so nothing was removed`,
+            path,
+        };
+    }
+    try {
+        unlinkSync(path);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT") {
+            return { ok: true, path, existed: false };
+        }
+        return {
+            ok: false,
+            code: "unlink-failed",
+            message: `payload ${path} could not be removed: ${detail(cause)}`,
+            path,
+        };
+    }
+    return { ok: true, path, existed: true };
+}
+/** Is this the `{"$ref": "<uri>"}` form, and nothing else? */
+function referenceOf(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const keys = Object.keys(value);
+    if (keys.length !== 1 || keys[0] !== "$ref")
+        return null;
+    const ref = value.$ref;
+    return typeof ref === "string" ? ref : null;
+}
+/**
+ * Load the material stored under `hash`, verifying it against `hash`.
+ *
+ * The verification is unconditional and the value is withheld when it fails:
+ * `hash-mismatch` says the file on disk is not the payload the request bound to,
+ * and returning it "so the caller can decide" would hand a channel exactly the
+ * bytes the binding exists to keep away from an approver.
+ */
+export function loadPayload(storeDir, hash) {
+    const path = payloadPath(storeDir, hash);
+    if (!isPayloadHash(hash)) {
+        return {
+            ok: false,
+            code: "unreadable",
+            message: `${JSON.stringify(hash)} is not a payload hash (SHA-256, lowercase hex); the store is addressed by hash and nothing else`,
+            path,
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT") {
+            return { ok: false, code: "absent", message: `no payload is stored at ${path}`, path };
+        }
+        return {
+            ok: false,
+            code: "unreadable",
+            message: `payload ${path} could not be read: ${detail(cause)}`,
+            path,
+        };
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            code: "unreadable",
+            message: `payload ${path} is not valid JSON: ${detail(cause)}`,
+            path,
+        };
+    }
+    const reference = referenceOf(value);
+    if (reference !== null) {
+        return {
+            ok: false,
+            code: "reference",
+            message: `payload ${hash} is stored as an external reference (${reference}) and is not resolved here; a channel may show the reference but must not present bytes no hash bound`,
+            path,
+            reference,
+        };
+    }
+    let actual;
+    try {
+        actual = payloadHash(value);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            code: "unreadable",
+            message: `payload ${path} could not be canonicalized for verification: ${detail(cause)}`,
+            path,
+        };
+    }
+    if (actual !== hash) {
+        return {
+            ok: false,
+            code: "hash-mismatch",
+            message: `payload ${path} hashes to ${actual}, not to the ${hash} it is filed under; the stored bytes are not the bytes the request bound to and will not be rendered`,
+            path,
+        };
+    }
+    return { ok: true, value, path };
+}
+//# sourceMappingURL=payload-store.js.map

package/dist/src/core/payload-store.js.map

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

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

@@ -0,0 +1,71 @@
+/**
+ * Content binding: the hash an approval is bound to (amended SPEC.md §6.2, §10,
+ * APRV-20 pass two / amendment A1).
+ *
+ * ## What this buys
+ *
+ * Before content binding, a grant approved an *action key*. The bytes that key
+ * would ultimately execute were whatever the executor happened to hold at
+ * execution time, which is to say: whatever the agent decided after the human
+ * said yes. The amended §10 closes that:
+ *
+ * > An execution token is bound to the request, its `idempotency_key`, AND its
+ * > `payload_hash`. Adapters and `approval run` MUST recompute the hash of the
+ * > payload they are about to execute and MUST refuse, with a distinct
+ * > machine-readable reason (`payload-mismatch`), when it differs from the hash
+ * > the grant recorded. A grant therefore approves specific bytes.
+ *
+ * So the hash is the *whole* mechanism: `core/gate.ts` refuses to admit a manual
+ * action whose declaration carries none (`payload-hash-required`), copies it
+ * onto `approval.requested` and then onto `approval.granted`, and
+ * `core/token.ts` refuses to spend a token against different bytes
+ * (`payload-mismatch`).
+ *
+ * ## Why JCS, and why not "just hash the string"
+ *
+ * §6.2 says "SHA-256 over the RFC 8785 canonical serialization of the action's
+ * concrete payload". Canonicalization is what makes the hash reproducible across
+ * two implementations that agree about the *payload* but not about key order,
+ * whitespace, or number formatting — which is exactly the situation an adapter
+ * written in another language is in. The same canonicalizer the log's hash chain
+ * uses (`core/jcs.ts`) is used here, so there is one serialization rule in this
+ * codebase and not two.
+ *
+ * ## The `approval run` payload
+ *
+ * §6.2 names it: "for `approval run`, the argv array and cwd". {@link
+ * runPayloadHash} is that definition made executable — the hash of
+ * `{"argv": [...], "cwd": "..."}` — and `approval run` computes it
+ * automatically from the command it is about to spawn. An adapter whose payload
+ * is something else (a message body and its recipients, a proposed record)
+ * hashes that with {@link payloadHash} and presents the result explicitly.
+ *
+ * The cwd is inside the hash on purpose: `rm -rf build` means two different
+ * things in two different directories, and a binding that ignored the working
+ * directory would approve one of them and execute the other.
+ *
+ * Pure: no I/O, no clock, no randomness.
+ */
+/** The form a `payload_hash` takes everywhere: SHA-256, lowercase hex. */
+export declare const PAYLOAD_HASH_PATTERN: RegExp;
+/** Is this a well-formed `payload_hash`? The schema says the same thing. */
+export declare function isPayloadHash(value: unknown): value is string;
+/**
+ * SHA-256 (lowercase hex) over the RFC 8785 canonical serialization of a
+ * payload — the definition amended SPEC.md §6.2 gives for `payload_hash`.
+ *
+ * Throws `JcsError` for a value RFC 8785 cannot serialize (a cycle, a NaN, a
+ * function). That is deliberate: a payload that cannot be canonicalized cannot
+ * be bound to, and returning a plausible-looking digest for it would be worse
+ * than failing.
+ */
+export declare function payloadHash(value: unknown): string;
+/**
+ * The `payload_hash` of an `approval run` invocation: the argv array and cwd.
+ *
+ * `argv` is the child's argv as it will actually be spawned — the command name
+ * first, then its arguments — not the `approval` wrapper's own flags, which
+ * have no side effect to bind. `cwd` is the absolute directory the child will
+ * run in.
+ */
+export declare function runPayloadHash(argv: readonly string[], cwd: string): string;

package/dist/src/core/payload.js

@@ -0,0 +1,80 @@
+/**
+ * Content binding: the hash an approval is bound to (amended SPEC.md §6.2, §10,
+ * APRV-20 pass two / amendment A1).
+ *
+ * ## What this buys
+ *
+ * Before content binding, a grant approved an *action key*. The bytes that key
+ * would ultimately execute were whatever the executor happened to hold at
+ * execution time, which is to say: whatever the agent decided after the human
+ * said yes. The amended §10 closes that:
+ *
+ * > An execution token is bound to the request, its `idempotency_key`, AND its
+ * > `payload_hash`. Adapters and `approval run` MUST recompute the hash of the
+ * > payload they are about to execute and MUST refuse, with a distinct
+ * > machine-readable reason (`payload-mismatch`), when it differs from the hash
+ * > the grant recorded. A grant therefore approves specific bytes.
+ *
+ * So the hash is the *whole* mechanism: `core/gate.ts` refuses to admit a manual
+ * action whose declaration carries none (`payload-hash-required`), copies it
+ * onto `approval.requested` and then onto `approval.granted`, and
+ * `core/token.ts` refuses to spend a token against different bytes
+ * (`payload-mismatch`).
+ *
+ * ## Why JCS, and why not "just hash the string"
+ *
+ * §6.2 says "SHA-256 over the RFC 8785 canonical serialization of the action's
+ * concrete payload". Canonicalization is what makes the hash reproducible across
+ * two implementations that agree about the *payload* but not about key order,
+ * whitespace, or number formatting — which is exactly the situation an adapter
+ * written in another language is in. The same canonicalizer the log's hash chain
+ * uses (`core/jcs.ts`) is used here, so there is one serialization rule in this
+ * codebase and not two.
+ *
+ * ## The `approval run` payload
+ *
+ * §6.2 names it: "for `approval run`, the argv array and cwd". {@link
+ * runPayloadHash} is that definition made executable — the hash of
+ * `{"argv": [...], "cwd": "..."}` — and `approval run` computes it
+ * automatically from the command it is about to spawn. An adapter whose payload
+ * is something else (a message body and its recipients, a proposed record)
+ * hashes that with {@link payloadHash} and presents the result explicitly.
+ *
+ * The cwd is inside the hash on purpose: `rm -rf build` means two different
+ * things in two different directories, and a binding that ignored the working
+ * directory would approve one of them and execute the other.
+ *
+ * Pure: no I/O, no clock, no randomness.
+ */
+import { createHash } from "node:crypto";
+import { canonicalize } from "./jcs.js";
+/** The form a `payload_hash` takes everywhere: SHA-256, lowercase hex. */
+export const PAYLOAD_HASH_PATTERN = /^[a-f0-9]{64}$/u;
+/** Is this a well-formed `payload_hash`? The schema says the same thing. */
+export function isPayloadHash(value) {
+    return typeof value === "string" && PAYLOAD_HASH_PATTERN.test(value);
+}
+/**
+ * SHA-256 (lowercase hex) over the RFC 8785 canonical serialization of a
+ * payload — the definition amended SPEC.md §6.2 gives for `payload_hash`.
+ *
+ * Throws `JcsError` for a value RFC 8785 cannot serialize (a cycle, a NaN, a
+ * function). That is deliberate: a payload that cannot be canonicalized cannot
+ * be bound to, and returning a plausible-looking digest for it would be worse
+ * than failing.
+ */
+export function payloadHash(value) {
+    return createHash("sha256").update(canonicalize(value), "utf8").digest("hex");
+}
+/**
+ * The `payload_hash` of an `approval run` invocation: the argv array and cwd.
+ *
+ * `argv` is the child's argv as it will actually be spawned — the command name
+ * first, then its arguments — not the `approval` wrapper's own flags, which
+ * have no side effect to bind. `cwd` is the absolute directory the child will
+ * run in.
+ */
+export function runPayloadHash(argv, cwd) {
+    return payloadHash({ argv: [...argv], cwd });
+}
+//# sourceMappingURL=payload.js.map