@litfamily/litcodex 1.0.0

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

@@ -0,0 +1,667 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { isWithin, skillLoopPaths, targetSkillDir } from "./paths.js";
+import { canonicalPathIdentity, SkillLoopError, validateProposal, validateRelativeFile, validateTargetSkillIdentity, } from "./types.js";
+function assertDirectory(path, label) {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new SkillLoopError("SKILL_LOOP_PATH_UNSAFE", `${label} is not a safe directory`);
+    }
+}
+function ensureDirectory(path, label) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    assertDirectory(path, label);
+}
+export function ensureWorkspaceState(paths) {
+    assertDirectory(paths.workspaceRoot, "workspace root");
+    ensureDirectory(paths.stateRoot, "skill-loop state root");
+}
+export function ensureAgentRoot(paths) {
+    const home = resolve(paths.agentRoot, "..", "..");
+    assertDirectory(home, "HOME");
+    const agents = join(home, ".agents");
+    ensureDirectory(agents, "agent directory");
+    ensureDirectory(paths.agentRoot, "agent skill root");
+}
+function ensureAgentLockRoot(paths) {
+    const home = resolve(paths.agentRoot, "..", "..");
+    assertDirectory(home, "HOME");
+    ensureDirectory(resolve(paths.agentRoot, ".."), "agent directory");
+}
+export function atomicWrite(path, bytes, mode = 0o600) {
+    ensureDirectory(dirname(path), "write parent");
+    if (existsSync(path) && lstatSync(path).isSymbolicLink()) {
+        throw new SkillLoopError("SKILL_LOOP_PATH_UNSAFE", "the write target is a symbolic link");
+    }
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    let descriptor;
+    try {
+        descriptor = openSync(temp, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, mode);
+        writeFileSync(descriptor, bytes);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        renameSync(temp, path);
+        fsyncDirectory(dirname(path));
+    }
+    catch (error) {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        if (existsSync(temp))
+            unlinkSync(temp);
+        throw error instanceof SkillLoopError
+            ? error
+            : new SkillLoopError("SKILL_LOOP_WRITE_FAILED", "the skill-loop write failed");
+    }
+}
+export function fsyncDirectory(path) {
+    const descriptor = openSync(path, constants.O_RDONLY);
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function reclaimStaleLock(lockPath, syncRoot) {
+    let before;
+    try {
+        before = lstatSync(lockPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "the skill-loop lock cannot be inspected safely");
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : before.uid;
+    if (before.isSymbolicLink() ||
+        !before.isFile() ||
+        before.size > 32 ||
+        (before.mode & 0o777) !== 0o600 ||
+        (before.uid !== uid && before.uid !== 0) ||
+        before.nlink !== 1) {
+        throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "the skill-loop lock is unsafe");
+    }
+    let owner;
+    try {
+        owner = readFileSync(lockPath, "utf8");
+    }
+    catch {
+        throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "the skill-loop lock cannot be read safely");
+    }
+    if (!/^[1-9]\d{0,9}\n$/u.test(owner)) {
+        throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "the skill-loop lock owner is invalid");
+    }
+    try {
+        process.kill(Number(owner.trim()), 0);
+        throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "another skill-loop mutation owns the lock");
+    }
+    catch (error) {
+        if (error instanceof SkillLoopError)
+            throw error;
+        if (error.code !== "ESRCH") {
+            throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "the skill-loop lock owner cannot be proven stale");
+        }
+    }
+    let after;
+    try {
+        after = lstatSync(lockPath);
+    }
+    catch {
+        throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "the skill-loop lock changed during inspection");
+    }
+    if (after.isSymbolicLink() ||
+        !after.isFile() ||
+        after.dev !== before.dev ||
+        after.ino !== before.ino ||
+        after.uid !== before.uid ||
+        after.mode !== before.mode ||
+        after.nlink !== before.nlink ||
+        after.size !== before.size ||
+        after.mtimeMs !== before.mtimeMs ||
+        after.ctimeMs !== before.ctimeMs ||
+        after.birthtimeMs !== before.birthtimeMs) {
+        throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "the skill-loop lock changed during inspection");
+    }
+    unlinkSync(lockPath);
+    fsyncDirectory(syncRoot);
+}
+function withMutationLock(lockPath, syncRoot, prepare, work) {
+    prepare();
+    let descriptor;
+    try {
+        descriptor = openSync(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    }
+    catch {
+        reclaimStaleLock(lockPath, syncRoot);
+        try {
+            descriptor = openSync(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        }
+        catch {
+            throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "another skill-loop mutation owns the lock");
+        }
+    }
+    const pin = fstatSync(descriptor);
+    const uid = typeof process.getuid === "function" ? process.getuid() : pin.uid;
+    if (!pin.isFile() || pin.nlink !== 1 || (pin.mode & 0o777) !== 0o600 || (pin.uid !== uid && pin.uid !== 0)) {
+        closeSync(descriptor);
+        throw new SkillLoopError("SKILL_LOOP_LOCK_BUSY", "the skill-loop lock is unsafe");
+    }
+    let result;
+    let workError;
+    let releasePin = pin;
+    try {
+        writeFileSync(descriptor, `${process.pid}\n`);
+        fsyncSync(descriptor);
+        releasePin = fstatSync(descriptor);
+        result = work();
+    }
+    catch (error) {
+        workError = error;
+    }
+    try {
+        closeSync(descriptor);
+        const beforeRelease = lstatSync(lockPath);
+        if (beforeRelease.isSymbolicLink() ||
+            !beforeRelease.isFile() ||
+            beforeRelease.dev !== releasePin.dev ||
+            beforeRelease.ino !== releasePin.ino ||
+            beforeRelease.uid !== releasePin.uid ||
+            beforeRelease.mode !== releasePin.mode ||
+            beforeRelease.nlink !== releasePin.nlink ||
+            beforeRelease.ctimeMs !== releasePin.ctimeMs ||
+            beforeRelease.birthtimeMs !== releasePin.birthtimeMs) {
+            throw new SkillLoopError("SKILL_LOOP_LOCK_RELEASE_FAILED", "the skill-loop lock changed before release");
+        }
+        unlinkSync(lockPath);
+        fsyncDirectory(syncRoot);
+    }
+    catch {
+        if (workError === undefined) {
+            throw new SkillLoopError("SKILL_LOOP_LOCK_RELEASE_FAILED", "the skill-loop lock could not be released");
+        }
+    }
+    if (workError !== undefined)
+        throw workError;
+    return result;
+}
+export function withSkillLoopLock(paths, work) {
+    return withMutationLock(paths.lockPath, paths.stateRoot, () => ensureWorkspaceState(paths), work);
+}
+export function withAgentMutationLock(paths, work) {
+    return withMutationLock(paths.agentMutationLockPath, resolve(paths.agentRoot, ".."), () => ensureAgentLockRoot(paths), work);
+}
+export function assertAgentMutationLockHeld(paths) {
+    let stat;
+    let owner;
+    try {
+        stat = lstatSync(paths.agentMutationLockPath);
+        owner = readFileSync(paths.agentMutationLockPath, "utf8");
+    }
+    catch {
+        throw new SkillLoopError("SKILL_LOOP_LOCK_REQUIRED", "the user skill mutation lock is required");
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : stat.uid;
+    if (stat.isSymbolicLink() ||
+        !stat.isFile() ||
+        stat.nlink !== 1 ||
+        (stat.mode & 0o777) !== 0o600 ||
+        (stat.uid !== uid && stat.uid !== 0) ||
+        owner !== `${process.pid}\n`) {
+        throw new SkillLoopError("SKILL_LOOP_LOCK_REQUIRED", "the user skill mutation lock is not held safely");
+    }
+}
+function proposalPath(paths, id) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(id)) {
+        throw new SkillLoopError("PROPOSAL_ID_INVALID", "the proposal id is invalid");
+    }
+    const path = resolve(paths.proposalsDir, `${id}.json`);
+    if (!isWithin(paths.proposalsDir, path))
+        throw new SkillLoopError("PROPOSAL_ID_INVALID", "the proposal id is invalid");
+    return path;
+}
+export function writeProposalRecord(paths, proposal) {
+    const validated = validateProposal(proposal, paths.agentRoot);
+    validateProposalLedgerBinding(paths, validated);
+    atomicWrite(proposalPath(paths, validated.id), `${JSON.stringify(validated, null, 2)}\n`);
+}
+export function readProposalRecord(paths, id) {
+    const path = proposalPath(paths, id);
+    if (!existsSync(path) || lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile()) {
+        throw new SkillLoopError("PROPOSAL_NOT_FOUND", "the proposal was not found");
+    }
+    try {
+        const proposal = validateProposal(JSON.parse(readFileSync(path, "utf8")), paths.agentRoot);
+        validateProposalLedgerBinding(paths, proposal);
+        return proposal;
+    }
+    catch (error) {
+        if (error instanceof SkillLoopError)
+            throw error;
+        throw new SkillLoopError("PROPOSAL_SCHEMA_INVALID", "the stored proposal is invalid");
+    }
+}
+function validateProposalLedgerBinding(paths, proposal) {
+    if (proposal.status === "pending" || proposal.status === "approved")
+        return;
+    const expectedOperation = proposal.status === "applied" ? "apply" : proposal.status === "rejected" ? "reject" : "rollback";
+    const entry = readLedgerFromPaths(paths).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");
+    }
+}
+export function storeProposal(workspaceRoot, value, options = {}) {
+    const stored = storeProposalBatch(workspaceRoot, [value], options);
+    const proposal = stored[0];
+    if (proposal === undefined)
+        throw new SkillLoopError("PROPOSAL_SCHEMA_INVALID", "the proposal batch was empty");
+    return proposal;
+}
+export function storeProposalBatch(workspaceRoot, values, options = {}) {
+    const paths = skillLoopPaths(workspaceRoot, options.env);
+    if (values.length < 1 || values.length > 32) {
+        throw new SkillLoopError("PROPOSAL_SCHEMA_INVALID", "a proposal batch must contain 1 to 32 records");
+    }
+    const proposals = values.map((value) => validateProposal(value, paths.agentRoot));
+    if (proposals.some((proposal) => proposal.status !== "pending")) {
+        throw new SkillLoopError("PROPOSAL_STATUS_INVALID", "new proposals must be pending");
+    }
+    if (new Set(proposals.map((proposal) => proposal.id)).size !== proposals.length) {
+        throw new SkillLoopError("PROPOSAL_EXISTS", "the proposal batch contains duplicate ids");
+    }
+    return withSkillLoopLock(paths, () => {
+        for (const proposal of proposals) {
+            assertNoCanonicalSkillCollision(paths, proposal.targetSkill);
+            assertTargetNotPinned(paths, proposal.targetSkill);
+        }
+        ensureDirectory(paths.proposalsDir, "proposal queue");
+        for (const proposal of proposals) {
+            if (existsSync(proposalPath(paths, proposal.id))) {
+                throw new SkillLoopError("PROPOSAL_EXISTS", "a proposal id already exists");
+            }
+        }
+        const stage = join(paths.proposalsDir, `.batch-${process.pid}-${randomUUID()}`);
+        mkdirSync(stage, { recursive: false, mode: 0o700 });
+        const moved = [];
+        try {
+            for (const proposal of proposals) {
+                atomicWrite(join(stage, `${proposal.id}.json`), `${JSON.stringify(proposal, null, 2)}\n`);
+            }
+            for (const proposal of proposals) {
+                const target = proposalPath(paths, proposal.id);
+                renameSync(join(stage, `${proposal.id}.json`), target);
+                moved.push(target);
+            }
+        }
+        catch (error) {
+            for (const target of moved) {
+                if (existsSync(target))
+                    unlinkSync(target);
+            }
+            throw error;
+        }
+        finally {
+            if (existsSync(stage))
+                rmSync(stage, { recursive: true, force: true });
+        }
+        return proposals;
+    });
+}
+export function assertNoCanonicalSkillCollision(paths, skillId) {
+    validateTargetSkillIdentity(skillId);
+    if (!existsSync(paths.agentRoot))
+        return;
+    assertDirectory(paths.agentRoot, "agent skill root");
+    const identity = canonicalPathIdentity(skillId);
+    for (const entry of readdirSync(paths.agentRoot, { withFileTypes: true })) {
+        if (canonicalPathIdentity(entry.name) !== identity)
+            continue;
+        if (entry.name !== skillId || !entry.isDirectory()) {
+            throw new SkillLoopError("TARGET_NOT_AGENT_OWNED", "an existing skill collides by canonical identity");
+        }
+    }
+}
+export function assertTargetNotPinned(paths, skillId) {
+    const sidecar = readUsage(paths);
+    if (sidecar === null)
+        return;
+    const skills = sidecar["skills"];
+    if (typeof skills !== "object" || skills === null || Array.isArray(skills)) {
+        throw new SkillLoopError("USAGE_INVALID", "the usage sidecar skills are invalid");
+    }
+    const entry = skills[skillId];
+    if (entry === undefined)
+        return;
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        throw new SkillLoopError("USAGE_INVALID", "the target usage entry is invalid");
+    }
+    const pinned = entry["pinned"];
+    if (typeof pinned !== "boolean") {
+        throw new SkillLoopError("USAGE_INVALID", "the target usage pin is invalid");
+    }
+    if (pinned)
+        throw new SkillLoopError("TARGET_PINNED", "the proposal target is pinned");
+}
+export function listProposals(workspaceRoot, options = {}) {
+    const paths = skillLoopPaths(workspaceRoot, options.env);
+    if (!existsSync(paths.proposalsDir))
+        return [];
+    assertDirectory(paths.proposalsDir, "proposal queue");
+    return readdirSync(paths.proposalsDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => readProposalRecord(paths, entry.name.slice(0, -5)))
+        .sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id));
+}
+function validateSnapshot(snapshot) {
+    if (!Array.isArray(snapshot) || snapshot.length > 256)
+        return false;
+    const identities = new Set();
+    for (const item of snapshot) {
+        if (typeof item !== "object" || item === null || Array.isArray(item))
+            return false;
+        const record = item;
+        if (Object.keys(record).some((key) => key !== "file" && key !== "blob"))
+            return false;
+        if (typeof record["file"] !== "string")
+            return false;
+        try {
+            validateRelativeFile(record["file"], "__ledger_target__");
+        }
+        catch {
+            return false;
+        }
+        const identity = canonicalPathIdentity(record["file"]);
+        if (identities.has(identity))
+            return false;
+        identities.add(identity);
+        const blob = record["blob"];
+        if (typeof blob !== "object" || blob === null || Array.isArray(blob))
+            return false;
+        const blobRecord = blob;
+        if (blobRecord["algorithm"] !== "sha256" ||
+            typeof blobRecord["digest"] !== "string" ||
+            !/^[a-f0-9]{64}$/u.test(blobRecord["digest"]) ||
+            typeof blobRecord["size"] !== "number" ||
+            !Number.isInteger(blobRecord["size"]) ||
+            blobRecord["size"] < 0) {
+            return false;
+        }
+    }
+    return true;
+}
+export function validateLedgerEntry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new SkillLoopError("LEDGER_INVALID", "the skill ledger entry is invalid");
+    }
+    const record = value;
+    const allowed = new Set([
+        "schema",
+        "id",
+        "createdAt",
+        "proposalId",
+        "actor",
+        "operation",
+        "targetSkill",
+        "targetRoot",
+        "before",
+        "after",
+        "restoresLedgerEntryId",
+        "reason",
+    ]);
+    if (Object.keys(record).some((key) => !allowed.has(key))) {
+        throw new SkillLoopError("LEDGER_INVALID", "the skill ledger entry has an unknown field");
+    }
+    const id = record["id"];
+    const createdAt = record["createdAt"];
+    const proposalId = record["proposalId"];
+    const actor = record["actor"];
+    const operation = record["operation"];
+    const targetSkill = record["targetSkill"];
+    const targetRoot = record["targetRoot"];
+    const restores = record["restoresLedgerEntryId"];
+    const reason = record["reason"];
+    if (record["schema"] !== "litfamily.skill-ledger/v1" ||
+        typeof id !== "string" ||
+        !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(id) ||
+        typeof createdAt !== "string" ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u.test(createdAt) ||
+        Number.isNaN(Date.parse(createdAt)) ||
+        !["user", "curator"].includes(actor) ||
+        !["apply", "reject", "rollback", "curator-transition"].includes(operation) ||
+        typeof targetSkill !== "string" ||
+        typeof targetRoot !== "string" ||
+        targetRoot.length < 1 ||
+        targetRoot.length > 2048 ||
+        !(proposalId === null ||
+            (typeof proposalId === "string" && proposalId.length >= 1 && proposalId.length <= 128)) ||
+        !(reason === undefined || (typeof reason === "string" && reason.length <= 8192)) ||
+        !validateSnapshot(record["before"]) ||
+        !validateSnapshot(record["after"])) {
+        throw new SkillLoopError("LEDGER_INVALID", "the skill ledger entry is invalid");
+    }
+    try {
+        validateTargetSkillIdentity(targetSkill);
+    }
+    catch {
+        throw new SkillLoopError("LEDGER_INVALID", "the skill ledger target identity is invalid");
+    }
+    if (operation === "rollback"
+        ? actor !== "user" || typeof restores !== "string" || restores.length < 1 || restores.length > 128
+        : restores !== undefined) {
+        throw new SkillLoopError("LEDGER_INVALID", "the skill ledger rollback mapping is invalid");
+    }
+    if ((operation === "apply" || operation === "reject") && (actor !== "user" || typeof proposalId !== "string")) {
+        throw new SkillLoopError("LEDGER_INVALID", "the skill ledger user decision mapping is invalid");
+    }
+    if (operation === "curator-transition" && (actor !== "curator" || proposalId !== null)) {
+        throw new SkillLoopError("LEDGER_INVALID", "the skill ledger curator mapping is invalid");
+    }
+    return record;
+}
+export function appendLedgerEntry(paths, entry) {
+    const validated = validateLedgerEntry(entry);
+    ensureDirectory(dirname(paths.ledgerPath), "ledger parent");
+    if (existsSync(paths.ledgerPath) && lstatSync(paths.ledgerPath).isSymbolicLink()) {
+        throw new SkillLoopError("SKILL_LOOP_PATH_UNSAFE", "the skill ledger is a symbolic link");
+    }
+    const existing = existsSync(paths.ledgerPath) ? readFileSync(paths.ledgerPath) : Buffer.alloc(0);
+    if (existing.byteLength > 0 && existing.at(-1) !== 0x0a) {
+        throw new SkillLoopError("LEDGER_INVALID", "the skill ledger has an incomplete final record");
+    }
+    atomicWrite(paths.ledgerPath, Buffer.concat([existing, Buffer.from(`${JSON.stringify(validated)}\n`, "utf8")]));
+}
+function readLedgerFromPaths(paths) {
+    if (!existsSync(paths.ledgerPath))
+        return [];
+    if (lstatSync(paths.ledgerPath).isSymbolicLink() || !lstatSync(paths.ledgerPath).isFile()) {
+        throw new SkillLoopError("SKILL_LOOP_PATH_UNSAFE", "the skill ledger is unsafe");
+    }
+    const lines = readFileSync(paths.ledgerPath, "utf8")
+        .split("\n")
+        .filter((line) => line.trim().length > 0);
+    const entries = lines.map((line) => {
+        try {
+            return validateLedgerEntry(JSON.parse(line));
+        }
+        catch (error) {
+            if (error instanceof SkillLoopError)
+                throw error;
+            throw new SkillLoopError("LEDGER_INVALID", "the skill ledger contains invalid JSON");
+        }
+    });
+    for (const entry of entries)
+        validateSnapshotBlobs(paths, [...entry.before, ...entry.after]);
+    if (new Set(entries.map((entry) => entry.id)).size !== entries.length) {
+        throw new SkillLoopError("LEDGER_INVALID", "the skill ledger contains duplicate ids");
+    }
+    const prior = new Map();
+    for (const entry of entries) {
+        if (entry.operation === "rollback") {
+            const source = entry.restoresLedgerEntryId === undefined ? undefined : prior.get(entry.restoresLedgerEntryId);
+            if (source === undefined ||
+                source.operation === "reject" ||
+                source.targetSkill !== entry.targetSkill ||
+                resolve(source.targetRoot) !== resolve(entry.targetRoot) ||
+                !snapshotsEqual(entry.before, source.after) ||
+                !snapshotsEqual(entry.after, source.before)) {
+                throw new SkillLoopError("LEDGER_INVALID", "a rollback ledger reference is invalid");
+            }
+        }
+        prior.set(entry.id, entry);
+    }
+    return entries;
+}
+export function readLedger(workspaceRoot, options = {}) {
+    return readLedgerFromPaths(skillLoopPaths(workspaceRoot, options.env));
+}
+function blobPath(paths, digest) {
+    return join(paths.blobsDir, digest.slice(0, 2), digest);
+}
+export function storeBlob(paths, bytes) {
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    const path = blobPath(paths, digest);
+    if (!existsSync(path))
+        atomicWrite(path, bytes);
+    const stored = readFileSync(path);
+    if (!stored.equals(bytes))
+        throw new SkillLoopError("BLOB_INTEGRITY_FAILED", "a stored skill blob mismatched");
+    return { algorithm: "sha256", digest, size: bytes.byteLength };
+}
+export function readBlob(paths, item) {
+    const path = blobPath(paths, item.blob.digest);
+    if (!existsSync(path) || lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile()) {
+        throw new SkillLoopError("BLOB_MISSING", "a required skill blob is missing");
+    }
+    const bytes = readFileSync(path);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== item.blob.digest || bytes.byteLength !== item.blob.size) {
+        throw new SkillLoopError("BLOB_INTEGRITY_FAILED", "a required skill blob failed integrity validation");
+    }
+    return bytes;
+}
+export function validateSnapshotBlobs(paths, snapshot) {
+    for (const item of snapshot)
+        readBlob(paths, item);
+}
+function collectFiles(root, directory = root, out = []) {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+            throw new SkillLoopError("TARGET_PATH_UNSAFE", "skill packages may not contain links");
+        if (stat.isDirectory())
+            collectFiles(root, path, out);
+        else if (stat.isFile())
+            out.push(path);
+        else
+            throw new SkillLoopError("TARGET_PATH_UNSAFE", "skill packages may contain regular files only");
+        if (out.length > 256)
+            throw new SkillLoopError("TARGET_TOO_LARGE", "the skill package contains too many files");
+    }
+    return out;
+}
+export function snapshotSkill(paths, skillId) {
+    assertNoCanonicalSkillCollision(paths, skillId);
+    const target = targetSkillDir(paths, skillId);
+    if (!existsSync(target))
+        return [];
+    assertDirectory(target, "agent-owned skill target");
+    return collectFiles(target)
+        .map((path) => {
+        const file = relative(target, path).replaceAll("\\", "/");
+        validateRelativeFile(file, "__snapshot_target__");
+        return { file, blob: storeBlob(paths, readFileSync(path)) };
+    })
+        .sort((left, right) => left.file.localeCompare(right.file));
+}
+export function snapshotDirectory(paths, directory) {
+    if (!isWithin(paths.agentRoot, directory) || directory === paths.agentRoot) {
+        throw new SkillLoopError("TARGET_PATH_UNSAFE", "the snapshot source escapes the agent root");
+    }
+    if (!existsSync(directory))
+        return [];
+    assertDirectory(directory, "snapshot source");
+    return collectFiles(directory)
+        .map((path) => {
+        const file = relative(directory, path).replaceAll("\\", "/");
+        validateRelativeFile(file, "__snapshot_target__");
+        return { file, blob: storeBlob(paths, readFileSync(path)) };
+    })
+        .sort((left, right) => left.file.localeCompare(right.file));
+}
+export function snapshotsEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function writeSnapshotToDirectory(paths, snapshot, directory) {
+    if (!isWithin(paths.agentRoot, directory) || directory === paths.agentRoot) {
+        throw new SkillLoopError("TARGET_PATH_UNSAFE", "the snapshot destination escapes the agent root");
+    }
+    mkdirSync(directory, { recursive: false, mode: 0o700 });
+    for (const item of snapshot) {
+        const target = resolve(directory, item.file);
+        if (!isWithin(directory, target))
+            throw new SkillLoopError("TARGET_PATH_UNSAFE", "a snapshot path escaped");
+        ensureDirectory(dirname(target), "snapshot directory");
+        atomicWrite(target, readBlob(paths, item));
+    }
+}
+export function replaceSkillWithSnapshot(paths, skillId, snapshot) {
+    ensureAgentRoot(paths);
+    const target = targetSkillDir(paths, skillId);
+    const nonce = `${process.pid}-${randomUUID()}`;
+    const stage = join(paths.agentRoot, `.litcodex-stage-${nonce}`);
+    const backup = join(paths.agentRoot, `.litcodex-backup-${nonce}`);
+    if (snapshot.length > 0)
+        writeSnapshotToDirectory(paths, snapshot, stage);
+    let movedTarget = false;
+    try {
+        if (existsSync(target)) {
+            renameSync(target, backup);
+            movedTarget = true;
+        }
+        if (snapshot.length > 0)
+            renameSync(stage, target);
+    }
+    catch (error) {
+        if (existsSync(target) && movedTarget)
+            rmSync(target, { recursive: true, force: true });
+        if (movedTarget && existsSync(backup))
+            renameSync(backup, target);
+        if (existsSync(stage))
+            rmSync(stage, { recursive: true, force: true });
+        throw error instanceof SkillLoopError
+            ? error
+            : new SkillLoopError("TARGET_WRITE_FAILED", "the agent skill transaction failed");
+    }
+    if (movedTarget && existsSync(backup)) {
+        try {
+            rmSync(backup, { recursive: true, force: true });
+        }
+        catch {
+            // The committed target is authoritative. A same-root backup is recoverable cleanup residue.
+        }
+    }
+    fsyncDirectory(paths.agentRoot);
+}
+export function readUsage(paths) {
+    if (!existsSync(paths.usagePath))
+        return null;
+    if (lstatSync(paths.usagePath).isSymbolicLink() || !lstatSync(paths.usagePath).isFile()) {
+        throw new SkillLoopError("USAGE_INVALID", "the usage sidecar is unsafe");
+    }
+    try {
+        return JSON.parse(readFileSync(paths.usagePath, "utf8"));
+    }
+    catch {
+        throw new SkillLoopError("USAGE_INVALID", "the usage sidecar is invalid");
+    }
+}
+export function writeUsage(paths, sidecar) {
+    ensureAgentRoot(paths);
+    atomicWrite(paths.usagePath, `${JSON.stringify(sidecar, null, 2)}\n`);
+}

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

@@ -0,0 +1,26 @@
+import type { SkillLedgerEntry, SkillProposal, SkillUsageSidecar } from "./types.js";
+export interface SkillTransactionCopy {
+    readonly kind: "backup" | "archive";
+    readonly relativePath: string;
+}
+export interface SkillTransactionJournal {
+    readonly schema: "litcodex.skill-transaction/v1";
+    readonly operation: "apply" | "rollback" | "curator-transition";
+    readonly ledger: SkillLedgerEntry;
+    readonly authorization: string;
+    readonly proposalBefore?: SkillProposal;
+    readonly proposalAfter?: SkillProposal;
+    readonly usageBefore?: SkillUsageSidecar | null;
+    readonly usageAfter?: SkillUsageSidecar;
+    readonly copies: readonly SkillTransactionCopy[];
+}
+export type SkillTransactionDraft = Omit<SkillTransactionJournal, "authorization" | "proposalBefore" | "usageBefore">;
+export interface SkillTransactionExpectation {
+    readonly operation: SkillTransactionJournal["operation"];
+    readonly proposalId?: string;
+    readonly restoresLedgerEntryId?: string;
+}
+export declare function readMutationJournal(workspaceRoot: string, env?: NodeJS.ProcessEnv): SkillTransactionJournal | null;
+export declare function writeMutationJournal(workspaceRoot: string, journal: SkillTransactionDraft, env?: NodeJS.ProcessEnv): SkillTransactionJournal;
+export declare function recoverMutationJournalWhileLocked(workspaceRoot: string, env: NodeJS.ProcessEnv | undefined, expected: SkillTransactionExpectation): SkillTransactionJournal | null;
+export declare function recoverMutationJournal(workspaceRoot: string, env: NodeJS.ProcessEnv | undefined, expected: SkillTransactionExpectation): SkillTransactionJournal | null;