ai-optimize-master 0.0.0-stage → 0.3.0

package/lib/apply.mjs

@@ -0,0 +1,264 @@
+// Turn scan findings into an ordered, reviewable plan; apply it under a
+// hash-bound, journaled, reversible transaction.
+import { resolve, sep, dirname } from 'node:path'
+import { sha256Hex, isInside, expandHome, realpathOrNull } from './util.mjs'
+import { archiveSkillDirectory, restoreSkillDirectory, pathState } from './archive.mjs'
+
+const RISK_ORDER = { low: 0, medium: 1, high: 2 }
+const VALID_RISK = new Set(Object.keys(RISK_ORDER))
+const VALID_KINDS = new Set(['archive-skill'])
+
+/**
+ * Supported step kinds in v0.2:
+ *  - archive-skill: move a whole skill directory under the optimizer's archive root.
+ * Only skills that (a) exist inside a declared skill root, (b) have a SKILL.md,
+ * and (c) were explicitly selected by the caller are eligible.
+ */
+export function buildPlan(scanResult, options = {}) {
+  const {
+    home = resolve(expandHome('~/.dsh-optimizer')),
+    selections = [],
+    includeFindings = true
+  } = options
+
+  const archiveRoot = resolve(home, 'archive')
+  const steps = []
+  const skipped = []
+
+  const byName = new Map()
+  const authorizedRoots = []
+  for (const root of scanResult.roots ?? []) {
+    authorizedRoots.push({ id: root.id, dir: resolve(root.dir) })
+    for (const skill of root.skills ?? []) {
+      const list = byName.get(skill.name) ?? []
+      list.push({ root: root.id, rootDir: root.dir, ...skill })
+      byName.set(skill.name, list)
+    }
+  }
+
+  const duplicateInfo = new Map((scanResult.duplicates ?? []).map(d => [d.name, d]))
+
+  for (const selection of selections) {
+    const name = typeof selection === 'string' ? selection : selection?.name
+    const wantedRoot = typeof selection === 'string' ? null : selection?.root
+    const copies = byName.get(name) ?? []
+    if (!copies.length) {
+      skipped.push({ name, reason: 'no-such-skill' })
+      continue
+    }
+    const chosen = wantedRoot ? copies.filter(c => c.root === wantedRoot) : copies
+    if (chosen.length !== 1) {
+      skipped.push({ name, reason: chosen.length ? 'ambiguous-root' : 'root-has-no-copy', candidates: chosen.map(c => c.root) })
+      continue
+    }
+    const target = chosen[0]
+    if (!target.hasSkillMd) {
+      skipped.push({ name, reason: 'no-skill-md' })
+      continue
+    }
+    const dir = resolve(target.dir)
+    if (!isInside(resolve(target.rootDir), dir)) {
+      skipped.push({ name, reason: 'outside-skill-root' })
+      continue
+    }
+    const duplicate = duplicateInfo.get(name)
+    const risk = duplicate?.classification === 'identical-copies' ? 'low' : 'medium'
+    steps.push({
+      id: `archive-skill:${target.root}:${name}`,
+      kind: 'archive-skill',
+      title: `Archive skill ${name} from ${target.root}`,
+      preview: { from: dir, to: resolve(archiveRoot, `${target.root}__${name}`) },
+      risk,
+      requiresAdmin: false,
+      reversible: true,
+      evidence: {
+        skillMdHash: target.skillMdHash,
+        duplicates: duplicate ? duplicate.classification : 'single-copy',
+        brokenReferences: target.brokenReferences ?? []
+      },
+      rationale: duplicate
+        ? 'Duplicate skill definition across tool roots; archive keeps a recoverable copy.'
+        : 'Explicitly selected single-copy skill. Archiving is reversible, but review why it was selected.'
+    })
+  }
+
+  steps.sort((a, b) => (RISK_ORDER[a.risk] - RISK_ORDER[b.risk]) || a.id.localeCompare(b.id))
+
+  const findings = includeFindings ? (scanResult.findings ?? []) : []
+  const plan = {
+    schema: 'dsh-optimizer/plan/v0.2',
+    platform: scanResult.platform,
+    archiveRoot,
+    authorizedRoots,
+    createdAt: new Date().toISOString(),
+    steps,
+    skipped,
+    findingIds: findings.map(f => f.id)
+  }
+  plan.planHash = sha256Hex(plan)
+  return plan
+}
+
+export function verifyPlanHash(plan) {
+  const { planHash, ...rest } = plan
+  return sha256Hex(rest) === planHash
+}
+
+/**
+ * Structural validation. Unknown values are rejected, never treated as "low":
+ * `RISK_ORDER[undefined] > 0` is false, so an unvalidated risk would slip through.
+ */
+export function validatePlan(plan) {
+  const problems = []
+  if (!plan || typeof plan !== 'object') return { ok: false, problems: ['plan-not-object'] }
+  if (plan.schema !== 'dsh-optimizer/plan/v0.2') problems.push('bad-schema')
+  if (typeof plan.planHash !== 'string' || !/^[0-9a-f]{64}$/.test(plan.planHash)) problems.push('bad-plan-hash')
+  if (typeof plan.archiveRoot !== 'string' || !plan.archiveRoot) problems.push('missing-archive-root')
+  if (!Array.isArray(plan.authorizedRoots) || !plan.authorizedRoots.length) problems.push('missing-authorized-roots')
+  if (!Array.isArray(plan.steps)) problems.push('steps-not-array')
+  for (const [index, step] of (plan.steps ?? []).entries()) {
+    const where = `steps[${index}]`
+    if (!step || typeof step !== 'object') { problems.push(`${where}:not-object`); continue }
+    if (typeof step.id !== 'string' || !step.id) problems.push(`${where}:bad-id`)
+    if (!VALID_KINDS.has(step.kind)) problems.push(`${where}:bad-kind`)
+    if (!VALID_RISK.has(step.risk)) problems.push(`${where}:bad-risk`)
+    if (typeof step.requiresAdmin !== 'boolean') problems.push(`${where}:bad-requires-admin`)
+    if (!step.preview || typeof step.preview.from !== 'string' || typeof step.preview.to !== 'string') problems.push(`${where}:bad-preview`)
+  }
+  return { ok: problems.length === 0, problems }
+}
+
+async function authorizeStep(step, plan) {
+  const from = resolve(step.preview.from)
+  const to = resolve(step.preview.to)
+  const archiveRoot = resolve(plan.archiveRoot)
+
+  if (!isInside(archiveRoot, to)) return { ok: false, reason: 'archive-target-outside-root' }
+  if (from === to) return { ok: false, reason: 'source-equals-target' }
+  if (isInside(from, archiveRoot)) return { ok: false, reason: 'archive-inside-source' }
+
+  const roots = plan.authorizedRoots.map(r => resolve(r.dir))
+  if (!roots.some(root => isInside(root, from))) return { ok: false, reason: 'source-outside-authorized-roots' }
+
+  // Symlinked ancestors can escape a prefix check; compare real paths when the
+  // path already exists.
+  const realFrom = await realpathOrNull(from)
+  const realRoots = []
+  for (const root of roots) realRoots.push(await realpathOrNull(root))
+  if (realFrom && !realRoots.filter(Boolean).some(root => isInside(root, realFrom))) {
+    return { ok: false, reason: 'source-realpath-outside-authorized-roots' }
+  }
+  const state = await pathState(from)
+  if (state.symlink) return { ok: false, reason: 'source-is-symlink' }
+  if (!state.exists) return { ok: false, reason: 'source-missing' }
+  if (!state.directory) return { ok: false, reason: 'source-not-directory' }
+  if ((await pathState(to)).exists) return { ok: false, reason: 'archive-target-exists' }
+  return { ok: true }
+}
+
+/**
+ * Apply a plan with a staged, journaled transaction.
+ *  - missing expect        -> code 4 (denied)
+ *  - planHash mismatch     -> code 3 (diverged)
+ *  - invalid plan/shape    -> code 1 (usage) before any write
+ *  - unknown risk/allow    -> rejected, never silently downgraded
+ *  - intent is persisted before the first destructive operation
+ *  - the journal is rewritten after every step, so a crash still leaves a record
+ */
+export async function applyPlan(plan, options) {
+  const { expect, allow = 'low', journal, isAdmin = false } = options
+
+  if (!expect) return { ok: false, code: 4, reason: 'missing-expected-plan-hash', journal: null }
+  if (!VALID_RISK.has(allow)) return { ok: false, code: 1, reason: 'invalid-allow-value', journal: null }
+
+  const validated = validatePlan(plan)
+  if (!validated.ok) return { ok: false, code: 1, reason: 'invalid-plan', problems: validated.problems, journal: null }
+  if (!verifyPlanHash(plan) || plan.planHash !== expect) return { ok: false, code: 3, reason: 'plan-diverged', journal: null }
+
+  const maxRisk = RISK_ORDER[allow]
+  const journalDoc = {
+    schema: 'dsh-optimizer/journal/v0.2',
+    planHash: plan.planHash,
+    createdAt: new Date().toISOString(),
+    archiveRoot: plan.archiveRoot,
+    steps: [],
+    results: []
+  }
+
+  // Persist intent before touching disk: a crash mid-run must be explainable.
+  journalDoc.phase = 'intent'
+  await journal.write(journalDoc)
+  journalDoc.phase = 'running'
+
+  for (const step of plan.steps) {
+    const risk = RISK_ORDER[step.risk] ?? Infinity
+    if (risk > maxRisk) {
+      journalDoc.results.push({ id: step.id, status: 'skipped', blocked: 'risk-not-allowed', risk: step.risk })
+      continue
+    }
+    if (step.requiresAdmin && !isAdmin) {
+      journalDoc.results.push({ id: step.id, status: 'blocked', blocked: 'requires-admin' })
+      continue
+    }
+    const authorization = await authorizeStep(step, plan)
+    if (!authorization.ok) {
+      journalDoc.results.push({ id: step.id, status: 'blocked', blocked: authorization.reason })
+      continue
+    }
+    const outcome = await archiveSkillDirectory(step, plan.archiveRoot)
+    if (outcome.code !== 'ok') {
+      journalDoc.results.push({ id: step.id, status: 'blocked', blocked: outcome.code })
+      await journal.write(journalDoc)
+      continue
+    }
+    journalDoc.steps.push({
+      id: step.id,
+      kind: step.kind,
+      before: outcome.before,
+      after: outcome.after
+    })
+    journalDoc.results.push({ id: step.id, status: 'applied', from: step.preview.from, to: step.preview.to })
+    // Rewrite after each step: a partial run is still recoverable.
+    await journal.write(journalDoc)
+  }
+
+  journalDoc.phase = 'done'
+  await journal.write(journalDoc)
+  const failures = journalDoc.results.filter(r => r.status === 'blocked')
+  return {
+    ok: failures.length === 0,
+    code: failures.length === 0 ? 0 : 1,
+    journal: journalDoc,
+    results: journalDoc.results
+  }
+}
+
+/**
+ * Undo an applied journal in reverse order.
+ * Refuses to overwrite a target that was re-created after apply, verifies the
+ * archived tree before restoring, and treats an already-restored step as done.
+ */
+export async function undoJournal(journalDoc, options = {}) {
+  const { journal } = options
+  const results = []
+  const steps = [...(journalDoc.steps ?? [])].reverse()
+  for (const step of steps) {
+    const outcome = await restoreSkillDirectory(step)
+    results.push({ id: step.id, status: outcome.code === 'ok' ? 'restored' : (outcome.code === 'already-restored' ? 'already-restored' : 'conflict'), code: outcome.code, detail: outcome.detail })
+    if (journal) {
+      journalDoc.results = [...(journalDoc.results ?? []), ...results]
+      journalDoc.phase = 'undoing'
+      await journal.write(journalDoc)
+      journalDoc.results = journalDoc.results.slice(0, -(results.length))
+    }
+  }
+  if (journal) {
+    journalDoc.results = [...(journalDoc.results ?? []), ...results]
+    journalDoc.phase = 'undone'
+    await journal.write(journalDoc)
+  }
+  const conflicts = results.filter(r => r.status === 'conflict')
+  return { ok: conflicts.length === 0, code: conflicts.length === 0 ? 0 : 3, results }
+}
+
+export { RISK_ORDER }

package/lib/archive.mjs

@@ -0,0 +1,130 @@
+// Archive + restore primitives. Shared by the CLI, the DSH plugin and tests so a
+// fix lands in every surface at once.
+import { cp, lstat, mkdir, rename, rm, readdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { buildManifest, verifyManifest, manifestDigest } from './manifest.mjs'
+
+export async function pathState(p) {
+  try {
+    const info = await lstat(p)
+    return { exists: true, symlink: info.isSymbolicLink(), directory: info.isDirectory() }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, symlink: false, directory: false }
+    throw error
+  }
+}
+
+// Move a skill directory into the archive root, with exclusive creation and a
+// verified copy before the original is touched.
+//
+// Contract:
+//  - the archive target must not already exist (never merge into a previous archive)
+//  - the source must not be a symlink (we do not follow links out of the root)
+//  - the copy is verified against a full manifest before the source is removed
+//  - if verification fails, the partial archive is removed and the source is kept
+export async function archiveSkillDirectory(step, archiveRoot) {
+  const from = step.preview.from
+  const to = step.preview.to
+  if (!to.startsWith(archiveRoot)) return { code: 'outside-archive-root' }
+
+  const state = await pathState(from)
+  if (!state.exists) return { code: 'source-missing' }
+  if (state.symlink) return { code: 'source-is-symlink' }
+  if (!state.directory) return { code: 'source-not-directory' }
+  if ((await pathState(to)).exists) return { code: 'archive-target-exists' }
+
+  const sourceManifest = await buildManifest(from)
+  await mkdir(dirname(to), { recursive: true })
+  const staging = `${to}.partial-${process.pid}-${Date.now()}`
+  await mkdir(staging, { recursive: true })
+  try {
+    await cp(from, staging, { recursive: true, force: false, errorOnExist: true })
+    const copied = await buildManifest(staging)
+    if (!sameEntries(sourceManifest, copied)) {
+      await rm(staging, { recursive: true, force: true })
+      return { code: 'copy-verification-failed' }
+    }
+    await rename(staging, to)
+    // Re-check the source right before removal: this narrows (but cannot fully
+    // eliminate) a concurrent-write window. See SECURITY.md "concurrent writes".
+    const current = await buildManifest(from)
+    if (!sameEntries(sourceManifest, current)) {
+      await rm(to, { recursive: true, force: true })
+      return { code: 'source-changed-during-copy' }
+    }
+    await rm(from, { recursive: true, force: true })
+    const archived = await buildManifest(to)
+    return {
+      code: 'ok',
+      before: { path: from, manifest: sourceManifest, digest: manifestDigest(sourceManifest) },
+      after: { path: to, manifest: archived, digest: manifestDigest(archived) }
+    }
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true }).catch(() => {})
+    throw error
+  }
+}
+
+// Restore one journaled step. Refuses to overwrite anything that appeared at the
+// original path after apply, and verifies the archived tree before restoring.
+export async function restoreSkillDirectory(step) {
+  const target = step.before.path
+  const archivePath = step.after.path
+
+  const archiveState = await pathState(archivePath)
+  if (!archiveState.exists) {
+    // Idempotency: if the original is back with the expected content, this step
+    // was already undone; otherwise the archive is gone and we cannot restore.
+    const targetState = await pathState(target)
+    if (targetState.exists && targetState.directory) {
+      const check = await verifyManifest(target, step.before.manifest)
+      if (check.ok) return { code: 'already-restored' }
+    }
+    return { code: 'archive-missing' }
+  }
+
+  const archiveCheck = await verifyManifest(archivePath, step.after.manifest)
+  if (!archiveCheck.ok) return { code: 'archive-integrity-failed', detail: archiveCheck }
+
+  const targetState = await pathState(target)
+  if (targetState.exists) return { code: 'target-occupied', detail: targetState }
+
+  await mkdir(dirname(target), { recursive: true })
+  const staging = `${target}.restore-${process.pid}-${Date.now()}`
+  try {
+    await cp(archivePath, staging, { recursive: true, force: false })
+    const check = await verifyManifest(staging, step.before.manifest)
+    if (!check.ok) {
+      await rm(staging, { recursive: true, force: true })
+      return { code: 'restore-verification-failed', detail: check }
+    }
+    await rename(staging, target)
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true }).catch(() => {})
+    throw error
+  }
+  const finalCheck = await verifyManifest(target, step.before.manifest)
+  if (!finalCheck.ok) return { code: 'restore-verification-failed', detail: finalCheck }
+  await removeEmptyParents(archivePath)
+  await rm(archivePath, { recursive: true, force: true })
+  return { code: 'ok' }
+}
+
+async function removeEmptyParents(path) {
+  let dir = dirname(path)
+  for (let i = 0; i < 4; i++) {
+    try {
+      const items = await readdir(dir)
+      if (items.length) return
+      await rm(dir, { recursive: false, force: true })
+      dir = dirname(dir)
+    } catch {
+      return
+    }
+  }
+}
+
+function sameEntries(a, b) {
+  return JSON.stringify(a.entries) === JSON.stringify(b.entries)
+}
+

package/lib/evolve.mjs

@@ -0,0 +1,128 @@
+// Evolve = read-only improvement proposals + change detection (v0.3).
+//
+// What this module will NOT do (std review, 2026-11-06):
+//  - delete a dangling reference automatically (a missing file may be generated later)
+//  - rewrite SKILL.md with a model (behaviour gain is unverifiable, privacy/prompt-injection risk)
+//  - convert identical copies into symlinks (changes path resolution and installer behaviour)
+//
+// It produces evidence + a diff, and leaves execution to the existing hash-bound
+// plan/apply path, which the caller must still approve.
+import { readTextIfExists } from './util.mjs'
+
+const REF_LINE = /^.*`((?:scripts|references|examples|assets|templates|docs)\/[^`\s)]+)`.*$/gm
+const WIN_PATH = /([A-Za-z]:\\[^\s`'"）)]+)/g
+
+function lineOf(text, index) {
+  return text.slice(0, index).split('\n').length
+}
+
+/**
+ * Build proposals from a scan result.
+ * Every proposal carries: skill, root, kind, evidence, suggestion, diff, and
+ * `apply: 'manual'` — there is no auto-apply path for these in v0.3.
+ */
+export async function propose(scanResult) {
+  const proposals = []
+  for (const root of scanResult.roots ?? []) {
+    for (const skill of root.skills ?? []) {
+      if (!skill.hasSkillMd) continue
+      const file = skill.dir.endsWith('SKILL.md') ? skill.dir : `${skill.dir}/SKILL.md`
+      const text = await readTextIfExists(file)
+      if (text === null) continue
+
+      // 1) Dangling local references: report, never delete.
+      for (const broken of skill.brokenReferences ?? []) {
+        const re = new RegExp(`^.*\`${escapeRe(broken)}\`.*$`, 'm')
+        const match = re.exec(text)
+        proposals.push({
+          id: `proposal:broken-reference:${root.id}:${skill.name}:${broken}`,
+          skill: skill.name,
+          root: root.id,
+          kind: 'broken-reference',
+          risk: 'medium',
+          apply: 'manual',
+          evidence: { missing: broken, line: match ? lineOf(text, match.index) : null, file },
+          suggestion: 'Either restore the referenced file or remove the instruction that points at it. Confirm which one is true for this skill before editing.',
+          diff: match ? `- ${match[0].trim()}\n+ (remove only if the referenced file is not generated at runtime)` : null,
+          note: 'A missing file only proves it cannot be resolved now; it does not prove the instruction is wrong.'
+        })
+      }
+
+      // 2) Windows-only absolute paths on a POSIX host: propose portable form.
+      if (process.platform !== 'win32') {
+        const seen = new Set()
+        for (const match of text.matchAll(WIN_PATH)) {
+          const raw = match[1]
+          if (seen.has(raw)) continue
+          seen.add(raw)
+          proposals.push({
+            id: `proposal:platform-path:${root.id}:${skill.name}:${hashish(raw)}`,
+            skill: skill.name,
+            root: root.id,
+            kind: 'platform-path',
+            risk: 'low',
+            apply: 'manual',
+            evidence: { path: raw, line: lineOf(text, match.index) },
+            suggestion: 'Replace the hard-coded Windows path with an environment-driven path. Note that `$HOME`/`~` are not expanded identically by every agent, so verify the target interpreter before editing.',
+            diff: `- ${raw}\n+ <portable path or environment variable, verified against the consuming agent>`
+          })
+        }
+      }
+    }
+  }
+
+  // 3) Duplicate groups: report only. Content equality does not authorise merging.
+  for (const duplicate of scanResult.duplicates ?? []) {
+    proposals.push({
+      id: `proposal:duplicate:${duplicate.name}`,
+      skill: duplicate.name,
+      root: null,
+      kind: 'duplicate',
+      risk: 'medium',
+      apply: 'manual',
+      evidence: { classification: duplicate.classification, copies: duplicate.copies.map(c => ({ root: c.root, dir: c.dir })) },
+      suggestion: duplicate.classification === 'identical-copies'
+        ? 'Pick one copy to own future edits, or move to a canonical source with links. Byte equality today does not promise equal upgrades later.'
+        : 'The copies already diverge. Diff them and decide which one is authoritative before touching either.',
+      diff: null
+    })
+  }
+
+  return {
+    schema: 'ai-optimize-master/evolve/v0.3',
+    platform: scanResult.platform,
+    generatedAt: new Date().toISOString(),
+    readOnly: true,
+    counts: proposals.reduce((acc, p) => { acc[p.kind] = (acc[p.kind] ?? 0) + 1; return acc }, {}),
+    proposals
+  }
+}
+
+/** Compare two scan results and report what appeared / disappeared. */
+export function compareScans(baseline, current) {
+  const key = finding => finding.id
+  const before = new Map((baseline.findings ?? []).map(f => [key(f), f]))
+  const after = new Map((current.findings ?? []).map(f => [key(f), f]))
+  const added = [...after.keys()].filter(id => !before.has(id))
+  const resolved = [...before.keys()].filter(id => !after.has(id))
+  const skillCount = result => (result.roots ?? []).reduce((n, r) => n + (r.skillCount ?? 0), 0)
+  return {
+    schema: 'ai-optimize-master/change/v0.3',
+    baselineAt: baseline.scannedAt ?? null,
+    currentAt: current.scannedAt ?? null,
+    skillCountBefore: skillCount(baseline),
+    skillCountAfter: skillCount(current),
+    added: added.map(id => after.get(id)).map(f => ({ id: f.id, title: f.title, severity: f.severity })),
+    resolved: resolved.map(id => before.get(id)).map(f => ({ id: f.id, title: f.title, severity: f.severity }))
+  }
+}
+
+function escapeRe(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function hashish(value) {
+  let hash = 0
+  for (const char of value) hash = (hash * 31 + char.charCodeAt(0)) >>> 0
+  return hash.toString(16)
+}

package/lib/manifest.mjs

@@ -0,0 +1,63 @@
+// Directory-level integrity: a single SKILL.md hash cannot prove an archive is
+// complete. A manifest covers every entry: relative path, type, file hash, and
+// symlink target.
+import { lstat, readdir, readFile, readlink } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { createHash } from 'node:crypto'
+
+export async function buildManifest(root) {
+  const entries = []
+  async function walk(dir) {
+    let items
+    try {
+      items = await readdir(dir, { withFileTypes: true })
+    } catch (error) {
+      if (error?.code === 'ENOENT') return
+      throw error
+    }
+    for (const item of items.sort((a, b) => a.name.localeCompare(b.name))) {
+      const absolute = join(dir, item.name)
+      const rel = relative(root, absolute).replaceAll('\\', '/')
+      const info = await lstat(absolute)
+      if (info.isSymbolicLink()) {
+        entries.push({ path: rel, type: 'symlink', target: await readlink(absolute) })
+      } else if (info.isDirectory()) {
+        entries.push({ path: rel, type: 'dir' })
+        await walk(absolute)
+      } else if (info.isFile()) {
+        const bytes = await readFile(absolute)
+        entries.push({ path: rel, type: 'file', sha256: createHash('sha256').update(bytes).digest('hex'), size: bytes.length })
+      } else {
+        entries.push({ path: rel, type: 'other' })
+      }
+    }
+  }
+  await walk(root)
+  return { root, entries }
+}
+
+export function manifestDigest(manifest) {
+  return createHash('sha256').update(JSON.stringify(manifest.entries)).digest('hex')
+}
+
+export function manifestsEqual(a, b) {
+  return manifestDigest(a) === manifestDigest(b)
+}
+
+// Verify that a tree still matches a manifest. Any added, removed, or modified
+// entry makes the verification fail; "looks fine" is not a verification.
+export async function verifyManifest(root, manifest) {
+  const current = await buildManifest(root)
+  if (manifestsEqual(current, manifest)) return { ok: true, digest: manifestDigest(current) }
+  const expectedPaths = new Set(manifest.entries.map(e => e.path))
+  const actualPaths = new Set(current.entries.map(e => e.path))
+  const missing = [...expectedPaths].filter(p => !actualPaths.has(p))
+  const extra = [...actualPaths].filter(p => !expectedPaths.has(p))
+  const changed = []
+  for (const entry of manifest.entries) {
+    const other = current.entries.find(e => e.path === entry.path)
+    if (!other) continue
+    if (other.type !== entry.type || other.sha256 !== entry.sha256 || other.target !== entry.target) changed.push(entry.path)
+  }
+  return { ok: false, digest: manifestDigest(current), missing, extra, changed }
+}