@intentius/chant 0.124.13 → 0.124.15

package/dist/workspace/factory-rules.js

@@ -0,0 +1,175 @@
+/**
+ * The factory's rules (#3406, ws-087): what every orchestrator of a factory
+ * must agree on, as pure functions over what the read contract prints. The
+ * reference Op (`../op/factory.ts`) runs them; an orchestrator supplies only
+ * execution (the builder, the context, the check).
+ *
+ * - Readiness ({@link pickable}): the item names a contract, or is an ask or
+ *   the box's first build from its intent ({@link isAsk}); a work item a
+ *   person wrote by hand or a finding's triage item stays with its author
+ *   (#3503). On top of the work kind's `ready`, the box's intent is decided,
+ *   a contract the item builds is approved and in force,
+ *   the item is under its attempt limit, it is not done and waiting to be
+ *   applied on its branch, its slice-tier and understand questions are not
+ *   open, an understand answer of redraft or ask holds it, and a failed last
+ *   build holds it until a person asks for a retry ({@link retryState}).
+ * - The understand point's answers ({@link understandOutcome}): proceed
+ *   builds; refuse drops the item on its branch; redraft and ask build
+ *   nothing and leave it for its author. Each maps to a lease outcome, and
+ *   only a build's outcome counts as an attempt (#3147).
+ * - Done ({@link doneVerdict}): the builder finished, the check ran and
+ *   passed, and every criterion the factory may tick has passing evidence. A
+ *   criterion verified `manual` or `runtime` is not the factory's to tick, so
+ *   an item with one is not done by the factory.
+ * - Retry ({@link retryState}): a failed build is never tried again on its
+ *   own. A person's request, the item's `retry: { after, by, at }`, names the
+ *   lease token of the failed build it follows, so one request starts one run.
+ * - Implements ({@link proposeImplements}): a build recorded done proposes
+ *   each decision in force that constrains, by path, a path it changed.
+ */
+/** The decision point that gates every build of a person's ask (#3150). */
+export const UNDERSTAND_POINT = "understand";
+/** The decision point that picks a builder tier (ws-057, #3150). */
+export const TIER_POINT = "slice-tier";
+/** What the understand point answers. */
+export const UNDERSTAND_ANSWERS = ["proceed", "redraft", "ask", "refuse"];
+/** Why an item is not picked. Closed. */
+export const FACTORY_HOLDS = [
+    "not-ready",
+    "no-contract",
+    "intent-undecided",
+    "contract-not-approved",
+    "attempts-exhausted",
+    "awaiting-retry",
+    "built-not-applied",
+    "dropped-on-branch",
+    "question-open",
+    "redraft-or-ask",
+    "leased",
+];
+/** Whether a work item is a person's ask: its source names what they said, or it is the box's first build from its intent. */
+export function isAsk(data) {
+    const source = data?.source;
+    return !!(source && typeof source === "object" && (source.ask || source.intent));
+}
+/** The retry request on an item: `retry: { after, by, at }`, or null. */
+export function retryRequest(data) {
+    const r = data?.retry;
+    if (!r || typeof r !== "object" || typeof r.after !== "string" || typeof r.by !== "string")
+        return null;
+    return { after: r.after, by: r.by, at: typeof r.at === "string" ? r.at : "" };
+}
+/**
+ * Whether a person may ask for item `data`'s failed build to run again: the
+ * last claim is a failed build, nobody holds the lease, and attempts remain.
+ * `asked` says a request naming that build is already on the item.
+ */
+export function retryState(data, claims, attempts, leased) {
+    if (leased)
+        return { possible: false, reason: "held", message: "someone holds the item's lease now" };
+    const last = claims.at(-1);
+    if (!last || !last.attempt)
+        return { possible: false, reason: "no-failed-build", message: "the item's last claim is not a failed build, so there is nothing to retry" };
+    if (attempts.exhausted)
+        return { possible: false, reason: "attempts-exhausted", message: "the item has used every attempt its limit allows, so it is left to people" };
+    const asked = retryRequest(data)?.after === last.token;
+    return { possible: true, after: last.token, asked };
+}
+/** The lease outcome an understand answer leads to: null for proceed, which builds. */
+export function understandOutcome(answer) {
+    if (answer === "refuse")
+        return "dropped";
+    if (answer === "redraft" || answer === "ask")
+        return answer;
+    return null;
+}
+const OPEN = new Set(["escalated", "proposed"]);
+/**
+ * Whether the factory picks `item` now, or why not. The factory builds an
+ * item that names a contract, an ask, or an intent build, as studio's queue
+ * did (#3503); any other item is its author's. Asks are candidates while
+ * proposed as well as open; any other item only when the work kind reads it
+ * ready.
+ */
+export function pickable(item, ctx) {
+    const no = (hold, message) => ({ ok: false, hold, message });
+    if (ctx.intentDecided === false)
+        return no("intent-undecided", "the box's intent is not decided yet, so nothing is picked");
+    if (item.leased)
+        return no("leased", `${item.id} is leased`);
+    const ask = isAsk(item.data);
+    if (!item.contract && !ask)
+        return no("no-contract", `${item.id} names no contract and is not an ask or an intent build, so it is left to its author`);
+    const candidate = item.ready || (ask && item.proposedState !== null && item.state === item.proposedState);
+    if (!candidate)
+        return no("not-ready", `${item.id} is ${item.state ?? "in no state"} and not ready`);
+    if (item.contract && (item.warnings.includes("work-contract-undecided") || item.warnings.includes("work-contract-unknown"))) {
+        return no("contract-not-approved", `${item.id} builds ${item.contract.id}, which is not approved and in force`);
+    }
+    if (ctx.branch && !ctx.branch.applied && ctx.branch.state === "done")
+        return no("built-not-applied", `${item.id} is built on its branch and waits to be applied`);
+    if (ctx.branch && !ctx.branch.applied && ctx.branch.state === "dropped")
+        return no("dropped-on-branch", `${item.id} was dropped on its branch`);
+    if (ctx.attempts.exhausted)
+        return no("attempts-exhausted", `${item.id} has used every attempt, so it is left to people`);
+    const last = ctx.claims.at(-1);
+    if (last?.attempt && retryRequest(item.data)?.after !== last.token) {
+        return no("awaiting-retry", `${item.id}'s last build failed; a person asks for another with retry.after: ${last.token}`);
+    }
+    for (const [name, q] of [[TIER_POINT, item.tier === null ? ctx.questions.tier : null], [UNDERSTAND_POINT, ask ? ctx.questions.understand : null]]) {
+        if (q && OPEN.has(q.state))
+            return no("question-open", `${item.id}'s ${name} question is ${q.state}; a person answers it first`);
+    }
+    const u = ask ? ctx.questions.understand : null;
+    if (u && u.state === "answered" && (u.answer === "redraft" || u.answer === "ask")) {
+        return no("redraft-or-ask", `${item.id}'s understand question was answered ${String(u.answer)}; its author changes the item, which asks again`);
+    }
+    return { ok: true };
+}
+/** Whether a build is done, or why not. */
+export function doneVerdict(build, check, criteria) {
+    if (!build.finished)
+        return { done: false, reason: "the builder did not finish" };
+    if (build.reverted.length > 0)
+        return { done: false, reason: `the guard put back what the builder changed out of scope: ${build.reverted.join(", ")}` };
+    if (!check.ran)
+        return { done: false, reason: "no check ran" };
+    if (!check.ok)
+        return { done: false, reason: "the check failed" };
+    const people = criteria.filter((c) => c.verification === "manual" || c.verification === "runtime");
+    if (people.length > 0)
+        return { done: false, reason: `criteria ${people.map((c) => c.id).join(", ")} are verified ${people.map((c) => c.verification).join("/")}, which the factory never ticks` };
+    const unmet = criteria.filter((c) => !c.met);
+    if (unmet.length > 0)
+        return { done: false, reason: `criteria ${unmet.map((c) => c.id).join(", ")} have no passing evidence` };
+    return { done: true };
+}
+/**
+ * The decisions a done build proposes it implements (studio#243): from the
+ * intent graph's `constrains` edges of granularity `path` to each changed
+ * path, the decisions in force, less those the item already implements.
+ */
+export function proposeImplements(changed, already, inForce = ["decided", "ratified"]) {
+    const out = new Map();
+    for (const c of changed) {
+        for (const d of c.decisions) {
+            if (d.granularity !== "path" || d.state === null || !inForce.includes(d.state) || already.includes(d.id))
+                continue;
+            const paths = out.get(d.id) ?? [];
+            if (!paths.includes(c.path))
+                paths.push(c.path);
+            out.set(d.id, paths);
+        }
+    }
+    return [...out].map(([decision, paths]) => ({ decision, paths }));
+}
+/**
+ * The key of the state an item was read in, for a steward's ready step: a
+ * new key is work no run was started for. It names the item, its last claim
+ * and its open questions, so a person's answer to either point is a new key.
+ */
+export function readyKey(item, ctx, data) {
+    const last = ctx.claims.at(-1)?.token ?? "none";
+    const q = (x) => (x ? `${x.state}:${String(x.answer)}` : "-");
+    return `${item.id}@${last}#tier=${q(ctx.questions.tier)}#understand=${q(ctx.questions.understand)}#retry=${retryRequest(data)?.after ?? "-"}`;
+}

package/dist/workspace/generated-files.js

@@ -0,0 +1,92 @@
+/**
+ * Which files are generated, and by what (#2524 D14, #2541).
+ *
+ * One list answers the question for everyone who asks it: the drift check in
+ * `checks/generated.ts` and the lineage lock's `generated` class
+ * (`lineage-lock.ts`). The list is the member's declared `generated` entries
+ * plus the files core registers itself:
+ *
+ * | File                  | Class     |
+ * |-----------------------|-----------|
+ * | `skills/*\/SKILL.md`  | generated, by `chant update` |
+ * | `.mcp.json`           | seed      |
+ * | `.chant/types/`       | ignored: gitignored, never listed |
+ *
+ * A declared entry wins over the implicit rules, so a member can list a
+ * `SKILL.md` it keeps by hand. A hand-written entry is the project's own
+ * file, so the lock classes it `owned`.
+ *
+ * Everything here loads only with the lineage and workspace commands.
+ */
+import { relative, resolve, sep } from "node:path";
+import { findWorkspaceRoot } from "../project-root.js";
+import { isInside, readDeclaration } from "./declaration.js";
+import { memberHolding } from "./record-assets.js";
+import { workingTree } from "./tree.js";
+/** What `chant update` rewrites, registered as implicit generated entries. */
+export const IMPLICIT_GENERATED = [{ glob: "skills/*/SKILL.md", pattern: /^skills\/[^/]+\/SKILL\.md$/, command: "chant update" }];
+/** Written once at init and never again. */
+export const SEED_FILES = [".mcp.json"];
+/** Gitignored output, out of scope for both the lock and the drift check. */
+export const IGNORED_DIRS = [".chant/types"];
+/** The implicit entry `path` matches, if any. */
+export function implicitGenerated(path) {
+    return IMPLICIT_GENERATED.find((i) => i.pattern.test(path));
+}
+/** Class a file by the declared entries first, then by the implicit rules (D14). */
+export function classifyFile(path, declared) {
+    const entry = declared?.get(path);
+    if (entry)
+        return entry.handWritten ? { class: "owned" } : { class: "generated", command: entry.command };
+    if (IGNORED_DIRS.some((d) => path === d || path.startsWith(`${d}/`)))
+        return { class: "ignored" };
+    const implicit = implicitGenerated(path);
+    if (implicit)
+        return { class: "generated", command: implicit.command };
+    if (SEED_FILES.includes(path))
+        return { class: "seed" };
+    return { class: "owned" };
+}
+/**
+ * Every declared generated file of `declaration` that sits under `dir`
+ * (relative to the workspace root, `"."` for all of it), keyed by its path
+ * relative to `dir`.
+ */
+export function declaredFilesUnder(declaration, dir) {
+    const out = new Map();
+    for (const m of declaration.members) {
+        for (const g of m.generated) {
+            const full = m.dir === "." ? g.path : `${m.dir}/${g.path}`;
+            if (!isInside(full, dir))
+                continue;
+            out.set(dir === "." ? full : full.slice(dir.length + 1), { command: g.generator, handWritten: g.handWritten !== null });
+        }
+    }
+    return out;
+}
+/**
+ * Whether a workspace path (from the workspace root) is a generated file:
+ * declared in its member's `generated` entries, or one core registers. The
+ * `generated` of `graph --intent`'s region and file nodes and of `check
+ * --changes`'s paths.
+ */
+export function isGeneratedPath(declaration, path) {
+    const m = declaration.members.find((x) => x.name === memberHolding(path, declaration.members));
+    const dir = m?.dir ?? ".";
+    const rel = dir === "." ? path : path.slice(dir.length + 1);
+    return classifyFile(rel, declaredFilesUnder(declaration, dir)).class === "generated";
+}
+/**
+ * The declared generated files for the absolute directory `absDir`, from the
+ * nearest `chant.workspace.json` above it. Empty when there is none, which is
+ * the plain-project case: only the implicit rules apply. A declaration that
+ * can't be read throws its `WorkspaceReadError`; it is never read as empty.
+ */
+export function declaredFilesFor(absDir) {
+    const found = findWorkspaceRoot(absDir);
+    if (!found)
+        return new Map();
+    const declaration = readDeclaration(workingTree(found.dir));
+    const rel = relative(found.dir, resolve(absDir)).split(sep).join("/");
+    return declaredFilesUnder(declaration, rel === "" ? "." : rel);
+}

package/dist/workspace/glob.js

@@ -0,0 +1,45 @@
+/**
+ * Expand an example group's globs to directories (ws-051).
+ *
+ * The walk goes one path segment at a time, so a glob such as
+ * `lexicons/*\/examples/*` reads only the directories it can match, never the
+ * whole tree. Within a segment, picomatch does the matching; `**` matches zero
+ * or more directories. `node_modules` and dot-directories are never entered
+ * by a wildcard, though a literal segment may name them.
+ */
+// @ts-ignore — picomatch has no types declaration
+import picomatch from "picomatch";
+import { joinPath, skippedDir } from "./tree.js";
+const isLiteral = (segment) => !/[*?[\]{}()!+@]/.test(segment);
+/** Every directory `glob` matches in `tree`, sorted. */
+export function expandGlob(tree, glob) {
+    const segments = glob.split("/");
+    const matchers = segments.map((s) => s === "**" ? "**" : isLiteral(s) ? s : picomatch(s, { dot: false }));
+    const found = new Set();
+    const subdirs = (dir) => (tree.list(dir) ?? []).filter((e) => e.type === "dir" && !skippedDir(e.name)).map((e) => e.name);
+    const walk = (dir, index) => {
+        if (index === matchers.length) {
+            if (dir !== "")
+                found.add(dir);
+            return;
+        }
+        const m = matchers[index];
+        if (m === "**") {
+            walk(dir, index + 1);
+            for (const name of subdirs(dir))
+                walk(joinPath(dir, name), index);
+            return;
+        }
+        if (typeof m === "string") {
+            const next = joinPath(dir, m);
+            if (tree.stat(next) === "dir")
+                walk(next, index + 1);
+            return;
+        }
+        for (const name of subdirs(dir))
+            if (m(name))
+                walk(joinPath(dir, name), index + 1);
+    };
+    walk("", 0);
+    return [...found].sort();
+}

package/dist/workspace/graph-cache.js

@@ -0,0 +1,352 @@
+/**
+ * The per-member cache behind `chant workspace graph` (#2876, ws-059).
+ *
+ * ws-018 made chant the composer for declared workspaces, and a viewer
+ * rereads the composed graph on every refresh. Without a cache every read
+ * starts every member's chant again, so this module keeps each member's
+ * source read on disk and serves it while nothing the read depends on has
+ * changed.
+ *
+ * An entry is served only when every part of its key still matches:
+ *
+ * 1. The read is a source read. A member command line holding `--live`,
+ *    `--overlay` or `--traffic` observes an account, which changes with
+ *    nothing on disk to notice, so it is never cached or even stamped.
+ * 2. The member's stamp ({@link memberStamp}) is unchanged. It covers the
+ *    member's files and the install state its toolchain resolves through.
+ *    With `--at` the tree is the commit's, which never changes, so the commit
+ *    id stands in for the files.
+ * 3. The toolchain is unchanged: the real path of its `bin/chant` and its
+ *    package version, plus its source files when it is a checkout rather
+ *    than an install.
+ * 4. The member's command line and the ambient environment are unchanged,
+ *    since `--env`, build parameters and `buildParams` env mappings all
+ *    reach the answer. A few variables a shell changes on its own are left
+ *    out ({@link VOLATILE_ENV}); any other difference is a miss.
+ *
+ * A stamp that can't be taken caches nothing. So does a stamp that moved
+ * between the start and the end of the read, a member whose read failed, and
+ * a working-tree read whose newest file is younger than
+ * {@link FRESH_WINDOW_MS}: some file systems keep mtimes to the second, so an
+ * edit in the same tick as the read could otherwise hide behind an equal
+ * stamp.
+ *
+ * Entries live outside the workspace, in the user's cache directory
+ * ({@link graphCacheDir}), because a read never changes the workspace it
+ * reads (the conformance kit checks exactly that, #2679). One JSON file per
+ * key, written to a temporary name and renamed into place so concurrent
+ * readers never see half an entry. Each workspace holds at most
+ * {@link MAX_ENTRIES} entries and {@link MAX_BYTES} bytes; the least recently
+ * used go first.
+ *
+ * The key never looks at how a member is read, only at what the read takes
+ * in, so a member read through a generated reader project caches by its own
+ * directory's stamp like any other.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { readMemberIr } from "./compose-graph.js";
+import { memberArgv } from "./member-commands.js";
+/** The version of the entry format. An entry of any other version is a miss. */
+export const CACHE_FORMAT = 1;
+/** Overrides where chant keeps caches: `$CHANT_CACHE_DIR`, else `$XDG_CACHE_HOME/chant`, else `~/.cache/chant`. */
+export const CACHE_DIR_ENV = "CHANT_CACHE_DIR";
+export const MAX_ENTRIES = 512;
+export const MAX_BYTES = 128 * 1024 * 1024;
+/** A working-tree read whose newest file is younger than this is not stored. */
+export const FRESH_WINDOW_MS = 2000;
+/** Member flags that make a read observe an account. Such a read is never cached. */
+export const LIVE_FLAGS = ["--live", "--overlay", "--traffic"];
+/** Environment variables a shell or terminal changes on its own, left out of the key. */
+export const VOLATILE_ENV = [
+    "_",
+    "PWD",
+    "OLDPWD",
+    "SHLVL",
+    "COLUMNS",
+    "LINES",
+    "WINDOWID",
+    /^TERM/,
+    /^ITERM_/,
+    /^TMUX/,
+    /^SSH_/,
+    /^VSCODE_/,
+    /^npm_/,
+    /^VITEST/,
+    /^__/,
+    CACHE_DIR_ENV,
+];
+/** Directories no stamp walks into, whatever their depth. */
+const SKIPPED = new Set(["node_modules", "dist", ".git"]);
+/** Files, looked up from a member's directory to the file-system root, whose change means the install moved. */
+const INSTALL_FILES = [
+    join("node_modules", ".package-lock.json"),
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "bun.lock",
+    "bun.lockb",
+];
+/** Whether a member command line is a source read, and so may be cached. */
+export function isCacheableArgv(argv) {
+    return !argv.some((a) => LIVE_FLAGS.some((f) => a === f || a.startsWith(`${f}=`)));
+}
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/**
+ * Every regular file under `abs`, as `<relative path>\0<mtime ms>\0<size>`
+ * lines sorted by path. Directories named `node_modules`, `dist` or `.git`,
+ * every dot-directory, and the directories in `exclude` (relative to `abs`)
+ * are left out. Throws when the directory can't be read.
+ */
+function fileLines(abs, exclude) {
+    const excluded = new Set(exclude.map((e) => resolve(abs, e)));
+    const lines = [];
+    let newest = 0;
+    const walk = (at) => {
+        for (const e of readdirSync(at, { withFileTypes: true })) {
+            const path = join(at, e.name);
+            if (e.isDirectory()) {
+                if (SKIPPED.has(e.name) || e.name.startsWith(".") || excluded.has(path))
+                    continue;
+                walk(path);
+            }
+            else if (e.isFile()) {
+                const st = statSync(path);
+                lines.push(`${relative(abs, path).split(sep).join("/")}\0${st.mtimeMs}\0${st.size}`);
+                if (st.mtimeMs > newest)
+                    newest = st.mtimeMs;
+            }
+        }
+    };
+    walk(abs);
+    lines.sort();
+    return { lines, newest };
+}
+/** The install files found from `abs` up to the file-system root, with their mtime and size. */
+function installLines(abs) {
+    const lines = [];
+    for (let dir = resolve(abs);; dir = dirname(dir)) {
+        for (const name of INSTALL_FILES) {
+            const path = join(dir, name);
+            try {
+                const st = statSync(path);
+                if (st.isFile())
+                    lines.push(`${path}\0${st.mtimeMs}\0${st.size}`);
+            }
+            catch {
+                // Not here.
+            }
+        }
+        if (dirname(dir) === dir)
+            break;
+    }
+    return lines;
+}
+/**
+ * A member's stamp: its files and the install state around it. `abs` is the
+ * member's directory on disk, `exclude` the directories inside it that are
+ * other members' (set for member `.`). With `at`, the commit id stands in for
+ * the files, since a commit's tree never changes. Returns `undefined` when the
+ * stamp can't be taken, and then nothing is cached.
+ */
+export function memberStamp(abs, exclude = [], at) {
+    try {
+        const install = installLines(abs);
+        if (at)
+            return { value: `sha256:${sha256(["at", at.commit, at.dir, ...install].join("\n"))}`, newest: 0 };
+        const { lines, newest } = fileLines(abs, exclude);
+        return { value: `sha256:${sha256(["files", ...lines, "install", ...install].join("\n"))}`, newest };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * What distinguishes one chant from another for the key: the real path of its
+ * `bin/chant`, the version its package declares, and, for a chant that isn't
+ * installed under a `node_modules` directory (a source checkout), the stamp
+ * of its package's `src`, since a checkout changes without a version bump.
+ */
+export function toolchainStamp(toolchain) {
+    const pkgDir = dirname(dirname(toolchain.identity));
+    let version = "";
+    try {
+        version = String(JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf-8")).version ?? "");
+    }
+    catch {
+        // A bin outside a package: its path alone names it.
+    }
+    const installed = toolchain.identity.split(sep).includes("node_modules");
+    let source = "";
+    if (!installed && existsSync(join(pkgDir, "src"))) {
+        source = memberStamp(join(pkgDir, "src"))?.value ?? `unstamped:${Date.now()}`;
+    }
+    return `${toolchain.identity}\0${version}\0${source}`;
+}
+/** What a kind's reader adds to the key: its graph block, and the installed version of the package supplying it. */
+export function readerStamp(reader) {
+    let version = "";
+    try {
+        version = String(JSON.parse(readFileSync(join(reader.packageDir, "package.json"), "utf-8")).version ?? "");
+    }
+    catch {
+        // An unreadable manifest keys on the directory alone.
+    }
+    return JSON.stringify([reader.lexicon, reader.config, reader.packageDir, version]);
+}
+/** The ambient environment, less {@link VOLATILE_ENV}, as one digest. */
+export function environmentStamp(env = process.env) {
+    const keep = Object.keys(env)
+        .filter((k) => !VOLATILE_ENV.some((v) => (typeof v === "string" ? v === k : v.test(k))))
+        .sort();
+    return sha256(keep.map((k) => `${k}=${env[k] ?? ""}`).join("\0"));
+}
+export function cacheKey(parts) {
+    return sha256(JSON.stringify([CACHE_FORMAT, parts.member, parts.dir, parts.stamp, parts.toolchain, parts.argv, parts.env]));
+}
+/**
+ * The directory holding the cache of the workspace rooted at `root`:
+ * `<cache dir>/workspace-graph/<first 16 hex digits of sha256(real path of root)>`,
+ * where the cache dir is `$CHANT_CACHE_DIR`, else `$XDG_CACHE_HOME/chant`,
+ * else `~/.cache/chant`.
+ */
+export function graphCacheDir(root, env = process.env) {
+    const base = env[CACHE_DIR_ENV] || join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "chant");
+    let real = resolve(root);
+    try {
+        real = realpathSync(real);
+    }
+    catch {
+        // A root that can't be resolved keys on the path as given.
+    }
+    return join(base, "workspace-graph", sha256(real).slice(0, 16));
+}
+/**
+ * The cache for the workspace rooted at `root` (absolute, on disk). Nothing is
+ * created until the first `put`. Every failure to read or write is a miss or
+ * a skipped store, never an error: the cache can only make a read faster.
+ */
+export function openGraphCache(root, env = process.env) {
+    const dir = graphCacheDir(root, env);
+    const file = (key) => join(dir, `${key}.json`);
+    return {
+        dir,
+        get(key) {
+            try {
+                const entry = JSON.parse(readFileSync(file(key), "utf-8"));
+                if (entry.format !== CACHE_FORMAT || entry.key !== key || typeof entry.stdout !== "string")
+                    return undefined;
+                const now = new Date();
+                utimesSync(file(key), now, now);
+                return entry;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        put(entry) {
+            try {
+                mkdirSync(dir, { recursive: true });
+                const tmp = join(dir, `.${entry.key}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+                writeFileSync(tmp, JSON.stringify(entry));
+                renameSync(tmp, file(entry.key));
+                prune(dir);
+            }
+            catch {
+                // A cache that can't be written costs the next read a run, nothing more.
+            }
+        },
+    };
+}
+/** Drop the least recently used entries until the bounds hold. */
+function prune(dir) {
+    const entries = readdirSync(dir)
+        .filter((n) => n.endsWith(".json") && !n.startsWith("."))
+        .map((n) => {
+        try {
+            const st = statSync(join(dir, n));
+            return { path: join(dir, n), mtime: st.mtimeMs, size: st.size };
+        }
+        catch {
+            return undefined;
+        }
+    })
+        .filter((e) => e !== undefined)
+        .sort((a, b) => b.mtime - a.mtime);
+    let bytes = 0;
+    entries.forEach((e, i) => {
+        bytes += e.size;
+        if (i >= MAX_ENTRIES || bytes > MAX_BYTES)
+            rmSync(e.path, { force: true });
+    });
+}
+/**
+ * Look every member of a `graph` plan up in the cache. `at` is the commit
+ * being read, or null for the working tree. Members with a cacheable command
+ * line whose stamp can be taken end up in `hits` or in `pending`.
+ */
+export function splitCached(plan, args, cache, at, argvFor = (u) => memberArgv("graph", u, args)) {
+    const started = Date.now();
+    const env = environmentStamp();
+    const hits = [];
+    const stamps = new Map();
+    const pending = new Map();
+    for (const group of plan.groups) {
+        const tool = toolchainStamp(group.toolchain);
+        for (const unit of group.units) {
+            if (unit.group)
+                continue;
+            const argv = argvFor(unit);
+            if (!isCacheableArgv(argv))
+                continue;
+            // A member read through a generated reader project (#2874) is also keyed on
+            // the kind's graph block and the version of the package that reads it.
+            const reader = unit.reader ? readerStamp(unit.reader) : "";
+            const abs = unit.dir === "." ? plan.workspace.root : join(plan.workspace.root, ...unit.dir.split("/"));
+            const revision = at ? { commit: at, dir: unit.dir } : undefined;
+            const stamp = memberStamp(abs, unit.exclude, revision);
+            if (!stamp)
+                continue;
+            stamps.set(unit.id, stamp.value);
+            const key = cacheKey({ member: unit.member, dir: unit.dir, stamp: stamp.value, toolchain: `${tool}\0${reader}`, argv, env });
+            const entry = cache.get(key);
+            if (entry) {
+                hits.push({ unit, toolchain: group.toolchain, chant: entry.chant, mode: "member-run", id: unit.id, member: unit.member, dir: unit.dir, exclude: unit.exclude, exitCode: 0, stdout: entry.stdout, stderr: "" });
+            }
+            else {
+                pending.set(unit.id, { key, stamp, abs, exclude: unit.exclude, ...(revision ? { at: revision } : {}), member: unit.member });
+            }
+        }
+    }
+    return { hits, stamps, pending, started };
+}
+/** The plan without the units in `ids`; a toolchain left with no units is dropped. */
+export function withoutUnits(plan, ids) {
+    if (ids.size === 0)
+        return plan;
+    const groups = plan.groups.map((g) => ({ ...g, units: g.units.filter((u) => !ids.has(u.id)) })).filter((g) => g.units.length > 0);
+    return { ...plan, groups };
+}
+/**
+ * Store the reads that may be cached: the member exited 0, printed an IR, and
+ * its stamp is the same after the read as before it. A working-tree read of a
+ * file younger than the window is not stored.
+ */
+export function storeReads(split, results, cache) {
+    for (const r of results) {
+        const p = split.pending.get(r.id);
+        if (!p || r.exitCode !== 0 || "reason" in readMemberIr(r.stdout))
+            continue;
+        if (!p.at && p.stamp.newest > split.started - FRESH_WINDOW_MS)
+            continue;
+        const after = memberStamp(p.abs, p.exclude, p.at);
+        if (!after || after.value !== p.stamp.value)
+            continue;
+        cache.put({ format: CACHE_FORMAT, key: p.key, member: p.member, stamp: p.stamp.value, chant: r.chant, stdout: r.stdout });
+    }
+}