@litfamily/litclaude 1.0.6 → 1.0.7

package/plugins/litclaude/lib/skill-loop/mutation-transaction.mjs

@@ -1,529 +0,0 @@
-import { lstatSync, renameSync, rmSync, unlinkSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { dirname, join } from "node:path";
-
-import { validateProposal } from "./proposal-record.mjs";
-import { readProposalRecord, transitionProposalRecordUnlocked } from "./proposal-store.mjs";
-import {
-  appendLedgerEntryUnlocked,
-  captureSkillSnapshot,
-  captureStagedSnapshot,
-  readLedger,
-  rollbackEntryMatchesReference,
-  SESSION_START_LEDGER_WORK_LIMITS,
-  validateLedgerEntry,
-  verifySnapshotBlobs,
-} from "./ledger.mjs";
-import {
-  atomicWriteJson,
-  directoryIdentityMatches,
-  ensureSafeDirectoryChain,
-  isPlainObject,
-  parseTimestamp,
-  readStrictJsonFile,
-  RECORD_ID,
-  requireExactKeys,
-  skillRootsEquivalent,
-  SKILL_ID,
-} from "./common.mjs";
-import { readUsage, validateUsage, writeUsageUnlocked } from "./usage.mjs";
-import {
-  readSkillLoopConfig,
-  validateSkillLoopConfig,
-  writeSkillLoopConfigUnlocked,
-} from "./config.mjs";
-
-export class SkillLoopMutationTransactionError extends Error {
-  constructor(code, message = code) {
-    super(`${code}: ${message}`);
-    this.name = "SkillLoopMutationTransactionError";
-    this.code = code;
-  }
-}
-
-const MAX_JOURNAL_BYTES = 12 * 1024 * 1024;
-const fail = (code, message) => { throw new SkillLoopMutationTransactionError(code, message); };
-const snapshotsMatch = (left, right) => JSON.stringify(left) === JSON.stringify(right);
-const valuesMatch = (left, right) => JSON.stringify(left) === JSON.stringify(right);
-
-function expectedPatchUsage(journal) {
-  if (journal.usageBefore === null || journal.usageAfter === null) return null;
-  const expected = structuredClone(journal.usageBefore);
-  const entry = expected.skills[journal.targetSkill] ?? {
-    state: "active",
-    use_count: 0,
-    view_count: 0,
-    patch_count: 0,
-    created_at: journal.createdAt,
-    created_by: "agent",
-    last_used_at: null,
-    last_viewed_at: null,
-    last_patched_at: null,
-    archived_at: null,
-    pinned: false,
-  };
-  if (entry.state === "archived") return null;
-  entry.patch_count += 1;
-  entry.last_patched_at = journal.createdAt;
-  expected.skills[journal.targetSkill] = entry;
-  expected.updatedAt = journal.createdAt;
-  return expected;
-}
-
-function expectedRollbackUsage(journal) {
-  const transition = /^usage:(active|stale|archived)->(active|stale|archived)$/u.exec(
-    journal.ledgerEntry.reason ?? "",
-  );
-  if (!transition) return journal.usageBefore === null && journal.usageAfter === null ? null : false;
-  if (journal.usageBefore === null || journal.usageAfter === null
-    || journal.usageBefore.skills[journal.targetSkill]?.state !== transition[1]) return false;
-  const expected = structuredClone(journal.usageBefore);
-  expected.skills[journal.targetSkill].state = transition[2];
-  expected.skills[journal.targetSkill].archived_at = transition[2] === "archived" ? journal.createdAt : null;
-  expected.updatedAt = journal.createdAt;
-  return expected;
-}
-
-function expectedCuratorUsage(journal) {
-  const transition = /^usage:(active|stale|archived)->(active|stale|archived)$/u.exec(
-    journal.ledgerEntry.reason ?? "",
-  );
-  if (!transition || journal.usageBefore === null || journal.usageAfter === null
-    || journal.usageBefore.skills[journal.targetSkill]?.state !== transition[1]) return false;
-  const expected = structuredClone(journal.usageBefore);
-  expected.skills[journal.targetSkill].state = transition[2];
-  expected.skills[journal.targetSkill].archived_at = transition[2] === "archived" ? journal.createdAt : null;
-  expected.updatedAt = journal.createdAt;
-  return expected;
-}
-
-function stateDirectory(root, create) {
-  return ensureSafeDirectoryChain(root, [".litclaude"], {
-    create,
-    ErrorType: SkillLoopMutationTransactionError,
-    code: "MUTATION_TRANSACTION_UNSAFE",
-  });
-}
-
-function journalPath(root, create) {
-  const directory = stateDirectory(root, create);
-  return directory === null ? null : join(directory, "skill-mutation-transaction.json");
-}
-
-function validIdentity(identity) {
-  return identity === null || (isPlainObject(identity) && requireExactKeys(identity, ["dev", "ino", "birthtimeMs"])
-    && Number.isSafeInteger(identity.dev) && identity.dev >= 0
-    && Number.isSafeInteger(identity.ino) && identity.ino > 0
-    && Number.isFinite(identity.birthtimeMs) && identity.birthtimeMs >= 0);
-}
-
-function validTemporaryName(name, skill, kind, suffix) {
-  return typeof name === "string" && name.startsWith(`.${skill}.${kind}-${suffix}`)
-    && /^\.[a-z0-9][a-z0-9-]*\.(?:apply|rollback)-(?:before-)?[a-f0-9-]+$/u.test(name);
-}
-
-function validateJournal(journal) {
-  let bytes;
-  try { bytes = Buffer.from(`${JSON.stringify(journal, null, 2)}\n`, "utf8"); } catch { fail("MUTATION_TRANSACTION_INVALID"); }
-  if (bytes.length > MAX_JOURNAL_BYTES || !requireExactKeys(journal, [
-    "schema", "id", "kind", "requestId", "createdAt", "targetRoot", "targetSkill", "action",
-    "stageName", "displacedName", "archiveParts", "beforeIdentity", "stageIdentity",
-    "before", "after", "ledgerEntry", "proposalBefore", "proposalAfter", "usageBefore", "usageAfter",
-    "configBefore", "configAfter",
-  ], ["abortRequested"]) || journal.schema !== "litclaude.skill-mutation-transaction/v1" || !RECORD_ID.test(journal.id)
-    || !["apply", "rollback", "curator"].includes(journal.kind) || !RECORD_ID.test(journal.requestId)
-    || parseTimestamp(journal.createdAt) === null || !SKILL_ID.test(journal.targetSkill)
-    || typeof journal.targetRoot !== "string" || journal.targetRoot.length < 1 || journal.targetRoot.length > 2048
-    || !["create", "patch", "add-reference", "archive", "rollback", "curator-stale", "curator-archive"].includes(journal.action)
-    || (journal.kind === "curator"
-      ? journal.stageName !== null || journal.displacedName !== null
-      : !validTemporaryName(journal.stageName, journal.targetSkill, journal.kind, "")
-        || !validTemporaryName(journal.displacedName, journal.targetSkill, journal.kind, "before-"))
-    || !validIdentity(journal.beforeIdentity) || !validIdentity(journal.stageIdentity)
-    || (Object.hasOwn(journal, "abortRequested")
-      && (typeof journal.abortRequested !== "boolean"
-        || journal.kind !== "curator"
-        || !["curator-stale", "curator-archive"].includes(journal.action)))
-    || !Array.isArray(journal.before) || !Array.isArray(journal.after)
-    || (["archive", "curator-archive"].includes(journal.action)) !== Array.isArray(journal.archiveParts)
-    || (!["archive", "curator-archive"].includes(journal.action) && journal.archiveParts !== null)
-    || (journal.configBefore === null) !== (journal.configAfter === null)) {
-    fail("MUTATION_TRANSACTION_INVALID");
-  }
-  if (journal.archiveParts !== null && (journal.archiveParts.length !== 3
-    || journal.archiveParts[0] !== "skill-archives"
-    || !/^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z$/u.test(journal.archiveParts[1])
-    || journal.archiveParts[2] !== journal.targetSkill)) fail("MUTATION_TRANSACTION_INVALID");
-  try {
-    validateLedgerEntry(journal.ledgerEntry);
-    if (journal.ledgerEntry.id !== journal.id || journal.ledgerEntry.targetSkill !== journal.targetSkill
-      || journal.ledgerEntry.targetRoot !== journal.targetRoot
-      || journal.ledgerEntry.createdAt !== journal.createdAt
-      || !valuesMatch(journal.ledgerEntry.before, journal.before)
-      || !valuesMatch(journal.ledgerEntry.after, journal.after)) fail("MUTATION_TRANSACTION_INVALID");
-    if ((journal.proposalBefore === null) !== (journal.proposalAfter === null)) fail("MUTATION_TRANSACTION_INVALID");
-    if ((journal.proposalBefore === null) !== (journal.ledgerEntry.proposalId === null)) {
-      fail("MUTATION_TRANSACTION_INVALID");
-    }
-    if (journal.proposalBefore !== null) {
-      validateProposal(journal.proposalBefore);
-      validateProposal(journal.proposalAfter);
-      if (journal.proposalBefore.id !== journal.proposalAfter.id
-        || journal.proposalBefore.id !== journal.ledgerEntry.proposalId
-        || journal.proposalAfter.ledgerEntryId !== journal.id
-        || journal.proposalBefore.targetSkill !== journal.targetSkill
-        || journal.proposalBefore.targetRoot !== journal.targetRoot) fail("MUTATION_TRANSACTION_INVALID");
-    }
-    if ((journal.usageBefore === null) !== (journal.usageAfter === null)) fail("MUTATION_TRANSACTION_INVALID");
-    if (journal.usageBefore !== null) {
-      validateUsage(journal.usageBefore);
-      validateUsage(journal.usageAfter);
-    }
-    if (journal.configBefore !== null) {
-      validateSkillLoopConfig(journal.configBefore);
-      validateSkillLoopConfig(journal.configAfter);
-    }
-    if (journal.kind === "apply") {
-      const expectedProposal = journal.proposalBefore === null ? null : {
-        ...journal.proposalBefore,
-        status: "applied",
-        ledgerEntryId: journal.id,
-      };
-      const expectedUsage = journal.action === "patch" ? expectedPatchUsage(journal) : null;
-      if (journal.action === "rollback" || journal.ledgerEntry.operation !== "apply"
-        || journal.ledgerEntry.actor !== "user" || journal.requestId !== journal.ledgerEntry.proposalId
-        || journal.proposalBefore?.id !== journal.requestId || journal.proposalBefore?.status !== "approved"
-        || journal.proposalBefore?.action !== journal.action || !valuesMatch(journal.proposalAfter, expectedProposal)
-        || journal.configBefore !== null || journal.configAfter !== null
-        || (journal.action === "archive") !== (journal.stageIdentity === null && journal.after.length === 0)
-        || (expectedUsage === null) !== (journal.usageBefore === null)
-        || (expectedUsage !== null && !valuesMatch(journal.usageAfter, expectedUsage))) {
-        fail("MUTATION_TRANSACTION_INVALID");
-      }
-    } else if (journal.kind === "rollback") {
-      const expectedProposal = journal.proposalBefore === null ? null : {
-        ...journal.proposalBefore,
-        status: "rolled-back",
-        ledgerEntryId: journal.id,
-      };
-      const expectedUsage = expectedRollbackUsage(journal);
-      if (journal.action !== "rollback" || journal.ledgerEntry.operation !== "rollback"
-        || journal.ledgerEntry.actor !== "user" || journal.ledgerEntry.restoresLedgerEntryId !== journal.requestId
-        || !["applied", "rolled-back"].includes(journal.proposalBefore?.status ?? "applied")
-        || !valuesMatch(journal.proposalAfter, expectedProposal)
-        || journal.configBefore !== null || journal.configAfter !== null
-        || (journal.after.length === 0) !== (journal.stageIdentity === null)
-        || expectedUsage === false
-        || (expectedUsage !== null && !valuesMatch(journal.usageAfter, expectedUsage))) {
-        fail("MUTATION_TRANSACTION_INVALID");
-      }
-    } else {
-      const expectedUsage = expectedCuratorUsage(journal);
-      const transition = /^usage:(active|stale|archived)->(active|stale|archived)$/u.exec(
-        journal.ledgerEntry.reason ?? "",
-      );
-      const expectedConfig = journal.configBefore === null
-        ? null
-        : { ...journal.configBefore, lastCuratorRunAt: journal.createdAt };
-      if (journal.ledgerEntry.operation !== "curator-transition" || journal.ledgerEntry.actor !== "curator"
-        || journal.ledgerEntry.proposalId !== null || journal.requestId !== journal.id
-        || journal.proposalBefore !== null || journal.proposalAfter !== null
-        || journal.beforeIdentity === null || journal.before.length === 0
-        || journal.stageIdentity !== null || journal.stageName !== null || journal.displacedName !== null
-        || expectedUsage === false || !valuesMatch(journal.usageAfter, expectedUsage)
-        || journal.configBefore === null || !valuesMatch(journal.configAfter, expectedConfig)
-        || (journal.action === "curator-archive"
-          ? transition?.[1] !== "stale" || transition?.[2] !== "archived" || journal.after.length !== 0
-          : transition?.[1] !== "active" || transition?.[2] !== "stale"
-            || !valuesMatch(journal.after, journal.before))) {
-        fail("MUTATION_TRANSACTION_INVALID");
-      }
-    }
-  } catch (error) {
-    if (error instanceof SkillLoopMutationTransactionError) throw error;
-    fail("MUTATION_TRANSACTION_INVALID");
-  }
-  return journal;
-}
-
-function readJournalUnlocked(root) {
-  const path = journalPath(root, false);
-  if (path === null || !lstatSync(path, { throwIfNoEntry: false })) return null;
-  return validateJournal(readStrictJsonFile(path, SkillLoopMutationTransactionError,
-    "MUTATION_TRANSACTION_UNSAFE", { maxBytes: MAX_JOURNAL_BYTES, parseCode: "MUTATION_TRANSACTION_INVALID" }));
-}
-
-export function beginSkillMutationTransactionUnlocked(root, journal) {
-  if (readJournalUnlocked(root) !== null) fail("MUTATION_TRANSACTION_ACTIVE");
-  validateJournal(journal);
-  atomicWriteJson(journalPath(root, true), journal,
-    SkillLoopMutationTransactionError, "MUTATION_TRANSACTION_UNSAFE");
-  return journal;
-}
-
-export function requestCuratorMutationRollbackUnlocked(root, transactionId) {
-  const journal = readJournalUnlocked(root);
-  if (journal === null || journal.id !== transactionId || journal.kind !== "curator"
-    || !["curator-stale", "curator-archive"].includes(journal.action)
-    || journal.abortRequested === true) {
-    fail("MUTATION_TRANSACTION_INVALID");
-  }
-  const aborting = { ...journal, abortRequested: true };
-  validateJournal(aborting);
-  atomicWriteJson(journalPath(root, true), aborting,
-    SkillLoopMutationTransactionError, "MUTATION_TRANSACTION_UNSAFE");
-  return recoverSkillMutationTransactionUnlocked(root);
-}
-
-function clearJournalUnlocked(root) {
-  const path = journalPath(root, false);
-  const details = path === null ? null : lstatSync(path, { throwIfNoEntry: false });
-  if (!details) return;
-  if (!details.isFile() || details.isSymbolicLink() || details.nlink !== 1) fail("MUTATION_TRANSACTION_UNSAFE");
-  unlinkSync(path);
-}
-
-function directorySnapshot(root, path, targetRoot, skill, snapshotOptions) {
-  const details = lstatSync(path, { throwIfNoEntry: false });
-  if (!details) return null;
-  if (!details.isDirectory() || details.isSymbolicLink()) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-  const skills = ensureSafeDirectoryChain(root, [".claude", "skills"], {
-    create: false,
-    ErrorType: SkillLoopMutationTransactionError,
-    code: "MUTATION_TRANSACTION_UNSAFE",
-  });
-  if (skills !== null && path === join(skills, skill)) {
-    return captureSkillSnapshot(root, targetRoot, skill, snapshotOptions);
-  }
-  return captureStagedSnapshot(root, path, snapshotOptions);
-}
-
-function assertExactDirectory(root, path, identity, snapshot, targetRoot, skill, snapshotOptions) {
-  if (identity === null || !directoryIdentityMatches(path, identity)) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-  const actual = directorySnapshot(root, path, targetRoot, skill, snapshotOptions);
-  if (actual === null || !snapshotsMatch(actual, snapshot)) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-}
-
-function removeExactDirectory(root, path, identity, snapshot, targetRoot, skill, snapshotOptions) {
-  assertExactDirectory(root, path, identity, snapshot, targetRoot, skill, snapshotOptions);
-  const skills = ensureSafeDirectoryChain(root, [".claude", "skills"], {
-    create: false,
-    ErrorType: SkillLoopMutationTransactionError,
-    code: "MUTATION_TRANSACTION_UNSAFE",
-  });
-  if (skills === null || dirname(path) !== skills) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-  const quarantine = join(skills, `.${skill}.rollback-${randomUUID()}`);
-  try {
-    renameSync(path, quarantine);
-    if (!directoryIdentityMatches(quarantine, identity)) throw new Error("directory identity changed");
-    const quarantinedSnapshot = captureStagedSnapshot(root, quarantine, snapshotOptions);
-    if (!snapshotsMatch(quarantinedSnapshot, snapshot)) throw new Error("directory contents changed");
-    rmSync(quarantine, { recursive: true, force: true });
-  } catch (error) {
-    try {
-      if (!lstatSync(path, { throwIfNoEntry: false }) && lstatSync(quarantine, { throwIfNoEntry: false })) {
-        renameSync(quarantine, path);
-      }
-    } catch { /* Leave uncertain cleanup as a visible residue. */ }
-    if (error instanceof SkillLoopMutationTransactionError) throw error;
-    fail("MUTATION_TRANSACTION_AMBIGUOUS");
-  }
-}
-
-function ensureLedgerCommitted(root, journal) {
-  const ledger = readLedger(root);
-  const existing = ledger.find(({ id }) => id === journal.ledgerEntry.id);
-  if (existing) {
-    if (JSON.stringify(existing) !== JSON.stringify(journal.ledgerEntry)) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-  } else appendLedgerEntryUnlocked(root, journal.ledgerEntry);
-}
-
-function ensureUsageCommitted(root, journal) {
-  if (journal.usageBefore === null) return;
-  const current = readUsage(root);
-  if (JSON.stringify(current) === JSON.stringify(journal.usageAfter)) return;
-  if (JSON.stringify(current) !== JSON.stringify(journal.usageBefore)) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-  writeUsageUnlocked(root, journal.usageAfter);
-}
-
-function ensureProposalCommitted(root, journal) {
-  if (journal.proposalBefore === null) return;
-  const current = readProposalRecord(root, journal.proposalBefore.id);
-  if (JSON.stringify(current) === JSON.stringify(journal.proposalAfter)) return;
-  if (JSON.stringify(current) !== JSON.stringify(journal.proposalBefore)) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-  transitionProposalRecordUnlocked(root, current.id, journal.proposalAfter.status, journal.id);
-  const written = readProposalRecord(root, current.id);
-  if (JSON.stringify(written) !== JSON.stringify(journal.proposalAfter)) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-}
-
-function ensureConfigCommitted(root, journal) {
-  if (journal.configBefore === null) return;
-  const current = readSkillLoopConfig(root);
-  if (JSON.stringify(current) === JSON.stringify(journal.configAfter)) return;
-  if (JSON.stringify(current) !== JSON.stringify(journal.configBefore)) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-  writeSkillLoopConfigUnlocked(root, journal.configAfter);
-}
-
-function cleanupDisplaced(root, journal, skills, snapshotOptions) {
-  if (journal.displacedName === null) return;
-  const displaced = join(skills, journal.displacedName);
-  if (!lstatSync(displaced, { throwIfNoEntry: false })) return;
-  removeExactDirectory(root, displaced, journal.beforeIdentity, journal.before,
-    journal.targetRoot, journal.targetSkill, snapshotOptions);
-}
-
-function assertExactRollbackReference(root, journal) {
-  if (journal.kind !== "rollback") return;
-  try {
-    const reference = readLedger(root).find(({ id }) => id === journal.requestId);
-    if (!rollbackEntryMatchesReference(reference, journal.ledgerEntry)
-      || !snapshotsMatch(journal.before, reference.after)
-      || !snapshotsMatch(journal.after, reference.before)) {
-      fail("MUTATION_TRANSACTION_INVALID");
-    }
-    const referenceTransition = /^usage:(active|stale|archived)->(active|stale|archived)$/u.exec(
-      reference.reason ?? "",
-    );
-    if (referenceTransition) {
-      if (journal.usageBefore === null || journal.usageAfter === null) fail("MUTATION_TRANSACTION_INVALID");
-    } else if (journal.usageBefore !== null || journal.usageAfter !== null) {
-      fail("MUTATION_TRANSACTION_INVALID");
-    }
-  } catch (error) {
-    if (error instanceof SkillLoopMutationTransactionError) throw error;
-    fail("MUTATION_TRANSACTION_INVALID");
-  }
-}
-
-export function recoverSkillMutationTransactionUnlocked(root, {
-  afterUsageCommit,
-  afterLedgerCommit,
-  afterConfigCommit,
-  snapshotOptions,
-} = {}) {
-  const journal = readJournalUnlocked(root);
-  if (journal === null) return { status: "none" };
-  if (!skillRootsEquivalent(root, journal.targetRoot)) fail("MUTATION_TRANSACTION_INVALID");
-  assertExactRollbackReference(root, journal);
-  verifySnapshotBlobs(root, journal.before);
-  verifySnapshotBlobs(root, journal.after);
-  const skills = ensureSafeDirectoryChain(root, [".claude", "skills"], {
-    create: true,
-    ErrorType: SkillLoopMutationTransactionError,
-    code: "MUTATION_TRANSACTION_UNSAFE",
-  });
-  const target = join(skills, journal.targetSkill);
-  const stage = journal.stageName === null ? null : join(skills, journal.stageName);
-  const displaced = journal.displacedName === null ? null : join(skills, journal.displacedName);
-  const archiveBase = journal.archiveParts === null ? null : ensureSafeDirectoryChain(
-    root, [".litclaude", ...journal.archiveParts.slice(0, 2)], {
-      create: false,
-      ErrorType: SkillLoopMutationTransactionError,
-      code: "MUTATION_TRANSACTION_UNSAFE",
-    },
-  );
-  const archive = archiveBase === null ? null : join(archiveBase, journal.targetSkill);
-  const targetDetails = lstatSync(target, { throwIfNoEntry: false });
-  const stageDetails = stage === null ? null : lstatSync(stage, { throwIfNoEntry: false });
-  const displacedDetails = displaced === null ? null : lstatSync(displaced, { throwIfNoEntry: false });
-  const archiveDetails = archive === null ? null : lstatSync(archive, { throwIfNoEntry: false });
-
-  if (journal.abortRequested === true) {
-    if (journal.kind !== "curator"
-      || !["curator-stale", "curator-archive"].includes(journal.action)
-      || stageDetails || displacedDetails
-      || !valuesMatch(readUsage(root), journal.usageBefore)
-      || !valuesMatch(readSkillLoopConfig(root), journal.configBefore)
-      || readLedger(root, { workLimits: SESSION_START_LEDGER_WORK_LIMITS }).some(({ id }) => id === journal.id)) {
-      fail("MUTATION_TRANSACTION_AMBIGUOUS");
-    }
-    if (journal.action === "curator-stale") {
-      if (targetDetails && directoryIdentityMatches(target, journal.beforeIdentity) && !archiveDetails) {
-        clearJournalUnlocked(root);
-        return { status: "rolled-back", kind: journal.kind, requestId: journal.requestId };
-      }
-      fail("MUTATION_TRANSACTION_AMBIGUOUS");
-    }
-    if (!targetDetails && archive !== null && directoryIdentityMatches(archive, journal.beforeIdentity)) {
-      renameSync(archive, target);
-      if (!directoryIdentityMatches(target, journal.beforeIdentity)) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-      clearJournalUnlocked(root);
-      return { status: "rolled-back", kind: journal.kind, requestId: journal.requestId };
-    }
-    if (targetDetails && directoryIdentityMatches(target, journal.beforeIdentity) && !archiveDetails) {
-      clearJournalUnlocked(root);
-      return { status: "rolled-back", kind: journal.kind, requestId: journal.requestId };
-    }
-    fail("MUTATION_TRANSACTION_AMBIGUOUS");
-  }
-
-  const archiveAction = ["archive", "curator-archive"].includes(journal.action);
-  const targetAfter = archiveAction
-    ? !targetDetails && archive !== null && archiveDetails && directoryIdentityMatches(archive, journal.beforeIdentity)
-    : journal.action === "curator-stale"
-      ? targetDetails && directoryIdentityMatches(target, journal.beforeIdentity)
-        && snapshotsMatch(directorySnapshot(
-          root, target, journal.targetRoot, journal.targetSkill, snapshotOptions,
-        ), journal.after)
-    : journal.stageIdentity === null && journal.after.length === 0
-      ? !targetDetails
-      : targetDetails && directoryIdentityMatches(target, journal.stageIdentity)
-        && snapshotsMatch(directorySnapshot(
-          root, target, journal.targetRoot, journal.targetSkill, snapshotOptions,
-        ), journal.after);
-  if (targetAfter) {
-    if (archiveAction && archive !== null) {
-      assertExactDirectory(root, archive, journal.beforeIdentity, journal.before,
-        journal.targetRoot, journal.targetSkill, snapshotOptions);
-    }
-    if (stageDetails) fail("MUTATION_TRANSACTION_AMBIGUOUS");
-    if (displacedDetails) assertExactDirectory(root, displaced, journal.beforeIdentity, journal.before,
-      journal.targetRoot, journal.targetSkill, snapshotOptions);
-    ensureUsageCommitted(root, journal);
-    afterUsageCommit?.();
-    ensureLedgerCommitted(root, journal);
-    afterLedgerCommit?.();
-    ensureProposalCommitted(root, journal);
-    ensureConfigCommitted(root, journal);
-    afterConfigCommit?.();
-    cleanupDisplaced(root, journal, skills, snapshotOptions);
-    clearJournalUnlocked(root);
-    return {
-      status: "finalized",
-      kind: journal.kind,
-      requestId: journal.requestId,
-      ledgerEntry: journal.ledgerEntry,
-      path: target,
-      archivePath: archive,
-      transition: /^usage:(active|stale|archived)->(active|stale|archived)$/u.exec(
-        journal.ledgerEntry.reason ?? "",
-      )?.slice(1),
-    };
-  }
-
-  const targetBefore = journal.beforeIdentity === null
-    ? !targetDetails && journal.before.length === 0
-    : targetDetails && directoryIdentityMatches(target, journal.beforeIdentity)
-      && snapshotsMatch(directorySnapshot(
-        root, target, journal.targetRoot, journal.targetSkill, snapshotOptions,
-      ), journal.before);
-  if (targetBefore && !displacedDetails && !archiveDetails) {
-    if (stageDetails && stage !== null) removeExactDirectory(root, stage, journal.stageIdentity, journal.after,
-      journal.targetRoot, journal.targetSkill, snapshotOptions);
-    clearJournalUnlocked(root);
-    return { status: "rolled-back", kind: journal.kind, requestId: journal.requestId };
-  }
-
-  if (!targetDetails && displacedDetails && displaced !== null && !archiveDetails) {
-    assertExactDirectory(root, displaced, journal.beforeIdentity, journal.before,
-      journal.targetRoot, journal.targetSkill, snapshotOptions);
-    if (stageDetails && stage !== null) removeExactDirectory(root, stage, journal.stageIdentity, journal.after,
-      journal.targetRoot, journal.targetSkill, snapshotOptions);
-    renameSync(displaced, target);
-    assertExactDirectory(root, target, journal.beforeIdentity, journal.before,
-      journal.targetRoot, journal.targetSkill, snapshotOptions);
-    clearJournalUnlocked(root);
-    return { status: "rolled-back", kind: journal.kind, requestId: journal.requestId };
-  }
-  fail("MUTATION_TRANSACTION_AMBIGUOUS");
-}

package/plugins/litclaude/lib/skill-loop/proposal-reader.mjs

@@ -1,26 +0,0 @@
-import { readLedger, validateProposalReceipt } from "./ledger.mjs";
-import { SkillLoopProposalError } from "./proposal-record.mjs";
-import { listProposalRecords, readProposalRecord } from "./proposal-store.mjs";
-
-function validateReceipt(root, proposal, ledgerIndex) {
-  if (!["applied", "rolled-back"].includes(proposal.status)) return proposal;
-  try {
-    validateProposalReceipt(root, proposal, ledgerIndex);
-  } catch {
-    throw new SkillLoopProposalError("PROPOSAL_LEDGER_INVALID", "proposal receipt is missing or mismatched");
-  }
-  return proposal;
-}
-
-export function readProposalUnlocked(root, id) {
-  return validateReceipt(root, readProposalRecord(root, id));
-}
-
-export function listProposalsUnlocked(root, { ledgerWorkLimits } = {}) {
-  const proposals = listProposalRecords(root);
-  const needsReceipt = proposals.some(({ status }) => ["applied", "rolled-back"].includes(status));
-  const ledgerIndex = needsReceipt
-    ? new Map(readLedger(root, { workLimits: ledgerWorkLimits }).map((entry) => [entry.id, entry]))
-    : undefined;
-  return proposals.map((proposal) => validateReceipt(root, proposal, ledgerIndex));
-}

package/plugins/litclaude/lib/skill-loop/proposal-record.mjs

@@ -1,104 +0,0 @@
-import {
-  assertNoSecretStrings,
-  parseTimestamp,
-  portablePathIdentity,
-  prettyJsonBytes,
-  PROPOSAL_MAX_BYTES,
-  RECORD_ID,
-  requireExactKeys,
-  SKILL_ID,
-} from "./common.mjs";
-
-export class SkillLoopProposalError extends Error {
-  constructor(code, message = code) {
-    super(`${code}: ${message}`);
-    this.name = "SkillLoopProposalError";
-    this.code = code;
-  }
-}
-
-const required = [
-  "schema", "id", "createdAt", "host", "sessionRef", "signal", "targetSkill", "targetRoot",
-  "action", "rationale", "evidenceRefs", "status",
-];
-const optional = ["patch", "createSpec", "ledgerEntryId"];
-const text = (value, min, max) => typeof value === "string" && value.length >= min && value.length <= max;
-const schemaError = () => new SkillLoopProposalError("PROPOSAL_SCHEMA_INVALID", "proposal does not match v1 schema");
-
-function validateRelativeFile(file, targetSkill) {
-  const identity = portablePathIdentity(file);
-  const targetIdentity = portablePathIdentity(targetSkill);
-  if (identity === null || targetIdentity === null || identity === targetIdentity
-    || identity.startsWith(`${targetIdentity}/`)) {
-    throw new SkillLoopProposalError("PROPOSAL_PATH_INVALID", "proposal contains a non-portable relative path");
-  }
-}
-
-function validatePatch(patch, targetSkill) {
-  if (!requireExactKeys(patch, ["file", "oldString", "newString"])) throw schemaError();
-  validateRelativeFile(patch.file, targetSkill);
-  if (!text(patch.oldString, 1, 65536) || !text(patch.newString, 0, 65536)) throw schemaError();
-}
-
-function validateCreateSpec(createSpec, targetSkill) {
-  if (!requireExactKeys(createSpec, ["files"]) || !Array.isArray(createSpec.files)
-    || createSpec.files.length < 1 || createSpec.files.length > 64) throw schemaError();
-  const byteIdentities = new Set();
-  const canonicalIdentities = new Set();
-  for (const item of createSpec.files) {
-    if (!requireExactKeys(item, ["file", "content"]) || !text(item.content, 0, 65536)) throw schemaError();
-    validateRelativeFile(item.file, targetSkill);
-    const identity = portablePathIdentity(item.file);
-    if (byteIdentities.has(item.file) || canonicalIdentities.has(identity)) {
-      throw new SkillLoopProposalError("PROPOSAL_PATH_COLLISION", "proposal file identities collide");
-    }
-    byteIdentities.add(item.file);
-    canonicalIdentities.add(identity);
-  }
-}
-
-export function validateProposal(proposal) {
-  let serialized;
-  try {
-    serialized = prettyJsonBytes(proposal);
-  } catch {
-    throw schemaError();
-  }
-  if (serialized.length > PROPOSAL_MAX_BYTES) {
-    throw new SkillLoopProposalError("PROPOSAL_TOO_LARGE", "proposal exceeds 64 KiB");
-  }
-  if (!requireExactKeys(proposal, required, optional)
-    || proposal.schema !== "litfamily.skill-proposal/v1"
-    || !RECORD_ID.test(proposal.id)
-    || parseTimestamp(proposal.createdAt) === null
-    || proposal.host !== "litclaude"
-    || !text(proposal.sessionRef, 1, 512)
-    || !text(proposal.signal, 1, 128)
-    || !SKILL_ID.test(proposal.targetSkill)
-    || portablePathIdentity(proposal.targetSkill) === null
-    || !text(proposal.targetRoot, 1, 2048)
-    || !["patch", "create", "add-reference", "archive"].includes(proposal.action)
-    || !text(proposal.rationale, 1, 8192)
-    || !Array.isArray(proposal.evidenceRefs) || proposal.evidenceRefs.length > 32
-    || proposal.evidenceRefs.some((value) => !text(value, 1, 2048))
-    || new Set(proposal.evidenceRefs).size !== proposal.evidenceRefs.length
-    || !["pending", "approved", "applied", "rejected", "rolled-back"].includes(proposal.status)) {
-    throw schemaError();
-  }
-  const hasPatch = Object.hasOwn(proposal, "patch");
-  const hasCreate = Object.hasOwn(proposal, "createSpec");
-  if (proposal.action === "patch") {
-    if (!hasPatch || hasCreate) throw schemaError();
-    validatePatch(proposal.patch, proposal.targetSkill);
-  } else if (["create", "add-reference"].includes(proposal.action)) {
-    if (hasPatch || !hasCreate) throw schemaError();
-    validateCreateSpec(proposal.createSpec, proposal.targetSkill);
-  } else if (hasPatch || hasCreate) throw schemaError();
-  const needsLedger = ["applied", "rolled-back"].includes(proposal.status);
-  if (needsLedger !== Object.hasOwn(proposal, "ledgerEntryId")
-    || (needsLedger && !text(proposal.ledgerEntryId, 1, 128))) throw schemaError();
-  assertNoSecretStrings(proposal, () => {
-    throw new SkillLoopProposalError("PROPOSAL_SECRET_REFUSED", "credential-shaped proposal content was refused");
-  });
-  return proposal;
-}