@clossys/launcher 0.3.0 → 0.4.0

package/dist/materialize.js

@@ -0,0 +1,840 @@
+// Write an approved repository change set into a clean local clone and verify
+// the result (RFC apply-approved-plan §7 V4 and V8, migration step 3).
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { decideSetBinding, planPackagesFor, readHubAuthority } from "./admission.js";
+import { AGENTS_GUIDE_PATH, verifyAgentsGuide } from "./agents-guide.js";
+import { storeChangeSet } from "./apply-store.js";
+import { CANONICAL_KEYS, LEDGER_PATH, canonicalOrder, contentDigest, discoveryLinkRole, discoveryLinkTarget, lockfilePath, matchesPathPattern, validateRepositoryChangeSet, } from "./change-set-contract.js";
+import { JsonEditUnstableError, editJsonPointer, valueAtJsonPointer } from "./key-editor.js";
+import { renderInstalledLedger } from "./ledger-contract.js";
+import { trustInstalledLedger } from "./ledger-trust.js";
+import { checkLockfileInvariants } from "./lockfile-invariants.js";
+import { regenerateLockfile } from "./lockfile-regen.js";
+import { verifyReleaseAgeExemption } from "./release-age-edit.js";
+const BRANCH_SHAPE = /^clossys\/apply-[0-9a-f]{12}$/u;
+const DEFAULT_BRANCH_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/u;
+const COMMIT_SHAPE = /^[0-9a-f]{40}$/u;
+const TOOL_VERSION_SHAPE = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?$/u;
+const LEFTOVER_SKILL = /^\.agents\/skills\/clossys-[^/]+(?:\/.*)?$/u;
+const RESERVED_ROOTS = new Set(["clossys", ".github", ".starter"]);
+const isWhole = (file) => !("derived" in file);
+function result(exitCode, verdict, reason, detail) {
+    return detail === undefined ? { exitCode, verdict, reason } : { exitCode, verdict, reason, detail };
+}
+/**
+ * The time limit `status` puts on the git calls of the preconditions it shares with verify, through this variable; unset (verify's
+ * own case) there is no limit. A call that runs out of time has no status, which is read as a failure.
+ */
+export const GIT_TIMEOUT_ENV = "CLOSSYS_LAUNCHER_GIT_TIMEOUT_MS";
+function gitTimeout() {
+    const limit = Number(process.env[GIT_TIMEOUT_ENV]);
+    return Number.isSafeInteger(limit) && limit > 0 ? limit : undefined;
+}
+function git(root, args) {
+    const run = spawnSync("git", ["-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", ...args], {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: gitTimeout(),
+        killSignal: "SIGKILL",
+    });
+    return { status: run.status ?? 1, stdout: run.stdout ?? "" };
+}
+function safeDefaultBranch(branch) {
+    if (branch.includes(":") || branch.includes("+") || branch.includes("*"))
+        return false;
+    return DEFAULT_BRANCH_SHAPE.test(branch);
+}
+function refusalResult(refusal) {
+    return result(refusal.exitCode, refusal.exitCode === 1 ? "violated" : "indeterminate", refusal.reason, refusal.detail);
+}
+function digestAtPath(root, relPath) {
+    const path = join(root, relPath);
+    try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+            return contentDigest(readlinkSync(path));
+        if (stat.isFile())
+            return contentDigest(readFileSync(path, "utf8"));
+        return null;
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return null;
+        throw cause;
+    }
+}
+function gitShowUtf8(root, ref, path) {
+    const { status, stdout } = git(root, ["show", `${ref}:${path}`]);
+    if (status !== 0)
+        return null;
+    return stdout;
+}
+function gitShowBytes(root, ref, path) {
+    const run = spawnSync("git", ["-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", "show", `${ref}:${path}`], {
+        cwd: root,
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: gitTimeout(),
+        killSignal: "SIGKILL",
+    });
+    if ((run.status ?? 1) !== 0)
+        return null;
+    return run.stdout ?? null;
+}
+function declaredPaths(set) {
+    const paths = new Set(set.files.map((file) => file.path));
+    if (set.keys.length > 0)
+        paths.add("package.json");
+    return paths;
+}
+function writePaths(set) {
+    const paths = set.files.filter(isWhole).filter((file) => file.before !== file.after).map((file) => file.path);
+    if (set.keys.length > 0)
+        paths.push("package.json");
+    paths.push(LEDGER_PATH);
+    return paths;
+}
+function hasSymlinkAncestor(root, relPath) {
+    const parts = relPath.split("/");
+    if (parts.length <= 1)
+        return false;
+    let current = root;
+    for (let index = 0; index < parts.length - 1; index += 1) {
+        current = join(current, parts[index]);
+        try {
+            if (lstatSync(current).isSymbolicLink())
+                return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function ensureParentDir(root, relPath) {
+    const parent = dirname(relPath);
+    if (parent === ".")
+        return null;
+    const segments = parent.split("/");
+    let current = root;
+    for (const segment of segments) {
+        current = join(current, segment);
+        try {
+            const stat = lstatSync(current);
+            if (stat.isSymbolicLink())
+                return result(2, "indeterminate", "symlink-ancestor");
+            if (!stat.isDirectory())
+                return result(2, "indeterminate", "symlink-ancestor");
+        }
+        catch (cause) {
+            if (cause.code !== "ENOENT")
+                throw cause;
+            mkdirSync(current);
+        }
+    }
+    return null;
+}
+export function writeRegularFile(root, relPath, text, after) {
+    const parent = ensureParentDir(root, relPath);
+    if (parent !== null)
+        return parent;
+    const path = join(root, relPath);
+    try {
+        if (lstatSync(path).isSymbolicLink())
+            return result(2, "indeterminate", "symlink-ancestor");
+    }
+    catch (cause) {
+        if (cause.code !== "ENOENT")
+            throw cause;
+    }
+    writeFileSync(path, text, "utf8");
+    try {
+        const mode = lstatSync(path).mode & 0o777;
+        if ((mode & 0o111) !== 0)
+            chmodSync(path, 0o644);
+    }
+    catch {
+        // Best effort.
+    }
+    const readBack = readFileSync(path, "utf8");
+    if (readBack !== text)
+        return result(1, "violated", "content-mismatch");
+    if (contentDigest(readBack) !== after)
+        return result(1, "violated", "content-mismatch");
+    return null;
+}
+export function writeSymlink(root, relPath, target, after) {
+    const parent = ensureParentDir(root, relPath);
+    if (parent !== null)
+        return parent;
+    const path = join(root, relPath);
+    try {
+        if (lstatSync(path).isSymbolicLink())
+            unlinkSync(path);
+        else if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch (cause) {
+        if (cause.code !== "ENOENT")
+            throw cause;
+    }
+    symlinkSync(target, path);
+    if (contentDigest(readlinkSync(path)) !== after)
+        return result(1, "violated", "content-mismatch");
+    return null;
+}
+export function removePath(root, relPath) {
+    if (hasSymlinkAncestor(root, relPath))
+        return result(2, "indeterminate", "symlink-ancestor");
+    const path = join(root, relPath);
+    try {
+        unlinkSync(path);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return null;
+        throw cause;
+    }
+    if (existsSync(path))
+        return result(1, "violated", "removal-present");
+    return null;
+}
+export function resolveCloneRoot(clone) {
+    try {
+        const stat = lstatSync(clone);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return result(2, "indeterminate", "missing-clone");
+    }
+    catch {
+        return result(2, "indeterminate", "missing-clone");
+    }
+    let root;
+    try {
+        root = realpathSync(clone);
+    }
+    catch {
+        return result(2, "indeterminate", "missing-clone");
+    }
+    if (root !== clone)
+        return result(2, "indeterminate", "missing-clone");
+    return { root };
+}
+function checkSymlinksSupported(root) {
+    const { status, stdout } = git(root, ["config", "--get", "core.symlinks"]);
+    if (status !== 0)
+        return null;
+    if (stdout.trim() === "false")
+        return result(2, "indeterminate", "symlinks-unsupported");
+    return null;
+}
+function checkRemoteTip(root, set) {
+    const branch = set.repository.defaultBranch;
+    if (!safeDefaultBranch(branch))
+        return result(2, "indeterminate", "change-set-invalid");
+    const fetched = git(root, ["fetch", "--no-tags", "--refmap=", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`]);
+    if (fetched.status !== 0)
+        return result(2, "indeterminate", "remote-tip-unreadable");
+    const local = git(root, ["rev-parse", `refs/heads/${branch}`]);
+    const remote = git(root, ["rev-parse", `refs/remotes/origin/${branch}`]);
+    if (local.status !== 0 || remote.status !== 0)
+        return result(2, "indeterminate", "remote-tip-unreadable");
+    if (local.stdout.trim() !== remote.stdout.trim())
+        return result(1, "violated", "remote-tip-mismatch");
+    return null;
+}
+function digestAtRef(root, ref, relPath, mode) {
+    if (mode === "120000") {
+        const target = gitShowUtf8(root, ref, relPath);
+        if (target === null)
+            return null;
+        return contentDigest(target);
+    }
+    const text = gitShowUtf8(root, ref, relPath);
+    if (text === null)
+        return null;
+    return contentDigest(text);
+}
+/**
+ * Whether the bytes an exempt-release-age item writes at `path` are the base's bytes plus exactly the one scope entry, judged by
+ * verifyReleaseAgeExemption() over the base commit's own bytes (never the working tree) and its .npmrc. True for a file no such
+ * item names. The set carries the file's digest only, so this is the one place the "one entry, nothing else" rule is proved.
+ */
+function provesReleaseAgeEdit(root, set, file, after) {
+    return provesReleaseAgeEditWith((path) => gitShowUtf8(root, set.repository.baseCommit, path), set, file, after);
+}
+/**
+ * provesReleaseAgeEdit() over any reader of the base commit's own bytes: `readBase` returns the text of a path at the base
+ * commit, or null when there is none. The plan command's dry tree reads them from the clone's object database and never runs
+ * `git show`.
+ */
+export function provesReleaseAgeEditWith(readBase, set, file, after) {
+    const item = set.items.find((entry) => entry.id === file.item);
+    if (item === undefined || item.act !== "exempt-release-age")
+        return true;
+    if (item.path !== file.path)
+        return false;
+    const before = readBase(file.path);
+    // The digest the set names as `before` must be these very bytes, or the proof would be over another file.
+    if ((before === null ? null : contentDigest(before)) !== file.before)
+        return false;
+    const npmrc = readBase(".npmrc");
+    return verifyReleaseAgeExemption({ surface: item.surface, before, after, npmrc }).verified;
+}
+function checkBaseCommitMovement(root, set) {
+    const branch = set.repository.defaultBranch;
+    const tip = git(root, ["rev-parse", `refs/heads/${branch}`]);
+    if (tip.status !== 0)
+        return result(2, "indeterminate", "remote-tip-unreadable");
+    const tipCommit = tip.stdout.trim();
+    if (tipCommit === set.repository.baseCommit)
+        return null;
+    for (const file of set.files.filter(isWhole)) {
+        if (digestAtRef(root, tipCommit, file.path, file.mode) !== file.before)
+            return result(2, "indeterminate", "base-conflict");
+    }
+    return result(1, "violated", "superseded");
+}
+function persistChangeSet(hub, set) {
+    let hubReal;
+    try {
+        hubReal = realpathSync(hub);
+    }
+    catch {
+        return result(2, "indeterminate", "change-set-not-stored");
+    }
+    try {
+        storeChangeSet(hubReal, set);
+    }
+    catch {
+        return result(2, "indeterminate", "change-set-not-stored");
+    }
+    return null;
+}
+export function checkChangeSetShape(set) {
+    if (!BRANCH_SHAPE.test(set.branch) || !COMMIT_SHAPE.test(set.repository.baseCommit))
+        return result(2, "indeterminate", "change-set-invalid");
+    if (!validateRepositoryChangeSet(set).valid)
+        return result(2, "indeterminate", "change-set-invalid");
+    return null;
+}
+/**
+ * The base ledger, trusted against the acts of the plan committed at the hub
+ * (never the acts of the set being judged: a set cannot vouch for itself), with
+ * the exact bytes it was read from (null when the base has none).
+ */
+function baseLedgerTrust(root, set, heldChangeSets, planDigest, planPackages) {
+    const bytes = gitShowBytes(root, set.repository.baseCommit, LEDGER_PATH);
+    const ledgerBytes = bytes ?? new Uint8Array(0);
+    const trust = trustInstalledLedger(ledgerBytes.length === 0 ? null : ledgerBytes, { id: set.repository.id, nodeId: set.repository.nodeId }, heldChangeSets, { planPackageActs: [{ planDigest, packages: planPackages }] });
+    if (trust.state === "refused")
+        return result(2, "indeterminate", trust.rule);
+    const generation = trust.ledger?.generation ?? 0;
+    if (generation !== set.ledger.generation)
+        return result(1, "violated", "ledger-mismatch");
+    return { ledger: trust.ledger, bytes: ledgerBytes.length === 0 ? null : ledgerBytes };
+}
+export function refuseReservedSymlinks(root, paths) {
+    for (const reserved of RESERVED_ROOTS) {
+        try {
+            if (lstatSync(join(root, reserved)).isSymbolicLink())
+                return result(2, "indeterminate", "symlink-ancestor");
+        }
+        catch (cause) {
+            if (cause.code !== "ENOENT")
+                throw cause;
+        }
+    }
+    for (const rel of paths) {
+        const segments = rel.split("/");
+        let current = root;
+        for (let index = 0; index < segments.length; index += 1) {
+            current = join(current, segments[index]);
+            try {
+                if (lstatSync(current).isSymbolicLink())
+                    return result(2, "indeterminate", "symlink-ancestor");
+            }
+            catch (cause) {
+                if (cause.code === "ENOENT")
+                    break;
+                throw cause;
+            }
+        }
+    }
+    return null;
+}
+function declareRootEntryText(root, set, path) {
+    const item = set.items.find((entry) => entry.act === "declare-root-entry" && entry.path === path);
+    if (item === undefined || item.act !== "declare-root-entry")
+        return null;
+    let onDisk;
+    try {
+        onDisk = readFileSync(join(root, path), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        return editJsonPointer(onDisk, item.entries.map((entry) => ({ pointer: "/rootEntries/-", value: { name: entry.name, classification: entry.classification, disposition: entry.disposition } })));
+    }
+    catch (cause) {
+        if (cause instanceof JsonEditUnstableError)
+            return result(2, "indeterminate", "json-edit-unstable");
+        throw cause;
+    }
+}
+export function resolveFileText(root, set, file, texts) {
+    if (texts[file.path] !== undefined)
+        return texts[file.path];
+    if (file.mode === "120000") {
+        const role = discoveryLinkRole(file.path);
+        if (role !== null)
+            return discoveryLinkTarget(role);
+    }
+    const item = set.items.find((entry) => entry.id === file.item);
+    if (item?.act === "declare-root-entry" && item.path === file.path) {
+        const edited = declareRootEntryText(root, set, file.path);
+        if (edited === null)
+            return result(2, "indeterminate", "file-text-unavailable");
+        if (typeof edited !== "string")
+            return edited;
+        return edited;
+    }
+    return result(2, "indeterminate", "file-text-unavailable");
+}
+export function packagesForLockfile(set, invariants) {
+    const packages = [];
+    for (const row of invariants) {
+        const item = set.items.find((entry) => entry.id === row.item);
+        if (item === undefined || (item.act !== "install" && item.act !== "pin-starter"))
+            return null;
+        if (item.package.name !== row.name || item.package.version !== row.version || item.package.integrity !== row.integrity)
+            return null;
+        packages.push({ name: row.name, version: row.version, integrity: row.integrity, placement: item.placement });
+    }
+    return packages;
+}
+export function derivedLockfile(set) {
+    const derived = set.files.find((file) => "derived" in file && file.path !== LEDGER_PATH);
+    if (derived === undefined || !("derived" in derived))
+        return null;
+    const invariants = derived.invariants.filter((row) => "name" in row);
+    return { path: derived.path, invariants };
+}
+function porcelainPaths(root) {
+    const { status, stdout } = git(root, ["status", "--porcelain", "--untracked-files=all"]);
+    if (status !== 0)
+        return { ok: false };
+    const paths = [];
+    for (const line of stdout.split("\n")) {
+        if (line.length < 4)
+            continue;
+        let path = line.slice(3).trim();
+        const arrow = path.indexOf(" -> ");
+        if (arrow !== -1)
+            path = path.slice(arrow + 4);
+        if (path.length > 0)
+            paths.push(path);
+    }
+    return { ok: true, paths };
+}
+function diffPaths(root, baseCommit) {
+    const { status, stdout } = git(root, ["diff", "--name-only", baseCommit]);
+    if (status !== 0)
+        return { ok: false };
+    return {
+        ok: true,
+        paths: stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0),
+    };
+}
+/** The reader verify uses: the clone's working tree and its git status. */
+function workingTreeReader(root) {
+    return {
+        onBranch(branch) {
+            const head = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+            return head.status === 0 && head.stdout.trim() === branch;
+        },
+        changedPaths: (baseCommit) => diffPaths(root, baseCommit),
+        dirtyPaths: () => porcelainPaths(root),
+        hasSymlinkAncestor: (relPath) => hasSymlinkAncestor(root, relPath),
+        entry(relPath) {
+            const path = join(root, relPath);
+            let stat;
+            try {
+                stat = lstatSync(path);
+            }
+            catch (cause) {
+                if (cause.code === "ENOENT")
+                    return null;
+                throw cause;
+            }
+            if (stat.isSymbolicLink())
+                return { kind: "symlink", target: readlinkSync(path) };
+            if (stat.isFile())
+                return { kind: "file", executable: (stat.mode & 0o111) !== 0 };
+            return { kind: "other" };
+        },
+        bytes: (relPath) => readFileSync(join(root, relPath)),
+    };
+}
+function symlinkBeforeRead(reader, relPaths) {
+    for (const relPath of relPaths) {
+        if (reader.hasSymlinkAncestor(relPath))
+            return result(2, "indeterminate", "symlink-ancestor");
+    }
+    return null;
+}
+function expectedLedgerBytes(previous, set, binding, planPackages) {
+    return Buffer.from(renderInstalledLedger(previous, set, binding, planPackages), "utf8");
+}
+export async function runPreconditions(clone, hub, set, heldChangeSets, admission) {
+    const resolved = resolveCloneRoot(clone);
+    if ("exitCode" in resolved)
+        return resolved;
+    const { root } = resolved;
+    const shape = checkChangeSetShape(set);
+    if (shape !== null)
+        return shape;
+    const symlinks = checkSymlinksSupported(root);
+    if (symlinks !== null)
+        return symlinks;
+    const remote = checkRemoteTip(root, set);
+    if (remote !== null)
+        return remote;
+    let hubRoot = hub;
+    try {
+        hubRoot = realpathSync(hub);
+    }
+    catch {
+        // readHubAuthority refuses a hub it cannot read.
+    }
+    const authority = readHubAuthority(hubRoot);
+    if ("state" in authority)
+        return refusalResult(authority);
+    const planPackages = planPackagesFor(authority, set.repository.id);
+    const trust = baseLedgerTrust(root, set, heldChangeSets, authority.planDigest, planPackages);
+    if ("exitCode" in trust)
+        return trust;
+    const decided = await decideSetBinding({
+        hub: hubRoot,
+        clone: root,
+        set,
+        authority,
+        baseLedger: trust.ledger,
+        baseLedgerBytes: trust.bytes,
+        now: admission.now,
+        runReadiness: admission.runReadiness,
+    });
+    if (decided.state !== "bound")
+        return refusalResult(decided);
+    return { root, previousLedger: trust.ledger, binding: decided.binding, planPackages };
+}
+export async function verifyRepository(input) {
+    const pre = await runPreconditions(input.clone, input.hub, input.set, input.heldChangeSets ?? [], input);
+    if ("exitCode" in pre)
+        return pre;
+    return verifyPrepared(input.set, pre);
+}
+/**
+ * The body of verify, over preconditions (and so an admission) that were already computed, and over a reader of the tree it
+ * judges: the clone's working tree by default (verify), or one commit's tree (status).
+ */
+export function verifyPrepared(set, pre, reader = workingTreeReader(pre.root)) {
+    const { root, previousLedger, binding, planPackages } = pre;
+    const allowed = (path) => set.pathAllowList.some((pattern) => matchesPathPattern(path, pattern));
+    const declared = declaredPaths(set);
+    if (!reader.onBranch(set.branch))
+        return result(1, "violated", "diverged");
+    const porcelainEarly = reader.dirtyPaths();
+    if (!porcelainEarly.ok)
+        return result(2, "indeterminate", "status-unreadable");
+    const diffEarly = reader.changedPaths(set.repository.baseCommit);
+    if (!diffEarly.ok)
+        return result(2, "indeterminate", "status-unreadable");
+    const lockEarly = derivedLockfile(set);
+    const readPaths = [...declared, ...(lockEarly !== null ? [lockEarly.path] : [])];
+    const symlink = symlinkBeforeRead(reader, readPaths);
+    if (symlink !== null)
+        return symlink;
+    for (const path of declared) {
+        if (!allowed(path))
+            return result(1, "violated", "outside-allow-list");
+    }
+    // The Launcher's guide is checked before the whole-file loop so a changed byte is named for what it is: the set's own digest,
+    // then the constant text (G5). The file's text is read here and never echoed.
+    if (set.items.some((item) => item.act === "write-record" && item.source === "agents-guide")) {
+        const guide = set.files.find((file) => isWhole(file) && file.path === AGENTS_GUIDE_PATH);
+        if (guide !== undefined && guide.after !== null) {
+            let text = null;
+            try {
+                const entry = reader.entry(AGENTS_GUIDE_PATH);
+                if (entry !== null && entry.kind === "file")
+                    text = reader.bytes(AGENTS_GUIDE_PATH).toString("utf8");
+            }
+            catch {
+                text = null;
+            }
+            if (text === null || contentDigest(text) !== guide.after || !verifyAgentsGuide(text))
+                return result(1, "violated", "agents-guide-mismatch");
+        }
+    }
+    for (const file of set.files.filter(isWhole)) {
+        if (file.after !== null) {
+            try {
+                const entry = reader.entry(file.path);
+                if (entry === null)
+                    return result(1, "violated", "content-mismatch");
+                if (file.mode === "120000") {
+                    if (entry.kind !== "symlink")
+                        return result(1, "violated", "mode-mismatch");
+                    if (contentDigest(entry.target) !== file.after)
+                        return result(1, "violated", "content-mismatch");
+                }
+                else {
+                    if (entry.kind !== "file")
+                        return result(1, "violated", "mode-mismatch");
+                    if (entry.executable)
+                        return result(1, "violated", "mode-mismatch");
+                    const onDisk = reader.bytes(file.path).toString("utf8");
+                    if (contentDigest(onDisk) !== file.after)
+                        return result(1, "violated", "content-mismatch");
+                    if (!provesReleaseAgeEdit(root, set, file, onDisk))
+                        return result(1, "violated", "content-mismatch");
+                }
+            }
+            catch {
+                return result(1, "violated", "content-mismatch");
+            }
+        }
+        else {
+            const present = reader.entry(file.path);
+            if (present !== null && present.kind !== "other")
+                return result(1, "violated", "removal-present");
+        }
+    }
+    if (set.keys.length > 0) {
+        let manifest;
+        try {
+            manifest = reader.bytes("package.json").toString("utf8");
+        }
+        catch {
+            return result(1, "violated", "content-mismatch");
+        }
+        for (const key of set.keys) {
+            const at = valueAtJsonPointer(manifest, key.pointer);
+            if (key.after === null) {
+                if (at.found)
+                    return result(1, "violated", "content-mismatch");
+            }
+            else if (!at.found || at.value !== key.after)
+                return result(1, "violated", "content-mismatch");
+        }
+    }
+    const lock = derivedLockfile(set);
+    if (lock !== null) {
+        const format = lock.path === "package-lock.json" ? "npm" : lock.path === "pnpm-lock.yaml" ? "pnpm" : lock.path === "yarn.lock" ? null : null;
+        if (format === null)
+            return result(2, "indeterminate", "lockfile-format-unsupported");
+        const base = gitShowUtf8(root, set.repository.baseCommit, lock.path) ?? "";
+        let current;
+        try {
+            current = reader.bytes(lock.path).toString("utf8");
+        }
+        catch {
+            return result(1, "violated", "lockfile-invariants");
+        }
+        const packages = packagesForLockfile(set, lock.invariants);
+        if (packages === null)
+            return result(2, "indeterminate", "lockfile-invariants");
+        const checked = checkLockfileInvariants({ format, base, regenerated: current, packages });
+        if (checked.verdict === "violated")
+            return result(1, "violated", "lockfile-invariants");
+        if (checked.verdict === "indeterminate")
+            return result(2, "indeterminate", checked.reason);
+    }
+    const expectedLedger = expectedLedgerBytes(previousLedger, set, binding, planPackages);
+    let ledgerOnDisk;
+    try {
+        ledgerOnDisk = reader.bytes(LEDGER_PATH);
+    }
+    catch {
+        return result(1, "violated", "ledger-mismatch");
+    }
+    if (!ledgerOnDisk.equals(expectedLedger))
+        return result(1, "violated", "ledger-mismatch");
+    for (const path of diffEarly.paths) {
+        if (!declared.has(path))
+            return result(1, "violated", "undeclared-path");
+    }
+    for (const path of porcelainEarly.paths) {
+        if (!declared.has(path)) {
+            if (LEFTOVER_SKILL.test(path))
+                return result(1, "violated", "dirty", `${path} left by an earlier run`);
+            return result(1, "violated", "dirty");
+        }
+    }
+    return result(0, "materialized");
+}
+export function textsFromChangeSet(set) {
+    if (set.texts === undefined)
+        return {};
+    return Object.fromEntries(set.texts.map((row) => [row.path, row.text]));
+}
+export async function materializeRepository(input) {
+    const pre = await runPreconditions(input.clone, input.hub, input.set, input.heldChangeSets ?? [], input);
+    if ("exitCode" in pre)
+        return pre;
+    const { root, previousLedger, binding, planPackages } = pre;
+    const set = input.set;
+    const texts = { ...textsFromChangeSet(set), ...input.texts };
+    const baseMovement = checkBaseCommitMovement(root, set);
+    if (baseMovement !== null)
+        return baseMovement;
+    if (git(root, ["show-ref", "--verify", "--quiet", `refs/heads/${set.branch}`]).status === 0) {
+        const verified = verifyPrepared(set, pre);
+        if (verified.exitCode === 0) {
+            const stored = persistChangeSet(input.hub, set);
+            if (stored !== null)
+                return stored;
+            return verified;
+        }
+        if (verified.verdict === "indeterminate")
+            return verified;
+        return { exitCode: 1, verdict: "violated", reason: "diverged", detail: verified.reason === "agents-guide-mismatch" ? verified.reason : verified.detail };
+    }
+    for (const file of set.files.filter(isWhole)) {
+        const onDisk = digestAtPath(root, file.path);
+        if (onDisk !== file.before)
+            return result(1, "violated", "base-mismatch");
+    }
+    const porcelain = porcelainPaths(root);
+    if (!porcelain.ok)
+        return result(2, "indeterminate", "status-unreadable");
+    if (porcelain.paths.length > 0)
+        return result(1, "violated", "dirty");
+    const toWrite = set.files.filter(isWhole).filter((file) => file.before !== file.after);
+    const resolvedTexts = new Map();
+    for (const file of toWrite) {
+        const resolved = resolveFileText(root, set, file, texts);
+        if (typeof resolved !== "string")
+            return resolved;
+        if (file.after !== null && contentDigest(resolved) !== file.after)
+            return result(1, "violated", "content-mismatch");
+        if (!provesReleaseAgeEdit(root, set, file, resolved))
+            return result(1, "violated", "content-mismatch");
+        resolvedTexts.set(file.path, resolved);
+    }
+    let packageText;
+    if (set.keys.length > 0) {
+        const existing = gitShowUtf8(root, set.repository.baseCommit, "package.json");
+        if (existing === null)
+            return result(2, "indeterminate", "manifest-absent");
+        try {
+            packageText = editJsonPointer(existing, set.keys.map((key) => (key.after === null ? { pointer: key.pointer, remove: true } : { pointer: key.pointer, value: key.after })));
+        }
+        catch (cause) {
+            if (cause instanceof JsonEditUnstableError)
+                return result(2, "indeterminate", "json-edit-unstable");
+            throw cause;
+        }
+    }
+    const pathsToTouch = writePaths(set);
+    const symlinkCheck = refuseReservedSymlinks(root, pathsToTouch);
+    if (symlinkCheck !== null)
+        return symlinkCheck;
+    let ledgerBytes;
+    try {
+        ledgerBytes = expectedLedgerBytes(previousLedger, set, binding, planPackages);
+    }
+    catch (cause) {
+        if (cause instanceof TypeError)
+            return result(2, "indeterminate", "change-set-invalid");
+        throw cause;
+    }
+    if (git(root, ["checkout", "-b", set.branch, set.repository.baseCommit]).status !== 0) {
+        return result(2, "indeterminate", "branch-not-created");
+    }
+    for (const file of toWrite) {
+        if (file.after === null) {
+            const removed = removePath(root, file.path);
+            if (removed !== null)
+                return removed;
+            continue;
+        }
+        const text = resolvedTexts.get(file.path);
+        if (file.mode === "120000") {
+            const linked = writeSymlink(root, file.path, text, file.after);
+            if (linked !== null)
+                return linked;
+        }
+        else {
+            const written = writeRegularFile(root, file.path, text, file.after);
+            if (written !== null)
+                return written;
+        }
+    }
+    if (packageText !== undefined) {
+        const written = writeRegularFile(root, "package.json", packageText, contentDigest(packageText));
+        if (written !== null)
+            return written;
+    }
+    const lock = derivedLockfile(set);
+    let toolingVersion = null;
+    let toolingTool = null;
+    if (lock !== null) {
+        const lockpath = lockfilePath({ packageManager: set.observed.packageManager, lockfile: set.observed.lockfile });
+        if (lockpath === null || lockpath !== lock.path)
+            return result(2, "indeterminate", "lockfile-format-unsupported");
+        const packages = packagesForLockfile(set, lock.invariants);
+        if (packages === null)
+            return result(2, "indeterminate", "lockfile-invariants");
+        const baseLock = gitShowUtf8(root, set.repository.baseCommit, lock.path) ?? "";
+        const regen = await regenerateLockfile({
+            root,
+            packageManager: set.observed.packageManager,
+            lockfile: set.observed.lockfile,
+            toolVersion: input.toolVersion ?? null,
+            baseLockfile: baseLock,
+            packages,
+            now: input.now ?? (() => new Date()),
+        }, { spawn: input.spawn });
+        if (regen.verdict !== "satisfied") {
+            if (regen.verdict === "violated")
+                return result(1, "violated", regen.rule);
+            return result(2, "indeterminate", regen.reason);
+        }
+        // The runner already wrote the lockfile. `after` is the hex digest of those bytes.
+        let onDisk;
+        try {
+            onDisk = readFileSync(join(root, regen.path));
+        }
+        catch {
+            return result(1, "violated", "lockfile-invariants");
+        }
+        if (createHash("sha256").update(onDisk).digest("hex") !== regen.after)
+            return result(1, "violated", "lockfile-invariants");
+        toolingTool = regen.tooling.tool;
+        toolingVersion = regen.tooling.version;
+    }
+    const ledgerWritten = writeRegularFile(root, LEDGER_PATH, ledgerBytes.toString("utf8"), contentDigest(ledgerBytes.toString("utf8")));
+    if (ledgerWritten !== null)
+        return ledgerWritten;
+    const ledgerRead = readFileSync(join(root, LEDGER_PATH));
+    if (!ledgerRead.equals(ledgerBytes))
+        return result(1, "violated", "ledger-mismatch");
+    let toStore = set;
+    if (toolingVersion !== null && toolingTool !== null && TOOL_VERSION_SHAPE.test(toolingVersion)) {
+        const tooling = canonicalOrder([...(set.tooling ?? []).filter((row) => row.tool !== toolingTool), { tool: toolingTool, version: toolingVersion }], CANONICAL_KEYS.tool);
+        toStore = { ...set, tooling };
+    }
+    const stored = persistChangeSet(input.hub, toStore);
+    if (stored !== null)
+        return stored;
+    return result(0, "materialized");
+}
+//# sourceMappingURL=materialize.js.map