dsh-math-modeling-agent 0.1.1 → 0.2.0

package/skills/math-modeling-agent/scripts/run-state.mjs

@@ -4,7 +4,9 @@ import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { isDeepStrictEqual } from 'node:util'
 
-export const SCHEMA_VERSION = 1
+export const SCHEMA_VERSION = 2
+export const SUPPORTED_SCHEMA_VERSIONS = [1, 2]
+export const INTERACTION_DECISIONS = Object.freeze({ D1: 'routing', D2: 'assumptions', D3: 'direction', D4: 'verdict' })
 export const MODE_DEFAULTS = Object.freeze({
   fast: Object.freeze({ attempts: 2, researchQueries: 0, computeSeconds: 60 }),
   standard: Object.freeze({ attempts: 12, researchQueries: 12, computeSeconds: 1800 }),
@@ -282,7 +284,7 @@ function deeplyEqual(left, right) { return isDeepStrictEqual(left, right) }
 function validateRunShape(run, diagnostics, prefix = 'run') {
   addDiagnostic(diagnostics, exactKeys(run, RUN_KEYS), `${prefix} must contain exactly the contracted fields`)
   if (!isObject(run)) return
-  addDiagnostic(diagnostics, run.schemaVersion === SCHEMA_VERSION, `${prefix}.schemaVersion must equal ${SCHEMA_VERSION}`)
+  addDiagnostic(diagnostics, SUPPORTED_SCHEMA_VERSIONS.includes(run.schemaVersion), `${prefix}.schemaVersion must be one of ${SUPPORTED_SCHEMA_VERSIONS.join(',')}`)
   addDiagnostic(diagnostics, typeof run.taskId === 'string' && TASK_ID.test(run.taskId), `${prefix}.taskId must be kebab-case`)
   addDiagnostic(diagnostics, Object.hasOwn(MODE_DEFAULTS, run.mode), `${prefix}.mode is invalid`)
   addDiagnostic(diagnostics, STATUSES.includes(run.status), `${prefix}.status is invalid`)
@@ -297,7 +299,7 @@ function validateRunShape(run, diagnostics, prefix = 'run') {
 function validateLedgerShape(ledger, diagnostics) {
   addDiagnostic(diagnostics, exactKeys(ledger, LEDGER_KEYS), 'ledger must contain exactly the contracted fields')
   if (!isObject(ledger)) return
-  addDiagnostic(diagnostics, ledger.schemaVersion === SCHEMA_VERSION, `ledger.schemaVersion must equal ${SCHEMA_VERSION}`)
+  addDiagnostic(diagnostics, SUPPORTED_SCHEMA_VERSIONS.includes(ledger.schemaVersion), `ledger.schemaVersion must be one of ${SUPPORTED_SCHEMA_VERSIONS.join(',')}`)
   addDiagnostic(diagnostics, typeof ledger.taskId === 'string' && TASK_ID.test(ledger.taskId), 'ledger.taskId must be kebab-case')
   addDiagnostic(diagnostics, isObject(ledger.scope), 'ledger.scope must be an object')
   for (const key of ['assumptions', 'claims', 'obligations', 'subproblems', 'candidates', 'issues']) addDiagnostic(diagnostics, Array.isArray(ledger[key]), `ledger.${key} must be an array`)
@@ -312,7 +314,7 @@ function validateEventShape(event, diagnostics, index) {
     ? ['schemaVersion', 'sequence', 'type', 'taskId', 'timestamp', 'snapshot']
     : ['schemaVersion', 'sequence', 'type', 'taskId', 'from', 'to', 'reason', 'evidenceIds', 'issueIds', 'timestamp', 'snapshot']
   addDiagnostic(diagnostics, exactKeys(event, expectedKeys), `${prefix} must contain exactly the contracted fields`)
-  addDiagnostic(diagnostics, event.schemaVersion === SCHEMA_VERSION, `${prefix}.schemaVersion must equal ${SCHEMA_VERSION}`)
+  addDiagnostic(diagnostics, SUPPORTED_SCHEMA_VERSIONS.includes(event.schemaVersion), `${prefix}.schemaVersion must be one of ${SUPPORTED_SCHEMA_VERSIONS.join(',')}`)
   addDiagnostic(diagnostics, event.sequence === index, `${prefix}.sequence must equal ${index}`)
   addDiagnostic(diagnostics, typeof event.taskId === 'string' && TASK_ID.test(event.taskId), `${prefix}.taskId must be kebab-case`)
   addDiagnostic(diagnostics, event.type === expectedType, `${prefix}.type must be ${expectedType}`)
@@ -377,8 +379,8 @@ export async function initRun(root, { taskId, mode = 'standard', budget, budgets
       bestCandidateId: null, budget: effectiveBudget, createdAt: timestamp, updatedAt: timestamp,
     }
     const ledger = {
-      schemaVersion: SCHEMA_VERSION, taskId, scope: { independentAuditPassed: false }, assumptions: [], claims: [],
-      obligations: [], subproblems: [], candidates: [], issues: [],
+      schemaVersion: SCHEMA_VERSION, taskId, scope: { independentAuditPassed: false, interactions: [], decisionStack: [], robustnessExempt: false },
+      assumptions: [], claims: [], obligations: [], subproblems: [], candidates: [], issues: [],
     }
     const event = { schemaVersion: SCHEMA_VERSION, sequence: 0, type: 'RUN_INITIALIZED', taskId, timestamp, snapshot: clone(run) }
     const p = paths(root)
@@ -409,6 +411,51 @@ export async function initRun(root, { taskId, mode = 'standard', budget, budgets
   }, runtime)
 }
 
+/** The v2 interaction contract: decision records, decision-stack backtracking, and the robustness gate. */
+function hasDecisionRecord(scope, decisionPoint) {
+  return Array.isArray(scope?.interactions) && scope.interactions.some(entry =>
+    entry && (entry.decisionPoint === decisionPoint || entry.auto === true))
+}
+function decisionStackIds(scope) {
+  return Array.isArray(scope?.decisionStack)
+    ? scope.decisionStack.filter(entry => entry && typeof entry.id === 'string').map(entry => entry.id)
+    : []
+}
+function interactionContractViolations(run, ledger, to, reason) {
+  if (ledger.schemaVersion !== SCHEMA_VERSION) return []
+  const scope = ledger.scope ?? {}
+  const violations = []
+  const transitional = to !== undefined
+  const earlyStop = ['BLOCKED', 'CANCELLED'].includes(run.status)
+  if ((transitional && to === 'SCOPE_FROZEN') || (!transitional && run.status !== 'TRIAGE' && !earlyStop)) {
+    if (!hasDecisionRecord(scope, 'D1')) violations.push('D1 routing interaction record missing (ledger.scope.interactions)')
+  }
+  const enteringAttemptFromCandidates = transitional ? (to === 'ATTEMPT' && run.status === 'CANDIDATES_READY') : (run.currentAttempt >= 1)
+  if (enteringAttemptFromCandidates && !hasDecisionRecord(scope, 'D3')) violations.push('D3 direction-selection interaction record missing')
+  const enteringTerminalFromVerify = transitional
+    ? (FINAL_STATES.includes(to) && run.status === 'VERIFY')
+    : (FINAL_STATES.includes(run.status) && !['BLOCKED', 'CANCELLED'].includes(run.status))
+  if (enteringTerminalFromVerify && !hasDecisionRecord(scope, 'D4')) violations.push('D4 verdict interaction record missing')
+  if (transitional && (to === 'REVISE' || to === 'RESEARCH')) {
+    const ids = decisionStackIds(scope)
+    if (ids.length > 0 && !ids.some(id => typeof reason === 'string' && reason.includes(id))) {
+      violations.push(`REVISE/RESEARCH reason must reference a decisionStack entry id (available: ${ids.join(', ')})`)
+    }
+  }
+  const terminalAndExempt = transitional
+    ? (FINAL_STATES.includes(to) && !['BLOCKED', 'CANCELLED'].includes(to))
+    : (FINAL_STATES.includes(run.status) && !['BLOCKED', 'CANCELLED'].includes(run.status))
+  if (terminalAndExempt && scope.robustnessExempt !== true) {
+    const passed = Array.isArray(ledger.obligations) && ledger.obligations.some(o => o && o.kind === 'robustness' && o.status === 'PASS')
+    if (!passed) violations.push('terminal state requires a PASSED robustness-kind obligation (or scope.robustnessExempt: true)')
+  }
+  return violations
+}
+function enforceInteractionContract(run, ledger, to, reason) {
+  const violations = interactionContractViolations(run, ledger, to, reason)
+  if (violations.length > 0) throw new Error(`interaction contract violated: ${violations.join('; ')}`)
+}
+
 function enforceSolvedGate(run, ledger) {
   if (ledger.claims.length < 1) throw new Error('SOLVED requires at least one claim')
   if (ledger.obligations.some(item => item.required !== false && item.status !== 'PASS')) throw new Error('required obligations remain open')
@@ -473,12 +520,13 @@ async function readEvents(path) {
 
 async function validateRunUnlocked(root, expectedTaskId) {
   const diagnostics = []
+  const warnings = []
   let run, ledger, events
   const p = paths(root)
   try { run = await readJson(p.run) } catch (error) { diagnostics.push(`run unreadable: ${error.message}`) }
   try { ledger = await readJson(p.ledger) } catch (error) { diagnostics.push(`ledger unreadable: ${error.message}`) }
   try { events = await readEvents(p.events) } catch (error) { diagnostics.push(error.message) }
-  if (!run || !ledger || !events) return { valid: false, diagnostics }
+  if (!run || !ledger || !events) return { valid: false, diagnostics, warnings }
   validateRunShape(run, diagnostics)
   validateLedgerShape(ledger, diagnostics)
   validateJournal(events, diagnostics)
@@ -486,13 +534,34 @@ async function validateRunUnlocked(root, expectedTaskId) {
   const last = events.at(-1)
   if (last && run.eventSequence !== last.sequence) diagnostics.push('state/journal sequence mismatch')
   if (last && JSON.stringify(run) !== JSON.stringify(last.snapshot)) diagnostics.push('state/journal snapshot mismatch')
-  return { valid: diagnostics.length === 0, diagnostics, run: clone(run) }
+  if (ledger.schemaVersion !== SCHEMA_VERSION) warnings.push(`legacy run (ledger schema v${ledger.schemaVersion}): interaction contract not enforced`)
+  else {
+    for (const violation of interactionContractViolations(run, ledger, undefined, undefined)) {
+      warnings.push(`interaction contract: ${violation}`)
+    }
+  }
+  return { valid: diagnostics.length === 0, diagnostics, warnings, run: clone(run) }
 }
 
 export async function validateRun(root, expectedTaskId, runtime = {}) {
   return withLock(root, MUTATION_LOCK_FILE, 'validate', () => validateRunUnlocked(root, expectedTaskId), runtime)
 }
 
+/**
+ * Check the v2 interaction contract for a PROSPECTIVE transition without
+ * mutating anything. The agent workflow must call this before `transition`;
+ * the CLI `transition` command enforces it internally unless --skip-gate.
+ */
+export async function gateTransition(root, { to, reason }, runtime = {}) {
+  return withLock(root, MUTATION_LOCK_FILE, 'gate', async () => {
+    const p = paths(root)
+    const run = await readJson(p.run)
+    const ledger = await readJson(p.ledger)
+    const violations = interactionContractViolations(run, ledger, to, reason)
+    return { allowed: violations.length === 0, violations, status: run.status }
+  }, runtime)
+}
+
 export async function recoverRun(root, runtime = {}) {
   return withLock(root, MUTATION_LOCK_FILE, 'recover', async () => {
     const p = paths(root)
@@ -533,7 +602,21 @@ async function cli(argv) {
   const root = resolve(rootArg)
   const options = parseOptions(rest)
   if (command === 'init') return initRun(root, { taskId: options['task-id'], mode: options.mode ?? 'standard' })
-  if (command === 'transition') return transitionRun(root, { to: options.to, reason: options.reason, evidenceIds: options.evidence ? options.evidence.split(',').filter(Boolean) : [], issueIds: options.issues ? options.issues.split(',').filter(Boolean) : [], patch: options.candidate ? { bestCandidateId: options.candidate } : undefined })
+  if (command === 'gate') {
+    const result = await gateTransition(root, { to: options.to, reason: options.reason })
+    if (!result.allowed) process.exitCode = 1
+    return result
+  }
+  if (command === 'transition') {
+    if (options['skip-gate'] !== 'true') {
+      const gate = await gateTransition(root, { to: options.to, reason: options.reason })
+      if (!gate.allowed) {
+        process.exitCode = 1
+        return { error: `interaction contract violated: ${gate.violations.join('; ')}`, gate }
+      }
+    }
+    return transitionRun(root, { to: options.to, reason: options.reason, evidenceIds: options.evidence ? options.evidence.split(',').filter(Boolean) : [], issueIds: options.issues ? options.issues.split(',').filter(Boolean) : [], patch: options.candidate ? { bestCandidateId: options.candidate } : undefined })
+  }
   if (command === 'validate') {
     const result = await validateRun(root, options['task-id'])
     if (!result.valid) process.exitCode = 1
@@ -541,7 +624,7 @@ async function cli(argv) {
   }
   if (command === 'recover') return recoverRun(root)
   if (command === 'status') return statusRun(root)
-  throw new Error('usage: run-state.mjs <init|transition|validate|recover|status> <run-directory> [options]')
+  throw new Error('usage: run-state.mjs <init|transition|gate|validate|recover|status> <run-directory> [options]')
 }
 const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
 if (invoked) cli(process.argv.slice(2)).then(result => process.stdout.write(`${JSON.stringify(result)}\n`)).catch(error => { process.stdout.write(`${JSON.stringify({ error: error.message })}\n`); process.exitCode = 1 })

package/docs/assets/mathmodelingagent-overview.svg

@@ -1,92 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1066" height="620" viewBox="0 0 1066 620" role="img" aria-label="MathModelingAgent 工作流总览">
-  <defs>
-    <filter id="shadow" x="-4%" y="-4%" width="108%" height="112%">
-      <feDropShadow dx="0" dy="2" stdDeviation="4" flood-color="#0f172a" flood-opacity="0.06"/>
-    </filter>
-  </defs>
-  <rect width="1066" height="620" rx="16" fill="#f8fafc"/>
-  <text x="40" y="52" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="30" font-weight="700" fill="#0f172a">MathModelingAgent</text>
-  <text x="40" y="84" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="15" fill="#475569">从题目到可复现结论 · 模型负责提出，证据负责裁决</text>
-  <g font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="11" fill="#334155">
-    <rect x="774" y="26" width="116" height="28" rx="14" fill="#ffffff" stroke="#e2e8f0"/>
-    <text x="832" y="44" text-anchor="middle" fill="#475569">不绑定具体状态名</text>
-    <rect x="900" y="26" width="122" height="28" rx="14" fill="#ffffff" stroke="#e2e8f0"/>
-    <text x="961" y="44" text-anchor="middle" fill="#475569">不绑定文件结构</text>
-    <rect x="1032" y="26" width="104" height="28" rx="14" fill="#ffffff" stroke="#e2e8f0"/>
-    <text x="1084" y="44" text-anchor="middle" fill="#475569">工具可替换</text>
-  </g>
-  <g font-family="system-ui,-apple-system,'Segoe UI',sans-serif">
-    <rect x="40" y="112" width="184" height="250" rx="14" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
-    <rect x="40" y="112" width="184" height="8" rx="4" fill="#34d399"/>
-    <text x="56" y="156" font-size="17" font-weight="700" fill="#0f172a">题目与数据</text>
-    <text x="56" y="178" font-size="11" font-weight="700" letter-spacing="1" fill="#34d399">INPUT</text>
-    <circle cx="62" cy="208" r="4" fill="#34d399"/><text x="74" y="212" font-size="13" fill="#475569">题目 / PDF</text>
-    <circle cx="62" cy="240" r="4" fill="#34d399"/><text x="74" y="244" font-size="13" fill="#475569">数据与附件</text>
-    <circle cx="62" cy="272" r="4" fill="#34d399"/><text x="74" y="276" font-size="13" fill="#475569">目标与约束</text>
-
-    <rect x="246" y="112" width="184" height="250" rx="14" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
-    <rect x="246" y="112" width="184" height="8" rx="4" fill="#60a5fa"/>
-    <text x="262" y="156" font-size="17" font-weight="700" fill="#0f172a">理解与拆解</text>
-    <text x="262" y="178" font-size="11" font-weight="700" letter-spacing="1" fill="#60a5fa">UNDERSTAND</text>
-    <circle cx="268" cy="208" r="4" fill="#60a5fa"/><text x="280" y="212" font-size="13" fill="#475569">明确问题边界</text>
-    <circle cx="268" cy="240" r="4" fill="#60a5fa"/><text x="280" y="244" font-size="13" fill="#475569">拆成可验证子问题</text>
-    <circle cx="268" cy="272" r="4" fill="#60a5fa"/><text x="280" y="276" font-size="13" fill="#475569">登记关键假设</text>
-
-    <rect x="452" y="112" width="184" height="250" rx="14" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
-    <rect x="452" y="112" width="184" height="8" rx="4" fill="#a78bfa"/>
-    <text x="468" y="156" font-size="17" font-weight="700" fill="#0f172a">建模与执行</text>
-    <text x="468" y="178" font-size="11" font-weight="700" letter-spacing="1" fill="#a78bfa">EXPLORE</text>
-    <circle cx="474" cy="208" r="4" fill="#a78bfa"/><text x="486" y="212" font-size="13" fill="#475569">提出候选模型</text>
-    <circle cx="474" cy="240" r="4" fill="#a78bfa"/><text x="486" y="244" font-size="13" fill="#475569">计算 / 搜索 / 推导</text>
-    <circle cx="474" cy="272" r="4" fill="#a78bfa"/><text x="486" y="276" font-size="13" fill="#475569">保留过程产物</text>
-
-    <rect x="658" y="112" width="184" height="250" rx="14" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
-    <rect x="658" y="112" width="184" height="8" rx="4" fill="#fb923c"/>
-    <text x="674" y="156" font-size="17" font-weight="700" fill="#0f172a">证据验证</text>
-    <text x="674" y="178" font-size="11" font-weight="700" letter-spacing="1" fill="#fb923c">VERIFY</text>
-    <circle cx="680" cy="208" r="4" fill="#fb923c"/><text x="692" y="212" font-size="13" fill="#475569">主张 ↔ 验证义务</text>
-    <circle cx="680" cy="240" r="4" fill="#fb923c"/><text x="692" y="244" font-size="13" fill="#475569">独立重算 / 反例攻击</text>
-    <circle cx="680" cy="272" r="4" fill="#fb923c"/><text x="692" y="276" font-size="13" fill="#475569">证据不足就回去修正</text>
-
-    <rect x="864" y="112" width="184" height="250" rx="14" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
-    <rect x="864" y="112" width="184" height="8" rx="4" fill="#f472b6"/>
-    <text x="880" y="156" font-size="17" font-weight="700" fill="#0f172a">结果交付</text>
-    <text x="880" y="178" font-size="11" font-weight="700" letter-spacing="1" fill="#f472b6">DELIVER</text>
-    <circle cx="886" cy="208" r="4" fill="#f472b6"/><text x="898" y="212" font-size="13" fill="#475569">结论 + 局限</text>
-    <circle cx="886" cy="240" r="4" fill="#f472b6"/><text x="898" y="244" font-size="13" fill="#475569">代码 / 数据 / 复现材料</text>
-    <circle cx="886" cy="272" r="4" fill="#f472b6"/><text x="898" y="276" font-size="13" fill="#475569">审计 / 终态报告</text>
-  </g>
-  <g stroke="#94a3b8" stroke-width="2.5" fill="none" marker-end="url(#arrow)">
-    <line x1="224" y1="237" x2="242" y2="237"/>
-    <line x1="430" y1="237" x2="448" y2="237"/>
-    <line x1="636" y1="237" x2="654" y2="237"/>
-    <line x1="842" y1="237" x2="860" y2="237"/>
-  </g>
-  <defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 Z" fill="#94a3b8"/></marker></defs>
-  <path d="M750 362 C 750 430, 700 452, 544 452 L 544 366" fill="none" stroke="#6366f1" stroke-width="2" stroke-dasharray="6 5" marker-end="url(#arrowLoop)"/>
-  <defs><marker id="arrowLoop" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 Z" fill="#6366f1"/></marker></defs>
-  <rect x="404" y="430" width="284" height="28" rx="14" fill="#eef2ff" stroke="#c7d2fe"/>
-  <text x="546" y="448" text-anchor="middle" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="13" fill="#4338ca">证据不够 → 修正，而不是硬通过</text>
-
-  <rect x="40" y="478" width="1008" height="118" rx="14" fill="#ffffff" stroke="#e2e8f0"/>
-  <text x="64" y="512" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="15" font-weight="700" fill="#0f172a">可插拔能力</text>
-  <text x="64" y="534" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="12" fill="#64748b">实现可以换，语义不变：任何工具都只是为"建模"或"验证"提供证据。</text>
-  <g font-family="system-ui,-apple-system,'Segoe UI',sans-serif" text-anchor="middle">
-    <rect x="64" y="552" width="180" height="26" rx="8" fill="#f1f5f9"/>
-    <text x="154" y="569" font-size="12" font-weight="600" fill="#0f172a">数值计算</text>
-    <text x="154" y="582" font-size="10" fill="#64748b">Python / 其他运行时</text>
-    <rect x="258" y="552" width="180" height="26" rx="8" fill="#f1f5f9"/>
-    <text x="348" y="569" font-size="12" font-weight="600" fill="#0f172a">形式验证</text>
-    <text x="348" y="582" font-size="10" fill="#64748b">Lean / theorem prover</text>
-    <rect x="452" y="552" width="180" height="26" rx="8" fill="#f1f5f9"/>
-    <text x="542" y="569" font-size="12" font-weight="600" fill="#0f172a">符号计算</text>
-    <text x="542" y="582" font-size="10" fill="#64748b">Wolfram / CAS</text>
-    <rect x="646" y="552" width="180" height="26" rx="8" fill="#f1f5f9"/>
-    <text x="736" y="569" font-size="12" font-weight="600" fill="#0f172a">研究检索</text>
-    <text x="736" y="582" font-size="10" fill="#64748b">文献 / Web</text>
-    <rect x="840" y="552" width="180" height="26" rx="8" fill="#f1f5f9"/>
-    <text x="930" y="569" font-size="12" font-weight="600" fill="#0f172a">终审</text>
-    <text x="930" y="582" font-size="10" fill="#64748b">MCM / ICM audit</text>
-  </g>
-  <text x="1032" y="612" text-anchor="end" font-family="system-ui,-apple-system,'Segoe UI',sans-serif" font-size="10" fill="#94a3b8">README overview</text>
-</svg>