dsh-math-modeling-agent 0.4.1 → 0.5.0

package/skills/math-modeling-agent/scripts/correction-lineage.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto'
+import { cp, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join, basename } from 'node:path'
+
+function hashText(text) { return createHash('sha256').update(text, 'utf8').digest('hex') }
+function clone(value) { return JSON.parse(JSON.stringify(value)) }
+function list(value) { return Array.isArray(value) ? value.filter(item => typeof item === 'string' && item.trim()) : [] }
+
+async function readRun(root) { return JSON.parse(await readFile(join(root, 'run.json'), 'utf8')) }
+async function readLedger(root) { return JSON.parse(await readFile(join(root, 'ledger.json'), 'utf8')) }
+
+export async function applyFindingToLineage(lineageRoot, finding) {
+  const ledgerPath = join(lineageRoot, 'ledger.json')
+  const ledger = await readLedger(lineageRoot)
+  const reason = typeof finding.reason === 'string' && finding.reason.trim() ? finding.reason : 'evaluation finding requires correction'
+  const sourceIds = [finding.id].filter(Boolean)
+  const claimIds = list(finding.affectedClaims)
+  const obligationIds = list(finding.affectedObligations)
+  for (const claim of ledger.claims ?? []) {
+    if (claimIds.includes(claim.id)) {
+      claim.stale = true
+      claim.verdict = 'STALE'
+      claim.staleReason = reason
+      claim.staleSourceIds = sourceIds
+    }
+  }
+  for (const obligation of ledger.obligations ?? []) {
+    if (obligationIds.includes(obligation.id) || claimIds.includes(obligation.claimId)) {
+      obligation.status = 'STALE'
+      obligation.stale = true
+      obligation.staleReason = reason
+      obligation.staleSourceIds = sourceIds
+    }
+  }
+  await writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + '\n', 'utf8')
+  return ledger
+}
+
+export async function createCorrectionLineage(parentRunRoot, finding) {
+  if (!finding || typeof finding.id !== 'string' || !finding.id.trim()) throw new TypeError('finding.id is required')
+  const parentRun = await readRun(parentRunRoot)
+  const parentLedgerText = await readFile(join(parentRunRoot, 'ledger.json'), 'utf8')
+  const parentArtifactHash = hashText(JSON.stringify(parentRun) + '\n' + parentLedgerText)
+  const revision = (Number.isInteger(parentRun.revision) ? parentRun.revision : 0) + 1
+  const childRunRoot = await (async () => {
+    const { mkdtemp } = await import('node:fs/promises')
+    return mkdtemp(join(dirname(parentRunRoot), basename(parentRunRoot) + '-correction-'))
+  })()
+  await cp(parentRunRoot, childRunRoot, { recursive: true, filter: source => !source.endsWith('.run-state.lock') && !source.endsWith('.run-state.reclaim') })
+  const childRun = clone(parentRun)
+  childRun.schemaVersion = 3
+  childRun.lineageId = (parentRun.lineageId ?? parentRun.taskId) + '-correction-' + revision
+  childRun.parentRunId = parentRun.lineageId ?? parentRun.taskId
+  childRun.revision = revision
+  childRun.status = 'CORRECTION_REQUIRED'
+  childRun.updatedAt = new Date().toISOString()
+  await writeFile(join(childRunRoot, 'run.json'), JSON.stringify(childRun, null, 2) + '\n', 'utf8')
+  await applyFindingToLineage(childRunRoot, finding)
+  const lineage = { schemaVersion: 1, parentRunId: childRun.parentRunId, parentArtifactHash, findingIds: [finding.id], revision, status: 'CORRECTION_REQUIRED', childRunId: childRun.lineageId }
+  await writeFile(join(childRunRoot, 'lineage.json'), JSON.stringify(lineage, null, 2) + '\n', 'utf8')
+  return { childRunRoot, parentRunId: childRun.parentRunId, parentArtifactHash, revision, status: childRun.status, lineage }
+}
+
+export async function applyEvaluationFinding(parentRunRoot, finding) {
+  return createCorrectionLineage(parentRunRoot, finding)
+}
+
+export async function markSuperseded(parentRunRoot, childRunRoot) {
+  const childRun = await readRun(childRunRoot)
+  const lineagePath = join(childRunRoot, 'lineage.json')
+  let lineage
+  try { lineage = JSON.parse(await readFile(lineagePath, 'utf8')) } catch (error) { if (error.code !== 'ENOENT') throw error; lineage = { schemaVersion: 1, parentRunId: childRun.parentRunId ?? childRun.taskId, revision: childRun.revision ?? 1 } }
+  lineage.supersedes = parentRunRoot
+  lineage.status = 'SUPERSEDES_PARENT'
+  await writeFile(lineagePath, JSON.stringify(lineage, null, 2) + '\n', 'utf8')
+  return lineage
+}

package/skills/math-modeling-agent/scripts/evidence-store.mjs

@@ -0,0 +1,349 @@
+const EVIDENCE_REQUIRED_FIELDS = [
+  'id',
+  'kind',
+  'coveredClaimIds',
+  'coveredObligationIds',
+  'artifactPath',
+  'inputHashes',
+  'outputHashes',
+  'command',
+  'workdir',
+  'environment',
+  'exitCode',
+  'methodFamily',
+  'codeHash',
+  'level',
+  'limitations',
+]
+
+const EVIDENCE_STRING_FIELDS = [
+  'id',
+  'kind',
+  'artifactPath',
+  'command',
+  'workdir',
+  'methodFamily',
+  'codeHash',
+]
+
+const EVIDENCE_ARRAY_FIELDS = [
+  'coveredClaimIds',
+  'coveredObligationIds',
+  'limitations',
+]
+
+const EVIDENCE_NON_EMPTY_ARRAY_FIELDS = new Set([
+  'coveredClaimIds',
+  'coveredObligationIds',
+])
+
+const EVIDENCE_OBJECT_FIELDS = [
+  'inputHashes',
+  'outputHashes',
+  'environment',
+]
+
+const EVIDENCE_NON_EMPTY_OBJECT_FIELDS = new Set(EVIDENCE_OBJECT_FIELDS)
+
+const EVIDENCE_LEVELS = new Set([
+  'DERIVED',
+  'EXECUTED',
+  'VERIFIED',
+  'INDEPENDENTLY_VERIFIED',
+  'EXTERNALLY_VALIDATED',
+  'LEGACY_UNVERIFIED',
+])
+
+const VERIFICATION_REQUIRED_FIELDS = [
+  'id',
+  'recipeId',
+  'evidenceIds',
+  'verdict',
+  'independenceKey',
+]
+const VERIFICATION_ALLOWED_FIELDS = new Set([...VERIFICATION_REQUIRED_FIELDS, 'derivedFrom'])
+const VERIFICATION_VERDICTS = new Set(['PASS', 'FAIL', 'INCONCLUSIVE', 'NOT_RUN'])
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}
+
+function result(errors) {
+  return { valid: errors.length === 0, errors }
+}
+
+function addRequiredErrors(value, fields, errors) {
+  for (const field of fields) {
+    if (!hasOwn(value, field)) {
+      errors.push(field + ' is required')
+    }
+  }
+}
+
+function addUnknownFieldErrors(value, allowedFields, errors) {
+  for (const field of Object.keys(value)) {
+    if (!allowedFields.has(field)) {
+      errors.push('unknown top-level field: ' + field)
+    }
+  }
+}
+
+function addNonEmptyStringErrors(value, fields, errors) {
+  for (const field of fields) {
+    if (hasOwn(value, field) && (typeof value[field] !== 'string' || value[field].trim() === '')) {
+      errors.push(field + ' must be a nonempty string')
+    }
+  }
+}
+
+function addStringArrayErrors(value, fields, errors) {
+  for (const field of fields) {
+    if (!hasOwn(value, field)) continue
+    const current = value[field]
+    if (!Array.isArray(current)) {
+      errors.push(field + ' must be an array of strings')
+      continue
+    }
+    if (EVIDENCE_NON_EMPTY_ARRAY_FIELDS.has(field) && current.length === 0) {
+      errors.push(field + ' must not be empty')
+    }
+    if (current.some(item => typeof item !== 'string' || item.trim() === '')) {
+      errors.push(field + ' must contain only nonempty strings')
+    }
+  }
+}
+
+function addObjectErrors(value, fields, errors) {
+  for (const field of fields) {
+    if (hasOwn(value, field) && !isRecord(value[field])) {
+      errors.push(field + ' must be an object')
+    }
+  }
+}
+
+function addHashMapErrors(value, fields, errors) {
+  for (const field of fields) {
+    if (!hasOwn(value, field) || !isRecord(value[field])) continue
+    if (EVIDENCE_NON_EMPTY_OBJECT_FIELDS.has(field) && Object.keys(value[field]).length === 0) {
+      errors.push(field + ' must not be empty')
+    }
+    for (const [key, hash] of Object.entries(value[field])) {
+      if (typeof hash !== 'string' || hash.trim() === '') {
+        errors.push(field + '.' + key + ' must be a nonempty string')
+      }
+    }
+  }
+}
+
+function normalizeMarker(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ')
+}
+
+function isNonIndependentMarker(value) {
+  if (typeof value !== 'string' || value.trim() === '') return false
+  const marker = normalizeMarker(value)
+  return (
+    marker.includes('solver summary') ||
+    marker.includes('same summary') ||
+    marker.includes('deterministic result') ||
+    marker.includes('same result') ||
+    marker.includes('reprint')
+  )
+}
+
+function stringsIn(value) {
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.flatMap(stringsIn)
+  if (isRecord(value)) return Object.values(value).flatMap(stringsIn)
+  return []
+}
+
+function addIndependenceErrors(value, field, errors) {
+  if (!hasOwn(value, field)) return
+  if (stringsIn(value[field]).some(isNonIndependentMarker)) {
+    errors.push(field + ' must identify an independent check, not a solver summary, deterministic result, or reprint-only check')
+  }
+}
+
+export function validateEvidence(value) {
+  const errors = []
+  if (!isRecord(value)) return result(['evidence must be an object'])
+
+  addRequiredErrors(value, EVIDENCE_REQUIRED_FIELDS, errors)
+  addUnknownFieldErrors(value, new Set(EVIDENCE_REQUIRED_FIELDS), errors)
+  addNonEmptyStringErrors(value, EVIDENCE_STRING_FIELDS, errors)
+  addStringArrayErrors(value, EVIDENCE_ARRAY_FIELDS, errors)
+  addObjectErrors(value, EVIDENCE_OBJECT_FIELDS, errors)
+  addHashMapErrors(value, ['inputHashes', 'outputHashes'], errors)
+  if (hasOwn(value, 'environment') && isRecord(value.environment) && Object.keys(value.environment).length === 0) {
+    errors.push('environment must not be empty')
+  }
+
+  if (hasOwn(value, 'exitCode') && !Number.isInteger(value.exitCode)) {
+    errors.push('exitCode must be an integer')
+  }
+  if (hasOwn(value, 'level') && !EVIDENCE_LEVELS.has(value.level)) {
+    errors.push('level must be one of ' + [...EVIDENCE_LEVELS].join(', '))
+  }
+
+  return result(errors)
+}
+
+export function validateVerification(value) {
+  const errors = []
+  if (!isRecord(value)) return result(['verification must be an object'])
+
+  addRequiredErrors(value, VERIFICATION_REQUIRED_FIELDS, errors)
+  addUnknownFieldErrors(value, VERIFICATION_ALLOWED_FIELDS, errors)
+  addNonEmptyStringErrors(value, ['id', 'recipeId', 'independenceKey'], errors)
+  addStringArrayErrors(value, ['evidenceIds'], errors)
+
+  if (hasOwn(value, 'evidenceIds') && Array.isArray(value.evidenceIds) && value.evidenceIds.length === 0) {
+    errors.push('evidenceIds must not be empty')
+  }
+  if (hasOwn(value, 'verdict') && !VERIFICATION_VERDICTS.has(value.verdict)) {
+    errors.push('verdict must be one of ' + [...VERIFICATION_VERDICTS].join(', '))
+  }
+
+  if (hasOwn(value, 'derivedFrom')) {
+    const derivedFrom = value.derivedFrom
+    const validDerivedFrom =
+      (typeof derivedFrom === 'string' && derivedFrom.trim() !== '') ||
+      (Array.isArray(derivedFrom) && derivedFrom.length > 0 && derivedFrom.every(item => typeof item === 'string' && item.trim() !== ''))
+    if (!validDerivedFrom) {
+      errors.push('derivedFrom must be a nonempty string or string array')
+    }
+  }
+
+  addIndependenceErrors(value, 'independenceKey', errors)
+  addIndependenceErrors(value, 'derivedFrom', errors)
+  return result(errors)
+}
+
+function graphRecord(value, label) {
+  if (!isRecord(value)) throw new TypeError(label + ' must be an object')
+  if (typeof value.id !== 'string' || value.id.trim() === '') throw new TypeError(label + '.id must be a nonempty string')
+  return value
+}
+
+function graphCollection(graph, name) {
+  if (!isRecord(graph) || !Array.isArray(graph[name])) throw new TypeError('graph.' + name + ' must be an array')
+  return graph[name]
+}
+
+function assertUnique(collection, id, label) {
+  if (collection.some(item => item?.id === id)) throw new TypeError('duplicate ' + label + ' id: ' + id)
+}
+
+function assertKnown(collection, id, label) {
+  if (!collection.some(item => item?.id === id)) throw new TypeError('unknown ' + label + ' id: ' + id)
+}
+
+function assertStringIds(value, field) {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.length === 0 || value.some(item => typeof item !== 'string' || item.trim() === '')) throw new TypeError(field + ' must be a nonempty string array')
+  return value
+}
+
+export function createGraph(taskId) {
+  if (typeof taskId !== 'string' || taskId.trim() === '') throw new TypeError('taskId must be a nonempty string')
+  return {
+    schemaVersion: 3,
+    taskId,
+    scope: { independentAuditPassed: false, interactions: [], decisionStack: [], robustnessExempt: false },
+    requirements: [],
+    assumptions: [],
+    claims: [],
+    obligations: [],
+    subproblems: [],
+    candidates: [],
+    issues: [],
+    evidence: [],
+    verifications: [],
+    failures: [],
+  }
+}
+
+export function addRequirement(graph, value) {
+  const item = graphRecord(value, 'requirement')
+  const requirements = graphCollection(graph, 'requirements')
+  assertUnique(requirements, item.id, 'requirement')
+  requirements.push(item)
+  return item.id
+}
+
+export function addClaim(graph, value) {
+  const item = graphRecord(value, 'claim')
+  const claims = graphCollection(graph, 'claims')
+  assertUnique(claims, item.id, 'claim')
+  const requirementIds = value.requirementIds ?? []
+  if (!Array.isArray(requirementIds) || requirementIds.some(id => typeof id !== 'string' || id.trim() === '')) throw new TypeError('claim.requirementIds must be a string array')
+  for (const id of requirementIds) assertKnown(graphCollection(graph, 'requirements'), id, 'requirement')
+  item.requirementIds = requirementIds
+  item.obligationIds = value.obligationIds ?? []
+  item.evidenceIds = value.evidenceIds ?? []
+  claims.push(item)
+  return item.id
+}
+
+export function addObligation(graph, value) {
+  const item = graphRecord(value, 'obligation')
+  const obligations = graphCollection(graph, 'obligations')
+  assertUnique(obligations, item.id, 'obligation')
+  assertKnown(graphCollection(graph, 'claims'), item.claimId, 'claim')
+  item.evidenceIds = value.evidenceIds ?? []
+  obligations.push(item)
+  return item.id
+}
+
+export function addEvidence(graph, value) {
+  const item = graphRecord(value, 'evidence')
+  const validation = validateEvidence(item)
+  if (!validation.valid) throw new TypeError(validation.errors.join('; '))
+  const evidence = graphCollection(graph, 'evidence')
+  assertUnique(evidence, item.id, 'evidence')
+  for (const id of item.coveredClaimIds) assertKnown(graphCollection(graph, 'claims'), id, 'claim')
+  for (const id of item.coveredObligationIds) assertKnown(graphCollection(graph, 'obligations'), id, 'obligation')
+  evidence.push(item)
+  for (const claim of graphCollection(graph, 'claims')) {
+    if (item.coveredClaimIds.includes(claim.id) && !claim.evidenceIds.includes(item.id)) claim.evidenceIds.push(item.id)
+  }
+  for (const obligation of graphCollection(graph, 'obligations')) {
+    if (item.coveredObligationIds.includes(obligation.id) && !obligation.evidenceIds.includes(item.id)) obligation.evidenceIds.push(item.id)
+  }
+  return item.id
+}
+
+export function markStale(graph, id, { staleReason, staleSourceIds } = {}) {
+  if (typeof staleReason !== 'string' || staleReason.trim() === '') throw new TypeError('staleReason is required')
+  const sourceIds = assertStringIds(staleSourceIds, 'staleSourceIds')
+  const claims = graphCollection(graph, 'claims')
+  const obligations = graphCollection(graph, 'obligations')
+  const claim = claims.find(item => item?.id === id)
+  const obligation = obligations.find(item => item?.id === id)
+  if (!claim && !obligation) throw new TypeError('unknown claim or obligation id: ' + id)
+  const mark = item => {
+    item.stale = true
+    item.staleReason = staleReason
+    item.staleSourceIds = [...sourceIds]
+  }
+  if (claim) {
+    mark(claim)
+    claim.verdict = 'STALE'
+    for (const item of obligations.filter(entry => entry?.claimId === id)) { mark(item); item.status = 'STALE' }
+  } else {
+    mark(obligation)
+    obligation.status = 'STALE'
+    const owner = claims.find(item => item?.id === obligation.claimId)
+    if (owner) { mark(owner); owner.verdict = 'STALE' }
+  }
+  return id
+}

package/skills/math-modeling-agent/scripts/failure-insights.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const REQUIRED_FIELDS = [
+  'failureId', 'stage', 'subproblem', 'attempt', 'rootCause', 'candidateId', 'assumptionIds', 'symptom',
+  'minimalReproduction', 'command', 'inputHashes', 'codeHash', 'exitCode', 'affectedClaims', 'affectedObligations',
+  'whatWasRuledOut', 'scientificInsight', 'recovery', 'status', 'evidenceIds',
+]
+const ROOT_CAUSES = new Set(['DATA', 'TOOL', 'MODEL', 'ASSUMPTION', 'ANALYSIS', 'VALIDATION', 'EVIDENCE', 'RESEARCH_GAP'])
+const SCIENTIFIC_FAILURES = new Set(['MODEL', 'ASSUMPTION', 'ANALYSIS', 'VALIDATION', 'EVIDENCE'])
+
+function nonempty(value) { return typeof value === 'string' && value.trim() !== '' }
+function stringArray(value, allowEmpty = true) { return Array.isArray(value) && (allowEmpty || value.length > 0) && value.every(item => nonempty(item)) }
+
+export function validateFailure(value) {
+  const errors = []
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { valid: false, errors: ['failure must be an object'] }
+  for (const field of REQUIRED_FIELDS) if (!Object.hasOwn(value, field)) errors.push(field + ' is required')
+  for (const field of ['failureId', 'stage', 'subproblem', 'candidateId', 'symptom', 'minimalReproduction', 'command', 'codeHash', 'scientificInsight', 'recovery']) if (Object.hasOwn(value, field) && !nonempty(value[field])) errors.push(field + ' must be nonempty')
+  if (Object.hasOwn(value, 'attempt') && (!Number.isInteger(value.attempt) || value.attempt < 1)) errors.push('attempt must be a positive integer')
+  if (Object.hasOwn(value, 'rootCause') && !ROOT_CAUSES.has(value.rootCause)) errors.push('rootCause is invalid')
+  for (const field of ['assumptionIds', 'affectedClaims', 'affectedObligations', 'evidenceIds']) if (Object.hasOwn(value, field) && !stringArray(value[field])) errors.push(field + ' must be an array of strings')
+  if (Object.hasOwn(value, 'whatWasRuledOut') && !stringArray(value.whatWasRuledOut, false) && SCIENTIFIC_FAILURES.has(value.rootCause)) errors.push('whatWasRuledOut must be a nonempty string array')
+  if (Object.hasOwn(value, 'inputHashes') && (!value.inputHashes || typeof value.inputHashes !== 'object' || Array.isArray(value.inputHashes) || Object.keys(value.inputHashes).length === 0)) errors.push('inputHashes must be a nonempty object')
+  if (Object.hasOwn(value, 'exitCode') && !Number.isInteger(value.exitCode)) errors.push('exitCode must be an integer')
+  if (Object.hasOwn(value, 'status') && !['OPEN', 'RECOVERED', 'ABANDONED', 'STALE'].includes(value.status)) errors.push('status is invalid')
+  if (SCIENTIFIC_FAILURES.has(value.rootCause)) {
+    if (!stringArray(value.whatWasRuledOut, false)) errors.push('scientific failure requires whatWasRuledOut')
+    if (!nonempty(value.scientificInsight)) errors.push('scientific failure requires scientificInsight')
+  }
+  return { valid: errors.length === 0, errors: [...new Set(errors)] }
+}
+
+export async function appendFailure(runRoot, failure) {
+  const result = validateFailure(failure)
+  if (!result.valid) throw new TypeError(result.errors.join('; '))
+  const path = join(runRoot, 'failed', 'failures.jsonl')
+  await mkdir(join(runRoot, 'failed'), { recursive: true })
+  await appendFile(path, JSON.stringify(failure) + '\n', 'utf8')
+  return { path, failureId: failure.failureId }
+}
+
+export function renderFailureInsight(failure) {
+  const ruledOut = (failure.whatWasRuledOut ?? []).map(value => '- ' + value).join('\n') || '- 未记录'
+  return [
+    '## ' + failure.failureId,
+    '',
+    '- 环节：' + failure.stage + '；子问题：' + failure.subproblem + '；attempt：' + failure.attempt,
+    '- 根因：' + failure.rootCause,
+    '- 症状：' + failure.symptom,
+    '',
+    '### 最小复现',
+    failure.minimalReproduction,
+    '',
+    '### 已排除',
+    ruledOut,
+    '',
+    '### 科学启发',
+    failure.scientificInsight,
+    '',
+    '### 修正与恢复',
+    failure.recovery,
+    '',
+    '下游影响：claims=' + (failure.affectedClaims ?? []).join(', ') + '; obligations=' + (failure.affectedObligations ?? []).join(', ') + '.',
+    '证据：' + (failure.evidenceIds ?? []).join(', ') + '.',
+  ].join('\n')
+}
+
+export async function buildFailureInsights(runRoot) {
+  const path = join(runRoot, 'failed', 'failures.jsonl')
+  let text = ''
+  try { text = await readFile(path, 'utf8') } catch (error) { if (error.code !== 'ENOENT') throw error }
+  const failures = text.trim() ? text.trim().split('\n').map(JSON.parse) : []
+  const output = failures.length ? '# Failure Insights\n\n' + failures.map(renderFailureInsight).join('\n\n') + '\n' : '# Failure Insights\n\nNo structured failures recorded.\n'
+  const outputPath = join(runRoot, 'failure-insights.md')
+  await writeFile(outputPath, output, 'utf8')
+  return { count: failures.length, path: outputPath }
+}

package/skills/math-modeling-agent/scripts/input-snapshot.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto'
+import { chmod, copyFile, lstat, mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+
+const MANIFEST_PATH = ['inputs', 'manifest.json']
+
+function hashBytes(bytes) {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+function isContained(root, target) {
+  const value = relative(root, target)
+  return value === '' || (!value.startsWith('..' + sep) && value !== '..' && !isAbsolute(value))
+}
+
+function assertRelativePath(value) {
+  if (typeof value !== 'string' || value.trim() === '' || isAbsolute(value)) throw new TypeError('input path must be a nonempty relative path')
+  const normalized = value.replaceAll('\\', '/')
+  if (normalized.split('/').some(part => part === '..')) throw new TypeError('input path must remain contained')
+  return normalized
+}
+
+function aggregateHash(files) {
+  const material = files
+    .slice()
+    .sort((left, right) => left.relativePath.localeCompare(right.relativePath))
+    .map(file => file.relativePath + '\0' + file.snapshotHash)
+    .join('\n')
+  return hashBytes(Buffer.from(material, 'utf8'))
+}
+
+async function readManifest(runRoot) {
+  const path = resolve(runRoot, ...MANIFEST_PATH)
+  return { path, manifest: JSON.parse(await readFile(path, 'utf8')) }
+}
+
+export async function snapshotInputs(sourceRoot, runRoot, relativeFiles) {
+  if (!Array.isArray(relativeFiles) || relativeFiles.length === 0) throw new TypeError('relativeFiles must be a nonempty array')
+  const sourceBase = resolve(sourceRoot)
+  const runBase = resolve(runRoot)
+  const files = []
+  for (const input of relativeFiles) {
+    const relativePath = assertRelativePath(input)
+    const sourcePath = resolve(sourceBase, relativePath)
+    const snapshotPath = resolve(runBase, 'inputs', 'raw', relativePath)
+    if (!isContained(sourceBase, sourcePath) || !isContained(resolve(runBase, 'inputs', 'raw'), snapshotPath)) throw new TypeError('input path must remain contained')
+    const info = await lstat(sourcePath)
+    if (!info.isFile() || info.isSymbolicLink()) throw new TypeError('input must be a regular file: ' + relativePath)
+    const bytes = await readFile(sourcePath)
+    await mkdir(dirname(snapshotPath), { recursive: true })
+    await copyFile(sourcePath, snapshotPath)
+    await chmod(snapshotPath, 0o444)
+    const sourceHash = hashBytes(bytes)
+    const snapshotHash = hashBytes(await readFile(snapshotPath))
+    files.push({ relativePath, sourcePath, snapshotPath: relative(runBase, snapshotPath).replaceAll('\\', '/'), sourceHash, snapshotHash, bytes: bytes.length, readOnly: true })
+  }
+  const manifest = { schemaVersion: 1, sourceRoot: sourceBase, createdAt: new Date().toISOString(), files, inputSnapshotHash: aggregateHash(files) }
+  const manifestPath = resolve(runBase, ...MANIFEST_PATH)
+  await mkdir(dirname(manifestPath), { recursive: true })
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8')
+  return manifest
+}
+
+export async function verifySnapshot(runRoot) {
+  const { manifest } = await readManifest(runRoot)
+  const runBase = resolve(runRoot)
+  let snapshotChanged = false
+  let sourceChanged = false
+  let sourceUnknown = false
+  const files = []
+  for (const file of manifest.files) {
+    const snapshotPath = resolve(runBase, file.snapshotPath)
+    let snapshotHash = null
+    try { snapshotHash = hashBytes(await readFile(snapshotPath)) } catch (error) { if (error.code !== 'ENOENT') throw error }
+    const snapshotMismatch = snapshotHash !== file.snapshotHash
+    snapshotChanged ||= snapshotMismatch
+    let currentSourceHash = null
+    try { currentSourceHash = hashBytes(await readFile(file.sourcePath)) } catch (error) { if (error.code === 'ENOENT') sourceUnknown = true; else throw error }
+    const sourceMismatch = currentSourceHash !== null && currentSourceHash !== file.sourceHash
+    sourceChanged ||= sourceMismatch
+    files.push({ ...file, currentSnapshotHash: snapshotHash, currentSourceHash, snapshotMismatch, sourceMismatch })
+  }
+  const aggregate = aggregateHash(files.map(file => ({ relativePath: file.relativePath, snapshotHash: file.currentSnapshotHash ?? '' })))
+  const aggregateMismatch = aggregate !== manifest.inputSnapshotHash
+  return { valid: !snapshotChanged && !aggregateMismatch, snapshotChanged, sourceChanged, sourceUnknown, aggregateMismatch, files }
+}
+
+export async function assertSnapshotReadOnly(runRoot) {
+  const result = await verifySnapshot(runRoot)
+  const writable = []
+  for (const file of result.files) {
+    const path = resolve(runRoot, file.snapshotPath)
+    const info = await stat(path)
+    if (!file.readOnly || (info.mode & 0o200) !== 0) writable.push(file.relativePath)
+  }
+  return { valid: result.valid && writable.length === 0, writable, snapshot: result }
+}