approval-md 0.0.1 → 0.2.0

package/dist/src/daemon/draw.js

@@ -0,0 +1,458 @@
+/**
+ * The daemon's live-draw server (APRV-208).
+ *
+ * The daemon is the one process on this machine that legitimately holds the
+ * sampling secret: an operator starts it in a terminal where `eval "$(approval
+ * env)"` has run, and `core/child-env.ts` (APRV-205) strips `APPROVAL_*` from
+ * every child it spawns, so the secret goes no further. This module lets short
+ * lived gate processes that hold no secret — the harness hook, above all — ASK
+ * for a draw instead of failing closed on every action of a `supervised-live`
+ * class. `core/live-draw.ts` carries the protocol and the argument; this is the
+ * server half.
+ *
+ * ## Three things this server refuses to take on the asker's word
+ *
+ * 1. **The action.** It answers only for an `action_key` already carried by a
+ *    `task.registered` record in the VERIFIED log, declaring exactly this
+ *    `payload_hash`. That is what stops the socket being a private oracle: an
+ *    agent that wants to grind candidate payloads until one draws unsampled must
+ *    append a registration for each candidate first, in the append-only log,
+ *    where the attempt is permanent and countable. See `core/live-draw.ts`'s
+ *    header on why this matters more than the socket's file mode does.
+ * 2. **The rate.** It resolves the action's class against its own policy and
+ *    uses the `live_rate` IT derives. A `live_rate` in the question is a
+ *    proposal, never an instruction; the derived one is echoed back and the
+ *    asker refuses an answer to a different question.
+ * 3. **The policy.** Same: it checks its own attestation and echoes its own
+ *    `policy_sha256`. A daemon and a hook reading different policy files fail
+ *    closed rather than agreeing on the wrong rules.
+ *
+ * A fresh verified read per question is what makes (1) usable at all: the hook
+ * registers the task microseconds before it asks, and a daemon answering out of
+ * a tick's stale memory would refuse every real request. The read is cheap for
+ * the reason APRV-188 exists — the daemon's cache is warm and only the appended
+ * tail is walked.
+ *
+ * ## The secret
+ *
+ * Held in one private field, closed over by nothing, and never emitted: not in
+ * an answer, not in a warning, not in the `started` line. What leaves this
+ * process is a verdict and a MAC.
+ */
+import { chmodSync, mkdirSync, rmSync, statSync } from "node:fs";
+import { createServer } from "node:net";
+import { checkAttestation } from "../core/attest.js";
+import { DRAW_PROTOCOL_VERSION, DRAW_SOCKET_PATH_LIMIT, drawDirFor, drawMac, drawSocketPathFor, isHex64, isSamplingQuery, liveClassesOf, } from "../core/live-draw.js";
+import { loadPolicy } from "../core/policy-load.js";
+import { resolve as resolveClass } from "../core/policy-match.js";
+import { isSampled, resolveLiveSelector, resolveSampler, } from "../core/sampler.js";
+import { readVerifiedRecords } from "../core/state.js";
+/**
+ * The server this environment can run, or the reason it cannot (APRV-208).
+ *
+ * ## Where the secret comes from, and why that is the whole opt-in
+ *
+ * From the daemon's OWN environment, and nowhere else. `.approval/env` is a
+ * source MAP and `core/env-file.ts`'s load-bearing rule is that no verb reads it
+ * into its own environment (the reason is `APPROVAL_HUMAN`: a working-tree file
+ * that could set identity would put the human-only gate one `echo >>` away from
+ * being nobody's gate). That rule is not weakened here. The operator runs `eval
+ * "$(approval env)"` in the terminal they start the daemon from — the same act
+ * `approval setup sampling` already documents, resolving the keychain item or the
+ * env file's declared source — and this reads what that established.
+ *
+ * That act is also the feature's opt-in, which is why there is no flag to turn
+ * it on. Serving draws changes VERDICTS: a class an operator declared
+ * `supervised-live` at 0.1 goes from gating 100% to gating 10%, and a default
+ * that moved that under someone on an upgrade would be the surprise this project
+ * exists to prevent. But it moves only for an operator who has exported the
+ * secret into the daemon's shell on purpose, having already amended their policy
+ * to declare the class live. Both halves are deliberate acts by the human. What
+ * exists instead is a way OUT — `approval daemon run --no-draw` — because the
+ * one thing an operator must always be able to do is take a control back.
+ */
+export function drawServerFor(options) {
+    const where = options.policy.file !== undefined
+        ? { file: options.policy.file }
+        : { dir: options.policy.dir ?? process.cwd() };
+    if (options.schemaDir !== undefined)
+        where.schemaDir = options.schemaDir;
+    const load = loadPolicy(where);
+    const env = options.env ?? process.env;
+    // Asked FIRST, and answered quietly. A policy with no `supervised-live` class
+    // makes no draw at any rate, so an unset secret in this shell is not a fact
+    // about that operator's configuration: it is the ordinary state of every
+    // daemon that has never used the setting, and a warning printed on every start
+    // would be the noise that teaches an operator to stop reading the others. It
+    // has to come before the selector because `core/sampler.ts`'s refusals are
+    // worded for a caller that already knows a live class is in play ("declares a
+    // supervised-live class but names no ...", which would be false here).
+    if (load.ok && liveClassesOf(load.policy).length === 0) {
+        return {
+            ok: false,
+            reason: "no-live-class",
+            message: `${load.source.filename} declares no supervised-live class, so no draw is ever made and none is served.`,
+        };
+    }
+    // The availability question is asked through `core/sampler.ts`, so this and
+    // the in-process draw agree on what "no usable secret" means and on the words
+    // for each way of not having one. The secret itself is read here rather than
+    // there because a MAC needs the key and `resolveLiveSelector` returns a
+    // closure over it, deliberately.
+    const selector = resolveLiveSelector(load, env);
+    if (!selector.available) {
+        return { ok: false, reason: selector.reason, message: selector.message };
+    }
+    const secret = env[selector.secretEnv];
+    if (typeof secret !== "string" || secret.length === 0) {
+        return { ok: false, reason: "secret-unset", message: "the sampling secret is unset in this process" };
+    }
+    return {
+        ok: true,
+        server: new DrawServer({
+            logPath: options.logPath,
+            policy: options.policy,
+            ...(options.schemaDir === undefined ? {} : { schemaDir: options.schemaDir }),
+            ...(options.now === undefined ? {} : { now: options.now }),
+            secret,
+        }),
+    };
+}
+/** The largest question this server will read before hanging up. */
+const QUESTION_LIMIT = 8192;
+function payloadOf(record) {
+    const payload = record.payload;
+    return typeof payload === "object" && payload !== null
+        ? payload
+        : {};
+}
+/**
+ * The class a registered action declared, if the log declares this exact pair.
+ *
+ * Scans every `task.registered` because the question names no task: the action
+ * key is the identifier the whole runtime keys on, and requiring the asker to
+ * name a task too would be one more field to get wrong for no check gained. The
+ * pair must match on BOTH halves — an action registered with other bytes is not
+ * this question's action.
+ */
+function registeredClass(records, actionKey, payloadHash) {
+    let found = null;
+    for (const record of records) {
+        if (record.event !== "task.registered")
+            continue;
+        const declared = payloadOf(record)["actions"];
+        if (!Array.isArray(declared))
+            continue;
+        for (const entry of declared) {
+            if (typeof entry !== "object" || entry === null)
+                continue;
+            const item = entry;
+            if (item["idempotency_key"] !== actionKey)
+                continue;
+            if (item["payload_hash"] !== payloadHash)
+                continue;
+            if (typeof item["class"] !== "string")
+                continue;
+            found = item["class"];
+        }
+    }
+    return found;
+}
+/** The question, validated into its typed shape, or `null`. */
+function parseQuestion(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const body = parsed;
+    if (body["v"] !== DRAW_PROTOCOL_VERSION)
+        return null;
+    if (typeof body["action_key"] !== "string" || body["action_key"].length === 0)
+        return null;
+    if (!isHex64(body["payload_hash"]))
+        return null;
+    if (!isHex64(body["policy_hash"]))
+        return null;
+    const rate = body["live_rate"];
+    if (typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0 || rate > 1)
+        return null;
+    return {
+        v: DRAW_PROTOCOL_VERSION,
+        action_key: body["action_key"],
+        payload_hash: body["payload_hash"],
+        policy_hash: body["policy_hash"],
+        live_rate: rate,
+    };
+}
+/**
+ * A server that answers live draws for one log, over one owner-only socket.
+ *
+ * Started and stopped by the daemon loop. Every failure is a refusal to serve,
+ * never a throw into the loop: a daemon that could not open a socket must keep
+ * doing its job, and every asker fails closed to a human decision, which is
+ * exactly what happens today with no daemon at all.
+ */
+export class DrawServer {
+    options;
+    server = null;
+    answered = 0;
+    refused = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    /** How many questions were answered and refused, for the daemon's report. */
+    stats() {
+        return { answered: this.answered, refused: this.refused };
+    }
+    start() {
+        const path = drawSocketPathFor(this.options.logPath);
+        if (path.length > DRAW_SOCKET_PATH_LIMIT) {
+            return {
+                ok: false,
+                reason: "path-too-long",
+                detail: `${path} is ${String(path.length)} bytes, past the ${String(DRAW_SOCKET_PATH_LIMIT)}-byte limit a Unix socket address can carry`,
+            };
+        }
+        const dir = drawDirFor(this.options.logPath);
+        try {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            // `mkdirSync`'s mode is subject to umask and a pre-existing directory
+            // keeps whatever mode it had, so the mode is asserted rather than asked
+            // for. The socket below is 0600 regardless; this is the second lock.
+            chmodSync(dir, 0o700);
+            const stats = statSync(dir);
+            const euid = typeof process.geteuid === "function" ? process.geteuid() : null;
+            if (euid === null || stats.uid !== euid) {
+                return {
+                    ok: false,
+                    reason: "directory-unusable",
+                    detail: `${dir} is not owned by this user, so a socket in it could not be attributed to this daemon`,
+                };
+            }
+        }
+        catch (cause) {
+            return {
+                ok: false,
+                reason: "directory-unusable",
+                detail: `${dir} could not be prepared: ${cause instanceof Error ? cause.message : String(cause)}`,
+            };
+        }
+        // A socket file left by a daemon that was killed. Removing it is safe: a
+        // LIVE server holding this path would make the bind below fail with EADDRINUSE
+        // only if the file were still there, and a second daemon on one log is
+        // already refused by the append lockfile long before it reaches here.
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+            // Nothing to remove, or a path we cannot clear; the bind reports it.
+        }
+        const server = createServer((socket) => {
+            this.serve(socket);
+        });
+        server.on("error", () => {
+            // A listening error after start is a server that has stopped serving.
+            // Askers see a socket that will not answer and gate; nothing here throws
+            // into the daemon loop.
+        });
+        try {
+            server.listen(path);
+            chmodSync(path, 0o600);
+        }
+        catch (cause) {
+            try {
+                server.close();
+            }
+            catch {
+                // Never listened.
+            }
+            return {
+                ok: false,
+                reason: "listen-failed",
+                detail: `${path} could not be served: ${cause instanceof Error ? cause.message : String(cause)}`,
+            };
+        }
+        // The daemon must be free to exit while this is open.
+        server.unref();
+        this.server = server;
+        return { ok: true, path };
+    }
+    close() {
+        const server = this.server;
+        this.server = null;
+        if (server === null)
+            return;
+        try {
+            server.close();
+        }
+        catch {
+            // Already closed.
+        }
+        try {
+            rmSync(drawSocketPathFor(this.options.logPath), { force: true });
+        }
+        catch {
+            // A socket file we cannot remove is one the next start clears.
+        }
+    }
+    serve(socket) {
+        let buffer = "";
+        let done = false;
+        const answer = (body) => {
+            if (done)
+                return;
+            done = true;
+            try {
+                socket.end(`${JSON.stringify(body)}\n`);
+            }
+            catch {
+                // The asker hung up; nothing to report to.
+            }
+        };
+        const refuse = (detail) => {
+            this.refused += 1;
+            answer({ ok: false, detail });
+        };
+        socket.setEncoding("utf8");
+        socket.setTimeout(2_000, () => {
+            refuse("no question within the server's read timeout");
+            socket.destroy();
+        });
+        socket.on("error", () => {
+            done = true;
+        });
+        socket.on("data", (chunk) => {
+            if (done)
+                return;
+            buffer += chunk;
+            if (buffer.length > QUESTION_LIMIT) {
+                refuse("the question exceeded this protocol's size limit");
+                return;
+            }
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            const line = buffer.slice(0, newline);
+            // APRV-271. The status question comes first because a draw question can
+            // never look like one: it carries no `action_key`, so `parseQuestion`
+            // would refuse it, and an operator would be told their daemon was
+            // malfunctioning when it had been asked something older builds never
+            // defined. Answering it costs no verified read and no MAC.
+            if (isSamplingQuery(line)) {
+                this.answered += 1;
+                answer(this.samplingReport());
+                return;
+            }
+            const question = parseQuestion(line);
+            if (question === null) {
+                refuse("the question was malformed or declared another protocol version");
+                return;
+            }
+            answer(this.decide(question, refuse));
+        });
+    }
+    /**
+     * Answer one question, or refuse it.
+     *
+     * Returns the answer body; refusals go through `refuse` and this returns
+     * `undefined`, which `answer` above ignores because `done` is already set.
+     */
+    /** Where this daemon reads its policy from. One spelling, two readers. */
+    policyWhere() {
+        const where = this.options.policy.file !== undefined
+            ? { file: this.options.policy.file }
+            : { dir: this.options.policy.dir ?? process.cwd() };
+        if (this.options.schemaDir !== undefined)
+            where.schemaDir = this.options.schemaDir;
+        return where;
+    }
+    /**
+     * This daemon's report on its OWN sampler (APRV-271).
+     *
+     * Read through `core/sampler.ts` from this process's environment, which is
+     * the whole point: the operator exported the secret HERE, and every other
+     * process on the machine has had `APPROVAL_*` stripped from it. It carries
+     * the variable's NAME and the rate, both of which the policy file already
+     * states in the open, and never the value.
+     *
+     * No verified read, no attestation check and no MAC: this answer decides
+     * nothing. `core/live-draw.ts`'s header sets out what a caller may and may
+     * not conclude from it.
+     */
+    samplingReport() {
+        const load = loadPolicy(this.policyWhere());
+        const sampler = resolveSampler(load);
+        const now = this.options.now ?? (() => new Date().toISOString());
+        return {
+            v: DRAW_PROTOCOL_VERSION,
+            sampling: {
+                enabled: sampler.enabled,
+                reason: sampler.enabled ? null : sampler.reason,
+                secret_env: sampler.secretEnv,
+                rate: sampler.rate,
+                live_classes: load.ok ? liveClassesOf(load.policy) : [],
+            },
+            daemon_pid: process.pid,
+            answered_at: now(),
+        };
+    }
+    decide(question, refuse) {
+        const where = this.policyWhere();
+        const load = loadPolicy(where);
+        if (!load.ok) {
+            refuse(`this daemon cannot load its policy (${load.code}), so it can derive no rate`);
+            return undefined;
+        }
+        const read = readVerifiedRecords(this.options.logPath, this.options.schemaDir === undefined ? {} : { schemaDir: this.options.schemaDir });
+        if (!read.ok) {
+            refuse(`this daemon's log does not verify (${read.code}), so it will answer nothing`);
+            return undefined;
+        }
+        // The policy this daemon is actually enforcing, by its own attestation
+        // check over its own bytes. Never the asker's claim.
+        const status = checkAttestation(read.records, load.source.path);
+        if (status.status !== "attested") {
+            refuse(`this daemon's policy is not attested (${status.status}), so no draw is derivable`);
+            return undefined;
+        }
+        const cls = registeredClass(read.records, question.action_key, question.payload_hash);
+        if (cls === null) {
+            // The anti-grinding rule. A question about bytes nobody registered is a
+            // question about a hypothetical, and answering hypotheticals is what
+            // would turn this socket into the oracle the secret exists to deny.
+            refuse(`no task.registered in the verified log declares action ${question.action_key} with this payload_hash; a draw is answered only for an action already on the record`);
+            return undefined;
+        }
+        const resolution = resolveClass(load, cls);
+        if (resolution.supervision !== "live") {
+            refuse(`class ${cls} is not supervised-live under this daemon's policy; there is no fraction to draw`);
+            return undefined;
+        }
+        const rate = resolution.liveRate ?? 1;
+        const derived = {
+            v: DRAW_PROTOCOL_VERSION,
+            action_key: question.action_key,
+            payload_hash: question.payload_hash,
+            policy_hash: status.sha256,
+            live_rate: rate,
+        };
+        const selected = isSampled(this.options.secret, derived.payload_hash, derived.live_rate);
+        const now = this.options.now ?? (() => new Date().toISOString());
+        const body = {
+            v: DRAW_PROTOCOL_VERSION,
+            question: derived,
+            selected,
+            mac: drawMac(this.options.secret, derived, selected),
+            daemon_pid: process.pid,
+            answered_at: now(),
+        };
+        this.answered += 1;
+        return body;
+    }
+}
+//# sourceMappingURL=draw.js.map

package/dist/src/daemon/draw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draw.js","sourceRoot":"","sources":["../../../src/daemon/draw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,YAAY,EAA4B,MAAM,UAAU,CAAC;AAElE,OAAO,EAAE,gBAAgB,EAA0B,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,UAAU,EACV,OAAO,EACP,iBAAiB,EACjB,OAAO,EACP,eAAe,EACf,aAAa,GAId,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAA0B,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,cAAc,GAEf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAwE;IAExE,MAAM,KAAK,GACT,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS;QAC/B,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE;QAC/B,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;IACnD,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACzE,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAEvC,8EAA8E;IAC9E,4EAA4E;IAC5E,yEAAyE;IACzE,+EAA+E;IAC/E,6EAA6E;IAC7E,2EAA2E;IAC3E,8EAA8E;IAC9E,uEAAuE;IACvE,IAAI,IAAI,CAAC,EAAE,IAAI,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,eAAe;YACvB,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,iFAAiF;SAClH,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,wEAAwE;IACxE,iCAAiC;IACjC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;IAC3E,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,8CAA8C,EAAE,CAAC;IACxG,CAAC;IACD,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,IAAI,UAAU,CAAC;YACrB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;YAC5E,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;YAC1D,MAAM;SACP,CAAC;KACH,CAAC;AACJ,CAAC;AAiCD,oEAAoE;AACpE,MAAM,cAAc,GAAG,IAAI,CAAC;AAE5B,SAAS,SAAS,CAAC,MAAmB;IACpC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QACpD,CAAC,CAAE,OAAmC;QACtC,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,eAAe,CACtB,OAAsB,EACtB,SAAiB,EACjB,WAAmB;IAEnB,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,KAAK,KAAK,iBAAiB;YAAE,SAAS;QACjD,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;YAAE,SAAS;QACvC,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAAE,SAAS;YAC1D,MAAM,IAAI,GAAG,KAAgC,CAAC;YAC9C,IAAI,IAAI,CAAC,iBAAiB,CAAC,KAAK,SAAS;gBAAE,SAAS;YACpD,IAAI,IAAI,CAAC,cAAc,CAAC,KAAK,WAAW;gBAAE,SAAS;YACnD,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ;gBAAE,SAAS;YAChD,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+DAA+D;AAC/D,SAAS,aAAa,CAAC,IAAY;IACjC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/D,MAAM,IAAI,GAAG,MAAiC,CAAC;IAC/C,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,qBAAqB;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3F,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAC/B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7F,OAAO;QACL,CAAC,EAAE,qBAAqB;QACxB,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC;QAC9B,YAAY,EAAE,IAAI,CAAC,cAAc,CAAC;QAClC,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC;QAChC,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,UAAU;IACJ,OAAO,CAAoB;IACpC,MAAM,GAAkB,IAAI,CAAC;IAC7B,QAAQ,GAAG,CAAC,CAAC;IACb,OAAO,GAAG,CAAC,CAAC;IAEpB,YAAY,OAA0B;QACpC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,6EAA6E;IAC7E,KAAK;QACH,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC5D,CAAC;IAED,KAAK;QACH,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,GAAG,sBAAsB,EAAE,CAAC;YACzC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,eAAe;gBACvB,MAAM,EAAE,GAAG,IAAI,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,oBAAoB,MAAM,CAAC,sBAAsB,CAAC,6CAA6C;aACzI,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACjD,sEAAsE;YACtE,wEAAwE;YACxE,qEAAqE;YACrE,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC5B,MAAM,IAAI,GAAG,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YAC9E,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;gBACxC,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,MAAM,EAAE,oBAAoB;oBAC5B,MAAM,EAAE,GAAG,GAAG,sFAAsF;iBACrG,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,oBAAoB;gBAC5B,MAAM,EAAE,GAAG,GAAG,2BAA2B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;aAClG,CAAC;QACJ,CAAC;QAED,yEAAyE;QACzE,+EAA+E;QAC/E,uEAAuE;QACvE,sEAAsE;QACtE,IAAI,CAAC;YACH,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;QACvE,CAAC;QAED,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,sEAAsE;YACtE,yEAAyE;YACzE,wBAAwB;QAC1B,CAAC,CAAC,CAAC;QACH,IAAI,CAAC;YACH,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACpB,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,CAAC;YAAC,MAAM,CAAC;gBACP,kBAAkB;YACpB,CAAC;YACD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,eAAe;gBACvB,MAAM,EAAE,GAAG,IAAI,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;aACjG,CAAC;QACJ,CAAC;QACD,sDAAsD;QACtD,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO;QAC5B,IAAI,CAAC;YACH,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;QACD,IAAI,CAAC;YACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;QACjE,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,MAAc;QAC1B,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,IAAI,GAAG,KAAK,CAAC;QACjB,MAAM,MAAM,GAAG,CAAC,IAAa,EAAQ,EAAE;YACrC,IAAI,IAAI;gBAAE,OAAO;YACjB,IAAI,GAAG,IAAI,CAAC;YACZ,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,2CAA2C;YAC7C,CAAC;QACH,CAAC,CAAC;QACF,MAAM,MAAM,GAAG,CAAC,MAAc,EAAQ,EAAE;YACtC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;YAClB,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QAChC,CAAC,CAAC;QAEF,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE;YAC5B,MAAM,CAAC,8CAA8C,CAAC,CAAC;YACvD,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,IAAI,GAAG,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,IAAI,IAAI;gBAAE,OAAO;YACjB,MAAM,IAAI,KAAK,CAAC;YAChB,IAAI,MAAM,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;gBACnC,MAAM,CAAC,kDAAkD,CAAC,CAAC;gBAC3D,OAAO;YACT,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,OAAO,GAAG,CAAC;gBAAE,OAAO;YACxB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YACtC,wEAAwE;YACxE,sEAAsE;YACtE,kEAAkE;YAClE,qEAAqE;YACrE,2DAA2D;YAC3D,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;gBACnB,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtB,MAAM,CAAC,iEAAiE,CAAC,CAAC;gBAC1E,OAAO;YACT,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,0EAA0E;IAClE,WAAW;QACjB,MAAM,KAAK,GACT,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS;YACpC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE;YACpC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;QACxD,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS;YAAE,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;QACnF,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;;;;;OAYG;IACK,cAAc;QACpB,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAW,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;QACzE,OAAO;YACL,CAAC,EAAE,qBAAqB;YACxB,QAAQ,EAAE;gBACR,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM;gBAC/C,UAAU,EAAE,OAAO,CAAC,SAAS;gBAC7B,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,YAAY,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;aACxD;YACD,UAAU,EAAE,OAAO,CAAC,GAAG;YACvB,WAAW,EAAE,GAAG,EAAE;SACnB,CAAC;IACJ,CAAC;IAEO,MAAM,CAAC,QAAsB,EAAE,MAAgC;QACrE,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,CAAC,uCAAuC,IAAI,CAAC,IAAI,6BAA6B,CAAC,CAAC;YACtF,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,IAAI,GAAG,mBAAmB,CAC9B,IAAI,CAAC,OAAO,CAAC,OAAO,EACpB,IAAI,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,CAAC,sCAAsC,IAAI,CAAC,IAAI,8BAA8B,CAAC,CAAC;YACtF,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,uEAAuE;QACvE,qDAAqD;QACrD,MAAM,MAAM,GAAsB,gBAAgB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnF,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,MAAM,CAAC,yCAAyC,MAAM,CAAC,MAAM,4BAA4B,CAAC,CAAC;YAC3F,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,GAAG,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;QACtF,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,wEAAwE;YACxE,qEAAqE;YACrE,oEAAoE;YACpE,MAAM,CACJ,0DAA0D,QAAQ,CAAC,UAAU,sFAAsF,CACpK,CAAC;YACF,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC3C,IAAI,UAAU,CAAC,WAAW,KAAK,MAAM,EAAE,CAAC;YACtC,MAAM,CAAC,SAAS,GAAG,kFAAkF,CAAC,CAAC;YACvG,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,IAAI,CAAC,CAAC;QAEtC,MAAM,OAAO,GAAiB;YAC5B,CAAC,EAAE,qBAAqB;YACxB,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,WAAW,EAAE,MAAM,CAAC,MAAM;YAC1B,SAAS,EAAE,IAAI;SAChB,CAAC;QACF,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QACzF,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAW,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;QACzE,MAAM,IAAI,GAAe;YACvB,CAAC,EAAE,qBAAqB;YACxB,QAAQ,EAAE,OAAO;YACjB,QAAQ;YACR,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;YACpD,UAAU,EAAE,OAAO,CAAC,GAAG;YACvB,WAAW,EAAE,GAAG,EAAE;SACnB,CAAC;QACF,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/src/daemon/git-evidence.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Per-event git commits — SPEC.md §8's optional hardening (APRV-42).
+ *
+ * > "Optionally, the log directory is a git repo and the daemon commits per
+ * > event with its own identity, giving signed, distributed tamper evidence for
+ * > free."
+ *
+ * The chain in `events.jsonl` already detects mutation and truncation on its
+ * own. What a git repository adds is a *second, independent* record of the same
+ * bytes: a mutation that is plausible against one layer has to be plausible
+ * against the other at the same time, and the second layer is one an operator
+ * can clone, mirror, and diff from somewhere the tamperer does not control.
+ * Neither layer is trusted to police the other, which is the point of having
+ * two: `approval log verify` never consults git, and nothing here ever reads a
+ * verdict out of a commit.
+ *
+ * ## Opt-in, and only for a standalone log deployment
+ *
+ * This is off unless the operator asks for it, and refuses to turn on unless the
+ * log's own directory is a repository *root*. The two layouts do not mix:
+ *
+ * - **Standalone log deployment.** The log home (`.approval/`, or whatever
+ *   directory holds the log when it is not under a `log/` folder) is its own git
+ *   repository, containing the log, the payload store, and nothing else. Enable
+ *   the opt-in here.
+ * - **Nested project layout** — this repository's own dogfood arrangement, where
+ *   `.approval/` is committed as part of a larger project repo. Perfectly valid,
+ *   and the opt-in is REFUSED for it.
+ *
+ * Why refuse the nested case rather than make it work? Because a hash chain does
+ * not survive a merge. Two branches that each append independently produce a
+ * chain that is corrupt by construction, and no merge strategy repairs the
+ * semantics. An outer repository's ordinary history operations — rebase, amend,
+ * squash, force-push, `filter-branch` — rewrite the very bytes the evidence is
+ * made of, and a daemon committing into someone else's branch would be a second
+ * writer to a history the project's humans also write. Evidence that the subject
+ * of the investigation can rewrite is not evidence. So the runtime does not try
+ * to be clever about it: own-root repository, or no git evidence at all.
+ *
+ * ## What it does, precisely
+ *
+ * After every tick in which the log moved, the daemon calls {@link
+ * GitEvidenceRecorder.commit} with the verified head it just read. The recorder
+ * stages the log file and the payload store, and commits with a message naming
+ * the head's `(seq, hash)`. Batching is **one commit per tick**, not literally
+ * one per event: ticks are the only moment the daemon has a verified head in
+ * hand, and a commit is only meaningful against a head that verified. A tick
+ * that observed three appends produces one commit naming the new head and the
+ * number of records it covers — the intermediate states are still fully
+ * recoverable from the log itself, which is the artifact being witnessed.
+ *
+ * ## What it deliberately does not do
+ *
+ * It never pushes, never fetches, never creates or moves a branch by name, never
+ * touches a remote, and never writes to any git config outside the single
+ * `git commit` invocation (identity is passed with `-c`, per command, so the
+ * operator's `user.name` is neither read into the commit nor overwritten on
+ * disk). Commits are local, to the log's own repository, authored by the daemon
+ * as itself. A failure to commit is a warning, never a stop: git evidence is
+ * hardening on top of the chain, and a daemon that halted approvals because a
+ * disk was full of git objects would have converted a redundancy into a
+ * dependency.
+ */
+import type { LogHead } from "../core/log.js";
+/**
+ * The daemon's own git identity. Never the operator's: a commit that says a
+ * human made it is a false statement about who wrote the evidence, and the whole
+ * value of the second layer is that its authorship is unambiguous.
+ *
+ * The version is pinned to `package.json` by a test rather than read at runtime,
+ * because a module that resolves its own package root differs between the source
+ * tree and the build output for no benefit at all.
+ */
+export declare const APPROVALD_VERSION = "0.2.0";
+/** `user.name` on every commit this module makes. */
+export declare const GIT_EVIDENCE_AUTHOR_NAME = "approvald 0.2.0";
+/** `user.email` on every commit: fixed, and deliberately undeliverable. */
+export declare const GIT_EVIDENCE_AUTHOR_EMAIL = "approvald@noreply.approval.md";
+/**
+ * Why enabling git evidence was refused. **Frozen union**, additive-only, in the
+ * same sense as every other refusal vocabulary in this codebase (SPEC.md §11.1
+ * invariant 6: refusals are machine-readable and distinct). An operator's
+ * supervisor branches on these to tell "install git" apart from "your layout is
+ * wrong", and the repair differs for every one of them.
+ */
+export declare const GIT_EVIDENCE_REFUSAL_CODES: readonly [
+/** No usable `git` on PATH. The daemon runs fine without the opt-in. */
+"git-unavailable", 
+/** The directory that would hold the evidence repository does not exist. */
+"log-dir-missing", 
+/** It exists and is not a git repository. The repair is `git init` there. */
+"log-dir-not-repo", 
+/**
+ * It is inside a working tree it does not own — either some outer repository
+ * tracks it, or it is a repository whose root is somewhere above. Hash chains
+ * do not survive merges and an outer history rewrites evidence.
+ */
+"log-dir-nested"];
+export type GitEvidenceRefusalCode = (typeof GIT_EVIDENCE_REFUSAL_CODES)[number];
+export interface GitEvidenceRefusal {
+    ok: false;
+    code: GitEvidenceRefusalCode;
+    message: string;
+}
+/**
+ * One line of git-evidence output. Its own frozen shape, reported through the
+ * callback the CLI supplies, so that `daemon/daemon.ts`'s event union stays
+ * exactly as it was: the hardening layer speaks for itself and the loop's
+ * contract is untouched.
+ */
+export type GitEvidenceEvent = {
+    event: "git_evidence";
+    /** The abbreviated commit this tick produced. */
+    commit: string;
+    /** The verified head the commit witnesses. */
+    seq: number;
+    hash: string;
+    /**
+     * Log lines added since the commit this one builds on — the batch size.
+     * The log is append-only, so a line is a record. `null` only when git
+     * declined to say, which is a reporting gap and never a correctness one.
+     */
+    records: number | null;
+} | {
+    event: "git_evidence_failed";
+    /** The git invocation that failed, as a bare subcommand name. */
+    step: string;
+    message: string;
+};
+/** Where git-evidence output goes. Injected, so this module writes to nothing. */
+export type GitEvidenceSink = (event: GitEvidenceEvent) => void;
+/**
+ * The hook the daemon calls. One method, taking the verified head of the log it
+ * just read, so that the loop's edit is a single line and no scheduling
+ * knowledge leaks into this file.
+ */
+export interface GitEvidenceRecorder {
+    commit(head: LogHead | null): void;
+}
+/**
+ * The directory that must be the evidence repository's root, for a given log.
+ *
+ * The same rule `payloadStoreDirFor` uses, for the same reason: SPEC.md §9 fixes
+ * the log at `<home>/log/events.jsonl` and the payload store at
+ * `<home>/payloads/`, so the only directory that contains *both* is `<home>`.
+ * Rooting the repository at the log's immediate directory would leave every
+ * payload file outside the evidence, which is precisely where a tamperer would
+ * then work. When a caller points `--log` somewhere flatter, the log's own
+ * directory is the home and the rule still holds.
+ */
+export declare function evidenceRootFor(logPath: string): string;
+export type EnableGitEvidenceResult = {
+    ok: true;
+    root: string;
+    recorder: GitEvidenceRecorder;
+} | GitEvidenceRefusal;
+/**
+ * Check every precondition and, when they all hold, build the recorder.
+ *
+ * Fail closed and fail *loudly*: each refusal is distinct, names the directory
+ * it judged, and states the repair. An operator who mistyped `--log` and an
+ * operator whose log lives inside a project repository need different sentences,
+ * and a single "git evidence unavailable" would have sent both of them looking
+ * in the wrong place.
+ */
+export declare function enableGitEvidence(logPath: string, sink: GitEvidenceSink): EnableGitEvidenceResult;
+/**
+ * The commit message: the head's `(seq, hash)` on the subject line, so a reader
+ * of `git log --oneline` can check a commit against the chain without opening
+ * anything, and the batch size in the body so the per-tick batching is visible
+ * rather than inferred.
+ */
+export declare function message(head: LogHead, records: number | null): string;