@litfamily/litcodex 1.0.0 → 1.0.2

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

@@ -1,667 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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;