dsh-math-modeling-agent 0.1.0

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

@@ -0,0 +1,547 @@
+#!/usr/bin/env node
+import { access, appendFile, mkdir, open, readFile, rename, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDeepStrictEqual } from 'node:util'
+
+export const SCHEMA_VERSION = 1
+export const MODE_DEFAULTS = Object.freeze({
+  fast: Object.freeze({ attempts: 2, researchQueries: 0, computeSeconds: 60 }),
+  standard: Object.freeze({ attempts: 12, researchQueries: 12, computeSeconds: 1800 }),
+  'high-assurance': Object.freeze({ attempts: 24, researchQueries: 30, computeSeconds: 7200 }),
+})
+
+const NON_FINAL_STATES = ['TRIAGE', 'SCOPE_FROZEN', 'INPUT_PROFILED', 'CLAIMS_REGISTERED', 'CANDIDATES_READY', 'ATTEMPT', 'EXECUTE', 'VERIFY', 'REVISE', 'RESEARCH', 'FORK']
+const FINAL_STATES = ['SOLVED', 'PARTIAL', 'CONDITIONAL', 'INCONCLUSIVE', 'REFUTED', 'INFEASIBLE', 'UNIDENTIFIABLE', 'BLOCKED', 'CANCELLED']
+const STATUSES = [...NON_FINAL_STATES, ...FINAL_STATES]
+const STOP_TRANSITIONS = ['BLOCKED', 'CANCELLED']
+const TRANSITIONS = Object.freeze({
+  TRIAGE: ['SCOPE_FROZEN', ...STOP_TRANSITIONS],
+  SCOPE_FROZEN: ['INPUT_PROFILED', ...STOP_TRANSITIONS],
+  INPUT_PROFILED: ['CLAIMS_REGISTERED', ...STOP_TRANSITIONS],
+  CLAIMS_REGISTERED: ['CANDIDATES_READY', ...STOP_TRANSITIONS],
+  CANDIDATES_READY: ['ATTEMPT', ...STOP_TRANSITIONS],
+  ATTEMPT: ['EXECUTE', ...STOP_TRANSITIONS],
+  EXECUTE: ['VERIFY', ...STOP_TRANSITIONS],
+  VERIFY: ['REVISE', 'RESEARCH', 'FORK', ...FINAL_STATES],
+  REVISE: ['ATTEMPT', ...STOP_TRANSITIONS],
+  RESEARCH: ['CANDIDATES_READY', ...STOP_TRANSITIONS],
+  FORK: ['ATTEMPT', ...STOP_TRANSITIONS],
+})
+const TASK_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const RUN_KEYS = ['schemaVersion', 'taskId', 'mode', 'status', 'eventSequence', 'currentAttempt', 'bestCandidateId', 'budget', 'createdAt', 'updatedAt']
+const IMMUTABLE_RUN_KEYS = ['schemaVersion', 'taskId', 'mode', 'budget', 'createdAt']
+const LEDGER_KEYS = ['schemaVersion', 'taskId', 'scope', 'assumptions', 'claims', 'obligations', 'subproblems', 'candidates', 'issues']
+const RUN_FILE = 'run.json'
+const LEDGER_FILE = 'ledger.json'
+const EVENTS_FILE = 'events.jsonl'
+const MUTATION_LOCK_FILE = '.run-state.lock'
+const RECLAIM_GUARD_FILE = '.run-state.reclaim'
+
+function clone(value) { return JSON.parse(JSON.stringify(value)) }
+function now() { return new Date().toISOString() }
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
+function exactKeys(value, keys) { return isObject(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key)) }
+function nonnegativeInteger(value) { return Number.isInteger(value) && value >= 0 }
+function validateBudgetShape(budget, diagnostics, prefix = 'budget') {
+  addDiagnostic(diagnostics, isObject(budget), `${prefix} must be an object`)
+  if (!isObject(budget)) return
+  addDiagnostic(diagnostics, exactKeys(budget, ['attempts', 'researchQueries', 'computeSeconds']), `${prefix} has invalid fields`)
+  addDiagnostic(diagnostics, Number.isFinite(budget.attempts) && Number.isInteger(budget.attempts) && budget.attempts >= 1, `${prefix}.attempts must be a finite integer >= 1`)
+  addDiagnostic(diagnostics, Number.isFinite(budget.researchQueries) && nonnegativeInteger(budget.researchQueries), `${prefix}.researchQueries must be a finite nonnegative integer`)
+  addDiagnostic(diagnostics, Number.isFinite(budget.computeSeconds) && nonnegativeInteger(budget.computeSeconds), `${prefix}.computeSeconds must be a finite nonnegative integer`)
+}
+async function readJson(path) { return JSON.parse(await readFile(path, 'utf8')) }
+const RENAME_DEFAULTS = Object.freeze({ attempts: 5, retryDelayMs: 5 })
+const WINDOWS_SHARING_ERRORS = new Set(['EPERM', 'EBUSY', 'EACCES'])
+async function renameWithRetry(source, target, runtime = {}) {
+  const options = { ...RENAME_DEFAULTS, ...(runtime.rename ?? {}) }
+  const renameFile = runtime.fs?.rename ?? rename
+  for (let attempt = 1; ; attempt += 1) {
+    try { return await renameFile(source, target) }
+    catch (error) {
+      if (!WINDOWS_SHARING_ERRORS.has(error.code) || attempt >= options.attempts) {
+        if (WINDOWS_SHARING_ERRORS.has(error.code)) error.message = `atomic rename failed after ${attempt} attempts: ${error.message}`
+        throw error
+      }
+      await sleep(options.retryDelayMs * attempt)
+    }
+  }
+}
+async function unlinkWithRetry(path, unlinkFile = unlink, options = RENAME_DEFAULTS) {
+  for (let attempt = 1; ; attempt += 1) {
+    try { await unlinkFile(path); return true }
+    catch (error) {
+      if (error.code === 'ENOENT') return false
+      if (!WINDOWS_SHARING_ERRORS.has(error.code) || attempt >= options.attempts) throw error
+      await sleep(options.retryDelayMs * attempt)
+    }
+  }
+}
+async function atomicWrite(path, value, runtime = {}) {
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+  try { await renameWithRetry(temporary, path, runtime) }
+  finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error }) }
+}
+function paths(root) { return { run: join(root, RUN_FILE), ledger: join(root, LEDGER_FILE), events: join(root, EVENTS_FILE) } }
+const LOCK_DEFAULTS = Object.freeze({ timeoutMs: 2000, retryDelayMs: 10, staleMs: 30_000 })
+function sleep(milliseconds) { return new Promise(resolve => setTimeout(resolve, milliseconds)) }
+function processIsAlive(pid) {
+  try { process.kill(pid, 0); return true }
+  catch (error) { return error.code === 'EPERM' }
+}
+function lockBusyError(operation) {
+  const error = new Error(`LOCK_BUSY: timed out waiting for run-state lock during ${operation}`)
+  error.code = 'LOCK_BUSY'
+  return error
+}
+async function readLockMetadata(lockPath) {
+  try { return JSON.parse(await readFile(lockPath, 'utf8')) } catch { return null }
+}
+async function validCompleteRunExists(root) {
+  try {
+    const p = paths(root)
+    validateAuthoritativeState(await readJson(p.run), await readJson(p.ledger), await readEvents(p.events))
+    return true
+  } catch { return false }
+}
+async function cleanupDeadInitAttempt(root, metadata) {
+  if (metadata?.operation !== 'init' || await validCompleteRunExists(root)) return
+  const owned = Array.isArray(metadata.ownedArtifacts) ? metadata.ownedArtifacts : []
+  for (const file of owned) {
+    if ([RUN_FILE, LEDGER_FILE, EVENTS_FILE].includes(file)) await unlink(join(root, file)).catch(error => { if (error.code !== 'ENOENT') throw error })
+  }
+  if (typeof metadata.stagingDir === 'string' && metadata.stagingDir.startsWith('.run-state-init-')) {
+    const stagingRoot = join(root, metadata.stagingDir)
+    for (const file of [RUN_FILE, LEDGER_FILE, EVENTS_FILE]) await unlink(join(stagingRoot, file)).catch(error => { if (error.code !== 'ENOENT') throw error })
+    await rmdir(stagingRoot).catch(error => { if (!['ENOENT', 'ENOTEMPTY'].includes(error.code)) throw error })
+  }
+}
+async function reclaimGuardIsBusy(path, runtime = {}) {
+  const accessFile = runtime.fs?.access ?? access
+  try { await accessFile(path); return true }
+  catch (error) {
+    if (error.code === 'ENOENT') return false
+    if (WINDOWS_SHARING_ERRORS.has(error.code)) return true
+    throw error
+  }
+}
+function sameLockGeneration(observedMetadata, observedStat, currentMetadata, currentStat) {
+  if (observedMetadata === null || currentMetadata === null) {
+    return observedMetadata === null && currentMetadata === null
+      && observedStat.dev === currentStat.dev
+      && observedStat.ino === currentStat.ino
+      && observedStat.size === currentStat.size
+      && observedStat.mtimeMs === currentStat.mtimeMs
+  }
+  return typeof observedMetadata.ownerId === 'string'
+    && currentMetadata.ownerId === observedMetadata.ownerId
+    && observedStat.dev === currentStat.dev
+    && observedStat.ino === currentStat.ino
+    && observedStat.size === currentStat.size
+    && observedStat.mtimeMs === currentStat.mtimeMs
+}
+function demonstrablyDeadAndStale(metadata, lockStat, lockOptions) {
+  const acquiredAt = Date.parse(metadata?.acquiredAt)
+  const staleSince = Number.isFinite(acquiredAt) ? acquiredAt : lockStat.mtimeMs
+  return typeof metadata?.ownerId === 'string'
+    && Number.isInteger(metadata.pid)
+    && Date.now() - staleSince >= lockOptions.staleMs
+    && !lockOptions.isProcessAlive(metadata.pid)
+}
+
+function isReclaimableLock(metadata, lockStat, lockOptions) {
+  if (metadata === null) return Date.now() - lockStat.mtimeMs >= lockOptions.staleMs
+  return demonstrablyDeadAndStale(metadata, lockStat, lockOptions)
+}
+
+async function reclaimStaleGuard(guardPath, lockOptions, runtime = {}) {
+  const statFile = runtime.fs?.stat ?? stat
+  const unlinkFile = runtime.fs?.unlink ?? unlink
+  try {
+    const guardStat = await statFile(guardPath)
+    if (Date.now() - guardStat.mtimeMs < lockOptions.staleMs) return false
+    const guardMetadata = await readLockMetadata(guardPath)
+    if (guardMetadata !== null && typeof guardMetadata.ownerId !== 'string') return false
+    await unlinkWithRetry(guardPath, unlinkFile)
+    return true
+  } catch (error) {
+    if (error.code === 'ENOENT') return true
+    throw error
+  }
+}
+async function reclaimDeadStaleLock(root, lockPath, guardPath, lockOptions) {
+  let observedMetadata, observedStat
+  try { [observedMetadata, observedStat] = await Promise.all([readLockMetadata(lockPath), stat(lockPath)]) }
+  catch (error) { if (error.code === 'ENOENT') return true; throw error }
+  if (!isReclaimableLock(observedMetadata, observedStat, lockOptions)) return false
+  const guardOwnerId = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+  let guard
+  try {
+    guard = await open(guardPath, 'wx')
+    await guard.writeFile(JSON.stringify({ ownerId: guardOwnerId }), 'utf8')
+  } catch (error) {
+    if (guard) {
+      await guard.close()
+      const currentGuard = await readLockMetadata(guardPath)
+      if (currentGuard?.ownerId === guardOwnerId) await unlinkWithRetry(guardPath)
+    }
+    if (['EEXIST', 'EPERM', 'EBUSY', 'EACCES'].includes(error.code)) return false
+    throw error
+  }
+  try {
+    let currentMetadata, currentStat
+    try { [currentMetadata, currentStat] = await Promise.all([readLockMetadata(lockPath), stat(lockPath)]) }
+    catch (error) { if (error.code === 'ENOENT') return true; throw error }
+    if (!sameLockGeneration(observedMetadata, observedStat, currentMetadata, currentStat)) return false
+    if (!isReclaimableLock(currentMetadata, currentStat, lockOptions)) return false
+    await cleanupDeadInitAttempt(root, currentMetadata)
+    const finalMetadata = await readLockMetadata(lockPath)
+    if (finalMetadata?.ownerId !== observedMetadata?.ownerId) return false
+    await unlinkWithRetry(lockPath)
+    return true
+  } finally {
+    await guard.close()
+    const currentGuard = await readLockMetadata(guardPath)
+    if (currentGuard?.ownerId === guardOwnerId) await unlinkWithRetry(guardPath)
+  }
+}
+async function withLock(root, file, operationName, operation, runtime = {}) {
+  await mkdir(root, { recursive: true })
+  const lockPath = join(root, file)
+  const guardPath = join(root, RECLAIM_GUARD_FILE)
+  const lockOptions = { ...LOCK_DEFAULTS, ...(runtime.lock ?? {}), isProcessAlive: runtime.lock?.isProcessAlive ?? processIsAlive }
+  const deadline = Date.now() + lockOptions.timeoutMs
+  const ownerId = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+  let lock
+  let metadata = { pid: process.pid, acquiredAt: now(), operation: operationName, ownerId }
+  while (!lock) {
+    if (await reclaimGuardIsBusy(guardPath, runtime)) {
+      if (await reclaimStaleGuard(guardPath, lockOptions, runtime)) {
+        if (Date.now() >= deadline) throw lockBusyError(operationName)
+        await sleep(lockOptions.retryDelayMs)
+        continue
+      }
+      if (Date.now() >= deadline) throw lockBusyError(operationName)
+      await sleep(lockOptions.retryDelayMs)
+      continue
+    }
+    try {
+      const candidate = await open(lockPath, 'wx')
+      if (await reclaimGuardIsBusy(guardPath, runtime)) {
+        await candidate.close()
+        await unlinkWithRetry(lockPath)
+        if (await reclaimStaleGuard(guardPath, lockOptions, runtime)) {
+          if (Date.now() >= deadline) throw lockBusyError(operationName)
+          await sleep(lockOptions.retryDelayMs)
+          continue
+        }
+        if (Date.now() >= deadline) throw lockBusyError(operationName)
+        await sleep(lockOptions.retryDelayMs)
+        continue
+      }
+      lock = candidate
+      await lock.writeFile(JSON.stringify(metadata), 'utf8')
+    } catch (error) {
+      if (!['EEXIST', 'EPERM', 'EBUSY', 'EACCES'].includes(error.code)) throw error
+      if (error.code === 'EEXIST' && await reclaimDeadStaleLock(root, lockPath, guardPath, lockOptions)) continue
+      if (Date.now() >= deadline) throw lockBusyError(operationName)
+      await sleep(lockOptions.retryDelayMs)
+    }
+  }
+  const updateMetadata = async patch => {
+    metadata = { ...metadata, ...patch }
+    await writeFile(lockPath, JSON.stringify(metadata), 'utf8')
+  }
+  try {
+    await runtime.hooks?.afterLockAcquired?.({ operation: operationName, ownerId })
+    return await operation({ ownerId, updateMetadata })
+  } finally {
+    await lock.close()
+    const current = await readLockMetadata(lockPath)
+    if (current?.ownerId === ownerId) await unlinkWithRetry(lockPath)
+  }
+}
+async function assertRunFilesDoNotExist(p) {
+  for (const path of [p.run, p.ledger, p.events]) {
+    try { await access(path); throw new Error('contracted run file already exists') }
+    catch (error) { if (error.code !== 'ENOENT') throw error }
+  }
+}
+function assertTaskId(taskId) { if (!TASK_ID.test(taskId ?? '')) throw new Error('taskId must be kebab-case') }
+function assertMode(mode) { if (!MODE_DEFAULTS[mode]) throw new Error(`unsupported mode: ${mode}`) }
+function linkedIds(input) { return [...(input.evidenceIds ?? []), ...(input.issueIds ?? [])] }
+function isAllowedTransition(from, to) { return (TRANSITIONS[from] ?? []).includes(to) }
+function illegalTransitionMessage(from, to) { return `illegal transition ${from} -> ${to}` }
+function nextAttempt(currentAttempt, to) { return currentAttempt + (to === 'ATTEMPT' ? 1 : 0) }
+function addDiagnostic(diagnostics, condition, message) { if (!condition) diagnostics.push(message) }
+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, 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`)
+  addDiagnostic(diagnostics, nonnegativeInteger(run.eventSequence), `${prefix}.eventSequence must be a nonnegative integer`)
+  addDiagnostic(diagnostics, nonnegativeInteger(run.currentAttempt), `${prefix}.currentAttempt must be a nonnegative integer`)
+  addDiagnostic(diagnostics, run.bestCandidateId === null || typeof run.bestCandidateId === 'string', `${prefix}.bestCandidateId must be a string or null`)
+  validateBudgetShape(run.budget, diagnostics, `${prefix}.budget`)
+  addDiagnostic(diagnostics, typeof run.createdAt === 'string' && run.createdAt.length > 0, `${prefix}.createdAt must be a string`)
+  addDiagnostic(diagnostics, typeof run.updatedAt === 'string' && run.updatedAt.length > 0, `${prefix}.updatedAt must be a string`)
+}
+
+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, 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`)
+}
+
+function validateEventShape(event, diagnostics, index) {
+  const prefix = `event[${index}]`
+  addDiagnostic(diagnostics, isObject(event), `${prefix} must be an object`)
+  if (!isObject(event)) return
+  const expectedType = index === 0 ? 'RUN_INITIALIZED' : 'STATUS_TRANSITION'
+  const expectedKeys = expectedType === 'RUN_INITIALIZED'
+    ? ['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, 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}`)
+  addDiagnostic(diagnostics, typeof event.timestamp === 'string' && event.timestamp.length > 0, `${prefix}.timestamp must be a string`)
+  addDiagnostic(diagnostics, isObject(event.snapshot), `${prefix}.snapshot must be an object`)
+  if (isObject(event.snapshot)) {
+    validateRunShape(event.snapshot, diagnostics, `${prefix}.snapshot`)
+    addDiagnostic(diagnostics, event.snapshot.taskId === event.taskId, `${prefix} snapshot task mismatch`)
+    addDiagnostic(diagnostics, event.snapshot.eventSequence === event.sequence, `${prefix} snapshot sequence mismatch`)
+    if (expectedType === 'RUN_INITIALIZED') {
+      addDiagnostic(diagnostics, event.snapshot.status === 'TRIAGE', `${prefix}.snapshot.status must be TRIAGE`)
+      addDiagnostic(diagnostics, event.snapshot.eventSequence === 0, `${prefix}.snapshot.eventSequence must equal 0`)
+      addDiagnostic(diagnostics, event.snapshot.currentAttempt === 0, `${prefix}.snapshot.currentAttempt must equal 0`)
+      addDiagnostic(diagnostics, event.snapshot.bestCandidateId === null, `${prefix}.snapshot.bestCandidateId must be null`)
+    }
+  }
+  if (expectedType === 'STATUS_TRANSITION') {
+    addDiagnostic(diagnostics, STATUSES.includes(event.from) && STATUSES.includes(event.to), `${prefix} transition states are invalid`)
+    addDiagnostic(diagnostics, typeof event.reason === 'string' && event.reason.trim().length > 0, `${prefix}.reason must be a nonempty string`)
+    const evidenceIdsValid = Array.isArray(event.evidenceIds) && event.evidenceIds.every(id => typeof id === 'string')
+    const issueIdsValid = Array.isArray(event.issueIds) && event.issueIds.every(id => typeof id === 'string')
+    addDiagnostic(diagnostics, evidenceIdsValid, `${prefix}.evidenceIds must be a string array`)
+    addDiagnostic(diagnostics, issueIdsValid, `${prefix}.issueIds must be a string array`)
+    addDiagnostic(diagnostics, evidenceIdsValid && issueIdsValid && linkedIds(event).length > 0, `${prefix} requires at least one evidence or issue ID`)
+  }
+}
+
+function validateJournal(events, diagnostics) {
+  if (events.length === 0) { diagnostics.push('event journal is empty'); return }
+  const taskId = events[0]?.taskId
+  const initializationSnapshot = events[0]?.snapshot
+  events.forEach((event, index) => {
+    validateEventShape(event, diagnostics, index)
+    addDiagnostic(diagnostics, event?.sequence === index, 'non-monotonic events')
+    addDiagnostic(diagnostics, event?.taskId === taskId, `event[${index}] task mismatch`)
+    if (index > 0) {
+      for (const key of IMMUTABLE_RUN_KEYS) {
+        addDiagnostic(diagnostics, deeplyEqual(event?.snapshot?.[key], initializationSnapshot?.[key]), `event[${index}] snapshot immutable field ${key} mismatch`)
+      }
+      const previousSnapshot = events[index - 1]?.snapshot
+      const previousStatus = previousSnapshot?.status
+      addDiagnostic(diagnostics, event?.from === previousStatus, `event[${index}] transition from does not match previous snapshot`)
+      addDiagnostic(diagnostics, event?.to === event?.snapshot?.status, `event[${index}] transition to does not match snapshot`)
+      addDiagnostic(diagnostics, isAllowedTransition(event?.from, event?.to), illegalTransitionMessage(event?.from, event?.to))
+      addDiagnostic(diagnostics, !FINAL_STATES.includes(previousStatus), `terminal state ${previousStatus} cannot have later events`)
+      const expectedAttempt = nextAttempt(previousSnapshot?.currentAttempt, event?.to)
+      addDiagnostic(diagnostics, event?.snapshot?.currentAttempt === expectedAttempt, `event[${index}] currentAttempt delta is invalid`)
+    }
+  })
+}
+
+export async function initRun(root, { taskId, mode = 'standard', budget, budgets }, runtime = {}) {
+  assertTaskId(taskId); assertMode(mode)
+  const effectiveBudget = { ...MODE_DEFAULTS[mode], ...(budget ?? budgets ?? {}) }
+  const budgetDiagnostics = []
+  validateBudgetShape(effectiveBudget, budgetDiagnostics)
+  if (budgetDiagnostics.length > 0) throw new Error(budgetDiagnostics.join('; '))
+  return withLock(root, MUTATION_LOCK_FILE, 'init', async ({ ownerId, updateMetadata }) => {
+    const timestamp = now()
+    const run = {
+      schemaVersion: SCHEMA_VERSION, taskId, mode, status: 'TRIAGE', eventSequence: 0, currentAttempt: 0,
+      bestCandidateId: null, budget: effectiveBudget, createdAt: timestamp, updatedAt: timestamp,
+    }
+    const ledger = {
+      schemaVersion: SCHEMA_VERSION, taskId, scope: { independentAuditPassed: 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)
+    await assertRunFilesDoNotExist(p)
+    const stagingName = `.run-state-init-${ownerId}`
+    const stagingRoot = join(root, stagingName)
+    const staged = paths(stagingRoot)
+    const published = []
+    await mkdir(stagingRoot)
+    await updateMetadata({ stagingDir: stagingName, ownedArtifacts: [LEDGER_FILE, EVENTS_FILE, RUN_FILE] })
+    try {
+      await writeFile(staged.ledger, `${JSON.stringify(ledger, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' })
+      await writeFile(staged.events, `${JSON.stringify(event)}\n`, { encoding: 'utf8', flag: 'wx' })
+      await writeFile(staged.run, `${JSON.stringify(run, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' })
+      for (const [source, target] of [[staged.ledger, p.ledger], [staged.events, p.events], [staged.run, p.run]]) {
+        await renameWithRetry(source, target, runtime)
+        published.push(target)
+        await runtime.hooks?.afterPublish?.({ file: target, count: published.length })
+      }
+      return clone(run)
+    } catch (error) {
+      for (const target of published.reverse()) await unlink(target).catch(cleanupError => { if (cleanupError.code !== 'ENOENT') throw cleanupError })
+      throw error
+    } finally {
+      for (const path of [staged.run, staged.events, staged.ledger]) await unlink(path).catch(error => { if (error.code !== 'ENOENT') throw error })
+      await rmdir(stagingRoot).catch(error => { if (!['ENOENT', 'ENOTEMPTY'].includes(error.code)) throw error })
+    }
+  }, runtime)
+}
+
+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')
+  if (ledger.issues.some(item => item.severity === 'critical' && item.status !== 'CLOSED')) throw new Error('critical issues remain open')
+  if (run.mode === 'high-assurance' && ledger.scope.independentAuditPassed !== true) throw new Error('independent audit must pass')
+}
+
+function validateTransitionInput(input) {
+  if (typeof input?.reason !== 'string' || input.reason.trim().length === 0) throw new Error('transition reason must be a nonempty string')
+  for (const key of ['evidenceIds', 'issueIds']) {
+    if (input[key] !== undefined && (!Array.isArray(input[key]) || input[key].some(id => typeof id !== 'string'))) throw new Error(`${key} must be an array of strings`)
+  }
+  if (linkedIds(input).length === 0) throw new Error('transition requires at least one evidence or issue ID')
+  if (input.patch !== undefined && (!isObject(input.patch) || Object.keys(input.patch).some(key => key !== 'bestCandidateId'))) throw new Error('patch may only contain bestCandidateId')
+  if (input.patch && (!Object.hasOwn(input.patch, 'bestCandidateId') || (input.patch.bestCandidateId !== null && typeof input.patch.bestCandidateId !== 'string'))) throw new Error('bestCandidateId must be a string or null')
+}
+
+function validateAuthoritativeState(run, ledger, events) {
+  const diagnostics = []
+  validateRunShape(run, diagnostics)
+  validateLedgerShape(ledger, diagnostics)
+  validateJournal(events, diagnostics)
+  if (run.taskId !== ledger.taskId || events.some(event => event.taskId !== run.taskId)) diagnostics.push('task mismatch')
+  const last = events.at(-1)
+  if (!last || run.eventSequence !== last.sequence) diagnostics.push('state/journal sequence mismatch')
+  if (!last || !deeplyEqual(run, last.snapshot)) diagnostics.push('state/journal snapshot mismatch')
+  if (diagnostics.length > 0) throw new Error(`invalid run state: ${diagnostics.join('; ')}`)
+}
+
+export async function transitionRun(root, input, runtime = {}) {
+  validateTransitionInput(input)
+  return withLock(root, MUTATION_LOCK_FILE, 'transition', async () => {
+    const p = paths(root)
+    const run = await readJson(p.run)
+    const ledger = await readJson(p.ledger)
+    const events = await readEvents(p.events)
+    validateAuthoritativeState(run, ledger, events)
+    if (!isAllowedTransition(run.status, input.to)) throw new Error(illegalTransitionMessage(run.status, input.to))
+    if (input.to === 'SOLVED') enforceSolvedGate(run, ledger)
+    const timestamp = now()
+    const bestCandidateId = input.patch && Object.hasOwn(input.patch, 'bestCandidateId') ? input.patch.bestCandidateId : run.bestCandidateId
+    const next = { ...run, status: input.to, currentAttempt: nextAttempt(run.currentAttempt, input.to), eventSequence: run.eventSequence + 1, bestCandidateId, updatedAt: timestamp }
+    const event = {
+      schemaVersion: SCHEMA_VERSION, sequence: next.eventSequence, type: 'STATUS_TRANSITION', taskId: run.taskId,
+      from: run.status, to: input.to, reason: input.reason, evidenceIds: input.evidenceIds ?? [], issueIds: input.issueIds ?? [], timestamp, snapshot: clone(next),
+    }
+    const prospectiveEvents = [...events, event]
+    validateAuthoritativeState(next, ledger, prospectiveEvents)
+    await appendFile(p.events, `${JSON.stringify(event)}\n`, 'utf8')
+    await atomicWrite(p.run, next, runtime)
+    return clone(next)
+  }, runtime)
+}
+
+async function readEvents(path) {
+  const text = await readFile(path, 'utf8')
+  if (!text.trim()) return []
+  return text.trimEnd().split(/\r?\n/).map((line, index) => {
+    try { return JSON.parse(line) } catch { throw new Error(`invalid event JSON at line ${index + 1}`) }
+  })
+}
+
+async function validateRunUnlocked(root, expectedTaskId) {
+  const diagnostics = []
+  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 }
+  validateRunShape(run, diagnostics)
+  validateLedgerShape(ledger, diagnostics)
+  validateJournal(events, diagnostics)
+  if (run.taskId !== ledger.taskId || events.some(event => event.taskId !== run.taskId) || (expectedTaskId && expectedTaskId !== run.taskId)) diagnostics.push('task mismatch')
+  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) }
+}
+
+export async function validateRun(root, expectedTaskId, runtime = {}) {
+  return withLock(root, MUTATION_LOCK_FILE, 'validate', () => validateRunUnlocked(root, expectedTaskId), runtime)
+}
+
+export async function recoverRun(root, runtime = {}) {
+  return withLock(root, MUTATION_LOCK_FILE, 'recover', async () => {
+    const p = paths(root)
+    const events = await readEvents(p.events)
+    if (events.length === 0) throw new Error('event journal is empty')
+    const last = events.at(-1)
+    const diagnostics = []
+    validateJournal(events, diagnostics)
+    if (diagnostics.length > 0) throw new Error(`malformed journal: ${diagnostics.join('; ')}`)
+    const solvedEvent = events.find(event => event.to === 'SOLVED')
+    if (solvedEvent) {
+      const ledger = await readJson(p.ledger)
+      enforceSolvedGate(solvedEvent.snapshot, ledger)
+    }
+    await runtime.hooks?.afterJournalValidated?.()
+    const snapshot = clone(last.snapshot)
+    await atomicWrite(p.run, snapshot, runtime)
+    return snapshot
+  }, runtime)
+}
+
+async function statusRunUnlocked(root) { return readJson(paths(root).run) }
+export async function statusRun(root, runtime = {}) {
+  return withLock(root, MUTATION_LOCK_FILE, 'status', () => statusRunUnlocked(root), runtime)
+}
+
+function parseOptions(args) {
+  const options = { _: [] }
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]
+    if (!token.startsWith('--')) options._.push(token)
+    else { const key = token.slice(2); const value = args[index + 1]; options[key] = value; index += 1 }
+  }
+  return options
+}
+async function cli(argv) {
+  const [command, rootArg = '.', ...rest] = 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 === 'validate') {
+    const result = await validateRun(root, options['task-id'])
+    if (!result.valid) process.exitCode = 1
+    return result
+  }
+  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]')
+}
+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/skills/math-modeling-audit/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: math-modeling-audit
+description: This skill should be used when the user asks to "独立核验数学模型", "检查推导", "寻找反例", "审计建模报告", "按 MCM/ICM 终审框架打分", "verify this model", or needs an artifact-only adversarial audit of mathematical claims, data, code, results, citations, or a competition paper.
+whenToUse: Use for existing artifacts and papers; do not take over open-ended model construction or silently rewrite the audited work.
+user-invocable: true
+---
+
+# Math Modeling Audit
+
+## Goal
+
+Independently decide which claims in an existing artifact pass, fail, or remain inconclusive, and why.
+
+## Interface
+
+Accept a paper, model, derivation, code/result artifact, or MathModelingAgent run. Optionally accept the original problem, competition year/code, target claims, and assurance level.
+
+Return per-claim verdicts, evidence levels, counterexamples, reproducibility findings, residual risk, and—only for MCM/ICM judging intent—the fixed final-panel report.
+
+## Workflow
+
+1. Freeze the artifact set and record review coverage.
+2. Reconstruct claims, assumptions, obligations, and evidence without trusting the author’s summary.
+3. Apply `references/verification-protocol.md` and `references/evidence-levels.md`.
+4. Audit data, parameters, leakage, citations, and reproducibility with `references/data-citation-audit.md`.
+5. Recompute applicable formulas and results through independent tools.
+6. Seek boundary cases, counterexamples, alternative explanations, and simpler models.
+7. Output PASS, FAIL, or INCONCLUSIVE per claim; do not silently repair the source.
+8. For MCM/ICM scoring intent only, load `references/mcm-icm-final-judge.md`, validate arithmetic with `scripts/mcm-score.mjs`, and preserve its fourteen-section output.
+
+## Invariants
+
+- Paper prose and solver success are not verification artifacts.
+- Missing evidence is reported, never supplied on the author’s behalf.
+- Lean verifies the formal statement, not its natural-language fidelity or data pipeline.
+- A score never feeds back into the solver’s SOLVED gate.
+- Disqualification risk stops ordinary award scoring.
+
+## Boundaries
+
+Do not edit the audited artifact. Do not reward complexity or presentation without evidence. Do not load the large MCM/ICM rubric for generic audits.

package/skills/math-modeling-audit/examples/audit-report.md

@@ -0,0 +1,13 @@
+# Audit Example
+
+## Claim C-004
+
+Claim: “The returned point is the global optimum.”
+
+Evidence supplied: one successful SLSQP run.
+
+Verdict: INCONCLUSIVE.
+
+Reason: solver success supports a stationary/best-found point only. The artifact contains no convexity proof, certified bound, multi-start/global search, or optimality gap.
+
+Required upgrade: weaken the claim to “best found local solution” or add an appropriate global-optimality certificate.