@litfamily/litopencode 1.0.1 → 1.0.2

package/dist/skill-loop/transaction.js

@@ -1,836 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { lstatIfPresent } from "../cli/native-skill-tree.js";
-import { parseStrictJson } from "../strict-json.js";
-import { skillLoopPaths } from "./config.js";
-import { parseSkillSnapshot, readSkillLedger, readSnapshotFile, restoreSnapshot, snapshotSkill } from "./ledger.js";
-import { assertPortableRelativeFile, canonicalRelativeIdentity, parseSkillProposal } from "./proposals.js";
-import { assertSkillLoopLockCapability, assertSkillLoopRootPins, anchoredAssertSkillPathAbsent, anchoredCopyIntoSkillsRoot, anchoredReadFileFromSkillsRoot, anchoredRemoveFromSkillsRoot, anchoredVerifySkillTree, anchoredWriteFileToSkillsRoot, ensureSafeRuntimeDirectory, readSafeRuntimeFile, removeSafeRuntimeFile, writeSafeRuntimeFile } from "./storage.js";
-const journalLimit = 32 * 1024 * 1024;
-const pinLimit = 4096;
-const receiptLimit = 128 * 1024;
-function invalid() {
-    throw new Error("SKILL_TRANSACTION_INVALID");
-}
-function equalSnapshots(left, right) {
-    return JSON.stringify(left) === JSON.stringify(right);
-}
-function digest(bytes) {
-    return createHash("sha256").update(bytes).digest("hex");
-}
-function pinPath(skillsRoot) {
-    return path.join(skillsRoot, ".litopencode-skill-loop.pin");
-}
-function rejectReceiptPath(paths, requestId) {
-    const name = digest(Buffer.from(`litopencode-reject-receipt/v1\0${requestId}`, "utf8"));
-    return path.join(paths.runtimeRoot, "skill-transaction-receipts", `reject-${name}.json`);
-}
-function runtimeImageFile(paths, image) {
-    return image.key === "ledger" ? paths.ledgerFile
-        : image.key === "usage" ? paths.usageFile
-            : path.join(paths.proposalsDir, `${image.proposalId}.json`);
-}
-async function runtimeImage(projectRoot, configRoot, key, proposalId) {
-    const paths = skillLoopPaths(projectRoot, configRoot);
-    const file = key === "ledger" ? paths.ledgerFile : key === "usage" ? paths.usageFile : path.join(paths.proposalsDir, `${proposalId}.json`);
-    const bytes = await readSafeRuntimeFile(projectRoot, file, { maxBytes: key === "ledger" ? 16 * 1024 * 1024 : key === "usage" ? 2 * 1024 * 1024 : 64 * 1024 });
-    return { key, ...(proposalId === undefined ? {} : { proposalId }), before: bytes === undefined ? null : bytes.toString("base64") };
-}
-async function currentRuntimeImage(projectRoot, paths, image) {
-    const bytes = await readSafeRuntimeFile(projectRoot, runtimeImageFile(paths, image), {
-        maxBytes: image.key === "ledger" ? 16 * 1024 * 1024 : image.key === "usage" ? 2 * 1024 * 1024 : 64 * 1024
-    });
-    return bytes === undefined ? null : bytes.toString("base64");
-}
-function parseReceiptImage(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        invalid();
-    const image = value;
-    if (image.key === "ledger") {
-        if (Object.keys(image).length !== 4 || Object.keys(image).some((key) => key !== "key" && key !== "size" && key !== "digest" && key !== "headId") ||
-            !Number.isInteger(image.size) || Number(image.size) < 1 || Number(image.size) > 16 * 1024 * 1024 ||
-            typeof image.digest !== "string" || !/^[a-f0-9]{64}$/u.test(image.digest) ||
-            typeof image.headId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(image.headId))
-            invalid();
-        return Object.freeze({ key: "ledger", size: Number(image.size), digest: image.digest, headId: image.headId });
-    }
-    if (image.key !== "proposal" || Object.keys(image).length !== 3 ||
-        Object.keys(image).some((key) => key !== "key" && key !== "proposalId" && key !== "after") ||
-        typeof image.proposalId !== "string" || typeof image.after !== "string" || Buffer.byteLength(image.after, "utf8") > 96 * 1024)
-        invalid();
-    {
-        const decoded = Buffer.from(image.after, "base64");
-        if (decoded.toString("base64") !== image.after)
-            invalid();
-    }
-    return Object.freeze({ key: "proposal", proposalId: image.proposalId, after: image.after });
-}
-function parseRejectReceipt(value, paths, expected) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        invalid();
-    const record = value;
-    const keys = ["schema", "state", "id", "journalDigest", "projectRoot", "request", "proposalId", "ownershipMarker", "runtime"];
-    if (Object.keys(record).length !== keys.length || Object.keys(record).some((key) => !keys.includes(key)) ||
-        record.schema !== "litfamily.skill-reject-receipt/v1" || record.state !== "terminal" ||
-        typeof record.id !== "string" || !/^tx-[a-f0-9-]{36}$/u.test(record.id) ||
-        typeof record.journalDigest !== "string" || !/^[a-f0-9]{64}$/u.test(record.journalDigest) ||
-        record.projectRoot !== path.resolve(paths.projectRoot) || record.proposalId !== expected.requestId ||
-        record.ownershipMarker !== "litopencodeAgentGenerated" || !Array.isArray(record.runtime) || record.runtime.length !== 2)
-        invalid();
-    const request = parseRequest(record.request);
-    if (request.kind !== "reject" || request.requestId !== expected.requestId)
-        invalid();
-    const runtime = record.runtime.map(parseReceiptImage);
-    const identities = new Set(runtime.map((image) => `${image.key}:${image.key === "proposal" ? image.proposalId : ""}`));
-    if (identities.size !== 2 || !identities.has("ledger:") || !identities.has(`proposal:${expected.requestId}`))
-        invalid();
-    return Object.freeze({
-        schema: "litfamily.skill-reject-receipt/v1",
-        state: "terminal",
-        id: record.id,
-        journalDigest: record.journalDigest,
-        projectRoot: record.projectRoot,
-        request: { kind: "reject", requestId: expected.requestId },
-        proposalId: expected.requestId,
-        ownershipMarker: "litopencodeAgentGenerated",
-        runtime: Object.freeze(runtime)
-    });
-}
-async function readRejectReceipt(projectRoot, paths, expected) {
-    const bytes = await readSafeRuntimeFile(projectRoot, rejectReceiptPath(paths, expected.requestId), { maxBytes: receiptLimit });
-    return bytes === undefined ? undefined : parseRejectReceipt(parseStrictJson(bytes.toString("utf8")), paths, expected);
-}
-async function assertRejectReceiptRuntime(projectRoot, paths, receipt, allowLedgerExtension) {
-    for (const image of receipt.runtime) {
-        if (image.key === "ledger") {
-            const observed = await readSafeRuntimeFile(projectRoot, paths.ledgerFile, { maxBytes: 16 * 1024 * 1024 });
-            if (observed === undefined || observed.byteLength < image.size || (!allowLedgerExtension && observed.byteLength !== image.size) ||
-                digest(observed.subarray(0, image.size)) !== image.digest)
-                invalid();
-            const entries = await readSkillLedger(projectRoot);
-            if (!entries.some((entry) => entry.id === image.headId) || (!allowLedgerExtension && entries.at(-1)?.id !== image.headId))
-                invalid();
-            continue;
-        }
-        if (await currentRuntimeImage(projectRoot, paths, image) !== image.after)
-            invalid();
-    }
-}
-async function writeRejectReceipt(projectRoot, paths, receipt) {
-    const file = rejectReceiptPath(paths, receipt.request.requestId);
-    const existing = await readSafeRuntimeFile(projectRoot, file, { maxBytes: receiptLimit });
-    const bytes = Buffer.from(`${JSON.stringify(receipt)}\n`, "utf8");
-    if (bytes.byteLength > receiptLimit)
-        invalid();
-    if (existing !== undefined) {
-        const parsed = parseRejectReceipt(parseStrictJson(existing.toString("utf8")), paths, receipt.request);
-        if (JSON.stringify(parsed) !== JSON.stringify(receipt))
-            invalid();
-        return;
-    }
-    await writeSafeRuntimeFile(projectRoot, file, bytes);
-}
-function parseRequest(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value) ||
-        Object.keys(value).length !== 2 || Object.keys(value).some((key) => key !== "kind" && key !== "requestId"))
-        invalid();
-    const record = value;
-    if ((record.kind !== "apply" && record.kind !== "reject" && record.kind !== "rollback" && record.kind !== "curator") ||
-        typeof record.requestId !== "string" || record.requestId.length < 1 || record.requestId.length > 128)
-        invalid();
-    try {
-        assertPortableRelativeFile(record.requestId);
-    }
-    catch {
-        invalid();
-    }
-    return Object.freeze({ kind: record.kind, requestId: record.requestId });
-}
-function parseJournal(value, paths) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        invalid();
-    const record = value;
-    const keys = ["schema", "id", "kind", "requestId", "projectRoot", "skillsRoot", "proposalId", "action", "ownershipMarker", "targets", "runtime", "backup"];
-    if (Object.keys(record).length !== keys.length || Object.keys(record).some((key) => !keys.includes(key)) ||
-        record.schema !== "litfamily.skill-transaction/v2" || typeof record.id !== "string" || !/^tx-[a-f0-9-]{36}$/u.test(record.id) ||
-        (record.kind !== "apply" && record.kind !== "reject" && record.kind !== "rollback" && record.kind !== "curator") ||
-        typeof record.requestId !== "string" || record.requestId.length < 1 || record.requestId.length > 128 ||
-        record.projectRoot !== path.resolve(paths.projectRoot) || record.skillsRoot !== path.resolve(paths.skillsRoot) ||
-        (record.proposalId !== null && typeof record.proposalId !== "string") || record.ownershipMarker !== "litopencodeAgentGenerated" ||
-        !Array.isArray(record.targets) || record.targets.length > 32 || !Array.isArray(record.runtime) || record.runtime.length > 3)
-        invalid();
-    try {
-        assertPortableRelativeFile(record.id);
-        assertPortableRelativeFile(record.requestId);
-    }
-    catch {
-        invalid();
-    }
-    const identities = new Set();
-    const targets = record.targets.map((value) => {
-        if (typeof value !== "object" || value === null || Array.isArray(value))
-            invalid();
-        const target = value;
-        const allowed = ["targetSkill", "proposalId", "action", "before", "after", "archivePath", "archiveStagePath"];
-        if (Object.keys(target).some((key) => !allowed.includes(key)) || typeof target.targetSkill !== "string" || target.targetSkill.includes("/") ||
-            (target.proposalId !== null && typeof target.proposalId !== "string") ||
-            (target.action !== "patch" && target.action !== "create" && target.action !== "add-reference" && target.action !== "archive" && target.action !== "rollback" && target.action !== "curator-archive") ||
-            (target.archivePath !== undefined && typeof target.archivePath !== "string") ||
-            (target.archiveStagePath !== undefined && typeof target.archiveStagePath !== "string"))
-            invalid();
-        try {
-            assertPortableRelativeFile(target.targetSkill);
-        }
-        catch {
-            invalid();
-        }
-        const identity = canonicalRelativeIdentity(target.targetSkill);
-        if (identities.has(identity))
-            invalid();
-        identities.add(identity);
-        let before;
-        let after;
-        try {
-            before = parseSkillSnapshot(target.before);
-            after = parseSkillSnapshot(target.after);
-        }
-        catch {
-            invalid();
-        }
-        if (target.action === "rollback" && equalSnapshots(before, after))
-            invalid();
-        let archivePath;
-        let archiveStagePath;
-        if ((target.archivePath === undefined) !== (target.archiveStagePath === undefined) ||
-            (target.archivePath !== undefined && target.action !== "archive" && target.action !== "curator-archive"))
-            invalid();
-        if (target.archivePath !== undefined && target.archiveStagePath !== undefined) {
-            const archive = path.resolve(target.archivePath);
-            const archiveStage = path.resolve(target.archiveStagePath);
-            const relative = path.relative(paths.runtimeRoot, archive);
-            const stageRelative = path.relative(paths.runtimeRoot, archiveStage);
-            if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) ||
-                stageRelative === "" || stageRelative === ".." || stageRelative.startsWith(`..${path.sep}`) || path.isAbsolute(stageRelative) ||
-                archive === archiveStage)
-                invalid();
-            archivePath = archive;
-            archiveStagePath = archiveStage;
-        }
-        return Object.freeze({
-            targetSkill: target.targetSkill,
-            proposalId: target.proposalId,
-            action: target.action,
-            before,
-            after,
-            ...(archivePath === undefined ? {} : { archivePath, archiveStagePath })
-        });
-    });
-    const runtimeKeys = new Set();
-    const runtime = record.runtime.map((value) => {
-        if (typeof value !== "object" || value === null || Array.isArray(value))
-            invalid();
-        const image = value;
-        if (Object.keys(image).some((key) => key !== "key" && key !== "proposalId" && key !== "before") ||
-            (image.key !== "ledger" && image.key !== "usage" && image.key !== "proposal") ||
-            (image.key === "proposal") !== (typeof image.proposalId === "string") ||
-            (image.before !== null && (typeof image.before !== "string" || Buffer.byteLength(image.before, "utf8") > journalLimit)))
-            invalid();
-        const identity = `${String(image.key)}:${String(image.proposalId ?? "")}`;
-        if (runtimeKeys.has(identity))
-            invalid();
-        runtimeKeys.add(identity);
-        if (typeof image.before === "string") {
-            const decoded = Buffer.from(image.before, "base64");
-            if (decoded.toString("base64") !== image.before)
-                invalid();
-        }
-        return { key: image.key, ...(typeof image.proposalId === "string" ? { proposalId: image.proposalId } : {}), before: image.before };
-    });
-    const action = record.action;
-    if ((record.kind === "apply" && (action !== "patch" && action !== "create" && action !== "add-reference" && action !== "archive")) ||
-        (record.kind === "reject" && action !== "reject") || (record.kind === "rollback" && action !== "rollback") ||
-        (record.kind === "curator" && action !== "curator"))
-        invalid();
-    if (((record.kind === "apply" || record.kind === "reject") && typeof record.proposalId !== "string") ||
-        (record.kind === "curator" && record.proposalId !== null) ||
-        (record.kind === "apply" && targets.length !== 1) || (record.kind === "reject" && targets.length !== 0) ||
-        (record.kind === "rollback" && targets.length !== 1) ||
-        targets.some((target) => target.proposalId !== record.proposalId ||
-            (record.kind === "curator" ? target.action !== "curator-archive" : record.kind === "rollback" ? target.action !== "rollback" : record.kind === "apply" ? target.action !== action : true)))
-        invalid();
-    const keysPresent = new Set(runtime.map((image) => image.key));
-    if (!keysPresent.has("ledger") || (record.kind !== "reject" && !keysPresent.has("usage")) ||
-        ((record.kind === "apply" || record.kind === "reject") && !keysPresent.has("proposal")))
-        invalid();
-    let backup = null;
-    if (record.backup !== null) {
-        if (record.kind !== "curator" || typeof record.backup !== "object" || Array.isArray(record.backup))
-            invalid();
-        const source = record.backup;
-        if (Object.keys(source).length !== 4 || typeof source.path !== "string" || typeof source.stagePath !== "string" ||
-            typeof source.markerToken !== "string" || !/^[a-f0-9-]{36}$/u.test(source.markerToken) ||
-            !Array.isArray(source.skills) || source.skills.length > 256)
-            invalid();
-        const backupPath = path.resolve(source.path);
-        const stagePath = path.resolve(source.stagePath);
-        const backupRelative = path.relative(paths.backupsDir, backupPath);
-        const stageRelative = path.relative(paths.backupsDir, stagePath);
-        if (backupRelative === "" || backupRelative === ".." || backupRelative.startsWith(`..${path.sep}`) || path.isAbsolute(backupRelative) ||
-            stageRelative === "" || stageRelative === ".." || stageRelative.startsWith(`..${path.sep}`) || path.isAbsolute(stageRelative) || stagePath === backupPath)
-            invalid();
-        const skillIdentities = new Set();
-        const skills = source.skills.map((value) => {
-            if (typeof value !== "object" || value === null || Array.isArray(value))
-                invalid();
-            const skill = value;
-            if (Object.keys(skill).length !== 2 || typeof skill.skillId !== "string" || skill.skillId.includes("/"))
-                invalid();
-            try {
-                assertPortableRelativeFile(skill.skillId);
-            }
-            catch {
-                invalid();
-            }
-            const identity = canonicalRelativeIdentity(skill.skillId);
-            if (skillIdentities.has(identity))
-                invalid();
-            skillIdentities.add(identity);
-            let snapshot;
-            try {
-                snapshot = parseSkillSnapshot(skill.snapshot);
-            }
-            catch {
-                invalid();
-            }
-            return Object.freeze({ skillId: skill.skillId, snapshot });
-        });
-        backup = Object.freeze({ path: backupPath, stagePath, markerToken: source.markerToken, skills: Object.freeze(skills) });
-    }
-    if ((record.kind === "curator") !== (backup !== null))
-        invalid();
-    return Object.freeze({
-        schema: "litfamily.skill-transaction/v2",
-        id: record.id,
-        kind: record.kind,
-        requestId: record.requestId,
-        projectRoot: record.projectRoot,
-        skillsRoot: record.skillsRoot,
-        proposalId: record.proposalId,
-        action: action,
-        ownershipMarker: "litopencodeAgentGenerated",
-        targets: Object.freeze(targets),
-        runtime: Object.freeze(runtime),
-        backup
-    });
-}
-function parsePin(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        invalid();
-    const record = value;
-    const keys = ["schema", "state", "id", "journalDigest", "projectRoot", "skillsRoot", "request", "ownershipMarker"];
-    if (Object.keys(record).length !== keys.length || Object.keys(record).some((key) => !keys.includes(key)) ||
-        record.schema !== "litfamily.skill-transaction-pin/v2" ||
-        (record.state !== "active" && record.state !== "terminal" && record.state !== "stale") ||
-        typeof record.id !== "string" || !/^tx-[a-f0-9-]{36}$/u.test(record.id) ||
-        typeof record.journalDigest !== "string" || !/^[a-f0-9]{64}$/u.test(record.journalDigest) ||
-        typeof record.projectRoot !== "string" || !path.isAbsolute(record.projectRoot) ||
-        typeof record.skillsRoot !== "string" || !path.isAbsolute(record.skillsRoot) ||
-        record.ownershipMarker !== "litopencodeAgentGenerated")
-        invalid();
-    return Object.freeze({
-        schema: "litfamily.skill-transaction-pin/v2",
-        state: record.state,
-        id: record.id,
-        journalDigest: record.journalDigest,
-        projectRoot: path.resolve(record.projectRoot),
-        skillsRoot: path.resolve(record.skillsRoot),
-        request: parseRequest(record.request),
-        ownershipMarker: "litopencodeAgentGenerated"
-    });
-}
-async function readPin(skillsRoot, capability) {
-    await assertSkillLoopRootPins(capability);
-    const observed = await anchoredReadFileFromSkillsRoot(capability, path.basename(pinPath(skillsRoot)), pinLimit);
-    if (observed === undefined)
-        return undefined;
-    return parsePin(parseStrictJson(observed.bytes.toString("utf8")));
-}
-async function writePin(skillsRoot, value, capability) {
-    await assertSkillLoopRootPins(capability);
-    const target = path.basename(pinPath(skillsRoot));
-    const before = await anchoredReadFileFromSkillsRoot(capability, target, pinLimit);
-    await anchoredWriteFileToSkillsRoot(capability, target, Buffer.from(`${JSON.stringify(value)}\n`, "utf8"), before === undefined ? null : {
-        dev: before.dev,
-        ino: before.ino,
-        ctimeMs: before.ctimeMs,
-        birthtimeMs: before.birthtimeMs
-    });
-}
-function pinFor(journal, bytes, state) {
-    return Object.freeze({
-        schema: "litfamily.skill-transaction-pin/v2",
-        state,
-        id: journal.id,
-        journalDigest: digest(bytes),
-        projectRoot: journal.projectRoot,
-        skillsRoot: journal.skillsRoot,
-        request: { kind: journal.kind, requestId: journal.requestId },
-        ownershipMarker: "litopencodeAgentGenerated"
-    });
-}
-function pinMatches(pin, journal, bytes) {
-    return pin.id === journal.id && pin.journalDigest === digest(bytes) && pin.projectRoot === journal.projectRoot &&
-        pin.skillsRoot === journal.skillsRoot && pin.request.kind === journal.kind && pin.request.requestId === journal.requestId &&
-        pin.ownershipMarker === journal.ownershipMarker;
-}
-export function createSkillTransactionId() {
-    return `tx-${randomUUID()}`;
-}
-function decodedImage(image) {
-    return image.before === null ? undefined : Buffer.from(image.before, "base64");
-}
-function expectedRejectedProposalBytes(journal, paths) {
-    const image = journal.runtime.find((candidate) => candidate.key === "proposal");
-    const before = image === undefined ? undefined : decodedImage(image);
-    if (before === undefined)
-        invalid();
-    const proposal = parseSkillProposal(parseStrictJson(before.toString("utf8")), paths.skillsRoot);
-    if (proposal.id !== journal.requestId || proposal.id !== journal.proposalId || proposal.status !== "pending")
-        invalid();
-    return Buffer.from(`${JSON.stringify({ ...proposal, status: "rejected" }, null, 2)}\n`, "utf8");
-}
-async function recognizedRejectAfterImages(projectRoot, paths, journal) {
-    const ledgerImage = journal.runtime.find((candidate) => candidate.key === "ledger");
-    const proposalImage = journal.runtime.find((candidate) => candidate.key === "proposal");
-    if (ledgerImage === undefined || proposalImage === undefined)
-        invalid();
-    const ledgerBefore = decodedImage(ledgerImage) ?? Buffer.alloc(0);
-    const ledgerAfterBase64 = await currentRuntimeImage(projectRoot, paths, ledgerImage);
-    const proposalAfterBase64 = await currentRuntimeImage(projectRoot, paths, proposalImage);
-    if (ledgerAfterBase64 === null || proposalAfterBase64 === null)
-        invalid();
-    const ledgerAfter = Buffer.from(ledgerAfterBase64, "base64");
-    const proposalAfter = Buffer.from(proposalAfterBase64, "base64");
-    const expectedProposal = expectedRejectedProposalBytes(journal, paths);
-    if (!proposalAfter.equals(expectedProposal) || ledgerAfter.byteLength <= ledgerBefore.byteLength ||
-        !ledgerAfter.subarray(0, ledgerBefore.byteLength).equals(ledgerBefore))
-        invalid();
-    const appended = ledgerAfter.subarray(ledgerBefore.byteLength).toString("utf8");
-    if (!appended.endsWith("\n") || appended.slice(0, -1).includes("\n") || appended.length <= 1)
-        invalid();
-    const entries = await readSkillLedger(projectRoot);
-    const terminal = entries.at(-1);
-    const proposal = parseSkillProposal(parseStrictJson(expectedProposal.toString("utf8")), paths.skillsRoot);
-    if (terminal === undefined || terminal.operation !== "reject" || terminal.actor !== "user" ||
-        terminal.proposalId !== journal.proposalId || terminal.targetSkill !== proposal.targetSkill ||
-        path.resolve(terminal.targetRoot) !== path.resolve(paths.skillsRoot) || terminal.before.length !== 0 || terminal.after.length !== 0 ||
-        terminal.restoresLedgerEntryId !== undefined || terminal.reason !== proposal.rationale)
-        invalid();
-    return Object.freeze([
-        Object.freeze({ key: "ledger", size: ledgerAfter.byteLength, digest: digest(ledgerAfter), headId: terminal.id }),
-        Object.freeze({ key: "proposal", proposalId: journal.requestId, after: proposalAfterBase64 })
-    ]);
-}
-async function rejectRuntimeMatchesBefore(projectRoot, paths, journal) {
-    for (const image of journal.runtime) {
-        if (await currentRuntimeImage(projectRoot, paths, image) !== image.before)
-            return false;
-    }
-    return true;
-}
-async function rollbackPartialReject(projectRoot, paths, journal) {
-    const ledgerImage = journal.runtime.find((candidate) => candidate.key === "ledger");
-    const proposalImage = journal.runtime.find((candidate) => candidate.key === "proposal");
-    if (ledgerImage === undefined || proposalImage === undefined)
-        invalid();
-    const currentProposal = await currentRuntimeImage(projectRoot, paths, proposalImage);
-    if (currentProposal !== proposalImage.before)
-        return false;
-    const expectedProposal = expectedRejectedProposalBytes(journal, paths);
-    const ledgerBefore = decodedImage(ledgerImage) ?? Buffer.alloc(0);
-    const ledgerAfterBase64 = await currentRuntimeImage(projectRoot, paths, ledgerImage);
-    if (ledgerAfterBase64 === null)
-        return false;
-    const ledgerAfter = Buffer.from(ledgerAfterBase64, "base64");
-    if (ledgerAfter.byteLength <= ledgerBefore.byteLength || !ledgerAfter.subarray(0, ledgerBefore.byteLength).equals(ledgerBefore))
-        return false;
-    const appended = ledgerAfter.subarray(ledgerBefore.byteLength).toString("utf8");
-    if (!appended.endsWith("\n") || appended.slice(0, -1).includes("\n") || appended.length <= 1)
-        return false;
-    const entries = await readSkillLedger(projectRoot);
-    const terminal = entries.at(-1);
-    const proposal = parseSkillProposal(parseStrictJson(expectedProposal.toString("utf8")), paths.skillsRoot);
-    if (terminal === undefined || terminal.operation !== "reject" || terminal.actor !== "user" ||
-        terminal.proposalId !== journal.proposalId || terminal.targetSkill !== proposal.targetSkill ||
-        path.resolve(terminal.targetRoot) !== path.resolve(paths.skillsRoot) || terminal.before.length !== 0 || terminal.after.length !== 0 ||
-        terminal.restoresLedgerEntryId !== undefined || terminal.reason !== proposal.rationale)
-        return false;
-    if (ledgerImage.before === null)
-        await removeSafeRuntimeFile(projectRoot, runtimeImageFile(paths, ledgerImage));
-    else
-        await writeSafeRuntimeFile(projectRoot, runtimeImageFile(paths, ledgerImage), ledgerBefore);
-    return true;
-}
-function backupMarkerBytes(journal) {
-    const backup = journal.backup;
-    if (backup === null)
-        invalid();
-    return Buffer.from(`${JSON.stringify({
-        schema: "litfamily.curator-backup/v1",
-        transactionId: journal.id,
-        markerToken: backup.markerToken,
-        backupPath: backup.path
-    })}\n`, "utf8");
-}
-async function expectedSnapshotFiles(projectRoot, snapshot, prefix = "") {
-    const expected = new Map();
-    for (const item of snapshot) {
-        const bytes = await readSnapshotFile(projectRoot, snapshot, item.file);
-        if (bytes === undefined)
-            invalid();
-        expected.set(prefix === "" ? item.file : path.posix.join(prefix, item.file), bytes);
-    }
-    return expected;
-}
-async function expectedBackupFiles(projectRoot, journal) {
-    const backup = journal.backup;
-    if (backup === null)
-        invalid();
-    const expected = new Map([[".litopencode-curator-backup.json", backupMarkerBytes(journal)]]);
-    for (const skill of backup.skills) {
-        for (const [file, bytes] of await expectedSnapshotFiles(projectRoot, skill.snapshot, skill.skillId))
-            expected.set(file, bytes);
-    }
-    return expected;
-}
-async function validateBackupTree(projectRoot, root, expected, allowPartial) {
-    const observed = await lstatIfPresent(root);
-    if (observed === null)
-        return false;
-    if (observed.isSymbolicLink() || !observed.isDirectory())
-        invalid();
-    const seen = new Set();
-    const walk = async (directory, prefix = "") => {
-        for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
-            if (entry.isSymbolicLink())
-                invalid();
-            const relative = prefix === "" ? entry.name : path.posix.join(prefix, entry.name);
-            const target = path.join(directory, entry.name);
-            if (entry.isDirectory()) {
-                if (![...expected.keys()].some((file) => file.startsWith(`${relative}/`)))
-                    invalid();
-                await walk(target, relative);
-                continue;
-            }
-            if (!entry.isFile() || seen.has(relative))
-                invalid();
-            const wanted = expected.get(relative);
-            if (wanted === undefined)
-                invalid();
-            const bytes = await readSafeRuntimeFile(projectRoot, target, { allowMissing: false, maxBytes: wanted.byteLength });
-            if (bytes === undefined || (allowPartial
-                ? bytes.byteLength > wanted.byteLength || !wanted.subarray(0, bytes.byteLength).equals(bytes)
-                : !wanted.equals(bytes)))
-                invalid();
-            seen.add(relative);
-        }
-    };
-    await walk(root);
-    if (!allowPartial && (seen.size !== expected.size || [...expected.keys()].some((file) => !seen.has(file))))
-        invalid();
-    return true;
-}
-export async function materializeTransactionSnapshot(projectRoot, stagePath, destinationPath, snapshot) {
-    await ensureSafeRuntimeDirectory(projectRoot, path.dirname(stagePath));
-    if (await lstatIfPresent(stagePath) !== null || await lstatIfPresent(destinationPath) !== null)
-        throw new Error("TARGET_ALREADY_EXISTS");
-    await fs.mkdir(stagePath, { mode: 0o700 });
-    const expected = await expectedSnapshotFiles(projectRoot, snapshot);
-    for (const [relative, bytes] of expected) {
-        const destination = path.join(stagePath, ...relative.split("/"));
-        await fs.mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
-        await fs.writeFile(destination, bytes, { mode: 0o600, flag: "wx" });
-    }
-    await validateBackupTree(projectRoot, stagePath, expected, false);
-    await fs.rename(stagePath, destinationPath);
-}
-async function cleanupJournalArchives(projectRoot, journal) {
-    for (const target of journal.targets) {
-        if (target.archivePath === undefined || target.archiveStagePath === undefined)
-            continue;
-        const expected = await expectedSnapshotFiles(projectRoot, target.before);
-        if (await validateBackupTree(projectRoot, target.archiveStagePath, expected, true)) {
-            await fs.rm(target.archiveStagePath, { recursive: true, force: false });
-        }
-        if (await validateBackupTree(projectRoot, target.archivePath, expected, false)) {
-            await fs.rm(target.archivePath, { recursive: true, force: false });
-        }
-    }
-}
-async function cleanupJournalBackup(projectRoot, journal) {
-    const backup = journal.backup;
-    if (backup === null)
-        return;
-    const expected = await expectedBackupFiles(projectRoot, journal);
-    if (await validateBackupTree(projectRoot, backup.stagePath, expected, true)) {
-        await fs.rm(backup.stagePath, { recursive: true, force: false });
-    }
-    if (await validateBackupTree(projectRoot, backup.path, expected, false)) {
-        await fs.rm(backup.path, { recursive: true, force: false });
-    }
-}
-async function prePinJournalIsUnchanged(projectRoot, paths, journal, validateTarget, targetPinned, capability) {
-    for (const image of journal.runtime) {
-        if (await currentRuntimeImage(projectRoot, paths, image) !== image.before)
-            return false;
-    }
-    try {
-        for (const target of journal.targets) {
-            await assertSkillLoopRootPins(capability);
-            validateTarget(target.targetSkill);
-            if (await targetPinned(target.targetSkill))
-                return false;
-            if (target.before.length === 0)
-                await anchoredAssertSkillPathAbsent(capability, target.targetSkill);
-            else
-                await anchoredVerifySkillTree(capability, target.targetSkill, target.before);
-            await anchoredAssertSkillPathAbsent(capability, `.${target.targetSkill}.${journal.id}.stage`);
-            await anchoredAssertSkillPathAbsent(capability, `.${target.targetSkill}.${journal.id}.backup`);
-            if (target.archivePath !== undefined && await lstatIfPresent(target.archivePath) !== null)
-                return false;
-            if (target.archiveStagePath !== undefined && await lstatIfPresent(target.archiveStagePath) !== null)
-                return false;
-        }
-    }
-    catch (error) {
-        if (error instanceof Error && error.message === "SKILL_LOOP_CONFLICT")
-            return false;
-        throw error;
-    }
-    const recoveryRoot = path.join(paths.runtimeRoot, "skill-transaction-recovery", journal.id);
-    if (await lstatIfPresent(recoveryRoot) !== null)
-        return false;
-    if (journal.backup !== null &&
-        (await lstatIfPresent(journal.backup.path) !== null || await lstatIfPresent(journal.backup.stagePath) !== null))
-        return false;
-    return true;
-}
-export async function recoverSkillTransaction(projectRoot, configRoot, expected, validateTarget, targetPinned, capability) {
-    const paths = skillLoopPaths(projectRoot, configRoot);
-    assertSkillLoopLockCapability(capability, paths.projectRoot, expected.kind === "reject" ? undefined : paths.skillsRoot);
-    if (expected.kind !== "reject")
-        await assertSkillLoopRootPins(capability);
-    const journalBytes = await readSafeRuntimeFile(projectRoot, paths.transactionFile, { maxBytes: journalLimit });
-    if (journalBytes === undefined) {
-        if (expected.kind !== "reject")
-            return false;
-        const rejectRequest = { kind: "reject", requestId: expected.requestId };
-        const receipt = await readRejectReceipt(projectRoot, paths, rejectRequest);
-        if (receipt === undefined)
-            return false;
-        await assertRejectReceiptRuntime(projectRoot, paths, receipt, true);
-        return "committed";
-    }
-    let journal;
-    try {
-        journal = parseJournal(parseStrictJson(journalBytes.toString("utf8")), paths);
-    }
-    catch {
-        invalid();
-    }
-    if (journal.kind !== expected.kind || journal.requestId !== expected.requestId)
-        throw new Error("SKILL_TRANSACTION_PENDING");
-    if (journal.kind === "reject") {
-        const rejectRequest = { kind: "reject", requestId: journal.requestId };
-        const receipt = await readRejectReceipt(projectRoot, paths, rejectRequest);
-        if (receipt !== undefined) {
-            if (receipt.id !== journal.id || receipt.journalDigest !== digest(journalBytes))
-                invalid();
-            await assertRejectReceiptRuntime(projectRoot, paths, receipt, false);
-            await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-            return "committed";
-        }
-        if (await rejectRuntimeMatchesBefore(projectRoot, paths, journal)) {
-            await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-            return "rolled-back";
-        }
-        try {
-            const after = await recognizedRejectAfterImages(projectRoot, paths, journal);
-            const terminal = Object.freeze({
-                schema: "litfamily.skill-reject-receipt/v1",
-                state: "terminal",
-                id: journal.id,
-                journalDigest: digest(journalBytes),
-                projectRoot: journal.projectRoot,
-                request: rejectRequest,
-                proposalId: journal.requestId,
-                ownershipMarker: "litopencodeAgentGenerated",
-                runtime: after
-            });
-            await writeRejectReceipt(projectRoot, paths, terminal);
-            await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-            return "committed";
-        }
-        catch (error) {
-            if (!(error instanceof Error && error.message === "SKILL_TRANSACTION_INVALID"))
-                throw error;
-        }
-        if (await rollbackPartialReject(projectRoot, paths, journal)) {
-            await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-            return "rolled-back";
-        }
-        invalid();
-    }
-    const pin = await readPin(paths.skillsRoot, capability);
-    const matchesPin = pin !== undefined && pinMatches(pin, journal, journalBytes);
-    if (pin === undefined || (!matchesPin && pin.state !== "active")) {
-        if (!await prePinJournalIsUnchanged(projectRoot, paths, journal, validateTarget, targetPinned, capability))
-            invalid();
-        await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-        return "rolled-back";
-    }
-    if (!matchesPin)
-        invalid();
-    if (pin.state === "terminal") {
-        await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-        return "committed";
-    }
-    if (pin.state === "stale") {
-        await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-        return "rolled-back";
-    }
-    for (const target of journal.targets) {
-        await assertSkillLoopRootPins(capability);
-        validateTarget(target.targetSkill);
-        if (await targetPinned(target.targetSkill))
-            throw new Error("TARGET_PINNED");
-        const skillRoot = path.join(paths.skillsRoot, target.targetSkill);
-        const current = await snapshotSkill(projectRoot, skillRoot);
-        const backup = path.join(paths.skillsRoot, `.${target.targetSkill}.${journal.id}.backup`);
-        if (!equalSnapshots(current, target.before) && !equalSnapshots(current, target.after)) {
-            if (current.length !== 0)
-                invalid();
-            const backupStat = await lstatIfPresent(backup);
-            if (backupStat === null || !equalSnapshots(await snapshotSkill(projectRoot, backup), target.before))
-                invalid();
-        }
-    }
-    for (const image of journal.runtime) {
-        const file = image.key === "ledger" ? paths.ledgerFile : image.key === "usage" ? paths.usageFile : path.join(paths.proposalsDir, `${image.proposalId}.json`);
-        if (image.before === null)
-            await removeSafeRuntimeFile(projectRoot, file);
-        else
-            await writeSafeRuntimeFile(projectRoot, file, Buffer.from(image.before, "base64"));
-    }
-    for (const target of journal.targets) {
-        await assertSkillLoopRootPins(capability);
-        const recoveryStage = path.join(paths.runtimeRoot, "skill-transaction-recovery", journal.id, target.targetSkill);
-        if (target.before.length > 0) {
-            await ensureSafeRuntimeDirectory(projectRoot, path.dirname(recoveryStage));
-            await restoreSnapshot(projectRoot, recoveryStage, target.before);
-        }
-        await anchoredRemoveFromSkillsRoot(capability, target.targetSkill);
-        if (target.before.length > 0) {
-            await anchoredCopyIntoSkillsRoot(capability, recoveryStage, target.targetSkill, target.before);
-            await anchoredVerifySkillTree(capability, target.targetSkill, target.before);
-        }
-        else
-            await anchoredAssertSkillPathAbsent(capability, target.targetSkill);
-        await anchoredRemoveFromSkillsRoot(capability, `.${target.targetSkill}.${journal.id}.stage`);
-        await anchoredRemoveFromSkillsRoot(capability, `.${target.targetSkill}.${journal.id}.backup`);
-        await fs.rm(path.join(paths.runtimeRoot, "skill-transaction-recovery", journal.id), { recursive: true, force: true });
-    }
-    await cleanupJournalBackup(projectRoot, journal);
-    await cleanupJournalArchives(projectRoot, journal);
-    await writePin(paths.skillsRoot, pinFor(journal, journalBytes, "stale"), capability);
-    await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-    return "rolled-back";
-}
-export async function beginSkillTransaction(projectRoot, configRoot, input) {
-    const paths = skillLoopPaths(projectRoot, configRoot);
-    assertSkillLoopLockCapability(input.capability, paths.projectRoot, input.request.kind === "reject" ? undefined : paths.skillsRoot);
-    if (input.request.kind !== "reject")
-        await assertSkillLoopRootPins(input.capability);
-    if (await readSafeRuntimeFile(projectRoot, paths.transactionFile, { maxBytes: journalLimit }) !== undefined)
-        throw new Error("SKILL_TRANSACTION_PENDING");
-    const runtime = [];
-    if (input.includeLedger)
-        runtime.push(await runtimeImage(projectRoot, configRoot, "ledger"));
-    if (input.includeUsage)
-        runtime.push(await runtimeImage(projectRoot, configRoot, "usage"));
-    if (input.includeProposal)
-        runtime.push(await runtimeImage(projectRoot, configRoot, "proposal", input.proposalId));
-    const journal = parseJournal({
-        schema: "litfamily.skill-transaction/v2",
-        id: input.id,
-        kind: input.request.kind,
-        requestId: input.request.requestId,
-        projectRoot: paths.projectRoot,
-        skillsRoot: paths.skillsRoot,
-        proposalId: input.proposalId,
-        action: input.action,
-        ownershipMarker: "litopencodeAgentGenerated",
-        targets: input.targets,
-        runtime,
-        backup: input.backup ?? null
-    }, paths);
-    const bytes = Buffer.from(`${JSON.stringify(journal)}\n`, "utf8");
-    if (bytes.byteLength > journalLimit)
-        invalid();
-    await writeSafeRuntimeFile(projectRoot, paths.transactionFile, bytes);
-    if (input.request.kind === "reject")
-        return;
-    try {
-        await assertSkillLoopRootPins(input.capability);
-        const priorPin = await readPin(paths.skillsRoot, input.capability);
-        if (priorPin?.state === "active")
-            throw new Error("SKILL_TRANSACTION_PENDING");
-        await writePin(paths.skillsRoot, pinFor(journal, bytes, "active"), input.capability);
-    }
-    catch (error) {
-        await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-        throw error;
-    }
-}
-export async function completeSkillTransaction(projectRoot, configRoot, expected, capability) {
-    const paths = skillLoopPaths(projectRoot, configRoot);
-    assertSkillLoopLockCapability(capability, paths.projectRoot, expected.kind === "reject" ? undefined : paths.skillsRoot);
-    if (expected.kind !== "reject")
-        await assertSkillLoopRootPins(capability);
-    const bytes = await readSafeRuntimeFile(projectRoot, paths.transactionFile, { allowMissing: false, maxBytes: journalLimit });
-    const journal = parseJournal(parseStrictJson(bytes.toString("utf8")), paths);
-    if (journal.kind !== expected.kind || journal.requestId !== expected.requestId)
-        throw new Error("SKILL_TRANSACTION_PENDING");
-    if (journal.kind === "reject") {
-        const request = { kind: "reject", requestId: journal.requestId };
-        const after = await recognizedRejectAfterImages(projectRoot, paths, journal);
-        await writeRejectReceipt(projectRoot, paths, Object.freeze({
-            schema: "litfamily.skill-reject-receipt/v1",
-            state: "terminal",
-            id: journal.id,
-            journalDigest: digest(bytes),
-            projectRoot: journal.projectRoot,
-            request,
-            proposalId: journal.requestId,
-            ownershipMarker: "litopencodeAgentGenerated",
-            runtime: after
-        }));
-        await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-        return;
-    }
-    const pin = await readPin(paths.skillsRoot, capability);
-    if (pin === undefined || pin.state !== "active" || !pinMatches(pin, journal, bytes))
-        invalid();
-    for (const target of journal.targets) {
-        await assertSkillLoopRootPins(capability);
-        if (target.after.length === 0)
-            await anchoredAssertSkillPathAbsent(capability, target.targetSkill);
-        else
-            await anchoredVerifySkillTree(capability, target.targetSkill, target.after);
-        await anchoredRemoveFromSkillsRoot(capability, `.${target.targetSkill}.${journal.id}.stage`);
-        await anchoredRemoveFromSkillsRoot(capability, `.${target.targetSkill}.${journal.id}.backup`);
-    }
-    await writePin(paths.skillsRoot, pinFor(journal, bytes, "terminal"), capability);
-    await removeSafeRuntimeFile(projectRoot, paths.transactionFile);
-}