@litfamily/litopencode 1.0.0

package/dist/skill-loop/transaction.js

@@ -0,0 +1,836 @@
+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);
+}