dsh-math-modeling-agent 0.3.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/distribution-parity.mjs

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto'
+import { lstat, readFile, readdir, realpath } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const MAX_FILES = 10_000
+const MAX_FILE_BYTES = 20 * 1024 * 1024
+const MAX_TOTAL_BYTES = 100 * 1024 * 1024
+const MAX_DEPTH = 32
+
+function normalizeRelative(path) {
+  return path.split(sep).join('/')
+}
+
+function assertInside(root, path) {
+  const relativePath = relative(root, path)
+  if (isAbsolute(relativePath) || relativePath === '..' || relativePath.startsWith('..' + sep)) {
+    throw new Error('distribution entry escapes package root: ' + path)
+  }
+}
+
+async function collectFiles(root, entries, { allowMissing = false } = {}) {
+  const realRoot = await realpath(root)
+  const files = new Map()
+  let totalBytes = 0
+
+  const visit = async (path, depth) => {
+    if (depth > MAX_DEPTH) throw new Error('distribution tree exceeds maximum depth: ' + path)
+    let information
+    try {
+      information = await lstat(path)
+    } catch (error) {
+      if (allowMissing && error?.code === 'ENOENT') return
+      throw error
+    }
+    if (information.isSymbolicLink()) throw new Error('symbolic link is not allowed in distribution: ' + path)
+    const realPath = await realpath(path)
+    assertInside(realRoot, realPath)
+    if (information.isDirectory()) {
+      for (const entry of await readdir(path)) await visit(join(path, entry), depth + 1)
+      return
+    }
+    if (!information.isFile()) return
+    if (information.size > MAX_FILE_BYTES) throw new Error('distribution file exceeds maximum size: ' + path)
+    totalBytes += information.size
+    if (totalBytes > MAX_TOTAL_BYTES) throw new Error('distribution tree exceeds maximum size')
+    if (files.size >= MAX_FILES) throw new Error('distribution tree exceeds maximum file count')
+    const relativePath = normalizeRelative(relative(root, path))
+    const digest = createHash('sha256').update(await readFile(path)).digest('hex')
+    files.set(relativePath, digest)
+  }
+
+  for (const entry of entries) {
+    if (typeof entry !== 'string' || !entry.trim()) throw new Error('package files entries must be non-empty strings')
+    const path = resolve(root, entry)
+    assertInside(root, path)
+    await visit(path, 0)
+  }
+  return files
+}
+
+/** Compare the allowlisted package files of a source and distribution root. */
+export async function compareDistribution(sourceRoot, candidateRoot) {
+  const source = resolve(sourceRoot)
+  const candidate = resolve(candidateRoot)
+  const manifest = JSON.parse(await readFile(join(source, 'package.json'), 'utf8'))
+  if (!Array.isArray(manifest.files) || manifest.files.length === 0) {
+    throw new Error('source package.json must declare a non-empty files allowlist')
+  }
+  const entries = [...new Set(['package.json', ...manifest.files])]
+  const expected = await collectFiles(source, entries)
+  const actual = await collectFiles(candidate, entries, { allowMissing: true })
+  const missing = [...expected.keys()].filter(path => !actual.has(path)).sort()
+  const extra = [...actual.keys()].filter(path => !expected.has(path)).sort()
+  const mismatched = [...expected.keys()]
+    .filter(path => actual.has(path) && actual.get(path) !== expected.get(path))
+    .sort()
+  const metadataMismatches = []
+  try {
+    const candidateManifest = JSON.parse(await readFile(join(candidate, 'package.json'), 'utf8'))
+    for (const key of ['name', 'version']) {
+      if (candidateManifest[key] !== manifest[key]) {
+        metadataMismatches.push(`${key}: expected ${manifest[key]}, received ${candidateManifest[key]}`)
+      }
+    }
+  } catch (error) {
+    metadataMismatches.push('package.json: ' + (error instanceof Error ? error.message : String(error)))
+  }
+  return {
+    ok: missing.length === 0 && extra.length === 0 && mismatched.length === 0 && metadataMismatches.length === 0,
+    sourceRoot: source,
+    candidateRoot: candidate,
+    expectedFileCount: expected.size,
+    candidateFileCount: actual.size,
+    missing,
+    extra,
+    mismatched,
+    metadataMismatches,
+  }
+}
+
+function parseArguments(argv) {
+  if (argv.length !== 2 || argv.some(value => !value || value.startsWith('-'))) {
+    throw new Error('usage: node distribution-parity.mjs <source-root> <candidate-root>')
+  }
+  return { sourceRoot: argv[0], candidateRoot: argv[1] }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  try {
+    const { sourceRoot, candidateRoot } = parseArguments(argv)
+    const result = await compareDistribution(sourceRoot, candidateRoot)
+    console.log(JSON.stringify(result, null, 2))
+    return result.ok ? 0 : 1
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 2
+  }
+}
+
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  process.exitCode = await main()
+}

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 }
+}