@avee1234/selfpatch 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@avee1234/selfpatch",
+  "version": "0.1.0",
+  "description": "The safe self-modification layer for AI agent harnesses. Every self-edit becomes a verifiable, gated, revertible artifact — a pull request your agent opens against its own brain. Zero dependencies.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "selfpatch": "bin/selfpatch.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "build:site-lib": "node scripts/build-site-lib.mjs"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "harness",
+    "self-improvement",
+    "rsi",
+    "governance",
+    "reward-hacking",
+    "safety",
+    "audit",
+    "rollback",
+    "open-format",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "homepage": "https://selfpatch.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abhid1234/selfpatch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/abhid1234/selfpatch/issues"
+  }
+}

package/src/adapters/claude-code-skills.js

@@ -0,0 +1,144 @@
+// selfpatch — Claude Code skills adapter (v0.1). The Foundry dogfood.
+//
+// Treat a `.agents/skills` tree as an editable *surface* and map a before/after
+// tree diff into a list of validated self-patches — one per changed skill file —
+// by composing the shipped `proposeSelfPatch`. These are the harness's OWN
+// orchestration skills (the factory editing itself), i.e. vision layer 4, so the
+// layer is `scaffolding`, not `skill`.
+//
+// Pure and synchronous, zero-dependency: the module does NO filesystem, process,
+// or network I/O. It operates on in-memory `{ relPath → content }` maps the CLI
+// injects (the CLI does the disk walk), mirroring the core/seam split every other
+// module uses — so it is fully unit-testable without disk. Its only import is
+// `proposeSelfPatch` / `ProposeError`.
+
+import { proposeSelfPatch, ProposeError } from "../propose.js";
+
+export const SKILL_LAYER = "scaffolding";
+export const DEFAULT_SKILLS_ROOT = ".agents/skills";
+export const DEFAULT_EVAL_COMMAND = "npm test";
+
+// Join a skills root and a repo-relative skill path into a stable POSIX
+// repo-relative `target`, independent of the host path separator. The target is
+// a logical repo path, not a filesystem path, so we normalize slashes and trim
+// redundant separators by hand rather than reach for the platform path module
+// (which would also make this module non-pure across OSes).
+export function skillTargetPath(skillsRoot, relPath) {
+  const root = String(skillsRoot).replace(/\\/g, "/").replace(/\/+$/, "");
+  const rel = String(relPath).replace(/\\/g, "/").replace(/^\/+/, "");
+  return root === "" ? rel : `${root}/${rel}`;
+}
+
+// Collect the keys of a plain object or a Map into a Set, so callers may pass
+// either shape for a tree.
+function treeKeys(tree) {
+  if (tree instanceof Map) return new Set(tree.keys());
+  return new Set(Object.keys(tree ?? {}));
+}
+
+// Read a rel's content from a plain object or a Map; `undefined` when absent.
+function treeGet(tree, rel) {
+  if (tree instanceof Map) return tree.get(rel);
+  return tree ? tree[rel] : undefined;
+}
+
+/**
+ * Classify a before/after skills-tree diff purely by string content.
+ *
+ * @param {object|Map} before  `{ relPath → content:string }` (or a Map).
+ * @param {object|Map} after   `{ relPath → content:string }` (or a Map).
+ * @returns {{ added: string[], modified: string[], removed: string[], unchanged: string[] }}
+ *   A rel present only in `after` ⇒ added; only in `before` ⇒ removed; in both
+ *   and differing ⇒ modified; in both and equal ⇒ unchanged. Each list is sorted
+ *   for deterministic output.
+ */
+export function diffSkillTrees(before, after) {
+  const beforeKeys = treeKeys(before);
+  const afterKeys = treeKeys(after);
+  const all = new Set([...beforeKeys, ...afterKeys]);
+
+  const added = [];
+  const modified = [];
+  const removed = [];
+  const unchanged = [];
+
+  for (const rel of all) {
+    const inBefore = beforeKeys.has(rel);
+    const inAfter = afterKeys.has(rel);
+    if (inAfter && !inBefore) {
+      added.push(rel);
+    } else if (inBefore && !inAfter) {
+      removed.push(rel);
+    } else if (treeGet(before, rel) === treeGet(after, rel)) {
+      unchanged.push(rel);
+    } else {
+      modified.push(rel);
+    }
+  }
+
+  added.sort();
+  modified.sort();
+  removed.sort();
+  unchanged.sort();
+  return { added, modified, removed, unchanged };
+}
+
+/**
+ * Diff two skills trees and build a validated self-patch for each changed file.
+ *
+ * Every added/modified skill becomes one `layer: "scaffolding"` self-patch with
+ * a `before_after` diff (an added file has `before: ""`), a per-target blast
+ * radius, and an operator-supplied `eval_contract`. Removed skills are surfaced
+ * in `changes.removed` but produce NO patch (a `before_after` patch with
+ * `after: ""` would write an empty file, not delete it — the honest bound of the
+ * shipped `apply`; the CLI routes removals to a human).
+ *
+ * @param {object|Map} before  `{ relPath → content:string }` (or a Map).
+ * @param {object|Map} after   `{ relPath → content:string }` (or a Map).
+ * @param {object} [opts]  `{ skillsRoot, author, rationale, evalCommand,
+ *   requires }`. `skillsRoot` defaults to `.agents/skills`, `evalCommand` to
+ *   `npm test`, `requires` to `human-gate` (fail-closed). `rationale` defaults
+ *   to a per-target string.
+ * @returns {{ patches: object[], changes: object }} `patches` in `added` then
+ *   `modified` order (each sorted); `changes` is the raw `diffSkillTrees` result.
+ * @throws {ProposeError} Re-thrown from `proposeSelfPatch` if an assembled patch
+ *   fails the #1 schema, carrying `.errors` so the CLI can exit 2.
+ */
+export function proposeSkillEdits(before, after, opts = {}) {
+  const {
+    skillsRoot = DEFAULT_SKILLS_ROOT,
+    author,
+    rationale,
+    evalCommand = DEFAULT_EVAL_COMMAND,
+    requires = "human-gate",
+  } = opts;
+
+  const changes = diffSkillTrees(before, after);
+  const patches = [];
+
+  // Added first, then modified — both already sorted — so patch order is stable.
+  for (const rel of [...changes.added, ...changes.modified]) {
+    const target = skillTargetPath(skillsRoot, rel);
+    const patch = proposeSelfPatch(
+      {
+        format: "before_after",
+        before: treeGet(before, rel) ?? "",
+        after: treeGet(after, rel),
+      },
+      {
+        author,
+        layer: SKILL_LAYER,
+        target,
+        rationale: rationale ?? `factory retro: skill edit to ${target}`,
+        command: evalCommand,
+        requires,
+        surfaces: [target],
+      }
+    );
+    patches.push(patch);
+  }
+
+  return { patches, changes };
+}
+
+export { ProposeError };

package/src/canonical.js

@@ -0,0 +1,24 @@
+// selfpatch — canonical serialization (shared).
+//
+// Deterministic, key-order-independent serialization for hashing. Objects emit
+// their keys sorted; arrays keep order; `undefined` collapses to `null` so a
+// missing field hashes identically to an explicit null.
+//
+// Extracted verbatim from `propose.js` so the self-patch content-hash `id` and
+// the ledger's hash chain share one definition. Zero-dependency, pure.
+
+export function canonicalize(v) {
+  if (v === null || v === undefined) return "null";
+  if (Array.isArray(v)) return "[" + v.map(canonicalize).join(",") + "]";
+  if (typeof v === "object") {
+    return (
+      "{" +
+      Object.keys(v)
+        .sort()
+        .map((k) => JSON.stringify(k) + ":" + canonicalize(v[k]))
+        .join(",") +
+      "}"
+    );
+  }
+  return JSON.stringify(v);
+}

package/src/gate.js

@@ -0,0 +1,232 @@
+// selfpatch — `gate` (v0.1). The policy engine.
+//
+// Given a self-patch (#1) and a protected-surface policy, decide
+// `approve | human-gate | block` with an explicit human-readable reason. The
+// decision is a *declarative* read of the policy (protected surfaces, blast
+// radius limits, per-target approval rules) — no predicate/escape-hatch code
+// yet (roadmap: "declarative core + optional escape hatch"; the escape hatch is
+// deferred).
+//
+// Pure and synchronous, zero-dependency. This module does NO process,
+// filesystem, or network I/O — the CLI reads/validates the files and prints the
+// verdict. So the whole gate logic is unit-testable with plain objects.
+//
+// Decision, in fail-closed precedence (strongest first):
+//   1. block   — the patch touches a **protected surface**, or its declared
+//                **blast radius** exceeds a policy limit. Hard policy violations
+//                win over everything, regardless of the patch's `requires`.
+//   2. else, resolve the effective `requires` for this patch as the STRICTEST of
+//      the patch's own `requires`, every matching `approvals` rule, and (only
+//      when no rule matches) the policy's `default_requires` (itself defaulting
+//      to `human-gate`). Then map on the strictness lattice auto < human-gate <
+//      forbidden:
+//        forbidden  ⇒ block
+//        human-gate ⇒ human-gate
+//        auto       ⇒ approve
+
+// Thrown when handed inputs that cannot be gated: a non-object patch or policy.
+// Fail closed — an ungateable self-patch is not silently "approved". Named/
+// exported to mirror `ProposeError` (#2) and `VerifyError` (#3) so callers can
+// rely on the type. The CLI validates both documents first, so this is a guard.
+export class GateError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GateError";
+  }
+}
+
+export const DECISIONS = ["approve", "human-gate", "block"];
+
+// Strictness lattice for `requires`. Higher rank = more restrictive (fail-
+// closed). Index in RANK_TO_DECISION maps the resolved rank to a decision.
+const REQUIRES_RANK = { auto: 0, "human-gate": 1, forbidden: 2 };
+const RANK_TO_DECISION = ["approve", "human-gate", "block"];
+
+// An unknown `requires` string is treated as the strictest level (fail closed);
+// the CLI validates first, so this only bites malformed direct callers.
+function requiresRank(r) {
+  return Object.prototype.hasOwnProperty.call(REQUIRES_RANK, r)
+    ? REQUIRES_RANK[r]
+    : REQUIRES_RANK.forbidden;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function isString(v) {
+  return typeof v === "string";
+}
+
+function nonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+function isNonNegativeNumber(v) {
+  return typeof v === "number" && Number.isFinite(v) && v >= 0;
+}
+
+function isAbsent(v) {
+  return v === undefined || v === null;
+}
+
+// Glob matcher: `*` matches any run of characters (including `/`); a pattern
+// with no `*` is an exact match. So `src/schema.js` matches only itself, `src/*`
+// matches everything under `src/`, and `*` matches any surface. Anchored full
+// match; all other regex metacharacters are matched literally.
+function matchSurface(pattern, value) {
+  if (!isString(pattern) || !isString(value)) return false;
+  const escaped = pattern
+    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    .replace(/\\\*/g, ".*");
+  return new RegExp("^" + escaped + "$").test(value);
+}
+
+// The concrete surfaces a patch touches: its `target` plus every declared
+// `blast_radius.surfaces` entry. Matched against `protected_surfaces` as the
+// union so a patch can't slip a protected file past by declaring it in only one
+// place.
+function touchedSurfaces(patch) {
+  const out = [];
+  if (nonEmptyString(patch.target)) out.push(patch.target);
+  const br = patch.blast_radius;
+  if (isPlainObject(br) && Array.isArray(br.surfaces)) {
+    for (const s of br.surfaces) if (isString(s)) out.push(s);
+  }
+  return out;
+}
+
+// First protected surface the patch touches, or null. Returns the matching
+// `{ surface, pattern }` so the reason can name both.
+function firstProtectedHit(touched, protectedSurfaces) {
+  for (const pattern of protectedSurfaces) {
+    for (const surface of touched) {
+      if (matchSurface(pattern, surface)) return { surface, pattern };
+    }
+  }
+  return null;
+}
+
+// First blast-radius limit the patch's declared blast radius exceeds, as a
+// reason string, or null. `surfaces` is always declared (schema-required), so
+// `max_surfaces` is always checkable; `files_changed`/`lines_changed` are only
+// compared when the patch declares them (nothing to "exceed" otherwise).
+function firstBlastViolation(patch, limits) {
+  const br = isPlainObject(patch.blast_radius) ? patch.blast_radius : {};
+  const surfaces = Array.isArray(br.surfaces) ? br.surfaces : [];
+  if (isNonNegativeNumber(limits.max_surfaces) && surfaces.length > limits.max_surfaces) {
+    return `declared blast radius of ${surfaces.length} surface(s) exceeds max_surfaces ${limits.max_surfaces}`;
+  }
+  if (
+    isNonNegativeNumber(limits.max_files_changed) &&
+    isNonNegativeNumber(br.files_changed) &&
+    br.files_changed > limits.max_files_changed
+  ) {
+    return `declared files_changed ${br.files_changed} exceeds max_files_changed ${limits.max_files_changed}`;
+  }
+  if (
+    isNonNegativeNumber(limits.max_lines_changed) &&
+    isNonNegativeNumber(br.lines_changed) &&
+    br.lines_changed > limits.max_lines_changed
+  ) {
+    return `declared lines_changed ${br.lines_changed} exceeds max_lines_changed ${limits.max_lines_changed}`;
+  }
+  return null;
+}
+
+// Does an `approvals` rule apply to this patch? A rule constrains by `layer`
+// and/or `target` (schema guarantees at least one). Every present constraint
+// must match; `target` is matched with the same glob as protected surfaces.
+function ruleMatches(rule, patch) {
+  if (!isPlainObject(rule)) return false;
+  if (isAbsent(rule.layer) && isAbsent(rule.target)) return false;
+  if (!isAbsent(rule.layer) && rule.layer !== patch.layer) return false;
+  if (!isAbsent(rule.target) && !matchSurface(rule.target, patch.target)) return false;
+  return true;
+}
+
+// Resolve the effective `requires` level: the strictest of the patch's own
+// `requires` and every matching approval rule; when no rule matches, the
+// policy's `default_requires` (defaulting to `human-gate`) applies instead.
+// Returns `{ level, rank, matched }`.
+function effectiveRequires(patch, policy) {
+  const levels = [patch.requires];
+  const approvals = Array.isArray(policy.approvals) ? policy.approvals : [];
+  let matched = false;
+  for (const rule of approvals) {
+    if (ruleMatches(rule, patch)) {
+      levels.push(rule.requires);
+      matched = true;
+    }
+  }
+  if (!matched) {
+    levels.push(isString(policy.default_requires) ? policy.default_requires : "human-gate");
+  }
+
+  let level = "auto";
+  let rank = 0;
+  for (const l of levels) {
+    const r = requiresRank(l);
+    if (r >= rank) {
+      rank = r;
+      level = l;
+    }
+  }
+  return { level, rank, matched };
+}
+
+/**
+ * Decide whether a self-patch may be applied under a policy.
+ *
+ * @param {object} patch   A self-patch object (valid per #1). Reads `target`,
+ *   `layer`, `blast_radius`, and `requires`.
+ * @param {object} policy  A protected-surface policy (valid per #1). Reads
+ *   `protected_surfaces`, `blast_radius_limits`, `approvals`, `default_requires`.
+ * @returns {{ decision: "approve"|"human-gate"|"block", reason: string }}
+ * @throws {GateError} If `patch` or `policy` is not a plain object.
+ */
+export function gate(patch, policy) {
+  if (!isPlainObject(patch)) {
+    throw new GateError("gate: `patch` must be an object");
+  }
+  if (!isPlainObject(policy)) {
+    throw new GateError("gate: `policy` must be an object");
+  }
+
+  // 1. Protected surface — the hardest violation; wins over any `requires`.
+  const protectedSurfaces = Array.isArray(policy.protected_surfaces)
+    ? policy.protected_surfaces
+    : [];
+  const hit = firstProtectedHit(touchedSurfaces(patch), protectedSurfaces);
+  if (hit) {
+    const via = hit.pattern === hit.surface ? "" : ` (matched by rule "${hit.pattern}")`;
+    return {
+      decision: "block",
+      reason: `touches protected surface "${hit.surface}"${via}`,
+    };
+  }
+
+  // 2. Blast radius over a declared limit.
+  const limits = isPlainObject(policy.blast_radius_limits)
+    ? policy.blast_radius_limits
+    : {};
+  const blast = firstBlastViolation(patch, limits);
+  if (blast) {
+    return { decision: "block", reason: blast };
+  }
+
+  // 3. Effective approval level.
+  const eff = effectiveRequires(patch, policy);
+  const decision = RANK_TO_DECISION[eff.rank] || "block";
+  const via = eff.matched ? "a policy approval rule" : "the patch/default level";
+  if (decision === "block") {
+    return { decision, reason: `effective requires "forbidden" (via ${via})` };
+  }
+  if (decision === "human-gate") {
+    return { decision, reason: `effective requires "human-gate" (via ${via})` };
+  }
+  return {
+    decision: "approve",
+    reason: `effective requires "auto"; no protected surface touched and within blast-radius limits`,
+  };
+}

package/src/index.js

@@ -0,0 +1,36 @@
+export {
+  validateSelfPatch,
+  validatePolicy,
+  LAYERS,
+  REQUIRES,
+  DIFF_FORMATS,
+  ERROR_CODES,
+} from "./schema.js";
+
+export { sha256hex } from "./sha256.js";
+
+export { proposeSelfPatch, ProposeError } from "./propose.js";
+
+export { verifySelfPatch, VerifyError } from "./verify.js";
+
+export { gate, GateError, DECISIONS } from "./gate.js";
+
+export {
+  LedgerError,
+  LEDGER_EVENTS,
+  hashEntry,
+  blobRef,
+  buildAppliedEntry,
+  buildRevertedEntry,
+  verifyChain,
+  findRevertable,
+} from "./ledger.js";
+
+export {
+  proposeSkillEdits,
+  diffSkillTrees,
+  skillTargetPath,
+  SKILL_LAYER,
+  DEFAULT_SKILLS_ROOT,
+  DEFAULT_EVAL_COMMAND,
+} from "./adapters/claude-code-skills.js";

package/src/ledger.js

@@ -0,0 +1,202 @@
+// selfpatch — `ledger` (v0.1). The hash-chained, tamper-evident record.
+//
+// The fourth verb: `apply` writes a surface and records the event, `revert <id>`
+// restores the pre-patch surface, and `log` prints the history. This module is
+// the **pure core** — chain construction, hashing, integrity verification, and
+// entry selection. It performs NO filesystem, process, or network I/O; the CLI
+// injects every read/write (the same core/seam split `verify` uses for
+// `runCheck`). Canonical hashing reuses `propose`'s key-order-independent
+// `canonicalize`, so a re-serialized entry hashes identically.
+//
+// Integrity is a **hash chain, not signatures**: each entry stores `prev` (the
+// hash of the preceding entry) and its own `hash` = sha256 over the entry's
+// canonical content excluding `hash` itself. Because the hash covers `prev`, any
+// edit, reorder, insertion, or deletion of a past entry breaks the chain and is
+// detected on read. This is tamper-*evidence* (detection), not prevention or
+// authorship — signatures are a deferred later milestone.
+
+import { sha256hex } from "./sha256.js";
+import { canonicalize } from "./canonical.js";
+
+// Thrown for un-chainable input (a non-array chain, an entry that isn't a plain
+// object) and for an ambiguous revert id-prefix. Named/exported to mirror
+// `ProposeError`/`VerifyError`/`GateError` so callers can rely on the type.
+export class LedgerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LedgerError";
+  }
+}
+
+// The event vocabulary the two mutating verbs write. `log` renders any event
+// type it finds, so a future pipeline can append `proposed`/`gated`/`blocked`
+// lifecycle entries without a format change (a non-goal here).
+export const LEDGER_EVENTS = ["applied", "reverted"];
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function sha256(content) {
+  return sha256hex(content);
+}
+
+/**
+ * The hash of an entry: `"sha256:" + sha256(canonical(entry without hash))`.
+ * `prev` IS included in the canonical content, so the hash covers the link to
+ * the predecessor — an attacker cannot reorder entries without breaking a hash.
+ * @throws {LedgerError} If `entry` is not a plain object.
+ */
+export function hashEntry(entry) {
+  if (!isPlainObject(entry)) {
+    throw new LedgerError("hashEntry: entry must be a plain object");
+  }
+  const hashable = {};
+  for (const k of Object.keys(entry)) {
+    if (k === "hash") continue;
+    hashable[k] = entry[k];
+  }
+  return "sha256:" + sha256(canonicalize(hashable));
+}
+
+/**
+ * A content-addressed reference to a surface snapshot:
+ * `"sha256:" + sha256(content)`. `null` content ⇒ `null` ref (an absent
+ * surface — a file `apply` created or that `revert` will delete). The
+ * object-store key is the hex after the `sha256:` prefix.
+ */
+export function blobRef(content) {
+  if (content === null || content === undefined) return null;
+  return "sha256:" + sha256(content);
+}
+
+// Attach `prev`/`seq`, then the `hash` over everything else. Pure. `partial`
+// carries every semantic field; the caller supplies `seq` and `prev`.
+function linkEntry(prevHash, seq, partial) {
+  const entry = { ...partial, seq, prev: prevHash ?? null };
+  entry.hash = hashEntry(entry);
+  return entry;
+}
+
+/**
+ * Assemble a hash-linked `applied` entry from a self-patch and its snapshots.
+ * `pre`/`post` are blob refs (or `null`); `reason` is omitted when absent.
+ */
+export function buildAppliedEntry({ patch, target, pre, post, ts, seq, prev, reason }) {
+  const partial = {
+    ts,
+    event: "applied",
+    patch_id: patch.id,
+    layer: patch.layer,
+    target,
+    rationale: patch.rationale,
+    pre,
+    post,
+  };
+  if (reason !== undefined && reason !== null) partial.reason = reason;
+  return linkEntry(prev, seq, partial);
+}
+
+/**
+ * Assemble a hash-linked `reverted` entry. `reverts` is the `hash` of the
+ * `applied` entry being undone; `pre`/`post` snapshot the surface around the
+ * restore.
+ */
+export function buildRevertedEntry({ patchId, target, reverts, pre, post, ts, seq, prev }) {
+  return linkEntry(prev, seq, {
+    ts,
+    event: "reverted",
+    patch_id: patchId,
+    target,
+    reverts,
+    pre,
+    post,
+  });
+}
+
+/**
+ * Verify a parsed chain. For each entry checks `prev` links to the previous
+ * entry's `hash` (`null` at genesis) AND `hash === hashEntry(entry)`. Detects
+ * mutation, reorder, insertion, and deletion. Returns `{ valid, brokenAt }`
+ * where `brokenAt` is the first failing index (`-1` if intact).
+ * @throws {LedgerError} If `entries` is not an array.
+ */
+export function verifyChain(entries) {
+  if (!Array.isArray(entries)) {
+    throw new LedgerError("verifyChain: entries must be an array");
+  }
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (!isPlainObject(entry)) return { valid: false, brokenAt: i };
+    const expectedPrev = i === 0 ? null : entries[i - 1].hash;
+    if (entry.prev !== expectedPrev) return { valid: false, brokenAt: i };
+    let recomputed;
+    try {
+      recomputed = hashEntry(entry);
+    } catch {
+      return { valid: false, brokenAt: i };
+    }
+    if (entry.hash !== recomputed) return { valid: false, brokenAt: i };
+  }
+  return { valid: true, brokenAt: -1 };
+}
+
+// Resolve an `id` to a single concrete `patch_id`. An **exact** full-id match
+// always wins (never ambiguous, even when it is also a prefix of a longer id).
+// Otherwise `id` is treated as a prefix: unique ⇒ that id, none ⇒ null, more
+// than one distinct id ⇒ throw. Returns `{ patchId }` / `{ patchId: null }`.
+function resolvePatchId(entries, id) {
+  const prefixIds = new Set();
+  let exact = false;
+  for (const e of entries) {
+    if (typeof e.patch_id !== "string") continue;
+    if (e.patch_id === id) exact = true;
+    if (e.patch_id.startsWith(id)) prefixIds.add(e.patch_id);
+  }
+  if (exact) return { patchId: id };
+  if (prefixIds.size > 1) {
+    throw new LedgerError(
+      `findRevertable: id prefix "${id}" is ambiguous (matches ${prefixIds.size} patches)`
+    );
+  }
+  if (prefixIds.size === 0) return { patchId: null };
+  return { patchId: [...prefixIds][0] };
+}
+
+/**
+ * Find the most recent `applied` entry for `id` that has not already been
+ * reverted — i.e. whose `hash` is not the `reverts` target of any later
+ * `reverted` entry. `id` is a full `sha256:…` or a unique prefix (an exact full
+ * id always resolves, even if it is also a prefix of a longer id).
+ *
+ * @returns {{ entry: object } | { entry: null, reason: "not-found" | "already-reverted" }}
+ * @throws {LedgerError} If the prefix matches more than one distinct patch id.
+ */
+export function findRevertable(entries, id) {
+  if (!Array.isArray(entries)) {
+    throw new LedgerError("findRevertable: entries must be an array");
+  }
+  if (typeof id !== "string" || id.length === 0) {
+    throw new LedgerError("findRevertable: id must be a non-empty string");
+  }
+  const { patchId } = resolvePatchId(entries, id);
+  if (patchId === null) return { entry: null, reason: "not-found" };
+
+  // The set of applied-entry hashes already undone by a `reverted` entry.
+  const revertedHashes = new Set();
+  for (const e of entries) {
+    if (e.event === "reverted" && typeof e.reverts === "string") {
+      revertedHashes.add(e.reverts);
+    }
+  }
+
+  // Walk newest-first; return the latest un-reverted apply for this id.
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e.event !== "applied") continue;
+    if (e.patch_id !== patchId) continue;
+    if (revertedHashes.has(e.hash)) continue;
+    return { entry: e };
+  }
+  return { entry: null, reason: "already-reverted" };
+}