dsh-math-modeling-agent 0.3.1 → 0.5.0

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

package/skills/math-modeling-agent/scripts/ledger-mutation.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { createHash, randomUUID } from 'node:crypto'
+import { appendFile, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import {
+  addClaim,
+  addEvidence,
+  addObligation,
+  addRequirement,
+  markStale,
+} from './evidence-store.mjs'
+
+function hashText(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value))
+}
+
+async function atomicWrite(path, text) {
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = path + '.tmp-' + process.pid + '-' + randomUUID()
+  await writeFile(temporary, text, 'utf8')
+  try {
+    await rename(temporary, path)
+  } finally {
+    await unlink(temporary).catch(error => {
+      if (error.code !== 'ENOENT') throw error
+    })
+  }
+}
+
+function mutationTarget(mutation) {
+  return typeof mutation.id === 'string' && mutation.id.trim() !== '' ? mutation.id : null
+}
+
+function applyMutation(ledger, mutation) {
+  if (!mutation || typeof mutation !== 'object' || Array.isArray(mutation)) throw new TypeError('mutation must be an object')
+  if (mutation.type === 'RUN_STATUS' || mutation.path === 'run.json') throw new TypeError('ledger mutation cannot write run.json')
+  switch (mutation.type) {
+    case 'ADD_REQUIREMENT': addRequirement(ledger, mutation.value); return mutation.value.id
+    case 'ADD_CLAIM': addClaim(ledger, mutation.value); return mutation.value.id
+    case 'ADD_OBLIGATION': addObligation(ledger, mutation.value); return mutation.value.id
+    case 'ADD_EVIDENCE': addEvidence(ledger, mutation.value); return mutation.value.id
+    case 'CLAIM_STALE':
+      markStale(ledger, mutation.id, { staleReason: mutation.staleReason, staleSourceIds: mutation.staleSourceIds })
+      return mutation.id
+    case 'OBLIGATION_STALE':
+      markStale(ledger, mutation.id, { staleReason: mutation.staleReason, staleSourceIds: mutation.staleSourceIds })
+      return mutation.id
+    default: throw new TypeError('unsupported ledger mutation type: ' + String(mutation.type))
+  }
+}
+
+export async function mutateLedger(root, mutation) {
+  if (typeof root !== 'string' || root.trim() === '') throw new TypeError('root must be a nonempty string')
+  const ledgerPath = join(root, 'ledger.json')
+  const journalPath = join(root, 'ledger-mutations.jsonl')
+  const beforeText = await readFile(ledgerPath, 'utf8')
+  const ledger = JSON.parse(beforeText)
+  const next = clone(ledger)
+  const targetId = applyMutation(next, mutation)
+  const afterText = JSON.stringify(next, null, 2) + '\n'
+  const journal = {
+    mutationId: randomUUID(),
+    type: mutation.type,
+    targetId: targetId ?? mutationTarget(mutation),
+    beforeHash: hashText(beforeText),
+    afterHash: hashText(afterText),
+    timestamp: new Date().toISOString(),
+  }
+  await atomicWrite(ledgerPath, afterText)
+  try {
+    await appendFile(journalPath, JSON.stringify(journal) + '\n', 'utf8')
+  } catch (error) {
+    await atomicWrite(ledgerPath, beforeText)
+    throw error
+  }
+  return { ledger: next, journal }
+}

package/skills/math-modeling-agent/scripts/migration-v3.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { cp, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+function clone(value) { return JSON.parse(JSON.stringify(value)) }
+function legacyEvidence(value) {
+  if (typeof value === 'string') return { id: value, level: 'LEGACY_UNVERIFIED', source: value, limitations: ['Migrated from legacy string evidence; artifact not independently verified.'] }
+  return { ...clone(value), level: 'LEGACY_UNVERIFIED', limitations: [...(value.limitations ?? []), 'Migrated from a v2 run; verification must be rerun.'] }
+}
+
+export async function migrateV2(sourceRoot, destinationRoot) {
+  await mkdir(destinationRoot, { recursive: true })
+  await cp(sourceRoot, destinationRoot, { recursive: true })
+  const run = JSON.parse(await readFile(join(sourceRoot, 'run.json'), 'utf8'))
+  const oldLedger = JSON.parse(await readFile(join(sourceRoot, 'ledger.json'), 'utf8'))
+  const ledger = {
+    ...oldLedger,
+    schemaVersion: 3,
+    requirements: oldLedger.requirements ?? [],
+    evidence: (oldLedger.evidence ?? []).map(legacyEvidence),
+    verifications: oldLedger.verifications ?? [],
+    failures: oldLedger.failures ?? [],
+    claims: (oldLedger.claims ?? []).map(claim => ({ ...claim, verdict: 'INCONCLUSIVE', stale: claim.stale ?? false, staleReason: claim.staleReason ?? null, staleSourceIds: claim.staleSourceIds ?? [] })),
+  }
+  const migratedRun = { ...run, schemaVersion: 3, lineageId: run.lineageId ?? run.taskId, parentRunId: run.parentRunId ?? null, revision: run.revision ?? 0, inputSnapshotHash: run.inputSnapshotHash ?? null, evidenceGraphHash: run.evidenceGraphHash ?? null }
+  await writeFile(join(destinationRoot, 'run.json'), JSON.stringify(migratedRun, null, 2) + '\n', 'utf8')
+  await writeFile(join(destinationRoot, 'ledger.json'), JSON.stringify(ledger, null, 2) + '\n', 'utf8')
+  const migration = { schemaVersion: 1, sourceSchemaVersion: run.schemaVersion, destinationSchemaVersion: 3, mintedEvidence: 0, downgradedEvidence: ledger.evidence.length, claimsDowngraded: ledger.claims.length, sourceRoot, destinationRoot }
+  await writeFile(join(destinationRoot, 'migration-v3.json'), JSON.stringify(migration, null, 2) + '\n', 'utf8')
+  return { run: migratedRun, ledger, migration }
+}

package/skills/math-modeling-agent/scripts/output-integrity.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+function decimalPlaces(numberFormat) {
+  if (typeof numberFormat !== 'string') return null
+  const match = numberFormat.match(/\.([0#]+)/)
+  return match ? match[1].length : 0
+}
+
+export function quantize(value, decimals, roundingMode = 'decimal-half-up') {
+  if (!Number.isFinite(value) || !Number.isInteger(decimals) || decimals < 0 || roundingMode !== 'decimal-half-up') throw new TypeError('quantize requires a finite value, nonnegative integer decimals, and decimal-half-up')
+  const scale = 10 ** decimals
+  const scaled = value * scale
+  const adjustment = Number.EPSILON * Math.max(1, Math.abs(scaled))
+  return (scaled < 0 ? -Math.round(-scaled + adjustment) : Math.round(scaled + adjustment)) / scale
+}
+
+export function inspectPrecision({ value, numberFormat, decimals = decimalPlaces(numberFormat) }) {
+  if (!Number.isFinite(value) || !Number.isInteger(decimals) || decimals < 0) throw new TypeError('inspectPrecision requires a finite value and nonnegative integer decimals')
+  const quantizedValue = quantize(value, decimals)
+  return {
+    displayPrecision: decimalPlaces(numberFormat),
+    storedValue: value,
+    quantizedValue,
+    storedPrecision: Object.is(value, quantizedValue) ? 'at-most-requested' : 'more-than-requested',
+    quantized: Object.is(value, quantizedValue),
+    decimals,
+  }
+}
+
+function pointMap(coordinates) {
+  if (!Array.isArray(coordinates)) throw new TypeError('coordinates must be an array')
+  const map = new Map()
+  for (const point of coordinates) {
+    if (!point || typeof point.id !== 'string' || map.has(point.id)) throw new TypeError('coordinates require unique string ids')
+    if (![point.x, point.y, point.z].every(Number.isFinite)) throw new TypeError('coordinates require finite x/y/z')
+    map.set(point.id, point)
+  }
+  return map
+}
+
+function distance(left, right) {
+  return Math.hypot(left.x - right.x, left.y - right.y, left.z - right.z)
+}
+
+export function checkQuantizedGeometry({ coordinates, deltas, decimals, constraints }) {
+  const original = pointMap(coordinates)
+  if (!Array.isArray(constraints)) throw new TypeError('constraints must be an array')
+  const quantized = [...original.values()].map(point => ({ ...point, x: quantize(point.x, decimals), y: quantize(point.y, decimals), z: quantize(point.z, decimals) }))
+  const quantizedDeltas = Array.isArray(deltas) ? deltas.map(value => quantize(value, decimals)) : null
+  const actual = pointMap(quantized)
+  const results = constraints.map(constraint => {
+    const left = actual.get(constraint.source)
+    const right = actual.get(constraint.target)
+    if (!left || !right || !Number.isFinite(constraint.originalLength) || constraint.originalLength <= 0 || !Number.isFinite(constraint.maxRelativeChange) || constraint.maxRelativeChange < 0) throw new TypeError('constraint references valid points and positive numeric limits')
+    const relativeChange = Math.abs(distance(left, right) - constraint.originalLength) / constraint.originalLength
+    return { ...constraint, relativeChange, strictPass: relativeChange <= constraint.maxRelativeChange, tolerancePass: relativeChange <= constraint.maxRelativeChange + 1e-12 }
+  })
+  const strictViolations = results.filter(result => !result.strictPass).length
+  const toleranceViolations = results.filter(result => !result.tolerancePass).length
+  return {
+    decimals,
+    quantizedCoordinates: quantized,
+    quantizedDeltas,
+    constraints: results,
+    strictViolations,
+    toleranceViolations,
+    worstRelativeChange: results.length ? Math.max(...results.map(result => result.relativeChange)) : 0,
+    verdict: strictViolations > 0 ? 'FAIL' : 'PASS',
+  }
+}
+
+function equalWithin(left, right, tolerance) {
+  if (typeof left === 'number' && typeof right === 'number') return Number.isFinite(left) && Number.isFinite(right) && Math.abs(left - right) <= tolerance
+  return JSON.stringify(left) === JSON.stringify(right)
+}
+
+export function compareArtifacts(left, right, { fields, tolerance = 0 } = {}) {
+  if (!left || typeof left !== 'object' || !right || typeof right !== 'object' || !Number.isFinite(tolerance) || tolerance < 0) throw new TypeError('compareArtifacts requires objects and nonnegative tolerance')
+  const selected = Array.isArray(fields) ? fields : [...new Set([...Object.keys(left), ...Object.keys(right)])]
+  const differences = selected.filter(field => !equalWithin(left[field], right[field], tolerance)).map(field => ({ field, left: left[field], right: right[field] }))
+  return { valid: differences.length === 0, differences }
+}

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { claimEvidenceMatrix } from './report-contract.mjs'
+
+const PAPER_FILES = [
+  'problem-understanding.md', 'problem-coverage.md', 'data-and-dataset.md', 'assumptions-and-scope.md',
+  'symbols.jsonl', 'method-derivation.md', 'parameter-provenance.md', 'validation-summary.md',
+  'robustness-and-uncertainty.md', 'failure-insights.md', 'model-evaluation-and-improvement.md',
+  'limitations-and-threats.md', 'references.md', 'reproducibility.md', 'claim-evidence-matrix.json',
+]
+
+function hashText(text) { return createHash('sha256').update(text, 'utf8').digest('hex') }
+function evidenceRefs(graph) { return (graph?.evidence ?? []).map(item => item.id).filter(Boolean).join(', ') || 'none recorded' }
+function claims(graph) { return (graph?.claims ?? []).map(item => item.statement + ' [evidence: ' + (item.evidenceIds ?? []).join(', ') + ']').join('\n') || 'No claims recorded.' }
+function markdown(title, graph, body) { return '# ' + title + '\n\n' + body + '\n\nEvidence references: ' + evidenceRefs(graph) + '.\n' }
+
+export async function buildPaperEvidence(runRoot) {
+  const ledgerPath = join(runRoot, 'ledger.json')
+  const ledgerText = await readFile(ledgerPath, 'utf8')
+  const graph = JSON.parse(ledgerText)
+  const outputRoot = join(runRoot, 'paper-evidence')
+  await mkdir(outputRoot, { recursive: true })
+  const content = {
+    'problem-understanding.md': markdown('Problem understanding', graph, 'This package records the frozen problem background, dataset scope, requested outputs and question dependency chain. Each claim below remains tied to its evidence IDs.\n\n' + claims(graph)),
+    'problem-coverage.md': markdown('Problem coverage', graph, 'Each registered requirement is mapped to a claim, obligation, evidence record and report location. Missing or stale mappings remain visible rather than being silently filled.'),
+    'data-and-dataset.md': markdown('Data and dataset', graph, 'The data section records source files, units, identifiers, coordinate conventions, observed ranges and the input snapshot hash.'),
+    'assumptions-and-scope.md': markdown('Assumptions and scope', graph, 'Global and subproblem assumptions are listed with their basis, risk, sensitivity plan and affected claims.'),
+    'symbols.jsonl': (graph.symbols ?? []).map(symbol => JSON.stringify(symbol)).join('\n') + ((graph.symbols ?? []).length ? '\n' : ''),
+    'method-derivation.md': markdown('Method and derivation', graph, 'The derivation section records equations, variable meanings, units, numerical method choices and the exact artifact that implements each step.'),
+    'parameter-provenance.md': markdown('Parameter provenance', graph, 'Every parameter is linked to problem text, data, theory, literature or an explicitly challengeable modeling simplification.'),
+    'validation-summary.md': markdown('Validation summary', graph, 'Verification verdicts are shown separately from obligation and claim status. A PASS verdict is not silently promoted to a supported claim.'),
+    'robustness-and-uncertainty.md': markdown('Robustness and uncertainty', graph, 'Perturbation targets, magnitudes, sampling rules, conclusion-flip criteria and untested scope are recorded here.'),
+    'failure-insights.md': markdown('Failure insights', graph, 'Failed directions preserve symptoms, root causes, exclusions, scientific insight, downstream impact and recovery conditions.'),
+    'model-evaluation-and-improvement.md': markdown('Model evaluation and improvement', graph, 'Candidate comparisons state the criterion, evidence scope, limitations and the next controlled improvement.'),
+    'limitations-and-threats.md': markdown('Limitations and threats', graph, 'Unproven global optimality, missing physical parameters, sampling restrictions and external-validity threats remain explicit.'),
+    'references.md': markdown('References', graph, 'References are mapped to the exact method, assumption or interpretation they support. Unknown metadata is not invented.'),
+    'reproducibility.md': markdown('Reproducibility', graph, 'The run records frozen inputs, commands, environment, code hashes, artifact hashes and clean-rerun conditions.'),
+    'claim-evidence-matrix.json': JSON.stringify(claimEvidenceMatrix(graph), null, 2) + '\n',
+  }
+  for (const file of PAPER_FILES) await writeFile(join(outputRoot, file), content[file], 'utf8')
+  return { files: [...PAPER_FILES], evidenceGraphHash: hashText(ledgerText), outputRoot }
+}

package/skills/math-modeling-agent/scripts/report-contract.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+export const SCIENTIFIC_SECTIONS = Object.freeze([
+  '问题重述',
+  '问题分析',
+  '模型假设',
+  '符号说明',
+  '模型建立与求解',
+  '验证',
+  '鲁棒性分析',
+  '模型的评价与改进',
+  '参考文献',
+])
+
+export const ADMINISTRATIVE_FIELDS = Object.freeze([
+  'objective', 'candidate', 'assumptionDelta', 'claimsChanged', 'artifacts', 'evidenceIds',
+  'obligations', 'issuesOpened', 'issuesClosed', 'attemptDelta', 'progress', 'budget', 'currentStatus', 'nextAction',
+])
+
+const SECTION_ALIASES = new Map([['模型评价与改进', '模型的评价与改进']])
+
+function normalizeHeading(value) {
+  return SECTION_ALIASES.get(String(value).trim()) ?? String(value).trim()
+}
+
+function textOf(input) {
+  if (typeof input === 'string') return input
+  if (input && typeof input.text === 'string') return input.text
+  return ''
+}
+
+function sectionBlocks(text) {
+  const matches = [...text.matchAll(/^##\s+(.+)$/gm)]
+  return matches.map((match, index) => ({ name: normalizeHeading(match[1]), body: text.slice(match.index + match[0].length, matches[index + 1]?.index ?? text.length).trim() }))
+}
+
+function quality(body) {
+  const value = body.toLowerCase()
+  return {
+    why: /why|为什么|原因|用于|问题是/.test(value),
+    how: /how|如何|按|使用|计算|重建|推导|方法/.test(value),
+    what: /what|结果|输出|得到|数值|结论/.test(value),
+    check: /check|检查|验证|比较|证据|审计|不一致/.test(value),
+  }
+}
+
+export function validateSymbols(symbols) {
+  const errors = []
+  if (!Array.isArray(symbols)) return { valid: false, errors: ['symbols must be an array'] }
+  const ids = new Set()
+  for (const [index, symbol] of symbols.entries()) {
+    if (!symbol || typeof symbol !== 'object' || Array.isArray(symbol)) { errors.push('symbols[' + index + '] must be an object'); continue }
+    const id = symbol.id ?? symbol.name
+    if (typeof id !== 'string' || id.trim() === '') errors.push('symbols[' + index + '] requires id or name')
+    else if (ids.has(id)) errors.push('duplicate symbol: ' + id)
+    else ids.add(id)
+    for (const field of ['meaning', 'unit']) if (typeof symbol[field] !== 'string' || symbol[field].trim() === '') errors.push('symbols[' + index + '].' + field + ' is required')
+  }
+  return { valid: errors.length === 0, errors }
+}
+
+export function validateReportText({ text, symbols = [], evidence = [] } = {}) {
+  const errors = []
+  if (typeof text !== 'string' || text.trim() === '') errors.push('report text is required')
+  const symbolResult = validateSymbols(symbols)
+  errors.push(...symbolResult.errors)
+  const evidenceCount = Array.isArray(evidence) ? evidence.length : 0
+  if (/\bglobal\s+optimum\b|\bglobally\s+optimal\b/i.test(text ?? '') && evidenceCount === 0) errors.push('global optimum claim requires evidence')
+  if (/\bverified\b/i.test(text ?? '') && evidenceCount === 0) errors.push('verified claim requires evidence')
+  return { valid: errors.length === 0, errors }
+}
+
+export function validateCoverage(entries) {
+  const blockers = []
+  const conditionals = []
+  if (!Array.isArray(entries)) return { canLeavePhase: false, blockers: ['coverage entries are missing'], conditionals: [] }
+  for (const entry of entries) {
+    if (!entry || typeof entry.requirementId !== 'string' || entry.requirementId.trim() === '') { blockers.push('unknown requirement'); continue }
+    if (entry.status === 'missing' || entry.status === 'stale') blockers.push(entry.requirementId)
+    else if (entry.status === 'partial') conditionals.push(entry.requirementId)
+  }
+  return { canLeavePhase: blockers.length === 0, blockers, conditionals }
+}
+
+export function validateAttemptReport(input) {
+  const text = textOf(input)
+  const blocks = sectionBlocks(text)
+  const names = new Set(blocks.map(block => block.name))
+  const errors = []
+  for (const section of SCIENTIFIC_SECTIONS) if (!names.has(section)) errors.push('missing scientific section: ' + section)
+  const administrative = input && typeof input === 'object' && !Array.isArray(input) ? input.administrative : null
+  for (const field of ADMINISTRATIVE_FIELDS) if (!administrative || !Object.hasOwn(administrative, field)) errors.push('missing administrative field: ' + field)
+  const qualityBySection = Object.fromEntries(blocks.map(block => [block.name, quality(block.body)]))
+  const missingQuality = Object.entries(qualityBySection).flatMap(([section, checks]) => Object.entries(checks).filter(([, present]) => !present).map(([kind]) => ({ section, kind })))
+  const textLint = validateReportText({ text, symbols: input?.symbols ?? [], evidence: input?.evidence ?? [] })
+  errors.push(...textLint.errors)
+  return { valid: errors.length === 0, errors, sections: blocks.map(block => block.name), quality: qualityBySection, missingQuality, canLeavePhase: errors.length === 0 }
+}
+
+export function claimEvidenceMatrix(graph) {
+  return {
+    schemaVersion: 1,
+    claims: (graph?.claims ?? []).map(claim => ({
+      claimId: claim.id,
+      statement: claim.statement,
+      verdict: claim.verdict ?? 'INCONCLUSIVE',
+      evidenceIds: [...(claim.evidenceIds ?? [])],
+      obligationIds: [...(claim.obligationIds ?? [])],
+      limitations: [...(claim.limitations ?? [])],
+    })),
+  }
+}