@intentius/chant 0.124.13 → 0.124.14

package/dist/op/activities/factory.js

@@ -0,0 +1,591 @@
+/**
+ * The factory reference Op's activities (#3406, ws-087): the rules of
+ * `../../workspace/factory-rules.ts` run against a workspace, and the two
+ * places an orchestrator's execution plugs in, the builder and the check, run
+ * as commands in the run's worktree.
+ *
+ *   factoryPick    which work items are buildable now, in order (the lease claims the first free one)
+ *   factoryAsk     the leased item's tier and, for an ask, the understand answer, through `decide`
+ *   factoryBuild   the builder hook, in the worktree, unless understand said not to build
+ *   factoryCheck   the check hook (or the box's `factory.check`), with its evidence on each criterion
+ *   factoryRecord  the outcome: done (amended, proposals added, committed with chant's trailers),
+ *                  dropped (committed), redraft or ask (nothing), or not_done (kept by the run)
+ *
+ * `factoryOp` in `../factory.ts` declares them in that order. An open
+ * question in `factoryAsk` stops the run waiting, as `decide` does.
+ *
+ * Commands run with no shell, split as `box publish` splits a publisher, and
+ * asynchronously, so the lease heartbeat keeps running while a builder works.
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { liveRunEnv } from "../run-live.js";
+/** Whether the declared kind file `file` is the one `kind` names, as a path from `cwd` (such as ../work/work.kind.mjs) or a trailing part of it. */
+function sameKind(file, kind, cwd) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    };
+    return real(resolve(cwd, kind)) === real(file) || file.endsWith(kind.replace(/^(\.\.?\/)+/, ""));
+}
+/** The work kind's items and the box's intent, read through the read contract. */
+/** The contract an item's own field names, when the kind links no contract kind: its state is unknown to chant. */
+function contractField(data, field) {
+    const value = data?.[field ?? "contract"];
+    return typeof value === "string" && value.trim() !== "" ? { id: value.trim(), state: null } : null;
+}
+async function readWork(cwd, kind) {
+    const { declaredKindFiles, queryDeclaredRecords } = await import("../../workspace/records-cli.js");
+    const { loadRecordKind } = await import("../../workspace/records.js");
+    const files = declaredKindFiles(cwd);
+    const set = await queryDeclaredRecords(files, { cwd });
+    let found;
+    const decisionStates = new Map();
+    for (const [i, doc] of set.kinds.entries()) {
+        if ("error" in doc)
+            continue;
+        const loaded = await loadRecordKind(files[i].file, cwd);
+        if (!loaded.kind.work) {
+            for (const r of doc.records)
+                if (r.id)
+                    decisionStates.set(r.id, { state: r.state, rank: r.state ? (loaded.kind.approval?.[r.state] ?? 0) : 0 });
+            continue;
+        }
+        if (found || (kind !== undefined && !sameKind(files[i].file, kind, cwd)))
+            continue;
+        const work = loaded.kind.work;
+        const states = loaded.kind.states ?? [];
+        const items = new Map();
+        for (const r of doc.records) {
+            if (r.id === null)
+                continue;
+            const data = r.data;
+            const tier = work.tier ? data?.[work.tier.field] : undefined;
+            items.set(r.id, {
+                id: r.id,
+                path: r.path,
+                state: r.state,
+                openState: work.open,
+                proposedState: states[0] !== undefined && states[0] !== work.open ? states[0] : null,
+                ready: r.ready ?? false,
+                data,
+                tier: typeof tier === "string" ? tier : null,
+                // The kind's contract link, else the item's own contract field (#3503): a kind whose contracts aren't
+                // a chant record kind yet, such as studio's markdown contracts, still names the contract an item builds.
+                contract: r.contract ?? contractField(data, work.contract?.field),
+                warnings: r.warnings.map((w) => w.code),
+                answers: (r.answers ?? []).map((a) => ({ id: a.id, point: a.point, state: a.state, answer: a.answer })),
+                leased: !!r.lease,
+                acceptance: (r.acceptance?.criteria ?? []).map((c) => ({ id: c.id, verification: c.verification, met: c.met })),
+            });
+        }
+        found = { kindFile: files[i].file, kindName: loaded.kind.name, work, states, stateField: loaded.kind.stateField ?? "state", items, intentDecided: null };
+    }
+    if (!found)
+        throw new Error("the factory reads a work kind, and the declaration names none");
+    // The box's intent (#2850): while the decision a box block names is not approved, nothing is picked.
+    const { readDeclaration } = await import("../../workspace/declaration.js");
+    const { locateWorkspace } = await import("../../workspace/which-chant.js");
+    const intents = readDeclaration(locateWorkspace(cwd).tree).members.map((m) => m.box?.intent).filter((x) => typeof x === "string");
+    if (intents.length > 0)
+        found.intentDecided = intents.every((id) => (decisionStates.get(id)?.rank ?? 0) > 0);
+    return found;
+}
+async function gitOut(args, cwd) {
+    const r = await run(["git", ...args], cwd, {});
+    return { ok: r.code === 0, out: r.stdout.trim() };
+}
+/**
+ * A record path from the repository's top: records --json reports paths from
+ * the repository root, but outside the process's own directory that report can
+ * come back relative to the process instead, so it is resolved and made relative again.
+ */
+async function fromTop(cwd, path) {
+    if (!path.startsWith("../"))
+        return path;
+    const top = (await gitOut(["rev-parse", "--show-toplevel"], cwd)).out;
+    try {
+        return relative(realpathSync(top), realpathSync(resolve(process.cwd(), path))).split(sep).join("/");
+    }
+    catch {
+        return path;
+    }
+}
+/** The item as its work branch holds it: the state there, and whether the branch is in HEAD. Null when there is no branch. */
+async function branchState(cwd, id, path) {
+    const ref = `refs/heads/chant/work/${id}`;
+    if (!(await gitOut(["rev-parse", "--verify", "-q", ref], cwd)).ok)
+        return null;
+    const shown = await gitOut(["show", `${ref}:${await fromTop(cwd, path)}`], cwd);
+    let state = null;
+    if (shown.ok) {
+        const { parseFrontMatter } = await import("../../workspace/records.js");
+        const fm = parseFrontMatter(shown.out);
+        if (fm.ok && typeof fm.value.state === "string")
+            state = fm.value.state;
+    }
+    const applied = (await gitOut(["merge-base", "--is-ancestor", ref, "HEAD"], cwd)).ok;
+    return { state, applied };
+}
+/** The points the workspace declares, by name, or an empty set when it declares none. */
+async function declaredPoints(cwd) {
+    try {
+        const { workspacePoints } = await import("../../workspace/points-cli.js");
+        const doc = await workspacePoints({ cwd });
+        return "error" in doc ? new Set() : new Set(doc.points.map((p) => p.name));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** The question a point would ask about the item as it is now, without writing anything; null when it can't be read. */
+async function dryQuestion(cwd, point, id) {
+    try {
+        const { workspacePoints } = await import("../../workspace/points-cli.js");
+        const doc = await workspacePoints({ cwd });
+        if ("error" in doc)
+            return null;
+        const p = doc.points.find((x) => x.name === point);
+        if (!p)
+            return null;
+        const { readInputs } = await import("../decide-read-inputs.js");
+        const { inputs } = await readInputs(p.inputs.map((i) => i.name), { "work-item": id }, cwd);
+        const { askPoint } = await import("../../workspace/decide.js");
+        const out = await askPoint({ cwd, point, inputs, subject: id, dryRun: true });
+        // Only a question already asked holds an item: one nobody asked yet is what the run asks.
+        if ("error" in out || !out.reused)
+            return null;
+        return { state: out.question.state, answer: out.question.answer };
+    }
+    catch {
+        return null;
+    }
+}
+async function contextFor(cwd, item, intentDecided, points) {
+    const { workHistory } = await import("../../workspace/work-cli.js");
+    const h = await workHistory({ id: item.id, cwd });
+    const claims = "error" in h ? [] : h.claims.map((c) => ({ token: c.token, ended: c.ended, outcome: c.release?.outcome ?? null, attempt: c.attempt }));
+    const attempts = "error" in h ? { exhausted: false } : { exhausted: h.attempts.exhausted };
+    const { isAsk, TIER_POINT, UNDERSTAND_POINT } = await import("../../workspace/factory-rules.js");
+    return {
+        intentDecided,
+        claims,
+        attempts,
+        branch: await branchState(cwd, item.id, item.path),
+        questions: {
+            tier: item.tier === null && points.has(TIER_POINT) ? await dryQuestion(cwd, TIER_POINT, item.id) : null,
+            understand: isAsk(item.data) && points.has(UNDERSTAND_POINT) ? await dryQuestion(cwd, UNDERSTAND_POINT, item.id) : null,
+        },
+    };
+}
+/** Run argv in cwd, without a shell, asynchronously. */
+function run(argv, cwd, env) {
+    return new Promise((settle) => {
+        // The run's activity file, as a shell step gets it, so a builder's lines reach its in-flight record (#3637).
+        const child = spawn(argv[0], argv.slice(1), { cwd, env: { ...process.env, ...liveRunEnv(), ...env }, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (b) => (stdout += b.toString("utf8")));
+        // A hook's stderr is its log: it goes to the run's log as it comes, as a shell step's does.
+        child.stderr.on("data", (b) => {
+            stderr += b.toString("utf8");
+            process.stderr.write(b);
+        });
+        child.on("error", (err) => settle({ code: null, stdout, stderr: `${stderr}${err.message}` }));
+        child.on("close", (code) => settle({ code, stdout, stderr }));
+    });
+}
+/** The last line of `stdout` that is a JSON object, or null. */
+function lastJson(stdout) {
+    const lines = stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const v = JSON.parse(lines[i]);
+            if (v !== null && typeof v === "object" && !Array.isArray(v))
+                return v;
+        }
+        catch {
+            // Not this line.
+        }
+    }
+    return null;
+}
+/**
+ * Start the build from the checkout's HEAD (#382). A branch behind HEAD moves up to it; one with
+ * commits HEAD doesn't have, such as work an earlier run left under a lease it lost, has them kept
+ * at refs/chant/kept/<item>/earlier-<commit> first, so no attempt builds on another's work unasked.
+ */
+async function freshStart(cwd, worktree, id) {
+    const head = (await gitOut(["rev-parse", "HEAD"], await checkoutRoot(cwd))).out;
+    const tip = (await gitOut(["rev-parse", "HEAD"], worktree)).out;
+    if (!head || !tip || head === tip)
+        return;
+    if (!(await gitOut(["merge-base", "--is-ancestor", tip, head], worktree)).ok) {
+        await gitOut(["update-ref", `refs/chant/kept/${id}/earlier-${tip.slice(0, 12)}`, tip], worktree);
+    }
+    await gitOut(["reset", "-q", "--hard", head], worktree);
+}
+/**
+ * The checkout's copy of the item, carried into the worktree when the worktree's differs or is missing
+ * (#382): an item written in the checkout and not committed yet, such as the box's first build, or an
+ * ask its author rewrote, is the one the run builds, as the points were asked about it.
+ */
+async function carryItem(cwd, worktree, id) {
+    const { copyFileSync, existsSync, readFileSync } = await import("node:fs");
+    const there = (await readWork(cwd)).items.get(id);
+    if (!there)
+        return;
+    const checkout = await checkoutRoot(cwd);
+    const rel = await fromTop(cwd, there.path);
+    const from = join(checkout, ...rel.split("/"));
+    const to = join(worktree, ...rel.split("/"));
+    if (!existsSync(from))
+        return;
+    if (existsSync(to) && readFileSync(to).equals(readFileSync(from)))
+        return;
+    mkdirSync(dirname(to), { recursive: true });
+    copyFileSync(from, to);
+}
+async function words(command) {
+    const { splitCommand } = await import("../../workspace/box-publish.js");
+    return splitCommand(command);
+}
+function leaseOf(lease, step) {
+    if (!lease || typeof lease.item !== "string" || typeof lease.token !== "string")
+        throw new Error(`${step} runs under the factory Op's work lease: pass workLeaseOutput() as lease`);
+    if (!lease.worktree)
+        throw new Error(`${step} needs the run's worktree: the factory Op changes the checkout, so its lease makes one`);
+    return lease;
+}
+const today = () => new Date().toISOString().slice(0, 10);
+/** Amend `id` in `cwd` through chant, refusing on any write error. */
+async function amend(cwd, kindFile, id, fields) {
+    const { amendRecord } = await import("../../workspace/records-write.js");
+    const doc = await amendRecord({ kind: kindFile, id, fields: JSON.stringify(fields), cwd });
+    if ("error" in doc)
+        throw new Error(`the factory could not amend ${id}: ${doc.error.code}: ${doc.error.message}`);
+}
+/** The kind file as seen from the worktree: the same path under the worktree when it sits in the checkout. */
+function inWorktree(kindFile, checkout, worktree) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    };
+    const [file, top, tree] = [real(kindFile), real(checkout), real(worktree)];
+    // Read from the worktree already (it sits under the checkout's .git), or outside the checkout: as it is.
+    if (file.startsWith(`${tree}/`) || !file.startsWith(`${top}/`))
+        return file;
+    return join(tree, file.slice(top.length + 1));
+}
+async function checkoutRoot(cwd) {
+    return (await gitOut(["rev-parse", "--show-toplevel"], cwd)).out || cwd;
+}
+/** Commit everything in the worktree with chant's trailers (ws-075). Null when there was nothing to commit. */
+async function commitAll(worktree, subject, item, kindName, token, runId, extra = {}) {
+    await gitOut(["add", "-A"], worktree);
+    if ((await gitOut(["diff", "--cached", "--quiet"], worktree)).ok)
+        return null;
+    const { formatChantTrailers } = await import("../../workspace/trailers.js");
+    const records = [`${kindName}:${item}`, ...(extra.records ?? []).filter((r) => r !== `${kindName}:${item}`)];
+    const trailers = formatChantTrailers({ ...(extra.agent ? { agent: extra.agent } : {}), lease: token, ...(runId ? { run: runId } : {}), records });
+    const r = await run(["git", "-c", "commit.gpgsign=false", "commit", "-q", "--no-verify", "-m", subject, ...(extra.body ? ["-m", extra.body] : []), "-m", trailers.join("\n")], worktree, {});
+    if (r.code !== 0)
+        throw new Error(`the factory could not commit ${item}: ${r.stderr.trim()}`);
+    return (await gitOut(["rev-parse", "HEAD"], worktree)).out;
+}
+// ── the activities ───────────────────────────────────────────────────────────
+/** Which work items are buildable now (#3406 rule 1): those that name a contract, asks and intent builds (#3503). */
+export async function factoryPick(args = {}) {
+    const cwd = args.cwd ?? process.cwd();
+    const { pickable, readyKey } = await import("../../workspace/factory-rules.js");
+    const w = await readWork(cwd, args.kind);
+    const points = await declaredPoints(cwd);
+    const out = { candidates: [], held: [], keys: [] };
+    for (const item of w.items.values()) {
+        if (item.state !== null && item.state !== item.openState && item.state !== item.proposedState)
+            continue;
+        const ctx = await contextFor(cwd, item, w.intentDecided, points);
+        const verdict = pickable(item, ctx);
+        if (verdict.ok) {
+            out.candidates.push(item.id);
+            out.keys.push(readyKey(item, ctx, item.data));
+        }
+        else {
+            out.held.push({ item: item.id, hold: verdict.hold, message: verdict.message });
+            // Said in the run's log too, so whoever reads why nothing was built sees it.
+            console.error(`factoryPick: skipped ${item.id}: ${verdict.message}`);
+        }
+    }
+    return out;
+}
+/**
+ * The steward's ready step for the factory Op (#382, `factoryReady` in ../factory.ts): one key per
+ * buildable item, naming the state it was read in, so a person's answer, a retry or a changed item
+ * starts a run and the same state does not start another. Only reads.
+ */
+export async function factoryReady(args = {}) {
+    const cwd = args.cwd ?? process.cwd();
+    const keys = (await factoryPick({ cwd, ...(args.kind !== undefined ? { kind: args.kind } : {}) })).keys;
+    if (args.also) {
+        const r = await run(await words(args.also), cwd, {});
+        if (r.code !== 0)
+            throw new Error(`factoryReady: ${args.also} exited ${r.code}: ${r.stderr.trim().split("\n").slice(-3).join(" ")}`);
+        let more;
+        try {
+            more = JSON.parse(r.stdout.trim().split("\n").pop() ?? "[]");
+        }
+        catch {
+            throw new Error(`factoryReady: ${args.also} printed no JSON list on its last line`);
+        }
+        if (!Array.isArray(more))
+            throw new Error(`factoryReady: ${args.also} printed no JSON list on its last line`);
+        for (const k of more)
+            keys.push(typeof k === "string" ? k : JSON.stringify(k));
+    }
+    return keys;
+}
+/** The leased item's tier and understand answer (#3406 rules 2 and 3). An open question stops the run waiting. */
+export async function factoryAsk(args) {
+    const cwd = args.cwd ?? process.cwd();
+    if (!args.lease?.item)
+        throw new Error("factoryAsk runs under the factory Op's work lease: pass workLeaseOutput() as lease");
+    const id = args.lease.item;
+    const { isAsk, understandOutcome, TIER_POINT, UNDERSTAND_POINT } = await import("../../workspace/factory-rules.js");
+    const w = await readWork(cwd, args.kind);
+    const item = w.items.get(id);
+    if (!item)
+        throw new Error(`no record of the work kind has id ${id}`);
+    const points = await declaredPoints(cwd);
+    const { decide } = await import("./decide.js");
+    const ask = isAsk(item.data);
+    let understand = null;
+    if (ask && points.has(UNDERSTAND_POINT))
+        understand = String((await decide({ point: UNDERSTAND_POINT, read: { "work-item": id }, subject: id, cwd, ...(args.backends ? { backends: args.backends } : {}) })).answer);
+    else if (ask)
+        understand = "proceed";
+    const outcome = understandOutcome(understand);
+    let tier = item.tier;
+    if (tier === null && outcome === null) {
+        tier = points.has(TIER_POINT) ? String((await decide({ point: TIER_POINT, read: { "work-item": id }, subject: id, cwd, ...(args.backends ? { backends: args.backends } : {}) })).answer) : (w.work.tier?.tiers[0] ?? "small");
+    }
+    return { item: id, ask, tier: tier ?? w.work.tier?.tiers[0] ?? "small", understand, outcome };
+}
+/** Run the builder hook in the worktree, unless understand said not to build (#3406). */
+export async function factoryBuild(args) {
+    const lease = leaseOf(args.lease, "factoryBuild");
+    const cwd = args.cwd ?? process.cwd();
+    if (args.ask.outcome !== null) {
+        // Nothing is built, but Record still writes the item's outcome (dropped) in the worktree, so an ask
+        // that lives only in the checkout, as every ask written from a surface does, is carried there first.
+        await carryItem(cwd, lease.worktree, lease.item);
+        return { ran: false, finished: false, exitCode: null, reverted: [], note: `understand answered ${args.ask.understand}: nothing is built`, report: null };
+    }
+    // A kept ask opens before it is built: chant writes the state in the worktree, so it goes with the build.
+    await freshStart(cwd, lease.worktree, lease.item);
+    await carryItem(cwd, lease.worktree, lease.item);
+    const w = await readWork(lease.worktree);
+    const item = w.items.get(lease.item);
+    if (item && item.proposedState !== null && item.state === item.proposedState) {
+        await amend(lease.worktree, inWorktree(w.kindFile, await checkoutRoot(cwd), lease.worktree), lease.item, { [w.stateField]: item.openState });
+    }
+    // An ask's builder writes its plan as the item's acceptance criteria and changes nothing else in it
+    // (#3406, studio#382): the item is kept as it was before the builder ran, and put back if it changed.
+    const { isAsk } = await import("../../workspace/factory-rules.js");
+    const opened = (await readWork(lease.worktree)).items.get(lease.item);
+    const acceptance = w.work.acceptance?.field ?? "acceptance";
+    const guarded = opened && isAsk(opened.data) ? { path: join(lease.worktree, ...(await fromTop(lease.worktree, opened.path)).split("/")), rel: await fromTop(lease.worktree, opened.path), data: opened.data } : null;
+    const { readFileSync, writeFileSync: write } = await import("node:fs");
+    const bytes = guarded ? readFileSync(guarded.path) : null;
+    const r = await run(await words(args.builder), lease.worktree, {
+        FACTORY_ITEM: lease.item,
+        FACTORY_TIER: args.ask.tier,
+        FACTORY_TOKEN: lease.token,
+        FACTORY_HOLDER: lease.holder,
+        FACTORY_WORKTREE: lease.worktree,
+        ...(args.context ? { FACTORY_CONTEXT: args.context } : {}),
+    });
+    // The builder's report: `reverted` lists what its guard put back, and `ok: false` says it did not finish though it exited 0.
+    const report = lastJson(r.stdout);
+    const reverted = Array.isArray(report?.reverted) ? report.reverted.filter((x) => typeof x === "string") : [];
+    if (guarded && bytes) {
+        const now = (await readWork(lease.worktree)).items.get(lease.item);
+        const rest = (data) => Object.fromEntries(Object.entries(data ?? {}).filter(([k]) => k !== acceptance).sort(([a], [b]) => a.localeCompare(b)));
+        const before = rest(guarded.data);
+        const after = now ? rest(now.data) : null;
+        if (!after || JSON.stringify(after) !== JSON.stringify(before)) {
+            const changed = after ? [...new Set([...Object.keys(before), ...Object.keys(after)])].filter((k) => JSON.stringify(before[k]) !== JSON.stringify(after[k])) : [];
+            write(guarded.path, bytes);
+            reverted.push(`${guarded.rel} (${after ? `it changed ${changed.join(", ")}, and only ${acceptance} is the builder's` : "chant no longer reads it"})`);
+        }
+    }
+    const finished = r.code === 0 && report?.ok !== false;
+    const note = typeof report?.note === "string" ? report.note : finished ? "the builder finished" : r.code === 0 ? "the builder reported it did not finish" : `the builder exited ${r.code}: ${r.stderr.trim().split("\n").slice(-3).join(" ")}`;
+    return { ran: true, finished, exitCode: r.code, reverted, note, report };
+}
+/** Run the check and attach its result as evidence to each criterion the factory ticks (#3406 rule 5). */
+export async function factoryCheck(args) {
+    const lease = leaseOf(args.lease, "factoryCheck");
+    // A build whose guard put changes back is not done whatever its check says, so it is not checked.
+    if (!args.build.ran || !args.build.finished || args.build.reverted.length > 0)
+        return { ran: false, ok: false, command: null, evidence: [], log: null, report: null };
+    let command = args.check ?? null;
+    if (command === null) {
+        const { readDeclaration } = await import("../../workspace/declaration.js");
+        const { locateWorkspace } = await import("../../workspace/which-chant.js");
+        command = readDeclaration(locateWorkspace(lease.worktree).tree).members.find((m) => m.box?.factory?.check)?.box?.factory?.check?.run ?? null;
+    }
+    if (command === null)
+        return { ran: false, ok: false, command: null, evidence: [], log: null, report: null };
+    const r = await run(await words(command), lease.worktree, {
+        FACTORY_ITEM: lease.item,
+        FACTORY_TOKEN: lease.token,
+        FACTORY_HOLDER: lease.holder,
+        FACTORY_WORKTREE: lease.worktree,
+        FACTORY_BUILD: JSON.stringify(args.build.report ?? {}),
+    });
+    // A check may report each criterion's own result as its last JSON line, { "criteria": { "AC-1": "pass", ... } }:
+    // then each criterion is ticked by its own result, and one it names no result for gets none.
+    const report = lastJson(r.stdout);
+    const ok = r.code === 0 && report?.ok !== false;
+    const per = report?.criteria && typeof report.criteria === "object" ? report.criteria : null;
+    const log = `.chant/factory/${lease.item}/check.log`;
+    const abs = join(lease.worktree, ...log.split("/"));
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, `$ ${command}\nexit ${r.code}\n\n${r.stdout}${r.stderr ? `\n--- stderr ---\n${r.stderr}` : ""}`);
+    const w = await readWork(lease.worktree);
+    const item = w.items.get(lease.item);
+    const evidence = [];
+    const { attachWorkEvidence } = await import("../../workspace/work-evidence.js");
+    for (const c of item?.acceptance ?? []) {
+        if (c.verification === "manual" || c.verification === "runtime")
+            continue;
+        const own = per ? per[c.id] : undefined;
+        if (per && own !== "pass" && own !== "fail")
+            continue;
+        const result = per ? own : ok ? "pass" : "fail";
+        const out = await attachWorkEvidence({ cwd: lease.worktree, item: lease.item, holder: lease.holder, token: lease.token, criterion: c.id, result, title: `factory check: ${command}`, path: log });
+        if (!("error" in out))
+            evidence.push(c.id);
+    }
+    return { ran: true, ok, command, evidence, log, report };
+}
+/** The decisions a done build proposes it implements, from the intent graph of each path it changed (studio#243). */
+async function proposals(worktree, base, already) {
+    const { proposeImplements } = await import("../../workspace/factory-rules.js");
+    // What the build changed since the base, the files it added among them: they are untracked until Record commits.
+    const tracked = (await gitOut(["diff", "--name-only", base], worktree)).out.split("\n");
+    const added = (await gitOut(["ls-files", "--others", "--exclude-standard"], worktree)).out.split("\n");
+    const changed = [...new Set([...tracked, ...added])].filter((p) => p && !p.startsWith(".chant/")).sort();
+    const { intentGraph } = await import("../../workspace/intent.js");
+    const rows = [];
+    for (const path of changed.slice(0, 20)) {
+        const { doc } = await intentGraph({ cwd: worktree, region: path });
+        if ("error" in doc)
+            continue;
+        const decisions = new Map(doc.nodes.filter((n) => n.kind === "decision").map((n) => [n.id, n]));
+        const out = [];
+        for (const e of doc.edges) {
+            if (e.kind !== "constrains")
+                continue;
+            const d = decisions.get(e.from);
+            if (d)
+                out.push({ id: d.record, state: d.state, granularity: e.granularity ?? "" });
+        }
+        rows.push({ path, decisions: out });
+    }
+    return proposeImplements(rows, already);
+}
+/** Record the outcome on the item's branch and name it for the lease's release (#3406 rules 4 to 6, 8). */
+export async function factoryRecord(args) {
+    const result = await recordOutcome(args);
+    if (args.after) {
+        const lease = leaseOf(args.lease, "factoryRecord");
+        const r = await run(await words(args.after), lease.worktree, {
+            FACTORY_ITEM: lease.item,
+            FACTORY_TOKEN: lease.token,
+            FACTORY_HOLDER: lease.holder,
+            FACTORY_WORKTREE: lease.worktree,
+            FACTORY_OUTCOME: result.outcome,
+            FACTORY_COMMIT: result.commit ?? "",
+            FACTORY_REASON: result.reason ?? "",
+            FACTORY_BUILD: JSON.stringify(args.build?.report ?? {}),
+            FACTORY_CHECK: JSON.stringify(args.check?.report ?? {}),
+        });
+        if (r.code !== 0)
+            console.error(`factoryRecord: the after hook exited ${r.code}: ${r.stderr.trim().split("\n").slice(-3).join(" ")}`);
+    }
+    return result;
+}
+/**
+ * What the hooks' reports add to the done commit's trailers (ws-075): `chantAgent`, the agent session
+ * a builder ran as, for Chant-Agent, and `records`, more `<kind>:<id>` records the build carries, such
+ * as the contract it built and the evidence its check wrote, from the builder's and the check's reports.
+ */
+function trailerExtras(build, check) {
+    const records = [];
+    for (const r of [build?.records, check?.records])
+        if (Array.isArray(r))
+            for (const x of r)
+                if (typeof x === "string" && /^[a-z][a-z0-9-]*:[A-Za-z0-9][A-Za-z0-9._-]*$/.test(x) && !records.includes(x))
+                    records.push(x);
+    const agent = typeof build?.chantAgent === "string" && build.chantAgent.trim() !== "" ? build.chantAgent.trim() : undefined;
+    return { ...(agent ? { agent } : {}), records };
+}
+/** The run id a builder's report names for the Chant-Run trailer: `run.id` or `run`, or undefined. */
+function runIdOf(report) {
+    const r = report?.run;
+    if (typeof r === "string" && r !== "")
+        return r;
+    const id = r && typeof r === "object" ? r.id : undefined;
+    return typeof id === "string" && id !== "" ? id : undefined;
+}
+async function recordOutcome(args) {
+    const lease = leaseOf(args.lease, "factoryRecord");
+    const cwd = args.cwd ?? process.cwd();
+    const root = await checkoutRoot(cwd);
+    const w = await readWork(lease.worktree);
+    const kindFile = inWorktree(w.kindFile, root, lease.worktree);
+    const item = w.items.get(lease.item);
+    if (!item)
+        throw new Error(`no record of the work kind has id ${lease.item} in the worktree`);
+    const none = { commit: null, implementsProposed: [] };
+    if (args.ask.outcome === "redraft" || args.ask.outcome === "ask")
+        return { outcome: args.ask.outcome, reason: `understand answered ${args.ask.understand}`, ...none };
+    if (args.ask.outcome === "dropped") {
+        await amend(lease.worktree, kindFile, lease.item, { [w.stateField]: "dropped", [w.work.closedOn]: today() });
+        const commit = await commitAll(lease.worktree, `${lease.item}: dropped, the understand point refused it`, lease.item, w.kindName, lease.token);
+        return { outcome: "dropped", reason: "understand answered refuse", commit, implementsProposed: [] };
+    }
+    const { doneVerdict } = await import("../../workspace/factory-rules.js");
+    const verdict = doneVerdict(args.build, args.check, item.acceptance);
+    if (!verdict.done) {
+        // The attempt is committed with why it is not done and chant's trailers, so the kept attempt the run
+        // makes of it (refs/chant/kept/<item>/<token>) says so and joins to the item and the lease.
+        const kept = await commitAll(lease.worktree, `${lease.item}: not done`, lease.item, w.kindName, lease.token, runIdOf(args.build.report), {
+            ...trailerExtras(args.build.report, args.check.report),
+            body: `Not done: ${verdict.reason}`,
+        }).catch(() => null);
+        return { outcome: "not_done", reason: verdict.reason, commit: kept, implementsProposed: [] };
+    }
+    const base = (await gitOut(["merge-base", "HEAD", (await gitOut(["rev-parse", "HEAD"], root)).out], lease.worktree)).out;
+    const already = Array.isArray(item.data?.[w.work.implements]) ? item.data[w.work.implements].filter((x) => typeof x === "string") : [];
+    const proposed = base ? await proposals(lease.worktree, base, already) : [];
+    await amend(lease.worktree, kindFile, lease.item, {
+        [w.stateField]: w.work.done,
+        [w.work.closedOn]: today(),
+        result: { lease: lease.token },
+        ...(proposed.length > 0 ? { [w.work.implements]: [...already, ...proposed.map((p) => p.decision)], implements_proposed: proposed } : {}),
+    });
+    const title = typeof item.data?.title === "string" ? item.data.title : lease.item;
+    const commit = await commitAll(lease.worktree, `${lease.item}: ${title}`, lease.item, w.kindName, lease.token, runIdOf(args.build.report), trailerExtras(args.build.report, args.check.report));
+    return { outcome: "done", reason: null, commit, implementsProposed: proposed };
+}