approval-md 0.1.0 → 0.2.0

package/dist/src/core/decision-refusal.d.ts

@@ -0,0 +1,185 @@
+/**
+ * What the log says when a human decided and the gate could not take it
+ * (APRV-235, amended SPEC.md §5.2).
+ *
+ * ## The fact this module is about
+ *
+ * Seen live on 2026-09-02, after the seq 13704 ceremony. Carter tapped approve
+ * on a request that had been asked under the previous policy. The gate refused
+ * `policy-drift`, which is right: the rules the approver was shown are not the
+ * rules in force, so a grant recorded there would claim a decision under a
+ * policy nobody put in front of them. But the refusal went to the operator's
+ * terminal and nowhere else. Nothing was appended, the request stayed pending
+ * in `QUEUE.md` and on Telegram, and the person who had tapped saw no reaction
+ * at all.
+ *
+ * Three things were wrong and this module fixes two of them (the third, the
+ * message edit, belongs to the channels).
+ *
+ * ## 1. A human's decision is a fact even when the gate cannot honour it
+ *
+ * The log is the truth. SPEC.md §11 makes human attention the audit budget, and
+ * an approver's tap SPENDS it whether or not an authorization comes out the
+ * other end. A reader looking at that log later found a request sitting
+ * unanswered with nothing to say a person had answered it, which is a question
+ * the log is supposed to be able to settle.
+ *
+ * So {@link recordRefusedDecision} appends one `audit.decision_refused`. It is
+ * an **audit-tier** record in the strict sense:
+ *
+ * - it grants nothing and mints no token;
+ * - `core/state.ts` does not settle a request on it, so no verdict moves;
+ * - `core/budgets.ts` charges nothing for it, so no budget moves;
+ * - `core/audit.ts` does not sample it and no streak counts it.
+ *
+ * `tests/decision-refusal.test.ts` asserts that last group by construction: the
+ * derived request state, the budget verdicts and the sampling draw are taken
+ * before and after and compared, and they are identical.
+ *
+ * ## The asymmetry: humans yes, agents no
+ *
+ * Gate-side refusals handed to an AGENT stay unlogged, and that is a choice
+ * rather than an omission. An agent that is refused reads the code, stops or
+ * asks again, and nothing was spent that a record could account for. A human
+ * who is refused has already spent the scarce thing, and cannot be asked to
+ * spend it again without the log saying the first spend happened. Recording
+ * every agent-side refusal would also put the busiest path in the runtime — a
+ * hook classifying every shell command — into the append path, which is a cost
+ * with no reader.
+ *
+ * ## 2. A request the gate calls void must stop being offered
+ *
+ * `policy-drift` is the one refusal where the gate does not merely decline this
+ * decision, it declares the REQUEST dead: "the pending request is void and the
+ * action must be requested again". Leaving it pending afterwards offers every
+ * approver on every channel a tap that cannot be honoured, forever, until the
+ * TTL lapses. So a drift refusal also appends `approval.withdrawn` with the
+ * runtime's own reason, `policy-drift` (APRV-106 gave the event; the schema's
+ * cross-rule makes that reason `system:`-only and `system:` that-reason-only).
+ * `approval queue`, `QUEUE.md` and every channel then read the request as
+ * settled, because they all derive state from `core/state.ts` and it settles on
+ * `approval.withdrawn` without looking at who wrote it or why.
+ *
+ * The action is not stranded: its caller requests it again, and the new request
+ * is routed, budgeted and displayed under the policy actually in force. That is
+ * what the refusal message already told them to do.
+ *
+ * ## Order, and what an interrupted write leaves behind
+ *
+ * The audit record is appended first and the withdrawal second, naming it in
+ * `payload.refused_seq`. Two appends are two records — the log never batches —
+ * so a crash between them is a state this code can reach, and the order is
+ * chosen for which half is safe to have alone. The explanation without the
+ * withdrawal leaves the request pending exactly as it is today, and a reader can
+ * see why. The withdrawal without the explanation would take a request out of a
+ * human's queue with nothing on the record saying who tapped, or why it was
+ * refused, which is the failure this task exists to end.
+ *
+ * ## Invariants
+ *
+ * - **Gate-typed events never accept caller timestamps** (§11.1). `ts` comes
+ *   from the injected clock at the write boundary; there is no parameter.
+ * - **Every check-then-append passes through compare-and-append** (§11.1(5)).
+ *   Both writes state the head they were derived against, and the whole cycle
+ *   re-enters from a fresh read on `head-moved` through
+ *   {@link withHeadRetry} — the same bounded retry APRV-236 gave `decide`.
+ * - **Self-reported fields never reduce scrutiny** (§11.1). Everything here only
+ *   ADDS to what a reviewer sees. The approver's identity comes from the
+ *   decision surface's configured actor, the same source a grant's does, and the
+ *   record's own actor is `system:` so that neither party to the refusal is its
+ *   author.
+ * - **Refusals stay machine-readable and distinct** (§11.1). The gate's code is
+ *   copied verbatim; nothing here invents, merges or softens one.
+ *
+ * ## No attestation check, deliberately
+ *
+ * Nothing here asks whether the policy is attested, for the reason `reject` and
+ * `revoke` do not: this write confers no authority. Refusing to record a refusal
+ * because a file changed would be the strict direction pointing the wrong way,
+ * and the case where it would bite hardest is `policy-not-attested` itself —
+ * exactly the refusal an operator most needs the log to remember. The write
+ * boundary still validates every record, so what lands is still constrained.
+ */
+import { type AppendError, type EventRecord } from "./log.js";
+import { type Decision } from "./state.js";
+import type { GateOptions } from "./gate.js";
+/**
+ * The actor every record here carries. `system:`, and the same id the runtime's
+ * other unprompted writes use: this is the gate stating what the gate did.
+ */
+export declare const DECISION_REFUSAL_ACTOR = "system:gate";
+/** The runtime's withdrawal reason, closed to requesters by the event schema. */
+export declare const POLICY_DRIFT_REASON = "policy-drift";
+/** Who decided what, on which surface — everything the record needs about the tap. */
+export interface RefusedDecision {
+    /** The action whose decision was refused. */
+    actionKey: string;
+    /** Which of the three human-only verbs was attempted. */
+    decision: Decision;
+    /** The approver, `human:<id>`, from the surface's configured identity. */
+    actor: string;
+    /** The surface that collected the gesture: `telegram`, `web`, `cli`. */
+    channel: string;
+}
+/** The gate refusal being recorded. Only these fields are ever read. */
+export interface RefusalFacts {
+    /** The gate's code, verbatim. */
+    code: string;
+    /** The gate's message, verbatim. */
+    message: string;
+    /**
+     * The two policy hashes the gate compared, on `policy-drift` alone. Supplied
+     * by the refusal that made the comparison rather than re-derived here: a
+     * second derivation could disagree with the one that actually refused, and
+     * then the record would describe a comparison nobody made.
+     */
+    drift?: {
+        requested: string;
+        attested: string;
+    };
+}
+/** What the module could not do. Never thrown; the caller carries on regardless. */
+export interface RefusalRecordFailure {
+    ok: false;
+    code: "log-unreadable" | "append-failed";
+    message: string;
+    append?: AppendError;
+}
+export type RecordRefusedDecisionResult = {
+    ok: true;
+    /**
+     * The `audit.decision_refused` record, or `null` when the refused actor
+     * was not a person and there was therefore nothing to record.
+     */
+    audit: EventRecord | null;
+    /** The `approval.withdrawn` record, on `policy-drift` alone; `null` otherwise. */
+    withdrawn: EventRecord | null;
+} | RefusalRecordFailure;
+/** Is this the refusal that declares the request itself void? */
+export declare function voidsTheRequest(code: string): boolean;
+/**
+ * Record that a human's decision was refused, and withdraw the request when the
+ * refusal was the gate declaring it void.
+ *
+ * Called by the decision SURFACES — `channels/contract.ts`'s
+ * `recordChannelDecision` and `cli/gate.ts`'s `commandDecide` — and never from
+ * inside `decide()`. That placement is deliberate twice over. `decide()`'s
+ * contract is that a refusal appends nothing, which is what lets a caller retry
+ * one without wondering what it wrote; and this record is about a HUMAN having
+ * decided, which is a fact only a surface that collected a human's gesture can
+ * assert.
+ *
+ * Best-effort by design: a failure here is returned, never thrown, and the
+ * caller shows the gate's refusal either way. The decision was already refused
+ * before this ran, and nothing about that outcome depends on this write landing.
+ *
+ * **Two writes, two retry cycles, and deliberately not one.** `head-retry.ts`
+ * asks that the unit of retry be a whole read-check-append cycle, and putting
+ * both appends inside one cycle would break that in the direction that matters:
+ * a moved head under the SECOND write would re-enter from the top and append a
+ * second `audit.decision_refused` for one tap. So each write has its own cycle,
+ * each re-reads and re-derives, and the withdrawal's cycle re-checks that the
+ * request is still pending — a decision or a withdrawal that landed in the
+ * window is the new verdict, and there is then nothing left to withdraw.
+ */
+export declare function recordRefusedDecision(logPath: string, decided: RefusedDecision, refusal: RefusalFacts, options?: GateOptions): RecordRefusedDecisionResult;

package/dist/src/core/env-file.d.ts

@@ -0,0 +1,450 @@
+/**
+ * `.approval/env` — the environment SOURCE MAP (SPEC.md §5.2, §11; APRV-73).
+ *
+ * Every secret this runtime touches is named by the policy and held in an
+ * environment variable: `channels.telegram.token_env` (§5.1), the chat id
+ * beside it, `audit.sampling_secret_env` (§5.2), `vault.passphrase_env` (§5.2),
+ * and `APPROVAL_HUMAN`, which is human identity itself (§11). The policy carries
+ * NAMES and never values, which is the right boundary and leaves an operator
+ * with five variables to get into a shell before any gate operation works, and
+ * no written-down place to say where they come from.
+ *
+ * This module is that written-down place. `.approval/env` is a source map, not
+ * a secret store: `KEY=VALUE` lines whose VALUE says WHERE the value lives.
+ *
+ * ```
+ * # one line per variable; # comments and blank lines are ignored
+ * APPROVAL_HUMAN=human:alice
+ * APPROVAL_TG_TOKEN=keychain:approval-telegram-token
+ * APPROVAL_VAULT_PASSPHRASE=secret-service:vault-passphrase
+ * APPROVAL_AUDIT_SECRET=env:
+ * ```
+ *
+ * Four value forms, and one of them is deliberately unpleasant:
+ *
+ * - `keychain:<service>` — macOS, `security find-generic-password -a "$USER"
+ *   -s <service> -w`. The value comes back on stdout and is never in an argv.
+ * - `secret-service:<label>` — Linux desktop, `secret-tool lookup approval
+ *   <label>`. Same property.
+ * - `env:` — inherited from the ambient environment. A documentation form: it
+ *   asserts "this one comes from the shell that launched you", and resolves to
+ *   nothing on its own.
+ * - a bare literal — permitted, and ALWAYS reported as plaintext. A rule people
+ *   route around is not a control: an operator who is told plainly that their
+ *   token is sitting in a file in the working tree can decide to accept that,
+ *   and an operator who is forbidden from writing it there writes it into their
+ *   shell profile instead, where nothing in this runtime can see it to say so.
+ *
+ * A value carrying some OTHER `word:` prefix is a literal, not an error, because
+ * `APPROVAL_HUMAN=human:alice` is the commonest line this file will ever hold.
+ * Near misses of the real schemes are reserved by name and refused rather than
+ * silently exported as text; see {@link RESERVED_SCHEMES}.
+ *
+ * ## THE LOAD-BEARING RULE: nothing loads this file implicitly
+ *
+ * No verb in this runtime reads `.approval/env` into its own environment. One
+ * verb, `approval env`, resolves it and prints an export block for a shell to
+ * evaluate; every other command sees only the environment the human who
+ * launched it had already established.
+ *
+ * The reason is `APPROVAL_HUMAN`. SPEC.md §11 states that human identity in v0.1
+ * is config-declared and that "the trust boundary is the local machine, and
+ * anyone who can set that configuration and write to the log is inside it". A
+ * working-tree file that could set `APPROVAL_HUMAN` would move that boundary to
+ * "anyone who can write a file in the repository": an agent that can edit source
+ * — which every agent working in a repository can — would thereby be able to
+ * attest a policy, grant its own request, and set a vault credential, on every
+ * invocation, as the human. The whole human-only gate would be one `echo >>`
+ * away from being nobody's gate.
+ *
+ * So the file is inert. A human evaluates `approval env` in their own shell,
+ * sees the export block that is about to run (or checks it value-free first with
+ * `--check`), and the process that performs a gate operation inherits an
+ * environment a human established. This is SPEC.md §11.1 invariant 7, and
+ * `tests/cli-env.test.ts` pins it by spawning `doctor`, `policy attest` and
+ * `channel telegram health` in a directory holding a complete `.approval/env`
+ * and asserting that none of them saw a byte of it.
+ *
+ * ## Mode 0600
+ *
+ * A file that may hold a literal secret is refused unless its mode is exactly
+ * `0600`, and the refusal prints the `chmod`. This is a lock on a door whose
+ * wall is missing (the same session can chmod it back), and it is worth having
+ * for the reason `umask` is worth having: the common failure is a
+ * world-readable file nobody looked at, not an adversary in the room.
+ *
+ * ## Determinism, and the one place it stops
+ *
+ * Parsing is a pure function of the bytes. Resolution is not: it shells out to
+ * helper binaries, which is why {@link SourceRunner} exists as an injectable
+ * seam and why the tests drive stub `security` / `secret-tool` scripts through
+ * PATH rather than touching a real Keychain.
+ *
+ * Nothing here throws. Every failure is a `{ ok: false, code, message }` from
+ * the frozen union {@link ENV_FILE_REFUSAL_CODES}. No credential VALUE appears
+ * in a refusal, a message, or a `source` label on any path.
+ */
+import type { PolicyLoadResult } from "./policy-load.js";
+/** The source map's filename, beside the log's home: `.approval/env`. */
+export declare const ENV_FILENAME = "env";
+/**
+ * The env file for a given log path — derived exactly as `vaultPathFor` derives
+ * the vault, so the log, the payload store, the vault and this file stay under
+ * one home: SPEC.md §9 fixes the log at `<home>/log/events.jsonl`, so the source
+ * map is `<home>/env`, a sibling of the log DIRECTORY and never inside it.
+ */
+export declare function envFilePathFor(logPath: string): string;
+/** The mode the file must have. Anything else is refused. */
+export declare const ENV_FILE_REQUIRED_MODE = 384;
+/**
+ * Everything this module can refuse. Frozen public API, per SPEC.md §11.1(6).
+ *
+ * Each code names a different repair, which is the test of whether a code earns
+ * its place. The three helper codes are separate for exactly that reason: "you
+ * are on a machine without `secret-tool`", "the item is not in your keychain",
+ * and "the helper ran and failed" are three different mornings.
+ */
+export declare const ENV_FILE_REFUSAL_CODES: readonly [
+/** The file's mode is not 0600. The refusal carries the `chmod` to run. */
+"env-file-mode", 
+/**
+ * The file exists and could not be read, stat'd, or (APRV-74) written. A
+ * filesystem fact in every case, with a filesystem repair, which is why the
+ * write path reuses this code rather than adding a fourth I/O name to a
+ * frozen union: "the directory is read-only" and "the file is unreadable"
+ * are the same morning and the same exit code.
+ */
+"env-file-io", 
+/** A line is neither blank, nor a comment, nor `KEY=VALUE`. */
+"env-file-syntax", 
+/** A KEY does not match `[A-Z_][A-Z0-9_]*`. No `export ` prefix is accepted. */
+"env-file-key-invalid", 
+/** The same KEY appears twice. Which one wins is not a thing to guess at. */
+"env-file-duplicate-key", 
+/** A VALUE carries a `scheme:` prefix this build does not implement. */
+"env-file-unknown-scheme", 
+/** A KEY with an empty VALUE. An empty secret is a configuration error. */
+"env-file-empty-value", 
+/** The helper binary for a scheme is not on PATH. Not the operator's fault. */
+"helper-binary-missing", 
+/** The helper ran and the named item is not there. Store it, or fix the name. */
+"helper-item-missing", 
+/** The helper ran and failed for some other reason (locked keyring, …). */
+"helper-failed", 
+/**
+ * A policy declared an `_env` NAME that is not a usable shell variable name.
+ * Never emitted as an `export` line: the export block is evaluated by a shell,
+ * and a name carrying a space or a `;` would be a policy file executing code.
+ */
+"invalid-variable-name"];
+export type EnvFileRefusalCode = (typeof ENV_FILE_REFUSAL_CODES)[number];
+/** A whole-file failure. Nothing here throws. */
+export interface EnvFileRefusal {
+    ok: false;
+    code: EnvFileRefusalCode;
+    message: string;
+    /** The file the refusal is about. */
+    path: string;
+    /** 1-based line number, for the parse refusals that have one. */
+    line?: number;
+}
+/** The four value forms. `literal` is the fallback and the explicit escape. */
+export type EnvSourceKind = "keychain" | "secret-service" | "env" | "literal";
+/** One `KEY=VALUE` line, parsed. */
+export interface EnvFileEntry {
+    key: string;
+    kind: EnvSourceKind;
+    /**
+     * The service name, the label, or the literal value. Empty for `env:`.
+     *
+     * For `literal` this IS the secret, so it is never put in a message, a
+     * `source` label, or a refusal by anything in this module.
+     */
+    argument: string;
+    /** 1-based line number, so a diagnostic can point at the line. */
+    line: number;
+}
+/**
+ * Parse the file's text. No interpolation, no quote stripping, no `export `
+ * prefix, no line continuations: this is a source map, not a shell script, and
+ * every one of those features is a way for a file to mean something other than
+ * what it looks like.
+ *
+ * Quotes are NOT stripped, which is worth saying out loud because `.env` files
+ * elsewhere do strip them: here `A="b"` is the five-character literal `"b"`.
+ */
+export declare function parseEnvFile(text: string, path: string): {
+    ok: true;
+    entries: EnvFileEntry[];
+} | EnvFileRefusal;
+/**
+ * The digest of an env file's bytes, as read.
+ *
+ * Not a secret and not derived from one in the sense that matters: the file may
+ * carry a plaintext literal, so this is a hash and never the text, and it is
+ * one-way. Its only consumer is `core/instance.ts`, which uses it to ask "was
+ * this exported value produced from the file as it now reads?" — a question
+ * about VERSIONS of a file, which needs an identifier for a version and nothing
+ * else (APRV-278).
+ */
+export declare function envFileDigest(text: string): string;
+/** An absent file's digest: the digest of the nothing that was read. */
+export declare const ABSENT_ENV_FILE_DIGEST: string;
+/** The file's contents, or the fact that there is no file. */
+export type EnvFileRead = {
+    ok: true;
+    present: false;
+    path: string;
+    entries: [];
+    digest: string;
+} | {
+    ok: true;
+    present: true;
+    path: string;
+    entries: EnvFileEntry[];
+    digest: string;
+} | EnvFileRefusal;
+/**
+ * Read and parse the source map.
+ *
+ * **An absent file is not an error.** Nobody has written one, which is the state
+ * of every working directory that keeps its variables in a shell profile, and it
+ * is the state `approval init` leaves behind. Every variable then falls to
+ * "inherited from the environment" or "unset", which is exactly the world
+ * before this file existed.
+ */
+export declare function readEnvFile(path: string): EnvFileRead;
+/** What one upserted KEY did to the file. */
+export interface EnvFileChange {
+    key: string;
+    /** The line as it will now read: `KEY=VALUE`. Never a secret — see below. */
+    value: string;
+    /**
+     * The VALUE that was on the line before, or `null` when the key was added.
+     *
+     * This CAN be a plaintext secret, if the operator had written one as a bare
+     * literal, so it exists for a caller that needs to decide whether it is
+     * REPLACING something, and no caller in this repository prints it. The
+     * boolean below is what the CLI reports on.
+     */
+    previous: string | null;
+    /** The value is unchanged: the line already said exactly this. */
+    unchanged: boolean;
+}
+/** A successful write. */
+export interface EnvFileWrite {
+    ok: true;
+    path: string;
+    /** The file did not exist and was created at 0600. */
+    created: boolean;
+    changes: EnvFileChange[];
+}
+/**
+ * Add or replace `KEY=VALUE` lines, preserving everything else in the file.
+ *
+ * **Line-oriented, not a rewrite.** The file is read as text, the line whose
+ * KEY matches is replaced IN PLACE, and a key that is not present is appended
+ * at the end. Comments, blank lines, ordering, and every entry this call was
+ * not asked about survive byte for byte. A writer that reparsed and re-emitted
+ * would be simpler and would quietly delete the operator's own comments the
+ * first time `approval setup channel telegram` ran — this file is one a human edits by
+ * hand, and round-trip fidelity for a hand-edited file is the same requirement
+ * the Backlog.md task files carry.
+ *
+ * The file is validated before it is touched: {@link readEnvFile}'s mode check
+ * and full parse both run, so `setup` never appends a line to a file it could
+ * not have read, and never lands a valid line in a file whose earlier line is a
+ * syntax error. A file that does not exist is created at 0600, along with its
+ * directory.
+ *
+ * Callers pass values, and a value here is a SOURCE (`keychain:<service>`), a
+ * chat id, or an identity — never a credential, except on the one path where an
+ * operator explicitly chose a plaintext literal after being told what it means.
+ * Nothing in this function prints anything.
+ */
+export declare function upsertEnvFileEntries(path: string, entries: ReadonlyArray<{
+    key: string;
+    value: string;
+}>): EnvFileWrite | EnvFileRefusal;
+/** What a helper lookup produced. The value, or a distinct reason it did not. */
+export type SourceOutcome = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    code: "helper-binary-missing" | "helper-item-missing" | "helper-failed";
+    message: string;
+};
+/**
+ * The two helper lookups, injectable.
+ *
+ * A seam rather than a direct `spawnSync` because the alternative is a test
+ * suite that reads the machine's real Keychain, and there is no version of that
+ * which is acceptable: it would prompt, it would depend on the developer's own
+ * secrets, and on the wrong day it would print one. Tests pass a fake here, and
+ * the ONE test that exercises {@link defaultSourceRunner} does it by putting
+ * stub `security` / `secret-tool` scripts on the child process's PATH — a real
+ * PATH lookup of a real command name, with no test-only flag in the runtime.
+ */
+export interface SourceRunner {
+    keychain(service: string): SourceOutcome;
+    secretService(label: string): SourceOutcome;
+}
+/**
+ * `security find-generic-password -a "$USER" -s <service> -w` and
+ * `secret-tool lookup approval <label>`.
+ *
+ * THE VALUE IS NEVER IN AN ARGV, in either direction: the argv carries a service
+ * name or a label, and the secret comes back on stdout. An argv is world-readable
+ * in `ps` for the length of the call, which is the whole reason `approval vault
+ * set` has no `--value` flag either.
+ *
+ * The exit-status readings are documented heuristics, not contracts. `security`
+ * exits 44 (`errSecItemNotFound`) for a missing item; `secret-tool` exits 0 with
+ * empty output when the lookup matches nothing. Anything else is
+ * {@link "helper-failed"}, which is the honest answer for a locked keyring or a
+ * D-Bus that is not running: the repair is not "store the item".
+ */
+/**
+ * The prefix a deferred lookup carries. See {@link NON_RESOLVING_RUNNER}.
+ */
+export declare const KEYSTORE_DEFERRED = "not resolved by doctor";
+/**
+ * A {@link SourceRunner} that looks nothing up (moved here by APRV-178).
+ *
+ * `security find-generic-password -w` can raise a keychain-unlock or ACL dialog
+ * and `secret-tool lookup` can block on a keyring prompt. Either would hang a
+ * command run over ssh or from CI, and a command that pops a keychain prompt
+ * also TEACHES people to click through keychain prompts. So the diagnostics —
+ * `approval doctor`, and `approval up`'s cross-instance report — resolve
+ * keystore-backed variables not at all: they report the scheme and the service
+ * name, which `.approval/env` already carries in the open, and leave the actual
+ * lookup to `approval env --check`, which a human runs deliberately and watches.
+ *
+ * It lives beside {@link defaultSourceRunner} rather than in one of its callers
+ * because two of them now need it and a second copy would be a second set of
+ * words for the same refusal.
+ */
+export declare const NON_RESOLVING_RUNNER: SourceRunner;
+export declare const defaultSourceRunner: SourceRunner;
+/** Where a resolved value came from, as a closed set. */
+export type EnvVariableStatus = "set-in-environment" | "resolved-from-keychain" | "resolved-from-secret-service" | "resolved-literal" | "unset";
+/** One variable, resolved. */
+export interface ResolvedVariable {
+    /** The variable's NAME, as the policy or the runtime default gave it. */
+    name: string;
+    status: EnvVariableStatus;
+    /** The value, present only when the status is not `unset`. */
+    value?: string;
+    /**
+     * Where it came from, in words, and NEVER a value: `the environment`,
+     * `keychain:approval-tg-token`, `literal (plaintext in .approval/env)`,
+     * `unset`.
+     */
+    source: string;
+    /**
+     * The value is sitting in plaintext in the working tree: a secret-bearing
+     * variable resolved from a bare literal.
+     *
+     * `APPROVAL_HUMAN` and the Telegram chat id are literals in most real files
+     * and are not secrets, so they are `false` — but note the `source` label says
+     * "literal (plaintext in .approval/env)" for EVERY literal regardless, because
+     * the reader deciding whether a file may be committed wants to see all of
+     * them.
+     */
+    plaintext: boolean;
+    /** What to do about an `unset`. Absent when there is nothing to do. */
+    fix?: string;
+    /** Why a resolution failed, when one did. Distinct and machine-readable. */
+    refusal?: {
+        code: EnvFileRefusalCode;
+        message: string;
+    };
+    /**
+     * The policy NAMED this variable (rather than the runtime defaulting it).
+     * `approval env --check` fails on an unresolved declared variable and not on
+     * an unresolved defaulted one: a policy that asked for something is a promise;
+     * a default the operator never mentioned is an offer.
+     */
+    declared: boolean;
+    /** The value would be a secret if it had one: token, passphrase, sampling. */
+    secretBearing: boolean;
+    /**
+     * What the INSTANCE's own `.approval/env` says about this variable, whether
+     * or not that is where the value came from (APRV-178).
+     *
+     * The ambient environment wins over the file and the file is then not even
+     * consulted, which is correct and is invariant 7 — but it is also how a
+     * production bot token exported in a shell profile silently became a demo
+     * instance's channel credential. Nothing could report that, because the
+     * resolution discarded the file entry it had ignored. It is kept here so
+     * `approval env --check`, `approval doctor` and `approval up` can say "this
+     * value is not the one your instance's file names".
+     *
+     * Value-free by construction: {@link DeclaredSource.service} is filled only
+     * for the two keystore schemes, whose argument is a service name the file
+     * carries in the open. A `literal` entry's argument IS the secret, so only
+     * its KIND is recorded.
+     */
+    fileSource?: DeclaredSource;
+}
+/** A `.approval/env` line, reduced to what may be printed. */
+export interface DeclaredSource {
+    kind: EnvSourceKind;
+    /** The service name or label, for `keychain:` and `secret-service:` only. */
+    service?: string;
+    /** 1-based line number in `.approval/env`. */
+    line: number;
+}
+/** A declared source in words, and never a value. */
+export declare function describeDeclaredSource(source: DeclaredSource): string;
+/** The whole answer. */
+export interface EnvResolution {
+    ok: true;
+    /** Was there a file at all? */
+    present: boolean;
+    path: string;
+    /**
+     * {@link envFileDigest} of the bytes this resolution read (APRV-278), or
+     * {@link ABSENT_ENV_FILE_DIGEST} when there was no file. It identifies a
+     * VERSION of the file and carries none of its contents.
+     */
+    digest: string;
+    variables: ResolvedVariable[];
+}
+interface Wanted {
+    name: string;
+    declared: boolean;
+    secretBearing: boolean;
+    /** The repair for an unset one. */
+    fix: string;
+}
+/**
+ * The variables `approval env` answers for, in a stable order.
+ *
+ * Five by name — human identity, the Telegram token and chat id, the vault
+ * passphrase, and the sampling secret — plus whatever else the policy names by
+ * the `_env` convention.
+ *
+ * The sampling secret is the one conditional member: `audit.sampling_secret_env`
+ * has NO default (an unnamed one disables sampling, SPEC.md §5.2), so listing a
+ * made-up variable for it would invent configuration the operator never chose.
+ * The other four all have defaults and are always listed.
+ */
+export declare function wantedVariables(load: PolicyLoadResult): Wanted[];
+/**
+ * Resolve every variable the policy implies, against the ambient environment
+ * first and the source map second.
+ *
+ * **The ambient environment always wins.** A variable already exported in the
+ * calling shell is reported `set-in-environment` and its file entry is not even
+ * consulted: the human's shell is the authority (that is invariant 7's whole
+ * point), and a file that could override an exported value would be a file that
+ * silently redirects a gate operation's credentials.
+ *
+ * A whole-file refusal (bad mode, unreadable, unparseable) is returned as-is:
+ * partial resolution of a file the runtime cannot fully read is how a typo turns
+ * into a half-configured environment.
+ */
+export declare function resolveEnvironment(load: PolicyLoadResult, envFilePath: string, runner?: SourceRunner, ambientEnv?: NodeJS.ProcessEnv): EnvResolution | EnvFileRefusal;
+export {};