approval-md 0.2.0 → 0.4.0

package/dist/src/core/read-scope.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Read scope: which directories an agent may read from (APRV-347).
+ *
+ * ## The hole this closes
+ *
+ * Writes and deletes have been path-scoped for a while. `files.delete.scratch`
+ * versus `files.delete.out_of_scope` is decided by comparing a resolved target
+ * against roots the caller supplied (`ClassifierContext.scratchRoots`), and the
+ * file tools carry their target into the payload a grant binds. Reads had none
+ * of that: every shell reader classified `read.shell` with no path bound, and
+ * `Read`, `Glob` and `Grep` were answered `allow` before classification ever
+ * ran. So a policy could say a great deal about what an agent may WRITE and
+ * nothing at all about what it may SEE, and an agent working in one directory
+ * could read every sibling of it.
+ *
+ * This module is the pure half of the read-side mirror. It holds the class
+ * name, the roots arithmetic, and the one genuinely fiddly question — which
+ * words of a read command are paths — and it touches no disk, reads no
+ * environment and resolves nothing. The impure half (relative paths resolved
+ * against a working directory, symlinks followed, the escape that only the
+ * filesystem can see) lives in `src/cli/hook.ts`, exactly where the delete
+ * rule's second pass lives, and it can only ever TIGHTEN this file's answer.
+ *
+ * ## Fail closed, in three places
+ *
+ * SPEC.md §11.1: ambiguity resolves to the stricter path. Here that is
+ *
+ * 1. a target this file cannot read as a path (a `$VAR`, a glob, a `~`) is out
+ *    of scope, because what it expands to is not in the text;
+ * 2. a read command naming NO target reads the working directory, so it is
+ *    checked against the working directory rather than waved through;
+ * 3. an empty root list means nothing is in scope — but a caller that passes no
+ *    roots at all gets today's answer instead (see {@link ClassifierContext}),
+ *    because a caller that forgot the field must not have every read it makes
+ *    turned into a decision.
+ *
+ * ## What a root is
+ *
+ * The gate root (the directory holding the policy file the runtime resolved),
+ * the session scratchpad, and the system temp root. A policy may WIDEN that
+ * with `read_scope.roots`; it may not narrow it below the gate root, because a
+ * runtime that cannot read its own policy, log and workspace cannot run at all.
+ */
+/**
+ * The class a read outside every root takes.
+ *
+ * A sibling of `read.shell` rather than a replacement for it: a read INSIDE the
+ * roots is the same ordinary, autonomous act it has always been, and a policy
+ * that says nothing about this class gets `defaults.autonomy` for it, which is
+ * the fail-closed direction for a name nobody has declared.
+ */
+export declare const READ_OUT_OF_SCOPE_CLASS = "read.file.out_of_scope";
+/**
+ * The `read_scope` block of a policy (SPEC.md §5, amended APRV-347).
+ *
+ * Additive and optional, with the same discipline `protected_paths` has: the
+ * built-in roots stand whatever this says, so a policy can widen the scope and
+ * never shrink it. A relative entry is resolved against the gate root, so a
+ * policy stays portable between a checkout and a clone of it.
+ */
+export interface ReadScope {
+    roots?: string[];
+}
+/**
+ * Is `candidate` AT or under `root`, by path segment?
+ *
+ * At-or-under rather than the delete rule's strictly-under: `ls <gate root>` is
+ * a read of the workspace an agent is working in, and a rule that made the root
+ * itself out of scope would classify the most ordinary command in the session.
+ *
+ * Segment matching, never string prefixes: `/dev/muse-other` must not match a
+ * root of `/dev/muse`, and `startsWith` says it does.
+ */
+export declare function isAtOrUnderReadRoot(candidate: string, root: string): boolean;
+/** Is this path inside ANY of these roots? */
+export declare function isInReadScope(candidate: string, roots: readonly string[]): boolean;
+/**
+ * A value whose expansion the classifier cannot see, and therefore may not
+ * vouch for. The same test the delete rule applies, and for the same reason:
+ * `cat $SOMEWHERE` reads whatever that variable holds.
+ */
+export declare function isUnreadableTarget(word: string): boolean;
+/**
+ * The effective read roots: the built-ins, plus whatever the policy added.
+ *
+ * Pure, and every input is the caller's. `gateRoot` is the directory holding
+ * the policy file the runtime resolved; `systemRoots` are the scratchpad and
+ * temp roots the caller already resolved (`resolveScratchRoots` in the hook);
+ * `declared` is `read_scope.roots` verbatim.
+ *
+ * A declared entry that is relative is joined onto the gate root. A declared
+ * entry the caller cannot vouch for — empty, or one this file can see is not a
+ * path at all — is DROPPED rather than accepted, because a root is an
+ * authorization and a malformed one must not become `/`.
+ *
+ * The result is de-duplicated and otherwise in the order given, so the first
+ * root a path matches is the most specific one a reader would expect.
+ */
+export declare function effectiveReadRoots(options: {
+    gateRoot: string;
+    declared?: readonly string[] | undefined;
+    systemRoots?: readonly string[] | undefined;
+}): string[];
+/**
+ * How a reader's positionals map to paths.
+ *
+ * - `all`: every positional is a file or directory (`cat a b`, `ls src`,
+ *   `diff a b`, `cut -d: -f1 /etc/passwd` — `cut`'s delimiter and field list
+ *   are flags, so none of its positionals is a pattern).
+ * - `after-pattern`: the FIRST positional is a pattern or a script and the rest
+ *   are paths (`grep needle src`, `sed -n 1,5p file`, `jq .x file.json`) —
+ *   UNLESS the pattern arrived through a flag (`-e`, `-f`), in which case every
+ *   positional is a path and the shape collapses to `all`.
+ * - `walk`: `find`'s shape — positionals up to the first primary are paths.
+ *
+ * Binaries absent from this table are absent on purpose, and each omission is a
+ * decision not to widen anything:
+ *
+ * - `echo`, `printf`, `tr`, `test`, `type`, `which`, `pwd`, `true`, `false`,
+ *   `cd`: their positionals are not files, or name a file without reading its
+ *   contents. A rule that treated `echo /etc/passwd` as a read of that file
+ *   would route text through a human.
+ * - `basename`, `dirname`, `readlink`, `realpath`: they manipulate or resolve a
+ *   path and never open it. What leaks is the existence of a name, which is not
+ *   what this class is about.
+ * - `less` and `more` are NOT added to the classifier's reader list by this
+ *   task. Adding them would take them from `unclassified` (a deny) to
+ *   `read.shell` (this repository's policy: autonomous), which is a widening,
+ *   and a task that exists to narrow reads has no business doing that in
+ *   passing. They are named in the follow-up in `docs/sandboxed-exec.md`.
+ *
+ * APRV-397 adds the packaging readers, so the reads the new classifier rows
+ * answer are scoped by the same arithmetic every other reader's are: `tar`,
+ * `gunzip` and `base64` are `all` (their operands are files, and a flag value
+ * that lands among the positionals resolves against the working directory,
+ * which costs nothing: see the note below), and `openssl` is `after-pattern`,
+ * because its first positional is the digest subcommand and the files follow it. Only
+ * the READ forms of those binaries ever reach this table: `tar -x`, a plain
+ * `gunzip` and `base64 -o` take write classes in the classifier, and this module
+ * scopes `read.shell` alone.
+ */
+export type ReadTargetShape = "all" | "after-pattern" | "walk";
+/** Which readers take paths, and where. Keyed by the binary's basename. */
+export declare const READ_TARGET_SHAPES: Readonly<Record<string, ReadTargetShape>>;
+/**
+ * The paths a read command will open, or `null` when this binary is not one
+ * whose reads this module scopes.
+ *
+ * An empty array is a real answer and is NOT the same as `null`: it means this
+ * reader opens the working directory (`ls`, `find`, `grep needle` with no file
+ * operand), and the caller checks the working directory in its place. `null`
+ * means "not a scoped reader", and the caller leaves the segment alone.
+ *
+ * Treating a non-path positional as a path costs nothing: a bare word resolves
+ * against the working directory, which is inside a root in every session this
+ * module is meant for. Treating a path as a non-path costs the whole property.
+ */
+export declare function readTargetsOf(bin: string, positionals: readonly string[], args?: readonly string[]): string[] | null;
+/**
+ * The verdict the PURE half can reach for one target.
+ *
+ * `out-of-scope` and `in-scope` are final. `needs-disk` is the honest answer
+ * for a relative path: its meaning depends on a working directory this file
+ * does not have, and the caller with the disk decides it. A caller that cannot
+ * do the second pass must treat `needs-disk` as out of scope — which is what
+ * `hook classify` and `hook <harness>` both do, through the same function.
+ */
+export type ReadTargetVerdict = "in-scope" | "out-of-scope" | "needs-disk";
+/**
+ * Read one target against the roots, as far as text alone can settle it.
+ *
+ * Absolute and inside a root: in scope. Absolute and outside every root: out of
+ * scope, decided here, no disk needed. Unreadable (a variable, a glob, a `~`):
+ * out of scope, because what it names is not in the text. Anything relative, or
+ * carrying a `..`, is `needs-disk`.
+ */
+export declare function readTargetVerdict(target: string, roots: readonly string[]): ReadTargetVerdict;
+/**
+ * The roots, rendered for a human: `approval policy check`'s line and the
+ * hook's verdict note say the same sentence.
+ */
+export declare function renderReadRoots(roots: readonly string[]): string;

package/dist/src/core/read-scope.js

@@ -0,0 +1,256 @@
+/**
+ * Read scope: which directories an agent may read from (APRV-347).
+ *
+ * ## The hole this closes
+ *
+ * Writes and deletes have been path-scoped for a while. `files.delete.scratch`
+ * versus `files.delete.out_of_scope` is decided by comparing a resolved target
+ * against roots the caller supplied (`ClassifierContext.scratchRoots`), and the
+ * file tools carry their target into the payload a grant binds. Reads had none
+ * of that: every shell reader classified `read.shell` with no path bound, and
+ * `Read`, `Glob` and `Grep` were answered `allow` before classification ever
+ * ran. So a policy could say a great deal about what an agent may WRITE and
+ * nothing at all about what it may SEE, and an agent working in one directory
+ * could read every sibling of it.
+ *
+ * This module is the pure half of the read-side mirror. It holds the class
+ * name, the roots arithmetic, and the one genuinely fiddly question — which
+ * words of a read command are paths — and it touches no disk, reads no
+ * environment and resolves nothing. The impure half (relative paths resolved
+ * against a working directory, symlinks followed, the escape that only the
+ * filesystem can see) lives in `src/cli/hook.ts`, exactly where the delete
+ * rule's second pass lives, and it can only ever TIGHTEN this file's answer.
+ *
+ * ## Fail closed, in three places
+ *
+ * SPEC.md §11.1: ambiguity resolves to the stricter path. Here that is
+ *
+ * 1. a target this file cannot read as a path (a `$VAR`, a glob, a `~`) is out
+ *    of scope, because what it expands to is not in the text;
+ * 2. a read command naming NO target reads the working directory, so it is
+ *    checked against the working directory rather than waved through;
+ * 3. an empty root list means nothing is in scope — but a caller that passes no
+ *    roots at all gets today's answer instead (see {@link ClassifierContext}),
+ *    because a caller that forgot the field must not have every read it makes
+ *    turned into a decision.
+ *
+ * ## What a root is
+ *
+ * The gate root (the directory holding the policy file the runtime resolved),
+ * the session scratchpad, and the system temp root. A policy may WIDEN that
+ * with `read_scope.roots`; it may not narrow it below the gate root, because a
+ * runtime that cannot read its own policy, log and workspace cannot run at all.
+ */
+/**
+ * The class a read outside every root takes.
+ *
+ * A sibling of `read.shell` rather than a replacement for it: a read INSIDE the
+ * roots is the same ordinary, autonomous act it has always been, and a policy
+ * that says nothing about this class gets `defaults.autonomy` for it, which is
+ * the fail-closed direction for a name nobody has declared.
+ */
+export const READ_OUT_OF_SCOPE_CLASS = "read.file.out_of_scope";
+/** Non-empty path segments, `.` dropped. Identical to the classifier's own. */
+function segmentsOf(candidate) {
+    return candidate
+        .split(/[/\\]+/u)
+        .filter((segment) => segment.length > 0 && segment !== ".");
+}
+/**
+ * Is `candidate` AT or under `root`, by path segment?
+ *
+ * At-or-under rather than the delete rule's strictly-under: `ls <gate root>` is
+ * a read of the workspace an agent is working in, and a rule that made the root
+ * itself out of scope would classify the most ordinary command in the session.
+ *
+ * Segment matching, never string prefixes: `/dev/muse-other` must not match a
+ * root of `/dev/muse`, and `startsWith` says it does.
+ */
+export function isAtOrUnderReadRoot(candidate, root) {
+    const want = segmentsOf(root);
+    const have = segmentsOf(candidate);
+    if (want.length === 0)
+        return false;
+    if (have.length < want.length)
+        return false;
+    return want.every((segment, index) => segment === have[index]);
+}
+/** Is this path inside ANY of these roots? */
+export function isInReadScope(candidate, roots) {
+    return roots.some((root) => isAtOrUnderReadRoot(candidate, root));
+}
+/**
+ * A value whose expansion the classifier cannot see, and therefore may not
+ * vouch for. The same test the delete rule applies, and for the same reason:
+ * `cat $SOMEWHERE` reads whatever that variable holds.
+ */
+export function isUnreadableTarget(word) {
+    return (word.includes("$") ||
+        word.includes("*") ||
+        word.includes("?") ||
+        word.includes("[") ||
+        word.startsWith("~"));
+}
+/**
+ * The effective read roots: the built-ins, plus whatever the policy added.
+ *
+ * Pure, and every input is the caller's. `gateRoot` is the directory holding
+ * the policy file the runtime resolved; `systemRoots` are the scratchpad and
+ * temp roots the caller already resolved (`resolveScratchRoots` in the hook);
+ * `declared` is `read_scope.roots` verbatim.
+ *
+ * A declared entry that is relative is joined onto the gate root. A declared
+ * entry the caller cannot vouch for — empty, or one this file can see is not a
+ * path at all — is DROPPED rather than accepted, because a root is an
+ * authorization and a malformed one must not become `/`.
+ *
+ * The result is de-duplicated and otherwise in the order given, so the first
+ * root a path matches is the most specific one a reader would expect.
+ */
+export function effectiveReadRoots(options) {
+    const roots = [];
+    const add = (candidate) => {
+        if (candidate.length === 0)
+            return;
+        if (!roots.includes(candidate))
+            roots.push(candidate);
+    };
+    add(options.gateRoot);
+    for (const root of options.systemRoots ?? [])
+        add(root);
+    for (const entry of options.declared ?? []) {
+        if (typeof entry !== "string" || entry.length === 0)
+            continue;
+        if (isUnreadableTarget(entry))
+            continue;
+        add(entry.startsWith("/") ? entry : `${options.gateRoot}/${entry}`);
+    }
+    return roots;
+}
+/** Which readers take paths, and where. Keyed by the binary's basename. */
+export const READ_TARGET_SHAPES = {
+    base64: "all",
+    cat: "all",
+    cksum: "all",
+    cut: "all",
+    diff: "all",
+    du: "all",
+    file: "all",
+    find: "walk",
+    grep: "after-pattern",
+    gunzip: "all",
+    head: "all",
+    jq: "after-pattern",
+    ls: "all",
+    md5sum: "all",
+    openssl: "after-pattern",
+    rg: "after-pattern",
+    sed: "after-pattern",
+    sha256sum: "all",
+    shasum: "all",
+    sort: "all",
+    stat: "all",
+    tail: "all",
+    tar: "all",
+    tree: "all",
+    uniq: "all",
+    wc: "all",
+};
+/**
+ * `find` primaries: the first word starting with `-` ends the path list.
+ *
+ * `find` is the one reader whose arguments are a little language, and its shape
+ * is `find [paths…] [expression]`. This one reads the RAW argument list rather
+ * than the flag-filtered positionals, because the filter is what tells the
+ * paths from the expression: in `find . -name '*.ts'` the pattern `*.ts` is a
+ * positional too, and a rule fed the filtered list would read it as a path,
+ * find it unreadable, and call an ordinary walk of the workspace out of scope.
+ */
+function walkTargets(args) {
+    const targets = [];
+    for (const word of args) {
+        if (word.startsWith("-"))
+            break;
+        targets.push(word);
+    }
+    return targets;
+}
+/**
+ * Flags that carry the pattern or the script, so every positional is a path.
+ *
+ * `grep -e needle src`, `sed -f script.sed file`, `rg --regexp needle dir`: the
+ * first positional is the FILE, and a rule that skipped it would leave the one
+ * target that matters unchecked. Under-detection is the failure mode that
+ * matters here — an unchecked read is a read outside the jail — so the shape
+ * widens to `all` whenever one of these appears.
+ */
+const PATTERN_BEARING_FLAGS = [
+    "-e",
+    "-f",
+    "--regexp",
+    "--expression",
+    "--file",
+];
+/** Did the pattern (or script) arrive through a flag rather than a positional? */
+function patternCameFromFlag(args) {
+    return args.some((arg) => PATTERN_BEARING_FLAGS.includes(arg) ||
+        PATTERN_BEARING_FLAGS.some((flag) => flag.startsWith("--") && arg.startsWith(`${flag}=`)));
+}
+/**
+ * The paths a read command will open, or `null` when this binary is not one
+ * whose reads this module scopes.
+ *
+ * An empty array is a real answer and is NOT the same as `null`: it means this
+ * reader opens the working directory (`ls`, `find`, `grep needle` with no file
+ * operand), and the caller checks the working directory in its place. `null`
+ * means "not a scoped reader", and the caller leaves the segment alone.
+ *
+ * Treating a non-path positional as a path costs nothing: a bare word resolves
+ * against the working directory, which is inside a root in every session this
+ * module is meant for. Treating a path as a non-path costs the whole property.
+ */
+export function readTargetsOf(bin, positionals, args = []) {
+    const shape = READ_TARGET_SHAPES[basenameOf(bin)];
+    if (shape === undefined)
+        return null;
+    switch (shape) {
+        case "all":
+            return [...positionals];
+        case "after-pattern":
+            return patternCameFromFlag(args) ? [...positionals] : positionals.slice(1);
+        case "walk":
+            return walkTargets(args.length === 0 ? positionals : args);
+    }
+}
+/** The last segment of a command word, so `/usr/bin/cat` reads as `cat`. */
+function basenameOf(bin) {
+    const segments = segmentsOf(bin);
+    return segments[segments.length - 1] ?? bin;
+}
+/**
+ * Read one target against the roots, as far as text alone can settle it.
+ *
+ * Absolute and inside a root: in scope. Absolute and outside every root: out of
+ * scope, decided here, no disk needed. Unreadable (a variable, a glob, a `~`):
+ * out of scope, because what it names is not in the text. Anything relative, or
+ * carrying a `..`, is `needs-disk`.
+ */
+export function readTargetVerdict(target, roots) {
+    if (target.length === 0)
+        return "needs-disk";
+    if (isUnreadableTarget(target))
+        return "out-of-scope";
+    if (!target.startsWith("/"))
+        return "needs-disk";
+    if (segmentsOf(target).includes(".."))
+        return "needs-disk";
+    return isInReadScope(target, roots) ? "in-scope" : "out-of-scope";
+}
+/**
+ * The roots, rendered for a human: `approval policy check`'s line and the
+ * hook's verdict note say the same sentence.
+ */
+export function renderReadRoots(roots) {
+    return roots.length === 0 ? "(none)" : roots.join(", ");
+}
+//# sourceMappingURL=read-scope.js.map

package/dist/src/core/read-scope.js.map

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

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

@@ -0,0 +1,160 @@
+/**
+ * The `approval run` payload: the argv, the cwd, and the bytes of the script
+ * the argv names (SPEC.md §6.2, §10.4; APRV-401).
+ *
+ * ## The hazard this closes
+ *
+ * §6.2 defined this payload as "the argv array and cwd", and `approval run`
+ * recomputes it from the argv and cwd it is about to spawn. For a command that
+ * IS its own bytes (`npm update @types/node`) that is the whole action. For a
+ * command that names a script it is not: the payload binds a NAME, and the
+ * bytes behind that name are whatever the path holds at execution time. The
+ * requester controls the file between the request and the grant, so a human
+ * approved a path and the runtime executed a file. Found on a live grant during
+ * APRV-398, exploited by nobody, filed as APRV-401.
+ *
+ * The payload hash is supposed to BE the binding (§10.4: "A grant therefore
+ * approves specific bytes"), so the repair is to put the bytes inside it. A
+ * script edited between the declaration and the execution hashes differently,
+ * and the difference refuses `payload-mismatch` before the child is spawned and
+ * before anything is appended, exactly as a changed argv already did.
+ *
+ * ## The shape, as the operator ruled it (APRV-401 notes, 2026-09-21)
+ *
+ * > the script digest is PART OF THE BINDING, never advisory. Shape: when argv
+ * > names an interpreter (bash, sh, zsh, node, python3 and kin) followed by a
+ * > path that resolves to a regular file at request time, the runtime reads and
+ * > hashes the file into the bound payload, the card shows the digest, byte
+ * > count and path, and approval run re-reads the file and refuses
+ * > payload-mismatch if the bytes changed. No interpretation of the script and
+ * > no second pass for files it sources; the limit is documented. Out of scope:
+ * > piped installers (already opaque), sourced files, interpreters the
+ * > classifier does not name.
+ *
+ * So this is an INTERPRETER-KEYED rule and not "every argv word that happens to
+ * name a file". One script per invocation: the first word after the interpreter
+ * that resolves to a readable regular file, which is the interpreter's operand
+ * whether or not a subcommand comes first (`deno run job.ts`).
+ * {@link SCRIPT_INTERPRETERS} is the list, and every member of it is a name
+ * `core/command-class.ts` already knows: the six shells of its unwrappable set,
+ * `node` from its own branch, and `python`, `python3`, `perl`, `ruby` and
+ * `deno` from its inline-source table. A launcher neither file names binds
+ * nothing, which is the documented limit rather than an oversight.
+ *
+ * The one thing here that the ruling does not spell out is the DEGENERATE case:
+ * `./install.sh` with no interpreter word at all, where the kernel reads the
+ * shebang and the script is `argv[0]` itself. It is bound, because it is the
+ * same fact with the interpreter implied rather than typed, and leaving it out
+ * would be a hole in the rule shaped exactly like the rule.
+ *
+ * ## What is NOT bound, stated plainly
+ *
+ * - **An inline program.** `bash -c '…'`, `node -e '…'`, `python3 -c '…'`: the
+ *   program is a word of the argv, so it was always bound, and there is no file
+ *   to read. The inline flags per interpreter are in {@link SCRIPT_INTERPRETERS}.
+ * - **Nothing resolved through PATH.** The interpreter itself is not hashed. Its
+ *   bytes are the host's rather than the requester's, and resolving a program
+ *   name through `PATH` would make the payload a function of the environment the
+ *   process happens to hold, which §11 says is never read implicitly.
+ * - **Nothing transitive.** A bound script that sources another file, curls a
+ *   second one, or execs a third binds only its own bytes. The digest is a
+ *   binding, not a sandbox.
+ * - **A piped installer.** `curl … | sh` has no file operand and is opaque to
+ *   the classifier for the same reason it is unbindable here.
+ * - **The instant between hashing and spawning.** The digest is taken, then
+ *   `execution.started` is appended, then the child is spawned. A file rewritten
+ *   inside that window runs unbound. Closing it needs the executor to hold the
+ *   bytes rather than the path, which is the adapter contract of §10.4.
+ *
+ * ## Absence is not a claim
+ *
+ * `script` is omitted when nothing is bound, and that omission is deliberate: an
+ * invocation naming no readable script hashes to exactly the value it hashed
+ * before this module existed, so every record already in the log, and every
+ * declaration already written into a task file, verifies unchanged. What the
+ * absence does NOT say is "this runtime checked and there was nothing" — it is
+ * the ordinary shape of a payload with no script to bind, and a reader wanting
+ * to know whether a digest was possible reads the argv, which is right there.
+ *
+ * Every skip is safe for one reason, and it is the same reason in each case: the
+ * value is recomputed at execution by this same rule. A file that was
+ * unreadable at declaration time and readable at execution time gains an entry
+ * and refuses; one that existed and was deleted loses one and refuses. The rule
+ * does not have to decide correctly what a command will do, because both ends
+ * apply it to the same tree and any disagreement is a refusal.
+ *
+ * Reads the filesystem, by design and by necessity: at most one file per call,
+ * and only the one the argv names. Writes nothing, appends nothing, reads no
+ * log, no policy, no environment and no clock.
+ */
+/** The payload key carrying the bound script. Omitted when there is none. */
+export declare const BOUND_SCRIPT_KEY = "script";
+/**
+ * How much of a file is read at once while digesting it.
+ *
+ * Chunked rather than `readFileSync`, because a script may be of any size and
+ * the executor must not be the thing that runs out of memory: a refusal to
+ * compute the binding is a refusal to execute.
+ */
+export declare const DIGEST_CHUNK_BYTES: number;
+/**
+ * The interpreters whose script operand is bound, and the flags that mean
+ * "the program is inline, there is no file".
+ *
+ * Every name here is one `core/command-class.ts` already knows, which is the
+ * ruling's "interpreters the classifier does not name" read as a positive list:
+ * the six shells of its unwrappable set, `node` from its own classification
+ * branch, and `python`, `python3`, `perl`, `ruby`, `deno` from its
+ * inline-source table. The list is duplicated rather than imported because
+ * those tables are private to that module and a public export of them would be
+ * a second consumer of a decision that belongs to classification; the comment
+ * is the seam, and a name added there without being added here binds nothing,
+ * which fails toward the old behaviour rather than toward a wrong digest.
+ *
+ * The shell inline flag is `-c` with any run of `l` and `i` before it, which is
+ * `INLINE_SCRIPT_FLAG` in that module, spelled here as the same regular
+ * expression for the same reason.
+ */
+export declare const SCRIPT_INTERPRETERS: ReadonlyMap<string, readonly (string | RegExp)[]>;
+/** One script the argv names, bound by its bytes. */
+export interface BoundScript {
+    /** Which argv word named it. */
+    argv_index: number;
+    /** The path as resolved against the payload's `cwd`: absolute, always. */
+    path: string;
+    /** The file's size in bytes, which the approver's card shows beside the digest. */
+    bytes: number;
+    /** SHA-256 (lowercase hex) of the file's bytes. */
+    sha256: string;
+}
+/** The `approval run` payload value, canonicalized and hashed by the caller. */
+export interface RunPayload {
+    argv: string[];
+    cwd: string;
+    /** Present only when the argv named a readable script. */
+    script?: BoundScript;
+}
+/**
+ * The script this argv runs, bound by its bytes, or `null` (APRV-401).
+ *
+ * Two shapes, and only two: an interpreter this module names followed by a path
+ * operand, and a path at `argv[0]` that the kernel will read a shebang from.
+ * Anything else binds nothing and the payload is what it always was.
+ */
+export declare function boundScript(argv: readonly string[], cwd: string): BoundScript | null;
+/**
+ * The value `approval run`'s `payload_hash` is taken over (SPEC.md §6.2).
+ *
+ * `{argv, cwd}` when the argv names no readable script, byte for byte what it
+ * has always been; `{argv, cwd, script}` when it does. The caller canonicalizes
+ * and hashes it — this function decides WHAT is bound and never how it is
+ * digested into an approval.
+ */
+export declare function runPayloadValue(argv: readonly string[], cwd: string): RunPayload;
+/**
+ * One line naming the bound script, for a refusal message or a terminal.
+ *
+ * Not a rendering an approver signs: the canonical renderer owns that, and this
+ * is the executor explaining to an agent WHICH file moved.
+ */
+export declare function describeBoundScript(script: BoundScript | null): string;