approval-md 0.0.1 → 0.2.0

package/dist/src/cli/log-checkpoint.js

@@ -0,0 +1,128 @@
+/**
+ * The CLI edge of `approval log checkpoint` (APRV-220).
+ *
+ * As everywhere else in this CLI, no logic lives here: `core/checkpoint.ts`
+ * signs and appends, and this file splits argv, decides WHERE the private key
+ * may come from, maps the result onto the frozen exit table, and decides what a
+ * terminal sees.
+ *
+ * ## Where the key may come from, and why that decision is NOT here any more
+ *
+ * `core/checkpoint.ts` takes the private key as a value and reads it from
+ * nowhere. That is deliberate: custody is a policy question, and answering it in
+ * one place means there is one file to read to learn every way a checkpoint key
+ * can reach a signature. Until APRV-257 that file was this one, because a
+ * terminal was the only place a checkpoint could be signed. The channel tap
+ * added two more callers, so the decision MOVED to `cli/checkpoint-tap.ts`
+ * rather than being copied into them, and this verb resolves its key with
+ * everyone else's function. The property is unchanged; the file holding it is
+ * not.
+ */
+import { isAbsolute, resolve } from "node:path";
+import { appendCheckpoint } from "../core/checkpoint.js";
+import { HUMAN_ACTOR_ENV, resolveHumanActor } from "../core/attest.js";
+import { resolveCheckpointKey } from "./checkpoint-tap.js";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import { LOG_CHECKPOINT_HELP } from "./help.js";
+import { refusal as renderRefusal, style } from "./style.js";
+import { usageErrorText } from "./usage.js";
+const CHECKPOINT_FLAGS = {
+    "--log": "string",
+    "--as": "string",
+    "--key-file": "string",
+    "--vault": "string",
+    "--policy": "string",
+    "--dir": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+};
+const DEFAULT_LOG_PATH = ".approval/log/events.jsonl";
+function absolute(path, cwd) {
+    return isAbsolute(path) ? path : resolve(cwd, path);
+}
+function usageError(streams, json, message) {
+    if (json)
+        streams.err(`${JSON.stringify({ ok: false, error: { code: "usage", message } })}\n`);
+    else
+        streams.err(usageErrorText(message, LOG_CHECKPOINT_HELP));
+    return EXIT_USAGE;
+}
+/**
+ * The exit code for a refusal.
+ *
+ * `log-corrupt` and `log-torn-tail` are integrity facts about the chain and go
+ * where `log verify` puts them; everything else here is a filesystem, key, or
+ * writer fact, which is exit 4. Nothing in this verb reports a missing key as
+ * corruption: an operator without a key has not got a broken log.
+ */
+function refusalExit(code) {
+    return code === "log-corrupt" || code === "log-torn-tail" ? EXIT_INTEGRITY : EXIT_IO;
+}
+export function commandLogCheckpoint(argv, streams, cwd) {
+    const json = argv.includes("--json");
+    const parsed = parseFlags(argv, CHECKPOINT_FLAGS);
+    if (!parsed.ok)
+        return usageError(streams, json, parsed.message);
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${LOG_CHECKPOINT_HELP}\n`);
+        return EXIT_OK;
+    }
+    const extra = parsed.positionals[0];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`);
+    }
+    // The human-only rule, spelled the way `policy attest` and `vault set` spell
+    // it. Refused here before any key is read, so a wrong identity never reaches
+    // the vault: an agent that could open the vault by getting the actor wrong
+    // would be an agent that could open the vault.
+    const asFlag = stringFlag(parsed.flags, "--as");
+    const actor = resolveHumanActor(asFlag === null ? {} : { actor: asFlag });
+    if (actor === null) {
+        return usageError(streams, json, asFlag === null
+            ? `no human identity: set ${HUMAN_ACTOR_ENV}=human:<id> or pass --as human:<id>`
+            : `--as expects a human identity matching human:<id>, got ${JSON.stringify(asFlag)}; \`approval log checkpoint\` is human-only and an agent: or system: actor cannot perform it`);
+    }
+    const logFlag = stringFlag(parsed.flags, "--log");
+    const logPath = logFlag === null ? absolute(DEFAULT_LOG_PATH, cwd) : absolute(logFlag, cwd);
+    const policyFlag = stringFlag(parsed.flags, "--policy");
+    const dirFlag = stringFlag(parsed.flags, "--dir");
+    const policyWhere = policyFlag !== null
+        ? { file: absolute(policyFlag, cwd) }
+        : { dir: dirFlag === null ? cwd : absolute(dirFlag, cwd) };
+    const key = resolveCheckpointKey(stringFlag(parsed.flags, "--key-file"), logPath, stringFlag(parsed.flags, "--vault"), policyWhere, cwd);
+    if (!key.ok)
+        return reportRefusal(key.code, key.message, streams, json);
+    const result = appendCheckpoint(logPath, key.privateKey, actor);
+    if (!result.ok)
+        return reportRefusal(result.code, result.message, streams, json);
+    return reportSigned(result, streams, json);
+}
+function reportRefusal(code, message, streams, json) {
+    if (json) {
+        streams.err(`${JSON.stringify({ ok: false, error: { code, message } })}\n`);
+    }
+    else {
+        streams.err(`${renderRefusal(style({ json }), code, message)}\n`);
+    }
+    return refusalExit(code);
+}
+function reportSigned(result, streams, json) {
+    if (json) {
+        streams.out(`${JSON.stringify({
+            ok: true,
+            seq: result.record.seq,
+            signed: { seq: result.head.seq, hash: result.head.hash },
+            key_sha256: result.fingerprint,
+            actor: result.record.actor,
+            ts: result.record.ts,
+        })}\n`);
+    }
+    else {
+        streams.out(`checkpoint ${String(result.record.seq)}: signed head seq ${String(result.head.seq)} ${result.head.hash}\n`);
+        streams.out(`key ${result.fingerprint}, signed by ${result.record.actor}\n`);
+    }
+    return EXIT_OK;
+}
+//# sourceMappingURL=log-checkpoint.js.map

package/dist/src/cli/log-checkpoint.js.map

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

package/dist/src/cli/log-sync.d.ts

@@ -0,0 +1,243 @@
+/**
+ * `approval log sync` (APRV-125) — the pull half of the log ritual, as a verb.
+ *
+ * ## The ritual this replaces
+ *
+ * Bringing the committed log up to date used to be a hand-run sequence: stash
+ * the working `events.jsonl`, pull, pop the stash, hope. It was our own
+ * sanctioned runbook and it was dangerous three ways.
+ *
+ * 1. It rewound the working log through git while a daemon held it open for
+ *    append. That is fork 2 of 2026-08-20 (APRV-104's notes): a rewound file
+ *    under a live appender, and two chains where there was one.
+ * 2. It reached the approver's phone as `policy.edit` over a protected path —
+ *    a true label that told the human nothing about what was happening.
+ * 3. `git stash pop` can conflict, and on the day it did, it left conflict
+ *    markers inside the log file mid-ceremony.
+ *
+ * The precedent for turning it into a verb is `policy amend` after the seq 2
+ * incident: when a hand-ritual proves dangerous, it becomes deterministic code
+ * the gate can read.
+ *
+ * ## The sequence, and why each step is where it is
+ *
+ * Everything below runs inside ONE hold of the append lockfile. The lock is
+ * usually taken per-append; here it spans the whole operation, because an
+ * append landing between the snapshot and the restore is precisely the
+ * interleaving that forks a chain.
+ *
+ *  1. **Primary checkout only.** The committed log has one home. A worktree has
+ *     no business synchronizing it, and `log-sync-not-primary` says so.
+ *  2. **Verify before touching anything.** The working chain is walked and its
+ *     head recorded. Nothing is decided from a log that does not verify.
+ *  3. **Snapshot, not stash.** The working log is copied aside, atomically, to
+ *     a file inside `.approval/`. `git stash` is never used, and the log never
+ *     routes through git state mutation.
+ *  4. **Baseline.** The working LOG is set to the bytes git has at `HEAD`, so
+ *     the path is clean and a fast-forward merge can move over it. This is a
+ *     plain write of bytes we already hold, not a checkout: the snapshot from
+ *     step 3 is the only copy that matters and it is already safe. The queue
+ *     projection is deliberately NOT baselined here; see the section below.
+ *  5. **Fetch, then a fast-forward CHECK, then the projections are discarded,
+ *     then the merge.** A non-fast-forward is named and refused rather than
+ *     merged; a merge commit over a log is a merge of two hash chains, which is
+ *     not a thing that exists.
+ *  6. **Payload reconciliation, between the check and the merge.** See the
+ *     section below: untracked payload files the incoming tree also carries are
+ *     proved byte-identical and then removed, so the fast-forward has a clean
+ *     path to write them onto.
+ *  7. **Reconcile.** The committed chain must be a prefix of the snapshot, or
+ *     equal to it, or an extension of it. Anything else is a fork:
+ *     `log-diverged`, both heads, the first divergent seq, snapshot restored,
+ *     nothing else touched. The comparison is `core/log-reconcile.ts`, shared
+ *     with doctor's `log-drift` check.
+ *  8. **Projections are REBUILT, never copied back.** QUEUE.md is re-rendered
+ *     from the reconciled log and the index is reindexed from it. The direction
+ *     is load-bearing: a projection restored from before the pull would be a
+ *     screenshot asserting something the log no longer says.
+ *  9. **Post-verify**, and only then is the snapshot removed.
+ *
+ * Any failure at any step restores the snapshot before returning. The working
+ * log is never left in a half state, and the snapshot outlives every failure
+ * path that could need it.
+ *
+ * ## Untracked payload files, and why the merge used to stop on them (APRV-225)
+ *
+ * On 2026-09-02, after a records advance to seq 11361 merged, `log sync` in the
+ * primary checkout refused `log-sync-git-failed`: `git merge --ff-only` will not
+ * write over an untracked working-tree file, and the advance had committed 33
+ * payload files that this checkout already held untracked. Every one of them was
+ * byte-identical to the incoming blob — they are content-addressed, so identical
+ * by construction — and the only way forward was a hand step: move them aside,
+ * sync, put them back.
+ *
+ * That hand step is now step 6, on the same reasoning as the whole verb: when a
+ * hand-ritual is provably safe, it becomes deterministic code, and when it is
+ * NOT provably safe it refuses rather than guessing. The proof is per file, and
+ * every part of it runs before a single byte is removed:
+ *
+ * - the local file is **self-addressed** — SHA-256 of its bytes is its own name
+ *   (the store writes RFC 8785 canonical bytes, so this holds for anything
+ *   `storePayload` wrote); the `{"$ref": …}` reference form is the store's
+ *   documented exception and is carried on byte equality alone.
+ * - the local bytes **equal the incoming blob**, compared as bytes read through
+ *   `git show`. Not git's blob id: that is SHA-1 over a header plus the content
+ *   and has nothing to do with the SHA-256 content address the store uses, so
+ *   comparing names to blob ids would be comparing two different hashes of two
+ *   different things and calling the disagreement a fork.
+ *
+ * A payload that fails either test refuses `log-sync-payload-mismatch`, naming
+ * the file. A payload is the material evidence an approval bound to: two
+ * different versions of one is not a merge conflict to be resolved, it is a
+ * question about which bytes a human said yes to. Nothing is merged, nothing is
+ * appended, and the working tree is left as it was found.
+ *
+ * A local payload the incoming tree does **not** carry is not this verb's
+ * business and is not touched: it blocks nothing, and it is very likely a
+ * payload this checkout has recorded and not yet advanced.
+ *
+ * ## The queue projection is disposable, and discarded LATE (APRV-292)
+ *
+ * On 2026-09-07, after a records pull request that carried `.approval/QUEUE.md`
+ * as well as the log, `log sync` refused twice with git's "local changes to
+ * .approval/QUEUE.md would be overwritten", the second time immediately after a
+ * hand-run `git checkout -- .approval/QUEUE.md`. The hand step was not wrong,
+ * it was just early: the running daemon re-rendered the projection again before
+ * the fast-forward reached it.
+ *
+ * The two files are exposed to different writers, which is why they are handled
+ * differently. Nothing can append to the log while this verb runs — sync holds
+ * the append lock for the whole ceremony, and every appender takes it. Nothing
+ * at all holds the projection: `channels/render-queue.ts`'s `writeQueue` renders
+ * and renames `QUEUE.md` on every daemon tick, under no lock, by design (the
+ * TTL countdowns in it move even when the log does not, so the file is rewritten
+ * whether or not anything was appended). A
+ * projection baselined at step 4 can therefore be dirty again by the time `git
+ * merge --ff-only` looks at it, and a stale render is enough to stop a pull of
+ * the log.
+ *
+ * So the projection is not baselined with the log. It is **discarded** as the
+ * last statement before the merge, which is the narrowest window this verb can
+ * offer, and when the merge fails with a projection dirty again the discard and
+ * the merge are retried exactly once. What is discarded is a rendering of the
+ * log, rebuilt at step 8 from the reconciled log, so there is nothing here to
+ * weigh: a projection carries no truth of its own and losing the last render
+ * costs nothing but the render. A projection git neither has at `HEAD` nor
+ * carries in the incoming tree is left alone, because it can stop no merge —
+ * `.approval/index.sqlite` is gitignored, and clearing a cache that blocks
+ * nothing would only make the next reader rebuild it.
+ *
+ * The snapshot the queue still gets is for the REFUSAL path alone: a refusal
+ * leaves the whole working tree as it was found, log and projection together.
+ * No success path ever copies it back — see step 8.
+ *
+ * ## This verb appends no event
+ *
+ * The log records decisions with real-world consequence. A fast-forward pull of
+ * the file the log lives in is housekeeping on the container, not a decision
+ * about the world, and an event for it would be the log narrating its own
+ * filesystem. Nothing here calls `appendEvent`, and the tests pin that the head
+ * seq is unchanged by a successful sync (SPEC §10.1, amended APRV-125).
+ */
+import { type LogDrift, type LogRelation } from "../core/log-reconcile.js";
+import type { LogHead } from "../core/verify.js";
+/**
+ * The steps, named. They are a public shape because the failure-injection hook
+ * takes one, and because a refusal says which step it stopped at.
+ */
+export declare const LOG_SYNC_STEPS: readonly ["primary", "verify", "snapshot", "baseline", "fetch", "ff-check", "payloads", "merge", "reconcile", "projections", "post-verify"];
+export type LogSyncStep = (typeof LOG_SYNC_STEPS)[number];
+/**
+ * Machine-readable refusal codes. Frozen public API, printed in the help.
+ *
+ * `log-diverged` is the one that matters and the one the runbook is written
+ * for: it is the only outcome here that means a human has to reconcile two
+ * chains by hand, because nothing in this codebase may do it for them.
+ */
+export declare const LOG_SYNC_REFUSAL_CODES: readonly ["log-sync-not-primary", "log-sync-no-branch", "log-sync-unverified", "log-sync-not-fast-forward", "log-sync-payload-mismatch", "log-diverged", "log-sync-locked", "log-sync-git-failed", "log-sync-projection-failed", "log-sync-restore-failed", "log-sync-io"];
+export type LogSyncRefusalCode = (typeof LOG_SYNC_REFUSAL_CODES)[number];
+/** Test-only seams. Nothing in the CLI sets these; the suites do. */
+export interface LogSyncHooks {
+    /**
+     * Fail just before this step runs, as an injected I/O error would.
+     *
+     * This exists so the snapshot-restore guarantee can be tested per step
+     * rather than argued for. It is a parameter of the FUNCTION and not a CLI
+     * flag on purpose: the shipped surface has no way to ask for a failure.
+     */
+    failBefore?: LogSyncStep;
+    /**
+     * Run `run` just before `step`, as a concurrent writer would (APRV-292).
+     *
+     * The daemon rewrites `QUEUE.md` under no lock, so "the projection is dirty
+     * again between the baseline and the merge" is a real interleaving and not a
+     * hypothesis. A test that cannot produce it can only assert that the code
+     * looks right. Like {@link failBefore} this is a parameter of the function and
+     * never a CLI flag: the shipped surface has no way to ask for interference.
+     */
+    interfere?: {
+        step: LogSyncStep;
+        run: () => void;
+    };
+}
+export interface LogSyncOptions {
+    cwd: string;
+    /** Remote to fetch from. Default `origin`. */
+    remote?: string;
+    /** Branch to fast-forward onto. Default: the checked-out branch. */
+    branch?: string | null;
+    hooks?: LogSyncHooks;
+}
+/** What a successful sync did. The `--json` success shape is built from this. */
+export interface LogSyncReport {
+    root: string;
+    logPath: string;
+    remote: string;
+    branch: string;
+    commitBefore: string;
+    commitAfter: string;
+    /** How many commits the fast-forward brought in. */
+    pulled: number;
+    headBefore: LogHead | null;
+    headAfter: LogHead | null;
+    relation: LogRelation;
+    ahead: number;
+    behind: number;
+    /** True when the snapshot was written back (the working chain was ahead). */
+    restored: boolean;
+    /**
+     * How many untracked payload files were proved byte-identical to the incoming
+     * tree and stood aside so the fast-forward could write them (APRV-225).
+     */
+    payloadsReconciled: number;
+    queue: {
+        path: string;
+        bytes: number;
+    };
+    index: "rebuilt" | "absent";
+}
+export type LogSyncResult = {
+    ok: true;
+    report: LogSyncReport;
+} | {
+    ok: false;
+    code: LogSyncRefusalCode;
+    message: string;
+    /** The step that refused, for the report and the tests. */
+    step: LogSyncStep;
+    /** Present on `log-diverged`: the whole comparison. */
+    drift?: LogDrift;
+    /** Verbatim git output, for a runbook's quote block. */
+    quote?: readonly string[];
+    /** True when the working log is back exactly as it was found. */
+    restored: boolean;
+};
+/**
+ * `approval log sync`, as a function.
+ *
+ * The CLI wrapper does argv, exit codes, and formatting; everything that could
+ * damage a log is here, in one sequence, with one restore path.
+ */
+export declare function logSync(options: LogSyncOptions): LogSyncResult;
+/** A commit, as a human reads one. */
+export declare function short(commit: string): string;