@1aboveio/skills 1.0.18 → 1.0.20

package/skills/engineering/resolve-issues/scripts/resource-formats.mjs

@@ -0,0 +1,625 @@
+// Typed proof for generated resource formats and the source-owned inputs that rebuild them.
+//
+// retention.mjs is deliberately strict in two places: a run-metadata name such as
+// `source`, `sources`, `results` or `raw` is never disposable, and a symbolic link that
+// points outside the target blocks removal. Both rules are right for a generic resource
+// and wrong for a proven package-manager or build artifact: real installed dependencies
+// ship a `source/` directory, and a virtual environment's `bin/python` is a reference to
+// the base interpreter by design. A blanket name guard therefore rejects genuine vendor
+// content, which is the reviewed defect this module narrows.
+//
+// This module is the narrow, read-only exception. It proves one typed format plus the
+// canonical, source-owned rebuild inputs that reproduce it, and reports which two
+// generic guards the caller may relax for that resource. It never deletes, registers,
+// quarantines, or prints a rebuild command, and it never executes anything: proof is
+// bounded lstat/readdir/hash work plus, for two manifests, JSON.parse. External symbolic
+// links inside a proven format are REFERENCES, so cleanup unlinks the link without
+// following it; no code here traverses one. Credential policy is not this module's: the
+// engine's credential guard stays in force for every resource, typed or not.
+//
+// API
+//   inspectResourceFormat({ format, path, inputs, inspection? })
+//     -> { ok, state, reason, format, root, markers, inputProofs,
+//          allowEmbeddedSourceNames, allowReferenceSymlinks,
+//          embeddedSourceNames, blockingMetadata, referenceSymlinks, retainInputs }
+//     Re-proves the markers and proves the rebuild inputs from disk. `inspection` is
+//     optional: pass the caller's own tree inspection ({ ok, reason, metadataNames,
+//     externalSymlinks }) so the name verdict and the external-link verdict reuse one
+//     walk. With no inspection, no name or link scan happens here at all.
+//   validateRebuildInputs(inputProofs)
+//     -> { ok, reason, checked, changed: [{ name, path, kind, detail }] }
+//     Re-reads each recorded input and reports missing / path / identity / hardlink /
+//     content changes against the recorded proof. Read-only.
+//   classifyRebuildState({ format, path, inputProofs, inspection? })
+//     -> { ok, state: 'ready'|'missing'|'partial'|'inputs-changed'|'unproven', ... }
+//     Re-proves the markers (cheap, targeted) and validates the recorded inputs, without
+//     writing. A root that looks present but is not usable after a manual cleanup stays
+//     'partial', never 'ready'. Pass `inspection` too and run metadata inside the tree
+//     keeps the same 'partial' verdict inspectResourceFormat reports.
+//   classifyEmbeddedNames({ format, names })
+//     -> { format, allowEmbeddedSourceNames, allowed, blocking }
+//     Pure split of the caller's metadata names into the vendored names a typed format
+//     may embed and the run metadata that still blocks removal.
+//
+// Formats and the canonical rebuild inputs each one needs (all inputs must be canonical
+// regular files outside the target, at most 4 inputs, at most 16 MiB each, one hard
+// link, no symbolic link; a JSON manifest must parse to an object):
+//   pnpm-install  <project>/node_modules  .modules.yaml + .pnpm/<package@version>/
+//                                         package.json + pnpm-lock.yaml
+//   uv-venv       <project>/.venv         pyvenv.cfg + bin/python reference +
+//                                         lib/python*/site-packages
+//                                         pyproject.toml + uv.lock
+//   next-build    <project>/.next         BUILD_ID + build-manifest.json + server/
+//                                         package.json + pnpm-lock.yaml
+//   pnpm-store    <project>/.pnpm-store    v<N>/files/<bucket>/<content-addressed>
+//                                         package.json + pnpm-lock.yaml
+// Anything else, including no format at all, is `generic`: no typed proof exists, `ok`
+// is false, and both allowances are false, so the caller keeps its existing strict
+// checks. A folder name never creates authority.
+//
+// The caller names the rebuild inputs. This module proves that the named files are the
+// canonical ones for the format, sit outside the target, and are unchanged since the
+// proof; it records their content hash and identity. It cannot decide that a particular
+// lockfile is the one that produced a particular artifact, so choosing an owner's own
+// inputs stays with the caller (retention.mjs, from the unit's project).
+//
+// Integration sketch (retention.mjs owns the real wiring):
+//   const proof = inspectResourceFormat({
+//     format: entry.resourceFormat, path: entry.path, inputs: rebuildInputsFor(entry),
+//     inspection,
+//   })
+//   if (!proof.ok) retain(entry, proof.reason)              // generic rules, unchanged
+//   else remove(entry.path, { unlinkLinks: proof.referenceSymlinks })  // unlink, never follow
+
+import { createHash } from 'node:crypto'
+import {
+  closeSync, constants as fsConstants, fstatSync, lstatSync, openSync, readSync, readdirSync,
+  readlinkSync, realpathSync,
+} from 'node:fs'
+import { basename, isAbsolute, join, resolve } from 'node:path'
+import { containsPath, normPath } from '../../harness-runtime/workspace-lifecycle.mjs'
+
+// Finite bounds. The input budget is a ceiling for one proof, not a size policy: two
+// source-owned configuration files comfortably fit, and a bound is still enforced.
+export const MAX_REBUILD_INPUTS = 4
+export const MAX_REBUILD_INPUT_BYTES = 16 * 1024 * 1024
+const HASH_CHUNK_BYTES = 1024 * 1024
+const MAX_MARKER_ENTRIES = 4096
+const MAX_BUCKET_ENTRIES = 512
+const MAX_BUCKETS_SCANNED = 64
+const MAX_MANIFEST_BYTES = 16 * 1024 * 1024
+
+// The four run-metadata names that real installed dependencies and build outputs
+// legitimately contain. Only a proven typed format may embed these.
+const VENDORED_SOURCE_NAMES = new Set(['source', 'sources', 'results', 'raw'])
+// Run metadata that stays blocking even inside a proven typed format. A generated tree
+// is never the owner of a plan, a finding record, a checkpoint, or a Git repository.
+const RUN_METADATA_NAMES = new Set([
+  'task-plan.json', 'issue-tree.json', 'taskplan.json', 'dropbox.json', 'findings.json',
+  'next-actions-seen.json', 'decisions', 'findings', 'reviewverdicts', 'review-verdicts',
+  'briefs', 'profiling', 'checkpoints', '.git',
+])
+
+const FORMATS = Object.freeze({
+  'pnpm-install': Object.freeze({
+    inputs: Object.freeze(['package.json', 'pnpm-lock.yaml']),
+    jsonInputs: Object.freeze(['package.json']),
+  }),
+  'uv-venv': Object.freeze({
+    inputs: Object.freeze(['pyproject.toml', 'uv.lock']),
+    jsonInputs: Object.freeze([]),
+  }),
+  'next-build': Object.freeze({
+    inputs: Object.freeze(['package.json', 'pnpm-lock.yaml']),
+    jsonInputs: Object.freeze(['package.json']),
+  }),
+  'pnpm-store': Object.freeze({
+    inputs: Object.freeze(['package.json', 'pnpm-lock.yaml']),
+    jsonInputs: Object.freeze(['package.json']),
+  }),
+})
+export const TYPED_FORMATS = Object.freeze(Object.keys(FORMATS))
+
+const CA_FILE_NAME = /^[0-9a-f]{32,}(?:[-._][A-Za-z0-9._-]+)?$/i
+const O_NOFOLLOW = fsConstants.O_NOFOLLOW ?? 0
+
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0
+const real = (p) => (realpathSync.native ? realpathSync.native(p) : realpathSync(p))
+
+function formatId(value) {
+  const id = typeof value === 'string' ? value.trim() : ''
+  return Object.hasOwn(FORMATS, id) ? id : 'generic'
+}
+
+function genericReason(requested) {
+  const named = typeof requested === 'string' && requested.trim() ? `'${requested.trim()}' is not a typed format` : 'no typed format was requested'
+  return `${named}; generic resources keep the existing strict metadata-name and external-link checks`
+}
+
+function verdict(fields) {
+  return {
+    ok: fields.ok === true,
+    state: fields.state,
+    reason: fields.reason ?? null,
+    format: fields.format ?? 'generic',
+    root: fields.root ?? null,
+    markers: fields.markers ?? [],
+    inputProofs: fields.inputProofs ?? null,
+    allowEmbeddedSourceNames: fields.allowEmbeddedSourceNames === true,
+    allowReferenceSymlinks: fields.allowReferenceSymlinks === true,
+    embeddedSourceNames: fields.embeddedSourceNames ?? [],
+    blockingMetadata: fields.blockingMetadata ?? [],
+    referenceSymlinks: fields.referenceSymlinks ?? [],
+    // Rebuild inputs are source-owned configuration: they are retained, never a
+    // deletion candidate, and this module only ever reads them.
+    retainInputs: true,
+  }
+}
+
+// ---- bounded, no-follow primitives ----
+
+function marker(rel, present, detail) {
+  return { rel, present: present === true, detail: detail ?? null }
+}
+
+// readdir + Dirent types never follow a symbolic link, so a linked directory is reported
+// as a link, not as the tree it points at.
+function listDir(abs, maxEntries = MAX_MARKER_ENTRIES) {
+  let all
+  try { all = readdirSync(abs, { withFileTypes: true }) } catch (error) {
+    return { entries: [], truncated: false, error: error?.code ?? error?.message ?? 'unreadable' }
+  }
+  const sorted = all.slice().sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  return { entries: sorted.slice(0, maxEntries), truncated: sorted.length > maxEntries, error: null }
+}
+
+// Opens with O_NOFOLLOW so a link swapped in after the lstat cannot redirect the read,
+// hashes the opened descriptor, and refuses a file that changes under it.
+function readBounded(path, expected, maxBytes) {
+  let fd = null
+  try {
+    fd = openSync(path, fsConstants.O_RDONLY | O_NOFOLLOW)
+    const opened = fstatSync(fd)
+    if (!opened.isFile() || opened.dev !== expected.dev || opened.ino !== expected.ino) return { error: `${path} changed before it could be read` }
+    if (opened.size <= 0) return { error: `${path} is empty` }
+    if (opened.size > maxBytes) return { error: `${path} exceeds the ${maxBytes}-byte bound` }
+    const digest = createHash('sha256')
+    const chunks = []
+    const buffer = Buffer.allocUnsafe(HASH_CHUNK_BYTES)
+    let read = 0
+    while (read < opened.size) {
+      const got = readSync(fd, buffer, 0, Math.min(buffer.length, opened.size - read), read)
+      if (got <= 0) return { error: `${path} ended before its recorded size` }
+      digest.update(buffer.subarray(0, got))
+      chunks.push(Buffer.from(buffer.subarray(0, got)))
+      read += got
+    }
+    if (readSync(fd, Buffer.alloc(1), 0, 1, opened.size) !== 0) return { error: `${path} grew while it was being read` }
+    const final = fstatSync(fd)
+    if (!final.isFile() || final.dev !== opened.dev || final.ino !== opened.ino
+      || final.size !== opened.size || final.mtimeMs !== opened.mtimeMs) {
+      return { error: `${path} changed while it was being read` }
+    }
+    return {
+      buffer: Buffer.concat(chunks, read),
+      hash: digest.digest('hex'),
+      bytes: read,
+      identity: { dev: opened.dev, ino: opened.ino, size: opened.size, mtimeMs: opened.mtimeMs },
+    }
+  } catch (error) {
+    return { error: `cannot read ${path}: ${error?.code ?? error?.message}` }
+  } finally {
+    if (fd !== null) { try { closeSync(fd) } catch { /* already closed */ } }
+  }
+}
+
+// ---- marker proof ----
+
+function probeFile(root, rel, markers, { requireContent = false, maxBytes = null } = {}) {
+  let st
+  try { st = lstatSync(join(root, rel)) } catch (error) {
+    if (error?.code === 'ENOENT') { markers.push(marker(rel, false, 'missing')); return { ok: false, reason: `${rel} is missing` } }
+    markers.push(marker(rel, false, `unreadable: ${error?.code ?? error?.message}`))
+    return { ok: false, reason: `cannot inspect ${rel}: ${error?.code ?? error?.message}` }
+  }
+  if (st.isSymbolicLink()) { markers.push(marker(rel, true, 'symbolic link')); return { ok: false, reason: `${rel} is a symbolic link; a linked marker cannot prove the format` } }
+  if (!st.isFile()) { markers.push(marker(rel, true, 'not a regular file')); return { ok: false, reason: `${rel} is not a regular file` } }
+  if (requireContent && st.size === 0) { markers.push(marker(rel, true, 'empty')); return { ok: false, reason: `${rel} is empty` } }
+  if (maxBytes !== null && st.size > maxBytes) { markers.push(marker(rel, true, 'oversize')); return { ok: false, reason: `${rel} exceeds the ${maxBytes}-byte bound` } }
+  markers.push(marker(rel, true, null))
+  return { ok: true, stat: st }
+}
+
+function probeDirectory(root, rel, markers, { requireEntry = false } = {}) {
+  let st
+  try { st = lstatSync(join(root, rel)) } catch (error) {
+    if (error?.code === 'ENOENT') { markers.push(marker(rel, false, 'missing')); return { ok: false, reason: `${rel} is missing` } }
+    markers.push(marker(rel, false, `unreadable: ${error?.code ?? error?.message}`))
+    return { ok: false, reason: `cannot inspect ${rel}: ${error?.code ?? error?.message}` }
+  }
+  if (st.isSymbolicLink()) { markers.push(marker(rel, true, 'symbolic link')); return { ok: false, reason: `${rel} is a symbolic link; a linked directory cannot prove the format` } }
+  if (!st.isDirectory()) { markers.push(marker(rel, true, 'not a directory')); return { ok: false, reason: `${rel} is not a directory` } }
+  const listed = listDir(join(root, rel))
+  if (listed.error) {
+    markers.push(marker(rel, true, `unreadable: ${listed.error}`))
+    return { ok: false, reason: `cannot enumerate ${rel}: ${listed.error}` }
+  }
+  if (requireEntry && listed.entries.length === 0) { markers.push(marker(rel, true, 'empty')); return { ok: false, reason: `${rel} is empty` } }
+  markers.push(marker(rel, true, listed.truncated ? `listing bound of ${MAX_MARKER_ENTRIES} entries reached` : null))
+  return { ok: true, entries: listed.entries, truncated: listed.truncated }
+}
+
+function provePnpmInstall(root, markers) {
+  const modules = probeFile(root, '.modules.yaml', markers, { requireContent: true })
+  if (!modules.ok) return modules
+  const virtual = probeDirectory(root, '.pnpm', markers)
+  if (!virtual.ok) return virtual
+  // pnpm names each virtual-store entry <name>@<version> or @scope+<name>@<version>.
+  const installed = virtual.entries.find((entry) => entry.isDirectory() && entry.name.includes('@') && entry.name.length > 2)
+  markers.push(marker('.pnpm/<package@version>', Boolean(installed), installed ? installed.name : 'no installed package directory'))
+  if (!installed) {
+    return { ok: false, reason: `.pnpm holds no installed package directory${virtual.truncated ? ' within the listing bound' : ''}, so the install is not proven complete` }
+  }
+  return { ok: true }
+}
+
+// bin/python is expected to be a REFERENCE to the base interpreter. It is read as a link
+// text and never resolved, opened, or stat'ed through.
+function proveInterpreterReference(root, markers) {
+  const rel = 'bin/python'
+  const path = join(root, rel)
+  let st
+  try { st = lstatSync(path) } catch (error) {
+    if (error?.code === 'ENOENT') { markers.push(marker(rel, false, 'missing')); return { ok: false, reason: `${rel} is missing` } }
+    markers.push(marker(rel, false, `unreadable: ${error?.code ?? error?.message}`))
+    return { ok: false, reason: `cannot inspect ${rel}: ${error?.code ?? error?.message}` }
+  }
+  if (st.isSymbolicLink()) {
+    let target
+    try { target = readlinkSync(path) } catch (error) {
+      markers.push(marker(rel, true, 'unreadable link'))
+      return { ok: false, reason: `cannot read the interpreter reference ${rel}: ${error?.code ?? error?.message}` }
+    }
+    if (!nonEmpty(target)) {
+      markers.push(marker(rel, true, 'empty link'))
+      return { ok: false, reason: `${rel} is an empty symbolic link` }
+    }
+    markers.push(marker(rel, true, `interpreter reference -> ${target.length > 200 ? `${target.slice(0, 197)}...` : target}`))
+    return { ok: true, interpreter: { kind: 'reference', target } }
+  }
+  if (st.isFile() && st.size > 0) {
+    markers.push(marker(rel, true, 'interpreter copy'))
+    return { ok: true, interpreter: { kind: 'file' } }
+  }
+  markers.push(marker(rel, true, 'not an interpreter'))
+  return { ok: false, reason: `${rel} is neither an interpreter reference nor a non-empty interpreter file` }
+}
+
+function proveUvVenv(root, markers) {
+  const config = probeFile(root, 'pyvenv.cfg', markers, { requireContent: true })
+  if (!config.ok) return config
+  const bin = probeDirectory(root, 'bin', markers)
+  if (!bin.ok) return bin
+  const interpreter = proveInterpreterReference(root, markers)
+  if (!interpreter.ok) return interpreter
+  const lib = probeDirectory(root, 'lib', markers)
+  if (!lib.ok) return lib
+  const pythonDir = lib.entries.find((entry) => entry.isDirectory() && /^python\d/i.test(entry.name))
+  markers.push(marker('lib/python*/', Boolean(pythonDir), pythonDir ? pythonDir.name : 'no python directory'))
+  if (!pythonDir) return { ok: false, reason: 'lib holds no python<version> directory' }
+  const sitePackages = probeDirectory(root, `lib/${pythonDir.name}/site-packages`, markers)
+  if (!sitePackages.ok) return sitePackages
+  return { ok: true, interpreter: interpreter.interpreter }
+}
+
+function proveNextBuild(root, markers) {
+  const buildId = probeFile(root, 'BUILD_ID', markers, { requireContent: true })
+  if (!buildId.ok) return buildId
+  const manifest = probeFile(root, 'build-manifest.json', markers, { requireContent: true, maxBytes: MAX_MANIFEST_BYTES })
+  if (!manifest.ok) return manifest
+  const read = readBounded(join(root, 'build-manifest.json'), manifest.stat, MAX_MANIFEST_BYTES)
+  if (read.error) return { ok: false, reason: read.error }
+  let parsed
+  try { parsed = JSON.parse(read.buffer.toString('utf8')) } catch { return { ok: false, reason: 'build-manifest.json is not readable JSON' } }
+  if (!isObject(parsed)) return { ok: false, reason: 'build-manifest.json does not contain a JSON object' }
+  const server = probeDirectory(root, 'server', markers, { requireEntry: true })
+  if (!server.ok) return server
+  return { ok: true }
+}
+
+// A content-addressed name is a long hex digest, optionally with pnpm's -index.json or
+// executable suffix. Bucket scanning is capped so a large store cannot turn this into a
+// walk; a store whose first bounded buckets hold no file stays unproven.
+function findContentAddressedEntry(dir, entries) {
+  let scanned = 0
+  for (const entry of entries) {
+    if (entry.isFile() && CA_FILE_NAME.test(entry.name)) return entry.name
+    if (!entry.isDirectory() || !/^[0-9a-f]{2}$/i.test(entry.name)) continue
+    if (++scanned > MAX_BUCKETS_SCANNED) return null
+    const bucket = listDir(join(dir, entry.name), MAX_BUCKET_ENTRIES)
+    if (bucket.error) continue
+    const hit = bucket.entries.find((child) => child.isFile() && CA_FILE_NAME.test(child.name))
+    if (hit) return `${entry.name}/${hit.name}`
+  }
+  return null
+}
+
+function provePnpmStore(root, markers) {
+  const listing = listDir(root)
+  if (listing.error) return { ok: false, reason: `cannot enumerate the store root: ${listing.error}` }
+  const versions = listing.entries
+    .filter((entry) => entry.isDirectory() && /^v\d+$/.test(entry.name))
+    .map((entry) => entry.name)
+    .sort((a, b) => Number(b.slice(1)) - Number(a.slice(1)) || (a < b ? 1 : a > b ? -1 : 0))
+  if (!versions.length) return { ok: false, reason: 'no versioned v<N> store directory at the root' }
+  const versionDir = versions[0]
+  markers.push(marker(versionDir, true, `store version ${versionDir.slice(1)}`))
+  const files = probeDirectory(root, `${versionDir}/files`, markers)
+  if (!files.ok) return files
+  const sample = findContentAddressedEntry(join(root, versionDir, 'files'), files.entries)
+  markers.push(marker(`${versionDir}/files/<content-addressed>`, Boolean(sample), sample ?? (files.truncated ? `listing bound of ${MAX_MARKER_ENTRIES} entries reached` : 'no content-addressed file')))
+  if (!sample) return { ok: false, reason: `${versionDir}/files holds no content-addressed file` }
+  return { ok: true }
+}
+
+const PROVERS = {
+  'pnpm-install': provePnpmInstall,
+  'uv-venv': proveUvVenv,
+  'next-build': proveNextBuild,
+  'pnpm-store': provePnpmStore,
+}
+
+function proveMarkers(format, target) {
+  const root = resolve(target)
+  let st
+  try { st = lstatSync(root) } catch (error) {
+    if (error?.code === 'ENOENT') return { ok: false, state: 'missing', reason: `${root} does not exist`, markers: [marker('.', false, 'missing')], root }
+    return { ok: false, state: 'partial', reason: `cannot inspect ${root}: ${error?.code ?? error?.message}`, markers: [marker('.', false, 'unreadable')], root }
+  }
+  if (st.isSymbolicLink()) return { ok: false, state: 'partial', reason: `${root} is a symbolic link; a linked root cannot prove the format`, markers: [marker('.', true, 'symbolic link')], root }
+  if (!st.isDirectory()) return { ok: false, state: 'partial', reason: `${root} is not a directory`, markers: [marker('.', true, 'not a directory')], root }
+  let rootReal
+  try { rootReal = real(root) } catch (error) {
+    return { ok: false, state: 'partial', reason: `cannot resolve ${root}: ${error?.code ?? error?.message}`, markers: [marker('.', true, 'unresolvable')], root }
+  }
+  const listing = listDir(root)
+  if (listing.error) return { ok: false, state: 'partial', reason: `cannot enumerate ${root}: ${listing.error}`, markers: [marker('.', true, 'unreadable')], root, rootReal }
+  const markers = []
+  const result = PROVERS[format](root, markers)
+  if (result.ok) return { ok: true, state: 'ready', reason: null, markers, root, rootReal, interpreter: result.interpreter ?? null }
+  // A root that still holds something is a partial root: it looks present after a manual
+  // cleanup but nothing here proves it usable. An empty root with no marker is missing.
+  const present = markers.some((entry) => entry.present)
+  const state = present || listing.entries.length > 0 ? 'partial' : 'missing'
+  return { ok: false, state, reason: result.reason, markers, root, rootReal }
+}
+
+// ---- rebuild input proof ----
+
+function flattenInputs(inputs) {
+  if (Array.isArray(inputs)) return inputs
+  if (isObject(inputs)) return Object.values(inputs)
+  return null
+}
+
+function proveInput({ name, path, role, parseJson, root }) {
+  let st
+  try { st = lstatSync(path) } catch (error) {
+    if (error?.code === 'ENOENT') return { error: `rebuild input ${path} is missing` }
+    return { error: `cannot inspect rebuild input ${path}: ${error?.code ?? error?.message}` }
+  }
+  if (st.isSymbolicLink()) return { error: `rebuild input ${path} is a symbolic link; a link is not a proven source` }
+  if (!st.isFile()) return { error: `rebuild input ${path} is not a regular file` }
+  if (st.nlink !== 1) return { error: `rebuild input ${path} has ${st.nlink} hard links; the file on disk is ambiguous` }
+  if (st.size <= 0) return { error: `rebuild input ${path} is empty` }
+  if (st.size > MAX_REBUILD_INPUT_BYTES) return { error: `rebuild input ${path} exceeds the ${MAX_REBUILD_INPUT_BYTES}-byte bound` }
+  let realPath
+  try { realPath = real(path) } catch (error) {
+    return { error: `cannot resolve rebuild input ${path}: ${error?.code ?? error?.message}` }
+  }
+  if (containsPath(root, realPath) || normPath(realPath) === normPath(root)) {
+    return { error: `rebuild input ${path} resolves inside the resource target; a rebuild input must sit outside it` }
+  }
+  const read = readBounded(path, st, MAX_REBUILD_INPUT_BYTES)
+  if (read.error) return { error: read.error }
+  let parsed = false
+  if (parseJson) {
+    let value
+    try { value = JSON.parse(read.buffer.toString('utf8')) } catch { return { error: `rebuild input ${path} is not readable JSON` } }
+    if (!isObject(value)) return { error: `rebuild input ${path} does not contain a JSON object` }
+    parsed = true
+  }
+  return {
+    value: {
+      name,
+      path,
+      realPath,
+      role,
+      sourceOwned: true,
+      identity: read.identity,
+      hash: read.hash,
+      bytes: read.bytes,
+      parsedJson: parsed,
+    },
+  }
+}
+
+function proveRebuildInputs(format, root, inputs) {
+  const spec = FORMATS[format]
+  const given = flattenInputs(inputs)
+  if (!given) return { ok: false, reason: `explicit canonical rebuild inputs are required to prove ${format}`, proofs: [] }
+  if (given.length > MAX_REBUILD_INPUTS) return { ok: false, reason: `${format} accepts at most ${MAX_REBUILD_INPUTS} rebuild inputs`, proofs: [] }
+  const byName = new Map()
+  for (const value of given) {
+    if (!nonEmpty(value) || !isAbsolute(value)) return { ok: false, reason: `rebuild input ${JSON.stringify(value)} must be an absolute path`, proofs: [] }
+    const name = basename(value)
+    if (!spec.inputs.includes(name)) return { ok: false, reason: `${name} is not a canonical rebuild input for ${format} (expected ${spec.inputs.join(' + ')})`, proofs: [] }
+    if (byName.has(name)) return { ok: false, reason: `rebuild input ${name} was supplied more than once`, proofs: [] }
+    byName.set(name, resolve(value))
+  }
+  const missing = spec.inputs.filter((name) => !byName.has(name))
+  if (missing.length) return { ok: false, reason: `missing canonical rebuild input(s) for ${format}: ${missing.join(', ')}`, proofs: [] }
+  const proofs = []
+  for (const name of spec.inputs) {
+    const path = byName.get(name)
+    const proof = proveInput({ name, path, root, role: name.includes('lock') ? 'lockfile' : 'manifest', parseJson: spec.jsonInputs.includes(name) })
+    if (proof.error) return { ok: false, reason: proof.error, proofs: [] }
+    proofs.push(proof.value)
+  }
+  return { ok: true, reason: null, proofs }
+}
+
+// ---- public API ----
+
+export function classifyEmbeddedNames({ format, names } = {}) {
+  const resolved = formatId(format)
+  const typed = resolved !== 'generic'
+  const allowed = []
+  const blocking = []
+  for (const name of Array.isArray(names) ? names : []) {
+    if (!nonEmpty(name)) continue
+    const base = basename(name)
+    if (typed && VENDORED_SOURCE_NAMES.has(base)) { allowed.push(name); continue }
+    // A vendored name blocks for a generic resource: only a proven typed format may
+    // embed one, so a folder name never grants itself authority.
+    if (RUN_METADATA_NAMES.has(base) || VENDORED_SOURCE_NAMES.has(base)) blocking.push(name)
+  }
+  return { format: resolved, allowEmbeddedSourceNames: typed, allowed, blocking }
+}
+
+export function validateRebuildInputs(inputProofs) {
+  if (!Array.isArray(inputProofs) || inputProofs.length === 0) {
+    return { ok: false, reason: 'no rebuild input proof was recorded, so the artifact cannot be proven reproducible', checked: 0, changed: [] }
+  }
+  if (inputProofs.length > MAX_REBUILD_INPUTS) {
+    return { ok: false, reason: `more than ${MAX_REBUILD_INPUTS} rebuild input proofs were recorded`, checked: 0, changed: [] }
+  }
+  const changed = []
+  for (const proof of inputProofs) {
+    const name = isObject(proof) && nonEmpty(proof.name) ? proof.name : '(unnamed)'
+    const path = isObject(proof) && nonEmpty(proof.path) ? proof.path : null
+    const record = (kind, detail) => changed.push({ name, path, kind, detail })
+    if (!isObject(proof) || !nonEmpty(proof.path) || !nonEmpty(proof.hash) || !isObject(proof.identity)) {
+      record('unproven', 'the recorded proof is incomplete')
+      continue
+    }
+    let st
+    try { st = lstatSync(proof.path) } catch (error) {
+      record(error?.code === 'ENOENT' ? 'missing' : 'unreadable', error?.code ?? error?.message ?? 'unreadable')
+      continue
+    }
+    if (st.isSymbolicLink()) { record('path', 'the input is now a symbolic link'); continue }
+    if (!st.isFile()) { record('path', 'the input is no longer a regular file'); continue }
+    if (st.nlink !== 1) { record('hardlink', `the input now has ${st.nlink} hard links`); continue }
+    let realPath
+    try { realPath = real(proof.path) } catch (error) {
+      record('unreadable', `cannot resolve the input: ${error?.code ?? error?.message}`)
+      continue
+    }
+    if (nonEmpty(proof.realPath) && normPath(realPath) !== normPath(proof.realPath)) {
+      record('path', `the input now resolves to ${realPath}`)
+      continue
+    }
+    if (st.dev !== proof.identity.dev || st.ino !== proof.identity.ino) {
+      record('identity', 'the input was replaced by a different file')
+      continue
+    }
+    if (st.size !== proof.identity.size) { record('content', `the input size changed from ${proof.identity.size} to ${st.size}`); continue }
+    if (st.size > MAX_REBUILD_INPUT_BYTES) { record('content', `the input exceeds the ${MAX_REBUILD_INPUT_BYTES}-byte bound`); continue }
+    const read = readBounded(proof.path, st, MAX_REBUILD_INPUT_BYTES)
+    if (read.error) { record('unreadable', read.error); continue }
+    if (read.hash !== proof.hash) record('content', 'the input content changed')
+  }
+  if (changed.length) {
+    return { ok: false, reason: `${changed.length} rebuild input(s) no longer match the recorded proof: ${changed.map((entry) => `${entry.name} (${entry.kind})`).join(', ')}`, checked: inputProofs.length, changed }
+  }
+  return { ok: true, reason: null, checked: inputProofs.length, changed: [] }
+}
+
+function readReferenceSymlinks(inspection) {
+  const list = Array.isArray(inspection?.externalSymlinks) ? inspection.externalSymlinks : []
+  return list
+    .filter((entry) => isObject(entry) && nonEmpty(entry.path))
+    .map((entry) => ({ path: entry.path, target: nonEmpty(entry.target) ? entry.target : null }))
+}
+
+// The caller's own tree inspection decides the name verdict, so a typed format can only
+// relax the guard when that inspection finished and found no run metadata.
+function inspectionBlock(format, inspection) {
+  const names = classifyEmbeddedNames({ format, names: inspection?.metadataNames })
+  if (inspection && inspection.ok !== true) {
+    return { blocked: true, names, reason: `the containing tree inspection did not finish (${inspection.reason ?? 'no reason given'}), so the format cannot be proven complete` }
+  }
+  if (names.blocking.length) {
+    return { blocked: true, names, reason: `run metadata inside the target is never disposable and a typed format does not change that: ${names.blocking.slice(0, 3).join(', ')}` }
+  }
+  return { blocked: false, names, reason: null }
+}
+
+export function inspectResourceFormat(options = {}) {
+  const requested = options?.format
+  const format = formatId(requested)
+  if (format === 'generic') return verdict({ ok: false, state: 'unproven', reason: genericReason(requested) })
+  if (!nonEmpty(options?.path)) return verdict({ ok: false, state: 'unproven', format, reason: `${format} needs the resource path it must prove` })
+
+  const markerProof = proveMarkers(format, options.path)
+  const inspection = inspectionBlock(format, options?.inspection)
+  const referenceSymlinks = readReferenceSymlinks(options?.inspection)
+  const base = {
+    format,
+    root: markerProof.rootReal ?? markerProof.root,
+    markers: markerProof.markers,
+    embeddedSourceNames: inspection.names.allowed,
+    blockingMetadata: inspection.names.blocking,
+    referenceSymlinks,
+  }
+
+  if (!markerProof.ok) return verdict({ ...base, ok: false, state: markerProof.state, reason: markerProof.reason })
+  if (inspection.blocked) return verdict({ ...base, ok: false, state: 'partial', reason: inspection.reason })
+  const inputs = proveRebuildInputs(format, markerProof.rootReal ?? markerProof.root, options.inputs)
+  if (!inputs.ok) {
+    return verdict({ ...base, ok: false, state: 'inputs-changed', reason: inputs.reason, inputProofs: null })
+  }
+  return verdict({
+    ...base,
+    ok: true,
+    state: 'ready',
+    allowEmbeddedSourceNames: true,
+    allowReferenceSymlinks: true,
+    inputProofs: inputs.proofs,
+  })
+}
+
+export function classifyRebuildState(options = {}) {
+  const requested = options?.format
+  const format = formatId(requested)
+  if (format === 'generic') return { ok: false, state: 'unproven', reason: genericReason(requested), format: 'generic', root: null, markers: [], inputCheck: null }
+  if (!nonEmpty(options?.path)) return { ok: false, state: 'unproven', reason: `${format} needs the resource path it must classify`, format, root: null, markers: [], inputCheck: null }
+
+  const markerProof = proveMarkers(format, options.path)
+  const inspection = inspectionBlock(format, options?.inspection)
+  const result = { format, root: markerProof.rootReal ?? markerProof.root, markers: markerProof.markers, blockingMetadata: inspection.names.blocking, inputCheck: null }
+  if (!markerProof.ok) return { ok: false, state: markerProof.state, reason: markerProof.reason, ...result }
+  if (inspection.blocked) return { ok: false, state: 'partial', reason: inspection.reason, ...result }
+
+  const required = FORMATS[format].inputs
+  const recorded = Array.isArray(options.inputProofs) ? options.inputProofs : []
+  const names = recorded.map((proof) => (isObject(proof) && nonEmpty(proof.name) ? proof.name : null))
+  const namesMatch = names.length === required.length && required.every((name) => names.includes(name))
+  if (!namesMatch) {
+    return {
+      ok: false,
+      state: 'inputs-changed',
+      reason: `the recorded rebuild input proof does not match the canonical ${format} inputs (expected ${required.join(' + ')})`,
+      ...result,
+    }
+  }
+  // Persisted labels are not authority: recheck each actual path's canonical
+  // input name and its location outside the resource before trusting its hash.
+  const fresh = proveRebuildInputs(format, result.root, recorded.map((proof) => proof?.path))
+  if (!fresh.ok) return { ok: false, state: 'inputs-changed', reason: fresh.reason, ...result }
+  const check = validateRebuildInputs(recorded)
+  if (!check.ok) return { ok: false, state: 'inputs-changed', reason: check.reason, ...result, inputCheck: check }
+  return { ok: true, state: 'ready', reason: null, ...result, inputCheck: check }
+}