@litfamily/litcodex 1.0.0

package/node_modules/@litcodex/lit-loop/dist/skill-loop/transaction.js

@@ -0,0 +1,524 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { snapshotIsAgentOwned } from "./ownership.js";
+import { skillLoopPaths } from "./paths.js";
+import { appendLedgerEntry, assertAgentMutationLockHeld, assertTargetNotPinned, atomicWrite, ensureAgentRoot, fsyncDirectory, readLedger, readProposalRecord, readUsage, replaceSkillWithSnapshot, snapshotDirectory, snapshotSkill, snapshotsEqual, validateLedgerEntry, validateSnapshotBlobs, withAgentMutationLock, writeProposalRecord, writeSnapshotToDirectory, writeUsage, } from "./store.js";
+import { SkillLoopError, validateProposal, validateRelativeFile } from "./types.js";
+import { nextAppliedUsageFrom, validateUsageSidecar } from "./usage.js";
+const JOURNAL_KEYS = new Set([
+    "schema",
+    "operation",
+    "ledger",
+    "authorization",
+    "proposalBefore",
+    "proposalAfter",
+    "usageBefore",
+    "usageAfter",
+    "copies",
+]);
+const COPY_KEYS = new Set(["kind", "relativePath"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sameBytes(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function validateCopies(value, ledger) {
+    if (!Array.isArray(value) || value.length > 2) {
+        throw new SkillLoopError("TRANSACTION_INVALID", "the skill transaction copies are invalid");
+    }
+    const copies = value.map((candidate) => {
+        if (!isRecord(candidate) || Object.keys(candidate).some((key) => !COPY_KEYS.has(key))) {
+            throw new SkillLoopError("TRANSACTION_INVALID", "a skill transaction copy is invalid");
+        }
+        const kind = candidate["kind"];
+        const relativePath = candidate["relativePath"];
+        if (!(kind === "backup" || kind === "archive") ||
+            typeof relativePath !== "string" ||
+            validateRelativeFile(relativePath, "__transaction_copy__") !== relativePath) {
+            throw new SkillLoopError("TRANSACTION_INVALID", "a skill transaction copy is invalid");
+        }
+        const segments = relativePath.split("/");
+        if (segments.length !== 2 ||
+            (kind === "backup" ? segments[1] !== ledger.targetSkill : segments[0] !== ledger.targetSkill)) {
+            throw new SkillLoopError("TRANSACTION_INVALID", "a skill transaction copy target is invalid");
+        }
+        return { kind: kind, relativePath };
+    });
+    if (new Set(copies.map((copy) => copy.kind)).size !== copies.length) {
+        throw new SkillLoopError("TRANSACTION_INVALID", "the skill transaction copies are duplicated");
+    }
+    return copies;
+}
+function validateJournal(value, expectedRoot) {
+    if (!isRecord(value) || Object.keys(value).some((key) => !JOURNAL_KEYS.has(key))) {
+        throw new SkillLoopError("TRANSACTION_INVALID", "the skill transaction journal is invalid");
+    }
+    const ledger = validateLedgerEntry(value["ledger"]);
+    const authorization = value["authorization"];
+    const operation = value["operation"];
+    if (value["schema"] !== "litcodex.skill-transaction/v1" ||
+        !(operation === "apply" || operation === "rollback" || operation === "curator-transition") ||
+        ledger.operation !== operation ||
+        typeof authorization !== "string" ||
+        !/^[a-f0-9]{64}$/u.test(authorization) ||
+        resolve(ledger.targetRoot) !== resolve(expectedRoot)) {
+        throw new SkillLoopError("TRANSACTION_INVALID", "the skill transaction operation is invalid");
+    }
+    const copies = validateCopies(value["copies"], ledger);
+    const rawProposalBefore = value["proposalBefore"];
+    const proposalBefore = rawProposalBefore === undefined ? undefined : validateProposal(rawProposalBefore, expectedRoot);
+    const rawProposal = value["proposalAfter"];
+    const proposalAfter = rawProposal === undefined ? undefined : validateProposal(rawProposal, expectedRoot);
+    const rawUsage = value["usageAfter"];
+    const usageAfter = rawUsage === undefined ? undefined : validateUsageSidecar(rawUsage);
+    const rawUsageBefore = value["usageBefore"];
+    const usageBefore = rawUsageBefore === undefined || rawUsageBefore === null ? rawUsageBefore : validateUsageSidecar(rawUsageBefore);
+    if (operation === "apply") {
+        const expectedProposalAfter = proposalBefore === undefined
+            ? undefined
+            : { ...proposalBefore, status: "applied", ledgerEntryId: ledger.id };
+        if (proposalBefore?.status !== "approved" ||
+            proposalBefore.id !== ledger.proposalId ||
+            proposalBefore.targetSkill !== ledger.targetSkill ||
+            usageBefore === undefined ||
+            proposalAfter?.status !== "applied" ||
+            proposalAfter.ledgerEntryId !== ledger.id ||
+            proposalAfter.id !== ledger.proposalId ||
+            proposalAfter.targetSkill !== ledger.targetSkill ||
+            !sameBytes(proposalAfter, expectedProposalAfter) ||
+            usageAfter?.updatedAt !== ledger.createdAt ||
+            usageAfter.skills[ledger.targetSkill]?.state !== "active" ||
+            copies.length !== 0) {
+            throw new SkillLoopError("TRANSACTION_INVALID", "the apply transaction metadata is inconsistent");
+        }
+    }
+    else if (operation === "rollback") {
+        const expectedProposalAfter = proposalBefore === undefined
+            ? undefined
+            : { ...proposalBefore, status: "rolled-back", ledgerEntryId: ledger.id };
+        if (usageBefore === undefined ||
+            usageAfter !== undefined ||
+            copies.length !== 0 ||
+            (ledger.proposalId === null) !== (proposalAfter === undefined) ||
+            (proposalAfter === undefined) !== (proposalBefore === undefined) ||
+            !sameBytes(proposalAfter, expectedProposalAfter) ||
+            (proposalAfter !== undefined &&
+                (proposalAfter.status !== "rolled-back" ||
+                    proposalAfter.ledgerEntryId !== ledger.id ||
+                    proposalAfter.id !== ledger.proposalId ||
+                    proposalAfter.targetSkill !== ledger.targetSkill ||
+                    proposalBefore?.id !== proposalAfter.id ||
+                    proposalBefore.targetSkill !== proposalAfter.targetSkill))) {
+            throw new SkillLoopError("TRANSACTION_INVALID", "the rollback transaction metadata is inconsistent");
+        }
+    }
+    else {
+        const expectedState = ledger.after.length === 0 ? "archived" : "stale";
+        const kinds = new Set(copies.map((copy) => copy.kind));
+        if (proposalAfter !== undefined ||
+            proposalBefore !== undefined ||
+            usageBefore === undefined ||
+            usageAfter?.updatedAt !== ledger.createdAt ||
+            usageAfter.skills[ledger.targetSkill]?.state !== expectedState ||
+            !kinds.has("backup") ||
+            (expectedState === "archived" ? !kinds.has("archive") : kinds.has("archive"))) {
+            throw new SkillLoopError("TRANSACTION_INVALID", "the curator transaction metadata is inconsistent");
+        }
+    }
+    return {
+        schema: "litcodex.skill-transaction/v1",
+        operation,
+        ledger,
+        authorization,
+        ...(proposalBefore === undefined ? {} : { proposalBefore }),
+        ...(proposalAfter === undefined ? {} : { proposalAfter }),
+        ...(usageBefore === undefined ? {} : { usageBefore }),
+        ...(usageAfter === undefined ? {} : { usageAfter }),
+        copies,
+    };
+}
+function authorityPath(agentRoot) {
+    return join(resolve(agentRoot, ".."), ".litcodex-skill-loop-authority");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalJson);
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, canonicalJson(value[key])]));
+    }
+    return value;
+}
+function journalPayload(workspaceRoot, journal) {
+    return JSON.stringify(canonicalJson({ workspaceRoot: resolve(workspaceRoot), journal }));
+}
+function readAuthority(agentRoot) {
+    const path = authorityPath(agentRoot);
+    if (!existsSync(path))
+        return null;
+    const parent = lstatSync(dirname(path));
+    let stat = lstatSync(path);
+    const uid = typeof process.getuid === "function" ? process.getuid() : stat.uid;
+    if (parent.isSymbolicLink() ||
+        !parent.isDirectory() ||
+        (parent.mode & 0o022) !== 0 ||
+        (parent.uid !== uid && parent.uid !== 0) ||
+        stat.isSymbolicLink() ||
+        !stat.isFile() ||
+        (stat.mode & 0o777) !== 0o600 ||
+        (stat.uid !== uid && stat.uid !== 0) ||
+        stat.nlink !== 1) {
+        throw new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction authority is unsafe");
+    }
+    for (let attempt = 0; stat.size !== 32 && attempt < 20; attempt += 1) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+        const next = lstatSync(path);
+        if (next.dev !== stat.dev ||
+            next.ino !== stat.ino ||
+            next.uid !== stat.uid ||
+            next.mode !== stat.mode ||
+            next.nlink !== stat.nlink ||
+            next.ctimeMs !== stat.ctimeMs ||
+            next.birthtimeMs !== stat.birthtimeMs) {
+            throw new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction authority changed during creation");
+        }
+        stat = next;
+    }
+    if (stat.size !== 32)
+        throw new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction authority is incomplete");
+    const key = readFileSync(path);
+    const after = lstatSync(path);
+    if (key.byteLength !== 32 ||
+        after.dev !== stat.dev ||
+        after.ino !== stat.ino ||
+        after.uid !== stat.uid ||
+        after.mode !== stat.mode ||
+        after.nlink !== stat.nlink ||
+        after.size !== stat.size ||
+        after.mtimeMs !== stat.mtimeMs ||
+        after.ctimeMs !== stat.ctimeMs ||
+        after.birthtimeMs !== stat.birthtimeMs)
+        throw new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction authority is invalid");
+    return key;
+}
+function ensureAuthority(agentRoot) {
+    const existing = readAuthority(agentRoot);
+    if (existing !== null)
+        return existing;
+    const key = randomBytes(32);
+    const path = authorityPath(agentRoot);
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        writeFileSync(descriptor, key);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        fsyncDirectory(dirname(path));
+        return readAuthority(agentRoot);
+    }
+    catch (error) {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        if (error.code === "EEXIST") {
+            const raced = readAuthority(agentRoot);
+            if (raced !== null)
+                return raced;
+        }
+        throw error instanceof SkillLoopError
+            ? error
+            : new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction authority could not be created safely");
+    }
+}
+function quarantineJournal(paths, raw) {
+    const root = join(paths.stateRoot, "skill-transaction-quarantine");
+    if (!existsSync(root))
+        mkdirSync(root, { recursive: false, mode: 0o700 });
+    const stat = lstatSync(root);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction quarantine is unsafe");
+    }
+    const digest = createHash("sha256").update(raw).digest("hex");
+    const destination = join(root, `${digest}.json`);
+    if (existsSync(destination))
+        unlinkSync(paths.transactionPath);
+    else
+        renameSync(paths.transactionPath, destination);
+    fsyncDirectory(root);
+    fsyncDirectory(paths.stateRoot);
+}
+function authorizedJournal(workspaceRoot, raw, paths) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString("utf8"));
+    }
+    catch {
+        quarantineJournal(paths, raw);
+        throw new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction journal is not authorized");
+    }
+    if (!isRecord(parsed) || typeof parsed["authorization"] !== "string") {
+        quarantineJournal(paths, raw);
+        throw new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction journal is not authorized");
+    }
+    let key;
+    try {
+        key = readAuthority(paths.agentRoot);
+    }
+    catch {
+        quarantineJournal(paths, raw);
+        throw new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction authority rejected the journal");
+    }
+    const authorization = parsed["authorization"];
+    const unsigned = { ...parsed };
+    delete unsigned["authorization"];
+    const expected = key === null
+        ? ""
+        : createHmac("sha256", key)
+            .update(journalPayload(workspaceRoot, unsigned))
+            .digest("hex");
+    if (key === null ||
+        !/^[a-f0-9]{64}$/u.test(authorization) ||
+        !timingSafeEqual(Buffer.from(authorization), Buffer.from(expected))) {
+        quarantineJournal(paths, raw);
+        throw new SkillLoopError("TRANSACTION_UNAUTHORIZED", "the transaction journal is not authorized");
+    }
+    return parsed;
+}
+export function readMutationJournal(workspaceRoot, env) {
+    const paths = skillLoopPaths(workspaceRoot, env);
+    if (!existsSync(paths.transactionPath))
+        return null;
+    const stat = lstatSync(paths.transactionPath);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new SkillLoopError("TRANSACTION_INVALID", "the skill transaction journal is unsafe");
+    }
+    try {
+        const raw = readFileSync(paths.transactionPath);
+        return validateJournal(authorizedJournal(workspaceRoot, raw, paths), paths.agentRoot);
+    }
+    catch (error) {
+        if (error instanceof SkillLoopError)
+            throw error;
+        throw new SkillLoopError("TRANSACTION_INVALID", "the skill transaction journal is invalid JSON");
+    }
+}
+export function writeMutationJournal(workspaceRoot, journal, env) {
+    const paths = skillLoopPaths(workspaceRoot, env);
+    assertAgentMutationLockHeld(paths);
+    if (existsSync(paths.transactionPath)) {
+        throw new SkillLoopError("TRANSACTION_BUSY", "a prior skill transaction requires recovery");
+    }
+    ensureAgentRoot(paths);
+    const proposalBefore = journal.proposalAfter === undefined ? undefined : readProposalRecord(paths, journal.proposalAfter.id);
+    validateTerminalProposalBinding(workspaceRoot, env, proposalBefore);
+    const usageBefore = readUsage(paths);
+    let expectedUsageAfter;
+    if (journal.operation === "apply") {
+        expectedUsageAfter = nextAppliedUsageFrom(usageBefore, journal.ledger.targetSkill, journal.ledger.createdAt);
+    }
+    else if (journal.operation === "curator-transition") {
+        const sidecar = usageBefore === null ? null : validateUsageSidecar(usageBefore);
+        if (sidecar === null) {
+            throw new SkillLoopError("TRANSACTION_METADATA_CONFLICT", "the curator usage preimage is unavailable");
+        }
+        const entry = sidecar?.skills[journal.ledger.targetSkill];
+        const state = journal.ledger.after.length === 0 ? "archived" : "stale";
+        if (entry === undefined ||
+            entry.pinned ||
+            (state === "stale" ? entry.state !== "active" : entry.state !== "stale")) {
+            throw new SkillLoopError("TRANSACTION_METADATA_CONFLICT", "the curator usage preimage is no longer eligible");
+        }
+        expectedUsageAfter = {
+            schema: "litfamily.skill-usage/v1",
+            updatedAt: journal.ledger.createdAt,
+            skills: {
+                ...sidecar.skills,
+                [journal.ledger.targetSkill]: {
+                    ...entry,
+                    state,
+                    archived_at: state === "archived" ? journal.ledger.createdAt : null,
+                },
+            },
+        };
+    }
+    if (JSON.stringify(journal.usageAfter) !== JSON.stringify(expectedUsageAfter)) {
+        throw new SkillLoopError("TRANSACTION_METADATA_CONFLICT", "the transaction usage postimage was stale");
+    }
+    const unsigned = {
+        ...journal,
+        ...(proposalBefore === undefined ? {} : { proposalBefore }),
+        usageBefore,
+    };
+    const key = ensureAuthority(paths.agentRoot);
+    const authorization = createHmac("sha256", key).update(journalPayload(workspaceRoot, unsigned)).digest("hex");
+    const validated = validateJournal({ ...unsigned, authorization }, paths.agentRoot);
+    validateSnapshotBlobs(paths, [...validated.ledger.before, ...validated.ledger.after]);
+    atomicWrite(paths.transactionPath, `${JSON.stringify(validated, null, 2)}\n`);
+    return validated;
+}
+function ensureSafeDirectory(path, label) {
+    if (!existsSync(path))
+        mkdirSync(path, { recursive: false, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new SkillLoopError("TRANSACTION_INVALID", `${label} is not a safe directory`);
+    }
+}
+function ensureCopy(workspaceRoot, env, journal, copy) {
+    const paths = skillLoopPaths(workspaceRoot, env);
+    const root = copy.kind === "backup" ? paths.curatorBackupsRoot : paths.archiveRoot;
+    ensureSafeDirectory(root, `${copy.kind} root`);
+    const [parentName] = copy.relativePath.split("/");
+    if (parentName === undefined)
+        throw new SkillLoopError("TRANSACTION_INVALID", "the copy parent is invalid");
+    const parent = join(root, parentName);
+    ensureSafeDirectory(parent, `${copy.kind} parent`);
+    const destination = join(root, copy.relativePath);
+    const stage = `${destination}.litcodex-stage-${journal.authorization.slice(0, 16)}`;
+    if (!existsSync(destination)) {
+        if (existsSync(stage))
+            rmSync(stage, { recursive: true, force: true });
+        writeSnapshotToDirectory(paths, journal.ledger.before, stage);
+        if (!snapshotsEqual(snapshotDirectory(paths, stage), journal.ledger.before)) {
+            throw new SkillLoopError("TRANSACTION_COPY_MISMATCH", "a staged transaction snapshot copy mismatched");
+        }
+        renameSync(stage, destination);
+        fsyncDirectory(parent);
+    }
+    else if (existsSync(stage))
+        rmSync(stage, { recursive: true, force: true });
+    if (!snapshotsEqual(snapshotDirectory(paths, destination), journal.ledger.before)) {
+        throw new SkillLoopError("TRANSACTION_COPY_MISMATCH", "a transaction snapshot copy mismatched");
+    }
+}
+function validateTerminalProposalBinding(workspaceRoot, env, proposal) {
+    if (proposal === undefined || proposal.status === "pending" || proposal.status === "approved")
+        return;
+    const expectedOperation = proposal.status === "applied" ? "apply" : proposal.status === "rejected" ? "reject" : "rollback";
+    const entry = readLedger(workspaceRoot, { env }).find((candidate) => candidate.id === proposal.ledgerEntryId);
+    if (entry === undefined ||
+        entry.operation !== expectedOperation ||
+        entry.proposalId !== proposal.id ||
+        entry.targetSkill !== proposal.targetSkill ||
+        resolve(entry.targetRoot) !== resolve(proposal.targetRoot)) {
+        throw new SkillLoopError("TRANSACTION_REFERENCE_INVALID", "the terminal proposal ledger binding is invalid");
+    }
+}
+function validateMetadataPlacement(workspaceRoot, env, journal) {
+    const paths = skillLoopPaths(workspaceRoot, env);
+    validateTerminalProposalBinding(workspaceRoot, env, journal.proposalBefore);
+    if (journal.proposalBefore !== undefined) {
+        const current = readProposalRecord(paths, journal.proposalBefore.id);
+        if (!sameBytes(current, journal.proposalBefore) && !sameBytes(current, journal.proposalAfter)) {
+            throw new SkillLoopError("TRANSACTION_METADATA_CONFLICT", "the transaction proposal changed after sealing");
+        }
+    }
+    if (journal.usageBefore !== undefined) {
+        const current = readUsage(paths);
+        const after = journal.usageAfter === undefined ? journal.usageBefore : journal.usageAfter;
+        if (!sameBytes(current, journal.usageBefore) && !sameBytes(current, after)) {
+            throw new SkillLoopError("TRANSACTION_METADATA_CONFLICT", "the transaction usage changed after sealing");
+        }
+    }
+    assertTargetNotPinned(paths, journal.ledger.targetSkill);
+}
+function validateOwnership(paths, journal) {
+    const beforeOwned = journal.ledger.before.length > 0 && snapshotIsAgentOwned(paths, journal.ledger.before);
+    const afterOwned = journal.ledger.after.length > 0 && snapshotIsAgentOwned(paths, journal.ledger.after);
+    if (journal.operation === "apply") {
+        const create = journal.proposalBefore?.action === "create";
+        const archive = journal.proposalBefore?.action === "archive";
+        if ((create ? journal.ledger.before.length !== 0 : !beforeOwned) ||
+            (archive ? journal.ledger.after.length !== 0 : !afterOwned)) {
+            throw new SkillLoopError("TRANSACTION_REFERENCE_INVALID", "the apply ownership invariant is invalid");
+        }
+    }
+    else if (journal.operation === "curator-transition" &&
+        (!beforeOwned || (journal.ledger.after.length > 0 && !afterOwned))) {
+        throw new SkillLoopError("TRANSACTION_REFERENCE_INVALID", "the curator ownership invariant is invalid");
+    }
+    else if (journal.operation === "rollback") {
+        if ((journal.ledger.before.length > 0 && !beforeOwned) || (journal.ledger.after.length > 0 && !afterOwned)) {
+            throw new SkillLoopError("TRANSACTION_REFERENCE_INVALID", "the rollback ownership invariant is invalid");
+        }
+    }
+}
+function validateExpectation(journal, expected) {
+    if (journal.operation !== expected.operation ||
+        (expected.proposalId !== undefined && journal.ledger.proposalId !== expected.proposalId) ||
+        (expected.restoresLedgerEntryId !== undefined &&
+            journal.ledger.restoresLedgerEntryId !== expected.restoresLedgerEntryId)) {
+        throw new SkillLoopError("TRANSACTION_PENDING_MISMATCH", "a different authorized transaction requires recovery");
+    }
+}
+function ensureLedger(workspaceRoot, env, journal) {
+    const paths = skillLoopPaths(workspaceRoot, env);
+    const existing = readLedger(workspaceRoot, { env }).find((entry) => entry.id === journal.ledger.id);
+    if (existing === undefined)
+        appendLedgerEntry(paths, journal.ledger);
+    else if (JSON.stringify(existing) !== JSON.stringify(journal.ledger)) {
+        throw new SkillLoopError("TRANSACTION_LEDGER_MISMATCH", "the transaction ledger id has conflicting bytes");
+    }
+}
+function validateLedgerPlacement(workspaceRoot, env, journal) {
+    const entries = readLedger(workspaceRoot, { env });
+    const existing = entries.find((entry) => entry.id === journal.ledger.id);
+    if (existing !== undefined) {
+        if (JSON.stringify(existing) !== JSON.stringify(journal.ledger)) {
+            throw new SkillLoopError("TRANSACTION_LEDGER_MISMATCH", "the transaction ledger id has conflicting bytes");
+        }
+        return;
+    }
+    if (journal.operation !== "rollback")
+        return;
+    const source = entries.find((entry) => entry.id === journal.ledger.restoresLedgerEntryId);
+    if (source === undefined ||
+        source.operation === "reject" ||
+        source.targetSkill !== journal.ledger.targetSkill ||
+        resolve(source.targetRoot) !== resolve(journal.ledger.targetRoot) ||
+        !snapshotsEqual(journal.ledger.before, source.after) ||
+        !snapshotsEqual(journal.ledger.after, source.before)) {
+        throw new SkillLoopError("TRANSACTION_REFERENCE_INVALID", "the rollback transaction reference is invalid");
+    }
+}
+export function recoverMutationJournalWhileLocked(workspaceRoot, env, expected) {
+    const paths = skillLoopPaths(workspaceRoot, env);
+    assertAgentMutationLockHeld(paths);
+    const journal = readMutationJournal(workspaceRoot, env);
+    if (journal === null)
+        return null;
+    validateExpectation(journal, expected);
+    validateSnapshotBlobs(paths, [...journal.ledger.before, ...journal.ledger.after]);
+    validateLedgerPlacement(workspaceRoot, env, journal);
+    validateMetadataPlacement(workspaceRoot, env, journal);
+    validateOwnership(paths, journal);
+    for (const copy of journal.copies)
+        ensureCopy(workspaceRoot, env, journal, copy);
+    const current = snapshotSkill(paths, journal.ledger.targetSkill);
+    if (snapshotsEqual(current, journal.ledger.before)) {
+        replaceSkillWithSnapshot(paths, journal.ledger.targetSkill, journal.ledger.after);
+    }
+    else if (!snapshotsEqual(current, journal.ledger.after)) {
+        throw new SkillLoopError("TRANSACTION_CAS_MISMATCH", "the transaction target has conflicting bytes");
+    }
+    if (!snapshotsEqual(snapshotSkill(paths, journal.ledger.targetSkill), journal.ledger.after)) {
+        throw new SkillLoopError("TRANSACTION_VERIFY_FAILED", "the transaction postimage failed verification");
+    }
+    ensureLedger(workspaceRoot, env, journal);
+    if (journal.proposalAfter !== undefined)
+        writeProposalRecord(paths, journal.proposalAfter);
+    if (journal.usageAfter !== undefined)
+        writeUsage(paths, journal.usageAfter);
+    unlinkSync(paths.transactionPath);
+    fsyncDirectory(paths.stateRoot);
+    return journal;
+}
+export function recoverMutationJournal(workspaceRoot, env, expected) {
+    const paths = skillLoopPaths(workspaceRoot, env);
+    if (!existsSync(paths.transactionPath))
+        return null;
+    return withAgentMutationLock(paths, () => recoverMutationJournalWhileLocked(workspaceRoot, env, expected));
+}

package/node_modules/@litcodex/lit-loop/dist/skill-loop/types.d.ts

@@ -0,0 +1,81 @@
+export type ProposalAction = "patch" | "create" | "add-reference" | "archive";
+export type ProposalStatus = "pending" | "approved" | "applied" | "rejected" | "rolled-back";
+export interface SkillProposalPatch {
+    readonly file: string;
+    readonly oldString: string;
+    readonly newString: string;
+}
+export interface SkillProposalCreateFile {
+    readonly file: string;
+    readonly content: string;
+}
+export interface SkillProposalCreateSpec {
+    readonly files: readonly SkillProposalCreateFile[];
+}
+export interface SkillProposal {
+    readonly schema: "litfamily.skill-proposal/v1";
+    readonly id: string;
+    readonly createdAt: string;
+    readonly host: "litcodex";
+    readonly sessionRef: string;
+    readonly signal: string;
+    readonly targetSkill: string;
+    readonly targetRoot: string;
+    readonly action: ProposalAction;
+    readonly patch?: SkillProposalPatch;
+    readonly createSpec?: SkillProposalCreateSpec;
+    readonly rationale: string;
+    readonly evidenceRefs: readonly string[];
+    readonly status: ProposalStatus;
+    readonly ledgerEntryId?: string;
+}
+export interface SkillBlobRef {
+    readonly algorithm: "sha256";
+    readonly digest: string;
+    readonly size: number;
+}
+export interface SkillSnapshotItem {
+    readonly file: string;
+    readonly blob: SkillBlobRef;
+}
+export interface SkillLedgerEntry {
+    readonly schema: "litfamily.skill-ledger/v1";
+    readonly id: string;
+    readonly createdAt: string;
+    readonly proposalId: string | null;
+    readonly actor: "user" | "curator";
+    readonly operation: "apply" | "reject" | "rollback" | "curator-transition";
+    readonly targetSkill: string;
+    readonly targetRoot: string;
+    readonly before: readonly SkillSnapshotItem[];
+    readonly after: readonly SkillSnapshotItem[];
+    readonly restoresLedgerEntryId?: string;
+    readonly reason?: string;
+}
+export interface SkillUsageEntry {
+    readonly state: "active" | "stale" | "archived";
+    readonly use_count: number;
+    readonly view_count: number;
+    readonly patch_count: number;
+    readonly created_at: string;
+    readonly created_by: "agent" | "user" | "installed" | "curator" | null;
+    readonly last_used_at: string | null;
+    readonly last_viewed_at: string | null;
+    readonly last_patched_at: string | null;
+    readonly archived_at: string | null;
+    readonly pinned: boolean;
+}
+export interface SkillUsageSidecar {
+    readonly schema: "litfamily.skill-usage/v1";
+    readonly updatedAt: string;
+    readonly skills: Readonly<Record<string, SkillUsageEntry>>;
+}
+export declare class SkillLoopError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare const SHIPPED_SKILL_IDS: Readonly<Set<string>>;
+export declare function canonicalPathIdentity(path: string): string;
+export declare function validateTargetSkillIdentity(skillId: string): string;
+export declare function validateRelativeFile(file: string, targetSkill: string): string;
+export declare function validateProposal(value: unknown, expectedRoot: string): SkillProposal;