@litfamily/litclaude 1.0.6 → 1.0.7

package/plugins/litclaude/lib/skill-loop/ledger.mjs

@@ -1,834 +0,0 @@
-import { randomUUID } from "node:crypto";
-import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  opendirSync,
-  renameSync,
-  rmdirSync,
-  rmSync,
-} from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
-
-import { parseStrictJson } from "../strict-json.mjs";
-import { resolveAgentTarget } from "./authority.mjs";
-import {
-  assertNoSecretStrings,
-  assertRegularSingleLink,
-  atomicWriteBytes,
-  captureDirectoryIdentity,
-  decodeSkillLoopUtf8,
-  directoryIdentityMatches,
-  ensureSafeDirectoryChain,
-  isPlainObject,
-  parseTimestamp,
-  portablePathIdentity,
-  readStrictJsonFile,
-  RECORD_ID,
-  requireExactKeys,
-  sha256,
-  skillRootFor,
-  skillRootsEquivalent,
-  SKILL_ID,
-  withSkillLoopLock,
-} from "./common.mjs";
-import { proposalFilePath, readProposalRecord, transitionProposalRecordUnlocked } from "./proposal-store.mjs";
-import { recoverReviewTransactionUnlocked } from "./review-transaction.mjs";
-import { readUsage, writeUsageUnlocked } from "./usage.mjs";
-import {
-  beginSkillMutationTransactionUnlocked,
-  recoverSkillMutationTransactionUnlocked,
-} from "./mutation-transaction.mjs";
-
-export class SkillLoopLedgerError extends Error {
-  constructor(code, message = code) {
-    super(`${code}: ${message}`);
-    this.name = "SkillLoopLedgerError";
-    this.code = code;
-  }
-}
-
-export const SESSION_START_LEDGER_WORK_LIMITS = Object.freeze({
-  maxEntries: 256,
-  maxBlobs: 512,
-  maxBlobBytes: 32 * 1024 * 1024,
-  maxTargetEntries: 256,
-});
-
-export const SNAPSHOT_WORK_LIMITS = Object.freeze({
-  maxDirectoryEntries: 1_024,
-  maxDirectories: 128,
-  maxDepth: 32,
-  maxFiles: 256,
-  maxBytes: 32 * 1024 * 1024,
-});
-
-export function createSnapshotWorkBudget() {
-  return { directoryEntries: 0, directories: 0, files: 0, bytes: 0 };
-}
-
-function validateLedgerWorkLimits(limits) {
-  if (limits === null || limits === undefined) return null;
-  const normalized = { ...SESSION_START_LEDGER_WORK_LIMITS, ...limits };
-  if (!limits || ![
-    normalized.maxEntries, normalized.maxBlobs, normalized.maxBlobBytes, normalized.maxTargetEntries,
-  ].every(Number.isSafeInteger)
-    || normalized.maxEntries < 1 || normalized.maxEntries > 4096
-    || normalized.maxBlobs < 1 || normalized.maxBlobs > 8192
-    || normalized.maxBlobBytes < 1 || normalized.maxBlobBytes > 256 * 1024 * 1024
-    || normalized.maxTargetEntries < 1 || normalized.maxTargetEntries > 4096) {
-    throw new SkillLoopLedgerError("LEDGER_WORK_CAP_INVALID");
-  }
-  return normalized;
-}
-
-const ledgerFile = (root, create) => {
-  const state = ensureSafeDirectoryChain(root, [".litclaude"], {
-    create,
-    ErrorType: SkillLoopLedgerError,
-    code: "LEDGER_STORE_UNSAFE",
-  });
-  return state === null ? null : join(state, "skill-ledger.jsonl");
-};
-
-function captureLedgerStoreFingerprint(root) {
-  const path = ledgerFile(root, false);
-  if (path === null) return { exists: false };
-  const details = lstatSync(path, { throwIfNoEntry: false });
-  if (!details) return { exists: false };
-  const bytes = assertRegularSingleLink(path, SkillLoopLedgerError, "LEDGER_STORE_UNSAFE", {
-    maxBytes: 16 * 1024 * 1024,
-  });
-  return {
-    exists: true,
-    dev: details.dev,
-    ino: details.ino,
-    size: bytes.length,
-    digest: sha256(bytes),
-  };
-}
-
-function validLedgerStoreFingerprint(fingerprint) {
-  return isPlainObject(fingerprint) && (fingerprint.exists === false
-    ? requireExactKeys(fingerprint, ["exists"])
-    : fingerprint.exists === true
-      && requireExactKeys(fingerprint, ["exists", "dev", "ino", "size", "digest"])
-      && Number.isSafeInteger(fingerprint.dev) && fingerprint.dev >= 0
-      && Number.isSafeInteger(fingerprint.ino) && fingerprint.ino > 0
-      && Number.isSafeInteger(fingerprint.size) && fingerprint.size >= 0
-      && /^[a-f0-9]{64}$/u.test(fingerprint.digest));
-}
-
-const blobDirectory = (root, create) => ensureSafeDirectoryChain(root, [".litclaude", "skill-ledger-blobs"], {
-  create,
-  ErrorType: SkillLoopLedgerError,
-  code: "LEDGER_STORE_UNSAFE",
-});
-
-export function ledgerBlobPath(root, digest) {
-  if (!/^[a-f0-9]{64}$/u.test(digest)) throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-  const directory = blobDirectory(root, false);
-  return directory === null ? join(root, ".litclaude", "skill-ledger-blobs", digest) : join(directory, digest);
-}
-
-function validateSnapshot(snapshot) {
-  if (!Array.isArray(snapshot) || snapshot.length > 256) throw new SkillLoopLedgerError("LEDGER_SCHEMA_INVALID");
-  const canonical = new Set();
-  for (const item of snapshot) {
-    const identity = portablePathIdentity(item?.file);
-    if (identity === null || canonical.has(identity)
-      || !requireExactKeys(item, ["file", "blob"])
-      || !requireExactKeys(item.blob, ["algorithm", "digest", "size"])
-      || item.blob.algorithm !== "sha256" || !/^[a-f0-9]{64}$/u.test(item.blob.digest)
-      || !Number.isSafeInteger(item.blob.size) || item.blob.size < 0) {
-      throw new SkillLoopLedgerError("LEDGER_SCHEMA_INVALID");
-    }
-    canonical.add(identity);
-  }
-}
-
-const snapshotsEqual = (left, right) => JSON.stringify(left) === JSON.stringify(right);
-const usageTransition = (entry) => /^usage:(active|stale|archived)->(active|stale|archived)$/u.exec(
-  entry?.reason ?? "",
-);
-
-export function rollbackEntryMatchesReference(reference, rollback) {
-  if (!reference || !rollback || !["apply", "curator-transition", "rollback"].includes(reference.operation)
-    || reference.actor !== (reference.operation === "curator-transition" ? "curator" : "user")
-    || rollback.operation !== "rollback" || rollback.actor !== "user"
-    || rollback.restoresLedgerEntryId !== reference.id
-    || rollback.proposalId !== reference.proposalId
-    || rollback.targetSkill !== reference.targetSkill || rollback.targetRoot !== reference.targetRoot
-    || !snapshotsEqual(rollback.before, reference.after)
-    || !snapshotsEqual(rollback.after, reference.before)) return false;
-  const referenceTransition = usageTransition(reference);
-  const rollbackTransition = usageTransition(rollback);
-  if (referenceTransition) {
-    return rollbackTransition !== null
-      && rollbackTransition[1] === referenceTransition[2]
-      && rollbackTransition[2] === referenceTransition[1];
-  }
-  return !Object.hasOwn(reference, "reason") && !Object.hasOwn(rollback, "reason");
-}
-
-export function validateLedgerEntry(entry) {
-  if (!requireExactKeys(entry, [
-    "schema", "id", "createdAt", "proposalId", "actor", "operation", "targetSkill", "targetRoot",
-    "before", "after",
-  ], ["restoresLedgerEntryId", "reason"])
-    || entry.schema !== "litfamily.skill-ledger/v1" || !RECORD_ID.test(entry.id)
-    || parseTimestamp(entry.createdAt) === null
-    || !(entry.proposalId === null || (typeof entry.proposalId === "string" && entry.proposalId.length > 0 && entry.proposalId.length <= 128))
-    || !["user", "curator"].includes(entry.actor)
-    || !["apply", "reject", "rollback", "curator-transition"].includes(entry.operation)
-    || !SKILL_ID.test(entry.targetSkill) || portablePathIdentity(entry.targetSkill) === null
-    || typeof entry.targetRoot !== "string" || entry.targetRoot.length < 1 || entry.targetRoot.length > 2048
-    || (Object.hasOwn(entry, "reason") && (typeof entry.reason !== "string" || entry.reason.length > 8192))) {
-    throw new SkillLoopLedgerError("LEDGER_SCHEMA_INVALID");
-  }
-  const rollback = entry.operation === "rollback";
-  if (rollback !== Object.hasOwn(entry, "restoresLedgerEntryId")
-    || (rollback && !RECORD_ID.test(entry.restoresLedgerEntryId))) throw new SkillLoopLedgerError("LEDGER_SCHEMA_INVALID");
-  if (["apply", "reject"].includes(entry.operation) && (entry.actor !== "user" || entry.proposalId === null)) {
-    throw new SkillLoopLedgerError("LEDGER_SCHEMA_INVALID");
-  }
-  if (entry.operation === "rollback" && entry.actor !== "user") throw new SkillLoopLedgerError("LEDGER_SCHEMA_INVALID");
-  if (entry.operation === "curator-transition" && (entry.actor !== "curator" || entry.proposalId !== null)) {
-    throw new SkillLoopLedgerError("LEDGER_SCHEMA_INVALID");
-  }
-  validateSnapshot(entry.before);
-  validateSnapshot(entry.after);
-  if (entry.operation === "reject" && (entry.before.length !== 0 || entry.after.length !== 0)) {
-    throw new SkillLoopLedgerError("LEDGER_SCHEMA_INVALID");
-  }
-  assertNoSecretStrings(entry, () => { throw new SkillLoopLedgerError("LEDGER_SECRET_REFUSED"); });
-  return entry;
-}
-
-export function readLedger(root, { workLimits = null } = {}) {
-  const limits = validateLedgerWorkLimits(workLimits);
-  const path = ledgerFile(root, false);
-  if (path === null || !lstatSync(path, { throwIfNoEntry: false })) return [];
-  let text;
-  try {
-    text = decodeSkillLoopUtf8(assertRegularSingleLink(path, SkillLoopLedgerError, "LEDGER_STORE_UNSAFE", {
-      maxBytes: 16 * 1024 * 1024,
-    }));
-  } catch (error) {
-    if (error instanceof SkillLoopLedgerError) throw error;
-    throw new SkillLoopLedgerError("LEDGER_STORE_INVALID");
-  }
-  const records = [];
-  const ids = new Set();
-  try {
-    const lines = text.split("\n");
-    if (lines.at(-1) === "") lines.pop();
-    for (const line of lines) {
-      if (line === "") throw new SkillLoopLedgerError("LEDGER_STORE_INVALID");
-      const entry = validateLedgerEntry(parseStrictJson(line));
-      if (ids.has(entry.id)) throw new SkillLoopLedgerError("LEDGER_SCHEMA_INVALID");
-      ids.add(entry.id);
-      records.push(entry);
-      if (limits && records.length > limits.maxEntries) {
-        throw new SkillLoopLedgerError("LEDGER_WORK_CAP_EXCEEDED");
-      }
-    }
-  } catch (error) {
-    if (error instanceof SkillLoopLedgerError) throw error;
-    throw new SkillLoopLedgerError("LEDGER_STORE_INVALID");
-  }
-  const byId = new Map(records.map((entry) => [entry.id, entry]));
-  const visiting = new Set();
-  const visited = new Set();
-  const visit = (entry) => {
-    if (visited.has(entry.id) || entry.operation !== "rollback") return;
-    if (visiting.has(entry.id)) throw new SkillLoopLedgerError("ROLLBACK_CYCLE");
-    visiting.add(entry.id);
-    const referenced = byId.get(entry.restoresLedgerEntryId);
-    if (referenced) visit(referenced);
-    visiting.delete(entry.id);
-    visited.add(entry.id);
-  };
-  for (const entry of records) visit(entry);
-  const prior = new Map();
-  const blobs = new Map();
-  let blobBytes = 0;
-  for (const entry of records) {
-    if (entry.operation !== "reject") {
-      resolveAgentTarget(root, entry.targetRoot, entry.targetSkill, {
-        allowMissing: true,
-        requireOwned: false,
-        ErrorType: SkillLoopLedgerError,
-        notOwnedCode: "TARGET_NOT_AGENT_OWNED",
-        pathCode: "SNAPSHOT_PATH_UNSAFE",
-        collisionCode: "TARGET_IDENTITY_COLLISION",
-        maxDirectoryEntries: limits?.maxTargetEntries ?? null,
-        workCapCode: "LEDGER_WORK_CAP_EXCEEDED",
-      });
-    }
-    for (const item of [...entry.before, ...entry.after]) {
-      const existing = blobs.get(item.blob.digest);
-      if (existing && existing.blob.size !== item.blob.size) throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-      if (existing) continue;
-      blobs.set(item.blob.digest, item);
-      blobBytes += item.blob.size;
-      if (limits && (blobs.size > limits.maxBlobs || blobBytes > limits.maxBlobBytes)) {
-        throw new SkillLoopLedgerError("LEDGER_WORK_CAP_EXCEEDED");
-      }
-    }
-    if (entry.operation === "rollback") {
-      if (entry.restoresLedgerEntryId === entry.id) throw new SkillLoopLedgerError("ROLLBACK_CYCLE");
-      const referenced = prior.get(entry.restoresLedgerEntryId);
-      if (!referenced) {
-        if (byId.has(entry.restoresLedgerEntryId)) throw new SkillLoopLedgerError("ROLLBACK_FORWARD_REFERENCE");
-        throw new SkillLoopLedgerError("ROLLBACK_ENTRY_INELIGIBLE");
-      }
-      if (!["apply", "curator-transition", "rollback"].includes(referenced.operation)) {
-        throw new SkillLoopLedgerError("ROLLBACK_ENTRY_INELIGIBLE");
-      }
-      if (referenced.targetSkill !== entry.targetSkill || referenced.targetRoot !== entry.targetRoot) {
-        throw new SkillLoopLedgerError("ROLLBACK_TARGET_MISMATCH");
-      }
-      if (!rollbackEntryMatchesReference(referenced, entry)) {
-        throw new SkillLoopLedgerError("ROLLBACK_INVERSE_INVALID");
-      }
-    }
-    prior.set(entry.id, entry);
-  }
-  for (const item of blobs.values()) verifySnapshotBlobs(root, [item]);
-  return records;
-}
-
-export function readLedgerReferenceSnapshot(root, {
-  workLimits = SESSION_START_LEDGER_WORK_LIMITS,
-} = {}) {
-  const before = captureLedgerStoreFingerprint(root);
-  const entries = readLedger(root, { workLimits });
-  const fingerprint = captureLedgerStoreFingerprint(root);
-  if (JSON.stringify(before) !== JSON.stringify(fingerprint)) {
-    throw new SkillLoopLedgerError("LEDGER_STORE_INVALID");
-  }
-  return { entries, fingerprint };
-}
-
-export function ledgerReferenceSnapshotUnchanged(root, fingerprint) {
-  if (!validLedgerStoreFingerprint(fingerprint)) return false;
-  try {
-    return JSON.stringify(captureLedgerStoreFingerprint(root)) === JSON.stringify(fingerprint);
-  } catch {
-    return false;
-  }
-}
-
-export function appendLedgerEntryUnlocked(root, entry) {
-  validateLedgerEntry(entry);
-  const existing = readLedger(root);
-  if (existing.some(({ id }) => id === entry.id)) throw new SkillLoopLedgerError("LEDGER_ID_COLLISION");
-  if (entry.operation !== "reject") {
-    resolveAgentTarget(root, entry.targetRoot, entry.targetSkill, {
-      allowMissing: true,
-      requireOwned: false,
-      ErrorType: SkillLoopLedgerError,
-      notOwnedCode: "TARGET_NOT_AGENT_OWNED",
-      pathCode: "SNAPSHOT_PATH_UNSAFE",
-    });
-  }
-  verifySnapshotBlobs(root, entry.before);
-  verifySnapshotBlobs(root, entry.after);
-  if (entry.operation === "rollback") {
-    if (entry.restoresLedgerEntryId === entry.id) throw new SkillLoopLedgerError("ROLLBACK_CYCLE");
-    const referenced = existing.find(({ id }) => id === entry.restoresLedgerEntryId);
-    if (!referenced || !["apply", "curator-transition", "rollback"].includes(referenced.operation)) {
-      throw new SkillLoopLedgerError("ROLLBACK_ENTRY_INELIGIBLE");
-    }
-    if (referenced.targetSkill !== entry.targetSkill || referenced.targetRoot !== entry.targetRoot) {
-      throw new SkillLoopLedgerError("ROLLBACK_TARGET_MISMATCH");
-    }
-    if (!rollbackEntryMatchesReference(referenced, entry)) {
-      throw new SkillLoopLedgerError("ROLLBACK_INVERSE_INVALID");
-    }
-  }
-  const path = ledgerFile(root, true);
-  const current = lstatSync(path, { throwIfNoEntry: false });
-  if (current && (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1)) {
-    throw new SkillLoopLedgerError("LEDGER_STORE_UNSAFE");
-  }
-  try {
-    const prior = current
-      ? assertRegularSingleLink(path, SkillLoopLedgerError, "LEDGER_STORE_UNSAFE", { maxBytes: 16 * 1024 * 1024 })
-      : Buffer.alloc(0);
-    const addition = Buffer.from(`${JSON.stringify(entry)}\n`, "utf8");
-    if (prior.length + addition.length > 16 * 1024 * 1024) {
-      throw new SkillLoopLedgerError("LEDGER_TOO_LARGE");
-    }
-    atomicWriteBytes(path, Buffer.concat([prior, addition]),
-      SkillLoopLedgerError, "LEDGER_APPEND_FAILED");
-  } catch (error) {
-    if (error instanceof SkillLoopLedgerError) throw error;
-    throw new SkillLoopLedgerError("LEDGER_APPEND_FAILED");
-  }
-  return entry;
-}
-
-export function appendLedgerEntry(root, entry) {
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    return appendLedgerEntryUnlocked(root, entry);
-  },
-    SkillLoopLedgerError, "LEDGER_LOCK_FAILED");
-}
-
-export function proposalReceiptMatches(proposal, entry, { operation, currentSnapshot } = {}) {
-  if (!entry || entry.operation !== operation || entry.proposalId !== proposal.id
-    || entry.targetSkill !== proposal.targetSkill || entry.targetRoot !== proposal.targetRoot
-    || parseTimestamp(entry.createdAt) === null || parseTimestamp(proposal.createdAt) === null
-    || parseTimestamp(entry.createdAt) < parseTimestamp(proposal.createdAt)) return false;
-  if (operation === "apply" && currentSnapshot !== undefined
-    && !snapshotsEqual(currentSnapshot, entry.after)) return false;
-  return true;
-}
-
-export function validateProposalReceipt(root, proposal, ledgerIndex) {
-  const index = ledgerIndex ?? new Map(readLedger(root).map((entry) => [entry.id, entry]));
-  const entry = index.get(proposal.ledgerEntryId);
-  const expectedOperation = proposal.status === "applied" ? "apply" : "rollback";
-  if (!proposalReceiptMatches(proposal, entry, { operation: expectedOperation })) {
-    throw new SkillLoopLedgerError("PROPOSAL_LEDGER_INVALID");
-  }
-  return entry;
-}
-
-function persistBlob(root, bytes, createdBlobs) {
-  const digest = sha256(bytes);
-  const directory = blobDirectory(root, true);
-  const path = join(directory, digest);
-  if (existsSync(path)) {
-    const current = assertRegularSingleLink(path, SkillLoopLedgerError, "LEDGER_BLOB_INVALID", {
-      maxBytes: 8 * 1024 * 1024,
-    });
-    if (current.length !== bytes.length || sha256(current) !== digest) throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-  } else {
-    atomicWriteBytes(path, bytes, SkillLoopLedgerError, "LEDGER_STORE_UNSAFE");
-    const details = lstatSync(path, { throwIfNoEntry: false });
-    if (!details?.isFile() || details.isSymbolicLink() || details.nlink !== 1) {
-      throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-    }
-    createdBlobs?.set(digest, { dev: details.dev, ino: details.ino });
-  }
-  return { algorithm: "sha256", digest, size: bytes.length };
-}
-
-export function cleanupCreatedSnapshotBlobs(root, createdBlobs, {
-  removeEmptyDirectory = false,
-  referencedDigests,
-} = {}) {
-  if (!(createdBlobs instanceof Map) || !(referencedDigests instanceof Set)
-    || createdBlobs.size > 256 || referencedDigests.size > 512) {
-    throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-  }
-  const removable = [];
-  for (const [digest, identity] of createdBlobs) {
-    if (!/^[a-f0-9]{64}$/u.test(digest) || !identity
-      || !Number.isSafeInteger(identity.dev) || identity.dev < 0
-      || !Number.isSafeInteger(identity.ino) || identity.ino <= 0) {
-      throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-    }
-    if (referencedDigests.has(digest)) continue;
-    const path = ledgerBlobPath(root, digest);
-    const details = lstatSync(path, { throwIfNoEntry: false });
-    if (!details) continue;
-    if (!details.isFile() || details.isSymbolicLink() || details.nlink !== 1
-      || details.dev !== identity.dev || details.ino !== identity.ino) {
-      throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-    }
-    const bytes = assertRegularSingleLink(path, SkillLoopLedgerError, "LEDGER_BLOB_INVALID", {
-      maxBytes: 8 * 1024 * 1024,
-    });
-    if (sha256(bytes) !== digest) throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-    removable.push(path);
-  }
-  for (const path of removable) rmSync(path);
-  if (removeEmptyDirectory) {
-    const directory = blobDirectory(root, false);
-    if (directory !== null) {
-      let handle;
-      try {
-        handle = opendirSync(directory);
-        if (handle.readSync() === null) {
-          handle.closeSync();
-          handle = undefined;
-          rmdirSync(directory);
-        }
-      } finally {
-        handle?.closeSync();
-      }
-    }
-  }
-}
-
-function safeTargetDirectory(root, targetRoot, targetSkill) {
-  if (!skillRootsEquivalent(root, targetRoot) || !SKILL_ID.test(targetSkill)) {
-    throw new SkillLoopLedgerError("SNAPSHOT_PATH_UNSAFE");
-  }
-  const skills = ensureSafeDirectoryChain(root, [".claude", "skills"], {
-    create: false,
-    ErrorType: SkillLoopLedgerError,
-    code: "SNAPSHOT_PATH_UNSAFE",
-  });
-  if (skills === null) return null;
-  const target = join(skills, targetSkill);
-  const details = lstatSync(target, { throwIfNoEntry: false });
-  if (!details) return null;
-  if (!details.isDirectory() || details.isSymbolicLink()) throw new SkillLoopLedgerError("SNAPSHOT_PATH_UNSAFE");
-  return target;
-}
-
-function validateSnapshotWorkLimits(workLimits) {
-  const limits = { ...SNAPSHOT_WORK_LIMITS, ...(workLimits ?? {}) };
-  if (![limits.maxDirectoryEntries, limits.maxDirectories, limits.maxDepth,
-    limits.maxFiles, limits.maxBytes].every(Number.isSafeInteger)
-    || limits.maxDirectoryEntries < 1 || limits.maxDirectoryEntries > 16_384
-    || limits.maxDirectories < 1 || limits.maxDirectories > 4_096
-    || limits.maxDepth < 1 || limits.maxDepth > 32
-    || limits.maxFiles < 1 || limits.maxFiles > 256
-    || limits.maxBytes < 1 || limits.maxBytes > 32 * 1024 * 1024) {
-    throw new SkillLoopLedgerError("SNAPSHOT_WORK_CAP_INVALID");
-  }
-  return limits;
-}
-
-function validateSnapshotWorkBudget(work) {
-  if (!work || !requireExactKeys(work, ["directoryEntries", "directories", "files", "bytes"])
-    || ![work.directoryEntries, work.directories, work.files, work.bytes].every(Number.isSafeInteger)
-    || work.directoryEntries < 0 || work.directories < 0 || work.files < 0 || work.bytes < 0) {
-    throw new SkillLoopLedgerError("SNAPSHOT_WORK_CAP_INVALID");
-  }
-  return work;
-}
-
-function captureDirectorySnapshot(root, target, {
-  workLimits = null,
-  work = null,
-  createdBlobs = null,
-} = {}) {
-  if (target === null) return [];
-  if (createdBlobs !== null && !(createdBlobs instanceof Map)) {
-    throw new SkillLoopLedgerError("SNAPSHOT_WORK_CAP_INVALID");
-  }
-  const limits = validateSnapshotWorkLimits(workLimits);
-  const capCode = workLimits === null ? "SNAPSHOT_TOO_LARGE" : "SNAPSHOT_WORK_CAP_EXCEEDED";
-  const budget = validateSnapshotWorkBudget(work ?? createSnapshotWorkBudget());
-  const files = [];
-  const identities = new Set();
-  const walk = (directory, depth) => {
-    budget.directories += 1;
-    if (budget.directories > limits.maxDirectories || depth > limits.maxDepth) {
-      throw new SkillLoopLedgerError(capCode);
-    }
-    let handle;
-    try {
-      handle = opendirSync(directory);
-      let entry;
-      while ((entry = handle.readSync()) !== null) {
-        budget.directoryEntries += 1;
-        if (budget.directoryEntries > limits.maxDirectoryEntries) throw new SkillLoopLedgerError(capCode);
-        const path = join(directory, entry.name);
-        const details = lstatSync(path, { throwIfNoEntry: false });
-        if (!details || details.isSymbolicLink()) throw new SkillLoopLedgerError("SNAPSHOT_PATH_UNSAFE");
-        if (details.isDirectory()) {
-          walk(path, depth + 1);
-          continue;
-        }
-        if (!details.isFile() || details.nlink !== 1) throw new SkillLoopLedgerError("SNAPSHOT_PATH_UNSAFE");
-        const file = relative(target, path).replaceAll("\\", "/");
-        const identity = portablePathIdentity(file);
-        if (identity === null || identities.has(identity)) throw new SkillLoopLedgerError("SNAPSHOT_PATH_UNSAFE");
-        identities.add(identity);
-        budget.files += 1;
-        if (budget.files > limits.maxFiles || details.size > 8 * 1024 * 1024
-          || details.size > limits.maxBytes - budget.bytes) {
-          throw new SkillLoopLedgerError(capCode);
-        }
-        const bytes = assertRegularSingleLink(path, SkillLoopLedgerError, "SNAPSHOT_PATH_UNSAFE", {
-          maxBytes: 8 * 1024 * 1024,
-        });
-        budget.bytes += bytes.length;
-        if (budget.bytes > limits.maxBytes) {
-          throw new SkillLoopLedgerError(capCode);
-        }
-        files.push({ file, blob: persistBlob(root, bytes, createdBlobs) });
-      }
-    } finally {
-      handle?.closeSync();
-    }
-  };
-  walk(target, 0);
-  return files.sort((left, right) => left.file.localeCompare(right.file));
-}
-
-export function captureSkillSnapshot(root, targetRoot, targetSkill, options = {}) {
-  return captureDirectorySnapshot(root, safeTargetDirectory(root, targetRoot, targetSkill), options);
-}
-
-export function captureStagedSnapshot(root, directory, options = {}) {
-  const skills = ensureSafeDirectoryChain(root, [".claude", "skills"], {
-    create: false,
-    ErrorType: SkillLoopLedgerError,
-    code: "SNAPSHOT_PATH_UNSAFE",
-  });
-  const path = resolve(directory);
-  const workspace = resolve(root);
-  const local = relative(workspace, path).replaceAll("\\", "/");
-  const temporary = skills !== null && dirname(path) === resolve(skills)
-    && /^\.[a-z0-9][a-z0-9-]*\.(?:apply|rollback)-/u.test(path.split(/[\\/]/u).at(-1));
-  const archived = /^\.litclaude\/skill-archives\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z\/[a-z0-9][a-z0-9-]*$/u.test(local);
-  if (!temporary && !archived) {
-    throw new SkillLoopLedgerError("SNAPSHOT_PATH_UNSAFE");
-  }
-  const details = lstatSync(path, { throwIfNoEntry: false });
-  if (!details?.isDirectory() || details.isSymbolicLink()) throw new SkillLoopLedgerError("SNAPSHOT_PATH_UNSAFE");
-  return captureDirectorySnapshot(root, path, options);
-}
-
-export function captureBackupSnapshot(root, directory, options = {}) {
-  const path = resolve(directory);
-  const local = relative(resolve(root), path).replaceAll("\\", "/");
-  if (!/^\.litclaude\/skill-backups\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z\/[a-z0-9][a-z0-9-]*$/u.test(local)) {
-    throw new SkillLoopLedgerError("SNAPSHOT_PATH_UNSAFE");
-  }
-  const details = lstatSync(path, { throwIfNoEntry: false });
-  if (!details?.isDirectory() || details.isSymbolicLink()) {
-    throw new SkillLoopLedgerError("SNAPSHOT_PATH_UNSAFE");
-  }
-  return captureDirectorySnapshot(root, path, options);
-}
-
-export function verifySnapshotBlobs(root, snapshot) {
-  validateSnapshot(snapshot);
-  for (const item of snapshot) {
-    const path = ledgerBlobPath(root, item.blob.digest);
-    if (!existsSync(path)) throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-    const bytes = assertRegularSingleLink(path, SkillLoopLedgerError, "LEDGER_BLOB_INVALID", {
-      maxBytes: 8 * 1024 * 1024,
-    });
-    if (bytes.length !== item.blob.size || sha256(bytes) !== item.blob.digest) {
-      throw new SkillLoopLedgerError("LEDGER_BLOB_INVALID");
-    }
-  }
-}
-
-export function materializeSnapshot(root, directory, snapshot) {
-  mkdirSync(directory, { mode: 0o700 });
-  for (const item of snapshot) {
-    const path = join(directory, ...item.file.split("/"));
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    const bytes = assertRegularSingleLink(ledgerBlobPath(root, item.blob.digest), SkillLoopLedgerError, "LEDGER_BLOB_INVALID");
-    atomicWriteBytes(path, bytes, SkillLoopLedgerError, "ROLLBACK_RESTORE_FAILED");
-  }
-}
-
-function assertNoCycle(entry, entriesById) {
-  const seen = new Set();
-  let current = entry;
-  while (current?.operation === "rollback") {
-    if (seen.has(current.id)) throw new SkillLoopLedgerError("ROLLBACK_CYCLE");
-    seen.add(current.id);
-    const next = entriesById.get(current.restoresLedgerEntryId);
-    if (!next) throw new SkillLoopLedgerError("ROLLBACK_ENTRY_INELIGIBLE");
-    if (next.targetSkill !== entry.targetSkill || next.targetRoot !== entry.targetRoot) {
-      throw new SkillLoopLedgerError("ROLLBACK_TARGET_MISMATCH");
-    }
-    current = next;
-  }
-}
-
-export function rollbackLedgerEntry(root, entryId, {
-  now = new Date().toISOString(),
-  beforeCommit,
-  afterIdentityCapture,
-  beforeProposalCommit,
-  afterTransactionBegin,
-  afterCurrentDisplaced,
-  afterLiveMutation,
-  afterUsageCommit,
-  afterLedgerCommit,
-  afterProposalCommit,
-} = {}) {
-  if (!RECORD_ID.test(entryId) || parseTimestamp(now) === null) throw new SkillLoopLedgerError("ROLLBACK_ENTRY_INELIGIBLE");
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    const mutationRecovery = recoverSkillMutationTransactionUnlocked(root);
-    if (mutationRecovery.status === "finalized" && mutationRecovery.kind === "rollback"
-      && mutationRecovery.requestId === entryId) {
-      return { ...mutationRecovery.ledgerEntry, recovered: true };
-    }
-    const recoveredPreparedMutation = mutationRecovery.status === "rolled-back"
-      && mutationRecovery.kind === "rollback" && mutationRecovery.requestId === entryId;
-    const ledger = readLedger(root);
-    const byId = new Map(ledger.map((entry) => [entry.id, entry]));
-    const target = byId.get(entryId);
-    if (!target || !["apply", "curator-transition", "rollback"].includes(target.operation)) {
-      throw new SkillLoopLedgerError("ROLLBACK_ENTRY_INELIGIBLE");
-    }
-    assertNoCycle(target, byId);
-    resolveAgentTarget(root, target.targetRoot, target.targetSkill, {
-      allowMissing: true,
-      requireOwned: false,
-      ErrorType: SkillLoopLedgerError,
-      notOwnedCode: "TARGET_NOT_AGENT_OWNED",
-      pathCode: "SNAPSHOT_PATH_UNSAFE",
-    });
-    verifySnapshotBlobs(root, target.before);
-    verifySnapshotBlobs(root, target.after);
-    const recovery = ledger.findLast((entry) => entry.operation === "rollback" && entry.restoresLedgerEntryId === target.id);
-    if (recovery) {
-      const current = captureSkillSnapshot(root, target.targetRoot, target.targetSkill);
-      if (snapshotsEqual(current, recovery.after)) {
-        if (target.proposalId) {
-          const proposal = readProposalRecord(root, target.proposalId);
-          transitionProposalRecordUnlocked(root, proposal.id, "rolled-back", recovery.id);
-        }
-        return { ...recovery, recovered: true };
-      }
-    }
-
-    const skills = ensureSafeDirectoryChain(root, [".claude", "skills"], {
-      create: true,
-      ErrorType: SkillLoopLedgerError,
-      code: "SNAPSHOT_PATH_UNSAFE",
-    });
-    const destination = join(skills, target.targetSkill);
-    const stage = join(skills, `.${target.targetSkill}.rollback-${randomUUID()}`);
-    const displaced = join(skills, `.${target.targetSkill}.rollback-before-${randomUUID()}`);
-    if (target.before.length > 0) materializeSnapshot(root, stage, target.before);
-    beforeCommit?.();
-    const current = captureSkillSnapshot(root, target.targetRoot, target.targetSkill);
-    if (!snapshotsEqual(current, target.after)) throw new SkillLoopLedgerError("ROLLBACK_CAS_MISMATCH");
-    const usageTransition = /^usage:(active|stale|archived)->(active|stale|archived)$/u.exec(target.reason ?? "");
-    const usageBefore = usageTransition ? readUsage(root) : null;
-    if (usageTransition && usageBefore.skills[target.targetSkill]?.state !== usageTransition[2]) {
-      throw new SkillLoopLedgerError("ROLLBACK_USAGE_CAS_MISMATCH");
-    }
-    let movedCurrent = false;
-    let installedStage = false;
-    let ledgerCommitted = false;
-    let usageCommitted = false;
-    try {
-      const expectedIdentity = captureDirectoryIdentity(destination, SkillLoopLedgerError, "SNAPSHOT_PATH_UNSAFE", {
-        allowMissing: current.length === 0,
-      });
-      afterIdentityCapture?.();
-      if (!directoryIdentityMatches(destination, expectedIdentity)) {
-        throw new SkillLoopLedgerError("ROLLBACK_IDENTITY_MISMATCH");
-      }
-      const restored = target.before.length > 0 ? captureStagedSnapshot(root, stage) : [];
-      const stageIdentity = captureDirectoryIdentity(stage, SkillLoopLedgerError, "SNAPSHOT_PATH_UNSAFE", {
-        allowMissing: target.before.length === 0,
-      });
-      if (!snapshotsEqual(restored, target.before)) throw new SkillLoopLedgerError("ROLLBACK_RESTORE_FAILED");
-      const rollbackId = `ledger-${randomUUID()}`;
-      const entry = {
-        schema: "litfamily.skill-ledger/v1",
-        id: rollbackId,
-        createdAt: now,
-        proposalId: target.proposalId,
-        actor: "user",
-        operation: "rollback",
-        targetSkill: target.targetSkill,
-        targetRoot: target.targetRoot,
-        before: current,
-        after: restored,
-        restoresLedgerEntryId: target.id,
-        ...(usageTransition ? { reason: `usage:${usageTransition[2]}->${usageTransition[1]}` } : {}),
-      };
-      const proposalBefore = target.proposalId ? readProposalRecord(root, target.proposalId) : null;
-      const proposalAfter = proposalBefore === null
-        ? null
-        : { ...proposalBefore, status: "rolled-back", ledgerEntryId: rollbackId };
-      const usageAfter = usageBefore === null ? null : structuredClone(usageBefore);
-      if (usageAfter) {
-        usageAfter.skills[target.targetSkill].state = usageTransition[1];
-        usageAfter.skills[target.targetSkill].archived_at = usageTransition[1] === "archived" ? now : null;
-        usageAfter.updatedAt = now;
-      }
-      beginSkillMutationTransactionUnlocked(root, {
-        schema: "litclaude.skill-mutation-transaction/v1",
-        id: rollbackId,
-        kind: "rollback",
-        requestId: entryId,
-        createdAt: now,
-        targetRoot: target.targetRoot,
-        targetSkill: target.targetSkill,
-        action: "rollback",
-        stageName: stage.split(/[\\/]/u).at(-1),
-        displacedName: displaced.split(/[\\/]/u).at(-1),
-        archiveParts: null,
-        beforeIdentity: expectedIdentity,
-        stageIdentity,
-        before: current,
-        after: restored,
-        ledgerEntry: entry,
-        proposalBefore,
-        proposalAfter,
-        usageBefore,
-        usageAfter,
-        configBefore: null,
-        configAfter: null,
-      });
-      afterTransactionBegin?.();
-      if (expectedIdentity !== null) {
-        renameSync(destination, displaced);
-        movedCurrent = true;
-        if (!directoryIdentityMatches(displaced, expectedIdentity)) {
-          renameSync(displaced, destination);
-          movedCurrent = false;
-          throw new SkillLoopLedgerError("ROLLBACK_IDENTITY_MISMATCH");
-        }
-      } else if (!directoryIdentityMatches(destination, null)) {
-        throw new SkillLoopLedgerError("ROLLBACK_IDENTITY_MISMATCH");
-      }
-      afterCurrentDisplaced?.();
-      if (target.before.length > 0) {
-        renameSync(stage, destination);
-        installedStage = true;
-      }
-      afterLiveMutation?.();
-      const liveRestored = captureSkillSnapshot(root, target.targetRoot, target.targetSkill);
-      if (!snapshotsEqual(liveRestored, target.before)) throw new SkillLoopLedgerError("ROLLBACK_RESTORE_FAILED");
-      if (usageTransition) {
-        writeUsageUnlocked(root, usageAfter);
-        usageCommitted = true;
-        afterUsageCommit?.();
-      }
-      appendLedgerEntryUnlocked(root, entry);
-      ledgerCommitted = true;
-      afterLedgerCommit?.();
-      if (target.proposalId) {
-        beforeProposalCommit?.(proposalFilePath(root, target.proposalId, false));
-        transitionProposalRecordUnlocked(root, proposalBefore.id, "rolled-back", entry.id);
-        afterProposalCommit?.();
-      }
-      const finalized = recoverSkillMutationTransactionUnlocked(root);
-      if (finalized.status !== "finalized") throw new SkillLoopLedgerError("ROLLBACK_STATE_UNKNOWN");
-      return { ...entry, ...(recoveredPreparedMutation ? { recovered: true } : {}) };
-    } catch (error) {
-      if (ledgerCommitted) {
-        throw new SkillLoopLedgerError("ROLLBACK_COMMITTED_METADATA_PENDING",
-          "rollback and ledger are committed; retry rollback to repair proposal state");
-      }
-      try {
-        if (installedStage && existsSync(destination)) rmSync(destination, { recursive: true, force: true });
-        if (movedCurrent && existsSync(displaced)) renameSync(displaced, destination);
-        if (usageCommitted && usageBefore) writeUsageUnlocked(root, usageBefore);
-      } catch {
-        throw new SkillLoopLedgerError("ROLLBACK_STATE_UNKNOWN");
-      }
-      if (error instanceof SkillLoopLedgerError) throw error;
-      throw new SkillLoopLedgerError("ROLLBACK_RESTORE_FAILED");
-    } finally {
-      rmSync(stage, { recursive: true, force: true });
-      if (!movedCurrent) rmSync(displaced, { recursive: true, force: true });
-    }
-  }, SkillLoopLedgerError, "LEDGER_LOCK_FAILED");
-}