@litfamily/litclaude 1.0.6 → 1.0.7

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

@@ -1,670 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { existsSync, lstatSync, opendirSync, renameSync, rmdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { isDeepStrictEqual } from "node:util";
-
-import { resolveAgentTarget } from "./authority.mjs";
-import {
-  captureDirectoryIdentity,
-  directoryIdentityMatches,
-  ensureSafeDirectoryChain,
-  parseTimestamp,
-  safeIsoPath,
-  skillRootFor,
-  withSkillLoopLock,
-} from "./common.mjs";
-import { readSkillLoopConfig, writeSkillLoopConfigUnlocked } from "./config.mjs";
-import {
-  captureBackupSnapshot,
-  captureSkillSnapshot,
-  captureStagedSnapshot,
-  cleanupCreatedSnapshotBlobs,
-  createSnapshotWorkBudget,
-  ledgerReferenceSnapshotUnchanged,
-  materializeSnapshot,
-  readLedgerReferenceSnapshot,
-  SESSION_START_LEDGER_WORK_LIMITS,
-} from "./ledger.mjs";
-import { readUsage, writeUsageUnlocked } from "./usage.mjs";
-import {
-  beginSkillMutationTransactionUnlocked,
-  recoverSkillMutationTransactionUnlocked,
-  requestCuratorMutationRollbackUnlocked,
-} from "./mutation-transaction.mjs";
-import { recoverReviewTransactionUnlocked } from "./review-transaction.mjs";
-
-export class SkillLoopCuratorError extends Error {
-  constructor(code, message = code) {
-    super(`${code}: ${message}`);
-    this.name = "SkillLoopCuratorError";
-    this.code = code;
-  }
-}
-
-const days = (value) => value * 24 * 60 * 60 * 1000;
-export const SESSION_START_CURATOR_LIMITS = Object.freeze({
-  maxSkills: 32,
-  maxBytes: 8 * 1024 * 1024,
-  maxTransitions: 8,
-  maxDirectoryEntries: 1_024,
-  maxDirectories: 128,
-  maxDepth: 8,
-  maxFiles: 256,
-});
-const WORK_CAP_ADVISORY = "Skill curator deferred: SessionStart work cap exceeded; run `/litclaude:skill-observer curator run` explicitly.";
-
-function latestActivity(entry) {
-  return Math.max(...[
-    entry.created_at, entry.last_used_at, entry.last_viewed_at, entry.last_patched_at,
-  ].filter(Boolean).map(parseTimestamp));
-}
-
-function validateWorkLimits(limits) {
-  if (limits === null) return null;
-  const normalized = { ...SESSION_START_CURATOR_LIMITS, ...limits };
-  if (limits && !Object.hasOwn(limits, "maxDirectoryEntries")
-    && Object.hasOwn(limits, "maxDirectories")) {
-    normalized.maxDirectoryEntries = limits.maxDirectories;
-  }
-  if (!limits || ![
-    normalized.maxSkills, normalized.maxBytes, normalized.maxTransitions,
-    normalized.maxDirectoryEntries, normalized.maxDirectories, normalized.maxDepth,
-    normalized.maxFiles,
-  ].every(Number.isSafeInteger)
-    || normalized.maxSkills < 1 || normalized.maxSkills > 256
-    || normalized.maxBytes < 1 || normalized.maxBytes > 32 * 1024 * 1024
-    || normalized.maxTransitions < 1 || normalized.maxTransitions > 64
-    || normalized.maxDirectoryEntries < 1 || normalized.maxDirectoryEntries > 16_384
-    || normalized.maxDirectories < 1 || normalized.maxDirectories > 4096
-    || normalized.maxDepth < 1 || normalized.maxDepth > 32
-    || normalized.maxFiles < 1 || normalized.maxFiles > 256) {
-    throw new SkillLoopCuratorError("CURATOR_WORK_CAP_INVALID");
-  }
-  return normalized;
-}
-
-function measuredSkillBytes(directory, byteAllowance, limits, work) {
-  let bytes = 0;
-  const walk = (path, depth) => {
-    work.directories += 1;
-    if (work.directories > limits.maxDirectories || depth > limits.maxDepth) return false;
-    let handle;
-    try {
-      handle = opendirSync(path);
-      let entry;
-      while ((entry = handle.readSync()) !== null) {
-        work.directoryEntries += 1;
-        if (work.directoryEntries > limits.maxDirectoryEntries) return false;
-        const child = join(path, entry.name);
-        const details = lstatSync(child, { throwIfNoEntry: false });
-        if (!details || details.isSymbolicLink()) throw new SkillLoopCuratorError("CURATOR_TARGET_UNSAFE");
-        if (details.isDirectory()) {
-          if (walk(child, depth + 1) === false) return false;
-          continue;
-        }
-        if (!details.isFile() || details.nlink !== 1) {
-          throw new SkillLoopCuratorError("CURATOR_TARGET_UNSAFE");
-        }
-        work.files += 1;
-        if (work.files > limits.maxFiles) return false;
-        bytes += details.size;
-        work.bytes += details.size;
-        if (bytes > byteAllowance || work.bytes > limits.maxBytes) return false;
-      }
-    } finally {
-      handle?.closeSync();
-    }
-    return true;
-  };
-  return walk(directory, 0) === false ? byteAllowance + 1 : bytes;
-}
-
-const deferredForWorkCap = () => ({
-  reason: "WORK_CAP_EXCEEDED",
-  transitions: [],
-  advisory: WORK_CAP_ADVISORY,
-});
-
-function captureCuratorSnapshot(root, skill, limits, work, createdBlobs, { capIsCas = false } = {}) {
-  try {
-    return captureSkillSnapshot(root, skillRootFor(root), skill, limits === null ? {} : {
-      workLimits: limits,
-      work,
-      createdBlobs,
-    });
-  } catch (error) {
-    if (error?.code === "SNAPSHOT_WORK_CAP_EXCEEDED") {
-      if (capIsCas) throw new SkillLoopCuratorError("CURATOR_CAS_MISMATCH");
-      return null;
-    }
-    throw error;
-  }
-}
-
-function referencedSnapshotDigests(entries) {
-  const digests = new Set();
-  for (const entry of entries) {
-    for (const item of [...entry.before, ...entry.after]) digests.add(item.blob.digest);
-  }
-  return digests;
-}
-
-const snapshotWorkFields = ["directoryEntries", "directories", "files", "bytes"];
-
-function validateSnapshotWork(work) {
-  if (!work || Object.keys(work).sort().join(",") !== [...snapshotWorkFields].sort().join(",")
-    || !snapshotWorkFields.every((field) => Number.isSafeInteger(work[field]) && work[field] >= 0)) {
-    throw new SkillLoopCuratorError("CURATOR_WORK_CAP_INVALID");
-  }
-  return work;
-}
-
-const copySnapshotWork = (work) => Object.fromEntries(
-  snapshotWorkFields.map((field) => [field, work[field]]),
-);
-
-const snapshotWorkDelta = (before, after) => Object.fromEntries(
-  snapshotWorkFields.map((field) => [field, after[field] - before[field]]),
-);
-
-function canAffordSnapshotWork(work, costs, limits) {
-  if (limits === null) return true;
-  const reserved = copySnapshotWork(work);
-  for (const cost of costs) {
-    for (const field of snapshotWorkFields) reserved[field] += cost[field];
-  }
-  return reserved.directoryEntries <= limits.maxDirectoryEntries
-    && reserved.directories <= limits.maxDirectories
-    && reserved.files <= limits.maxFiles
-    && reserved.bytes <= limits.maxBytes;
-}
-
-function assertCuratorSelectionCas(root, expectedConfig, expectedUsage) {
-  const config = readSkillLoopConfig(root);
-  const usage = readUsage(root);
-  if (!isDeepStrictEqual(config, expectedConfig) || !isDeepStrictEqual(usage, expectedUsage)) {
-    throw new SkillLoopCuratorError("CURATOR_CAS_MISMATCH");
-  }
-  return { config, usage };
-}
-
-function removeEmptyOwnedDirectory(path, identity) {
-  if (identity === null) return;
-  if (!directoryIdentityMatches(path, identity)) {
-    throw new SkillLoopCuratorError("CURATOR_CLEANUP_UNSAFE");
-  }
-  let handle;
-  try {
-    handle = opendirSync(path);
-    if (handle.readSync() !== null) return;
-  } finally {
-    handle?.closeSync();
-  }
-  if (!directoryIdentityMatches(path, identity)) {
-    throw new SkillLoopCuratorError("CURATOR_CLEANUP_UNSAFE");
-  }
-  const quarantine = `${path}.remove.${randomUUID()}`;
-  try {
-    renameSync(path, quarantine);
-    if (!directoryIdentityMatches(quarantine, identity)) throw new Error("directory identity changed");
-    let quarantined;
-    try {
-      quarantined = opendirSync(quarantine);
-      if (quarantined.readSync() !== null) throw new Error("directory gained an entry");
-    } finally {
-      quarantined?.closeSync();
-    }
-    rmdirSync(quarantine);
-  } catch {
-    try {
-      if (!existsSync(path) && existsSync(quarantine)) renameSync(quarantine, path);
-    } catch { /* Leave uncertain cleanup as a visible residue. */ }
-    throw new SkillLoopCuratorError("CURATOR_CLEANUP_UNSAFE");
-  }
-}
-
-export function runCurator(root, {
-  now = new Date().toISOString(),
-  lastActivityAt = now,
-  beforeTransition,
-  beforeConfigCommit,
-  afterIdentityCapture,
-  afterBackupPublish,
-  afterPostBackupCas,
-  afterMutationJournal,
-  afterArchiveRename,
-  afterUsageCommit,
-  afterLedgerCommit,
-  afterConfigCommit,
-  beforeDeferredCleanup,
-  workLimits = null,
-  snapshotWork = null,
-} = {}) {
-  const nowMs = parseTimestamp(now);
-  const lastActivityMs = parseTimestamp(lastActivityAt);
-  if (nowMs === null || lastActivityMs === null || lastActivityMs > nowMs) {
-    throw new SkillLoopCuratorError("CURATOR_CLOCK_INVALID");
-  }
-  const limits = validateWorkLimits(workLimits);
-  const traversalWork = validateSnapshotWork(snapshotWork ?? createSnapshotWorkBudget());
-  const snapshotOptions = limits === null ? undefined : { workLimits: limits, work: traversalWork };
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    let mutationRecovery;
-    try {
-      mutationRecovery = recoverSkillMutationTransactionUnlocked(root, { snapshotOptions });
-    } catch (error) {
-      if (error?.code === "SNAPSHOT_WORK_CAP_EXCEEDED") return deferredForWorkCap();
-      throw error;
-    }
-    if (mutationRecovery.status === "finalized" && mutationRecovery.kind === "curator") {
-      const [from, to] = mutationRecovery.transition;
-      return {
-        reason: "TRANSITIONS_APPLIED",
-        transitions: [{
-          skill: mutationRecovery.ledgerEntry.targetSkill,
-          from,
-          to,
-          ledgerEntryId: mutationRecovery.ledgerEntry.id,
-          archivedPath: mutationRecovery.archivePath,
-        }],
-        archiveRoot: mutationRecovery.archivePath === null ? null : join(mutationRecovery.archivePath, ".."),
-        recovered: true,
-      };
-    }
-    const createdBlobs = new Map();
-    let referencedDigests = null;
-    let ledgerReferenceFingerprint = null;
-    const blobStoreExisted = Boolean(lstatSync(
-      join(root, ".litclaude", "skill-ledger-blobs"), { throwIfNoEntry: false },
-    ));
-    const cleanupCreatedBlobs = ({ notify = false } = {}) => {
-      if (createdBlobs.size > 0) {
-        if (notify) beforeDeferredCleanup?.(new Map(createdBlobs));
-        if (!ledgerReferenceSnapshotUnchanged(root, ledgerReferenceFingerprint)) return;
-        cleanupCreatedSnapshotBlobs(root, createdBlobs, {
-          removeEmptyDirectory: !blobStoreExisted,
-          referencedDigests,
-        });
-      }
-    };
-    const deferAndCleanup = () => {
-      cleanupCreatedBlobs({ notify: true });
-      return deferredForWorkCap();
-    };
-    const config = readSkillLoopConfig(root);
-    if (nowMs - lastActivityMs < config.curator.minIdleHours * 60 * 60 * 1000) {
-      return { reason: "MIN_IDLE_NOT_REACHED", transitions: [] };
-    }
-    if (config.lastCuratorRunAt
-      && nowMs - parseTimestamp(config.lastCuratorRunAt) < days(config.curator.intervalDays)) {
-      return { reason: "INTERVAL_NOT_REACHED", transitions: [] };
-    }
-    let usage = readUsage(root);
-    let expectedConfig = config;
-    if (parseTimestamp(usage.updatedAt) > nowMs) throw new SkillLoopCuratorError("CURATOR_CLOCK_INVALID");
-    const skills = ensureSafeDirectoryChain(root, [".claude", "skills"], {
-      create: false,
-      ErrorType: SkillLoopCuratorError,
-      code: "CURATOR_TARGET_UNSAFE",
-    });
-    const eligible = [];
-    const candidates = [];
-    let inspectedSkills = 0;
-    let measuredBytes = 0;
-    const scanWork = traversalWork;
-    for (const name of Object.keys(usage.skills).sort()) {
-      inspectedSkills += 1;
-      if (limits && inspectedSkills > limits.maxSkills) return deferAndCleanup();
-      const entry = usage.skills[name];
-      if (entry.pinned || skills === null) continue;
-      try {
-        resolveAgentTarget(root, skillRootFor(root), name, {
-          allowMissing: false,
-          requireOwned: true,
-          ErrorType: SkillLoopCuratorError,
-          notOwnedCode: "CURATOR_NOT_AGENT_OWNED",
-          pathCode: "CURATOR_TARGET_UNSAFE",
-          maxDirectoryEntries: limits?.maxDirectoryEntries ?? null,
-          workCapCode: "CURATOR_WORK_CAP_EXCEEDED",
-        });
-      } catch (error) {
-        if (error?.code === "CURATOR_WORK_CAP_EXCEEDED") return deferAndCleanup();
-        continue;
-      }
-      eligible.push(name);
-      if (limits) {
-        const skillBytes = measuredSkillBytes(
-          join(skills, name), limits.maxBytes - scanWork.bytes, limits, scanWork,
-        );
-        measuredBytes += skillBytes;
-        if (measuredBytes > limits.maxBytes) return deferAndCleanup();
-      }
-      if (entry.use_count + entry.view_count + entry.patch_count === 0) continue;
-      const idleMs = nowMs - latestActivity(entry);
-      if (entry.state === "stale" && idleMs >= days(config.curator.archiveAfterDays)) {
-        candidates.push({ skill: name, from: "stale", to: "archived" });
-      } else if (entry.state === "active" && idleMs >= days(config.curator.staleAfterDays)) {
-        candidates.push({ skill: name, from: "active", to: "stale" });
-      }
-      if (limits && candidates.length > limits.maxTransitions) return deferAndCleanup();
-    }
-    beforeConfigCommit?.();
-    assertCuratorSelectionCas(root, expectedConfig, usage);
-    if (candidates.length > 0) {
-      let ledgerSnapshot;
-      try {
-        ledgerSnapshot = readLedgerReferenceSnapshot(root, {
-          workLimits: SESSION_START_LEDGER_WORK_LIMITS,
-        });
-      } catch (error) {
-        if (error?.code === "LEDGER_WORK_CAP_EXCEEDED") return deferredForWorkCap();
-        throw error;
-      }
-      referencedDigests = referencedSnapshotDigests(ledgerSnapshot.entries);
-      ledgerReferenceFingerprint = ledgerSnapshot.fingerprint;
-    }
-    const stamp = safeIsoPath(now);
-    let backupRoot = null;
-    let archiveRoot = null;
-    const snapshots = new Map();
-    if (candidates.length > 0) {
-      for (const skill of eligible) {
-        const snapshot = captureCuratorSnapshot(root, skill, limits, traversalWork, createdBlobs);
-        if (snapshot === null) return deferAndCleanup();
-        snapshots.set(skill, snapshot);
-      }
-    }
-    const prepared = [];
-    for (const candidate of candidates) {
-      const source = join(skills, candidate.skill);
-      const before = snapshots.get(candidate.skill)
-        ?? captureCuratorSnapshot(root, candidate.skill, limits, traversalWork, createdBlobs);
-      if (before === null) return deferAndCleanup();
-      beforeTransition?.(candidate.skill);
-      resolveAgentTarget(root, skillRootFor(root), candidate.skill, {
-        allowMissing: false,
-        requireOwned: true,
-        ErrorType: SkillLoopCuratorError,
-        notOwnedCode: "CURATOR_NOT_AGENT_OWNED",
-        pathCode: "CURATOR_TARGET_UNSAFE",
-        maxDirectoryEntries: limits?.maxDirectoryEntries ?? null,
-        workCapCode: "CURATOR_WORK_CAP_EXCEEDED",
-      });
-      const workBeforeLive = copySnapshotWork(traversalWork);
-      const live = captureCuratorSnapshot(root, candidate.skill, limits, traversalWork, createdBlobs);
-      if (live === null) return deferAndCleanup();
-      if (JSON.stringify(live) !== JSON.stringify(before)) throw new SkillLoopCuratorError("CURATOR_CAS_MISMATCH");
-      const expectedIdentity = captureDirectoryIdentity(source, SkillLoopCuratorError, "CURATOR_TARGET_UNSAFE");
-      afterIdentityCapture?.(candidate.skill);
-      if (!directoryIdentityMatches(source, expectedIdentity)) {
-        throw new SkillLoopCuratorError("CURATOR_IDENTITY_MISMATCH");
-      }
-      prepared.push({
-        candidate,
-        source,
-        before,
-        expectedIdentity,
-        recoveryCost: snapshotWorkDelta(workBeforeLive, traversalWork),
-      });
-    }
-    assertCuratorSelectionCas(root, expectedConfig, usage);
-    if (!canAffordSnapshotWork(
-      traversalWork,
-      prepared.flatMap(({ recoveryCost }) => [recoveryCost, recoveryCost, recoveryCost]),
-      limits,
-    )) {
-      return deferAndCleanup();
-    }
-
-    const transitions = [];
-    const publishedBackups = new Set();
-    const backupRecords = new Map();
-    const backupOwnership = { container: null, stamp: null };
-    const archiveOwnership = { container: null, stamp: null };
-    const ensureTimestampRoot = (name, code, ownership) => {
-      const containerPath = join(root, ".litclaude", name);
-      const stampPath = join(containerPath, stamp);
-      const containerExisted = Boolean(lstatSync(containerPath, { throwIfNoEntry: false }));
-      const stampExisted = Boolean(lstatSync(stampPath, { throwIfNoEntry: false }));
-      const directory = ensureSafeDirectoryChain(root, [".litclaude", name, stamp], {
-        create: true,
-        ErrorType: SkillLoopCuratorError,
-        code,
-      });
-      if (!containerExisted && ownership.container === null) {
-        ownership.container = {
-          path: containerPath,
-          identity: captureDirectoryIdentity(containerPath, SkillLoopCuratorError, code),
-        };
-      }
-      if (!stampExisted && ownership.stamp === null) {
-        ownership.stamp = {
-          path: stampPath,
-          identity: captureDirectoryIdentity(stampPath, SkillLoopCuratorError, code),
-        };
-      }
-      return directory;
-    };
-    const publishBackup = (skill, snapshot) => {
-      backupRoot ??= ensureTimestampRoot("skill-backups", "CURATOR_BACKUP_FAILED", backupOwnership);
-      const path = join(backupRoot, skill);
-      materializeSnapshot(root, path, snapshot);
-      backupRecords.set(skill, {
-        path,
-        identity: captureDirectoryIdentity(path, SkillLoopCuratorError, "CURATOR_BACKUP_FAILED"),
-        snapshot,
-        committed: false,
-      });
-      publishedBackups.add(skill);
-      afterBackupPublish?.(skill, path);
-    };
-    const cleanupUncommittedBackups = () => {
-      const removable = [];
-      for (const [skill, record] of backupRecords) {
-        if (record.committed) continue;
-        if (!directoryIdentityMatches(record.path, record.identity)) {
-          throw new SkillLoopCuratorError("CURATOR_CLEANUP_UNSAFE");
-        }
-        const cleanupSnapshot = captureBackupSnapshot(root, record.path, limits === null ? {} : {
-          workLimits: limits,
-          work: createSnapshotWorkBudget(),
-        });
-        if (!isDeepStrictEqual(cleanupSnapshot, record.snapshot)) {
-          throw new SkillLoopCuratorError("CURATOR_CLEANUP_UNSAFE");
-        }
-        removable.push([skill, record]);
-      }
-      for (const [skill, record] of removable) {
-        if (!directoryIdentityMatches(record.path, record.identity)) {
-          throw new SkillLoopCuratorError("CURATOR_CLEANUP_UNSAFE");
-        }
-        const quarantine = join(skills, `.${skill}.rollback-${randomUUID()}`);
-        try {
-          renameSync(record.path, quarantine);
-          if (!directoryIdentityMatches(quarantine, record.identity)) throw new Error("backup identity changed");
-          const quarantinedSnapshot = captureStagedSnapshot(root, quarantine, limits === null ? {} : {
-            workLimits: limits,
-            work: createSnapshotWorkBudget(),
-          });
-          if (!isDeepStrictEqual(quarantinedSnapshot, record.snapshot)) {
-            throw new Error("backup contents changed");
-          }
-          rmSync(quarantine, { recursive: true, force: true });
-        } catch {
-          try {
-            if (!existsSync(record.path) && existsSync(quarantine)) renameSync(quarantine, record.path);
-          } catch { /* Leave uncertain cleanup as a visible residue. */ }
-          throw new SkillLoopCuratorError("CURATOR_CLEANUP_UNSAFE");
-        }
-        backupRecords.delete(skill);
-      }
-      removeEmptyOwnedDirectory(backupOwnership.stamp?.path, backupOwnership.stamp?.identity ?? null);
-      removeEmptyOwnedDirectory(backupOwnership.container?.path, backupOwnership.container?.identity ?? null);
-    };
-    const cleanupOwnedArchiveDirectories = () => {
-      removeEmptyOwnedDirectory(archiveOwnership.stamp?.path, archiveOwnership.stamp?.identity ?? null);
-      removeEmptyOwnedDirectory(archiveOwnership.container?.path, archiveOwnership.container?.identity ?? null);
-    };
-    for (const { candidate, source, before, expectedIdentity } of prepared) {
-      if (!directoryIdentityMatches(source, expectedIdentity)) {
-        throw new SkillLoopCuratorError("CURATOR_IDENTITY_MISMATCH");
-      }
-      publishBackup(candidate.skill, before);
-      const live = captureCuratorSnapshot(root, candidate.skill, limits, traversalWork, createdBlobs);
-      if (live === null) {
-        cleanupUncommittedBackups();
-        if (transitions.length > 0) {
-          cleanupCreatedBlobs();
-          throw new SkillLoopCuratorError("CURATOR_CAS_MISMATCH");
-        }
-        return deferAndCleanup();
-      }
-      if (!isDeepStrictEqual(live, before) || !directoryIdentityMatches(source, expectedIdentity)) {
-        cleanupUncommittedBackups();
-        cleanupCreatedBlobs();
-        throw new SkillLoopCuratorError("CURATOR_CAS_MISMATCH");
-      }
-      let selectionCas;
-      try {
-        selectionCas = assertCuratorSelectionCas(root, expectedConfig, usage);
-      } catch (error) {
-        cleanupUncommittedBackups();
-        cleanupCreatedBlobs();
-        throw error;
-      }
-      afterPostBackupCas?.(candidate.skill);
-      let archivedPath = null;
-      if (candidate.to === "archived") {
-        archiveRoot ??= ensureTimestampRoot("skill-archives", "CURATOR_ARCHIVE_FAILED", archiveOwnership);
-        archivedPath = join(archiveRoot, candidate.skill);
-        if (existsSync(archivedPath)) throw new SkillLoopCuratorError("CURATOR_ARCHIVE_FAILED");
-      }
-      const after = candidate.to === "archived" ? [] : before;
-      const usageBefore = selectionCas.usage;
-      const usageAfter = structuredClone(usageBefore);
-      usageAfter.skills[candidate.skill].state = candidate.to;
-      usageAfter.skills[candidate.skill].archived_at = candidate.to === "archived" ? now : null;
-      usageAfter.updatedAt = now;
-      const configBefore = selectionCas.config;
-      const configAfter = { ...configBefore, lastCuratorRunAt: now };
-      const ledger = {
-        schema: "litfamily.skill-ledger/v1",
-        id: `ledger-${randomUUID()}`,
-        createdAt: now,
-        proposalId: null,
-        actor: "curator",
-        operation: "curator-transition",
-        targetSkill: candidate.skill,
-        targetRoot: skillRootFor(root),
-        before,
-        after,
-        reason: `usage:${candidate.from}->${candidate.to}`,
-      };
-      beginSkillMutationTransactionUnlocked(root, {
-        schema: "litclaude.skill-mutation-transaction/v1",
-        id: ledger.id,
-        kind: "curator",
-        requestId: ledger.id,
-        createdAt: now,
-        targetRoot: ledger.targetRoot,
-        targetSkill: candidate.skill,
-        action: candidate.to === "archived" ? "curator-archive" : "curator-stale",
-        stageName: null,
-        displacedName: null,
-        archiveParts: candidate.to === "archived"
-          ? ["skill-archives", stamp, candidate.skill]
-          : null,
-        beforeIdentity: expectedIdentity,
-        stageIdentity: null,
-        before,
-        after,
-        ledgerEntry: ledger,
-        proposalBefore: null,
-        proposalAfter: null,
-        usageBefore,
-        usageAfter,
-        configBefore,
-        configAfter,
-        abortRequested: false,
-      });
-      afterMutationJournal?.(candidate.skill);
-      const rollbackCandidateRace = () => {
-        const rolledBack = requestCuratorMutationRollbackUnlocked(root, ledger.id);
-        if (rolledBack.status !== "rolled-back") {
-          throw new SkillLoopCuratorError("CURATOR_STATE_UNKNOWN");
-        }
-        cleanupOwnedArchiveDirectories();
-        cleanupUncommittedBackups();
-        cleanupCreatedBlobs();
-        throw new SkillLoopCuratorError("CURATOR_CAS_MISMATCH");
-      };
-      if (candidate.to === "archived") {
-        renameSync(source, archivedPath);
-        if (!directoryIdentityMatches(archivedPath, expectedIdentity)) {
-          throw new SkillLoopCuratorError("CURATOR_IDENTITY_MISMATCH");
-        }
-        afterArchiveRename?.(candidate.skill);
-        let archiveRace = false;
-        try {
-          const archivedLive = captureStagedSnapshot(root, archivedPath, limits === null ? {
-            createdBlobs,
-          } : {
-            workLimits: limits,
-            work: traversalWork,
-            createdBlobs,
-          });
-          archiveRace = !isDeepStrictEqual(archivedLive, before);
-        } catch (error) {
-          if (["SNAPSHOT_WORK_CAP_EXCEEDED", "SNAPSHOT_PATH_UNSAFE"].includes(error?.code)) {
-            archiveRace = true;
-          } else {
-            throw error;
-          }
-        }
-        if (archiveRace) {
-          rollbackCandidateRace();
-        }
-      } else {
-        let staleRace = false;
-        try {
-          const staleLive = captureCuratorSnapshot(
-            root, candidate.skill, limits, traversalWork, createdBlobs,
-          );
-          staleRace = staleLive === null || !isDeepStrictEqual(staleLive, before)
-            || !directoryIdentityMatches(source, expectedIdentity);
-        } catch (error) {
-          if (error?.code === "SNAPSHOT_PATH_UNSAFE") staleRace = true;
-          else throw error;
-        }
-        if (staleRace) {
-          rollbackCandidateRace();
-        }
-      }
-      const finalized = recoverSkillMutationTransactionUnlocked(root, {
-        afterUsageCommit: () => afterUsageCommit?.(candidate.skill),
-        afterLedgerCommit: () => afterLedgerCommit?.(candidate.skill),
-        afterConfigCommit: () => afterConfigCommit?.(candidate.skill),
-        snapshotOptions,
-      });
-      if (finalized.status !== "finalized") throw new SkillLoopCuratorError("CURATOR_STATE_UNKNOWN");
-      usage = usageAfter;
-      expectedConfig = configAfter;
-      backupRecords.get(candidate.skill).committed = true;
-      for (const item of [...ledger.before, ...ledger.after]) referencedDigests.add(item.blob.digest);
-      transitions.push({ ...candidate, ledgerEntryId: ledger.id, archivedPath });
-    }
-    for (const [skill, snapshot] of snapshots) {
-      if (!publishedBackups.has(skill)) {
-        publishBackup(skill, snapshot);
-        backupRecords.get(skill).committed = true;
-      }
-    }
-    if (candidates.length === 0) {
-      usage.updatedAt = now;
-      writeUsageUnlocked(root, usage);
-      writeSkillLoopConfigUnlocked(root, { ...config, lastCuratorRunAt: now });
-    }
-    return { reason: candidates.length > 0 ? "TRANSITIONS_APPLIED" : "NO_ELIGIBLE_TRANSITIONS", transitions, backupRoot, archiveRoot };
-  }, SkillLoopCuratorError, "CURATOR_LOCK_FAILED");
-}