dsh-math-modeling-agent 0.4.1 → 0.5.0

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

@@ -1,707 +1,829 @@
-#!/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 = 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 }),
-  '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: ['RESEARCH', 'SCOPE_FROZEN', ...STOP_TRANSITIONS],
-  RESEARCH: ['SCOPE_FROZEN', 'CANDIDATES_READY', ...STOP_TRANSITIONS],
-  SCOPE_FROZEN: ['INPUT_PROFILED', ...STOP_TRANSITIONS],
-  INPUT_PROFILED: ['CLAIMS_REGISTERED', ...STOP_TRANSITIONS],
-  CLAIMS_REGISTERED: ['RESEARCH', '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],
-  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, 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`)
-  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, 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`)
-}
-
-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, 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}`)
-  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, contract }, 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, interactions: [], decisionStack: [], robustnessExempt: false, ...(contract === false ? { contractExempt: true } : {}) },
-      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)
-}
-
-/** The v2 interaction contract: decision records, decision-stack backtracking, and the robustness gate. */
-function hasDecisionRecord(scope, decisionPoint, { allowAuto = true } = {}) {
-  return Array.isArray(scope?.interactions) && scope.interactions.some(entry =>
-    entry && (entry.decisionPoint === decisionPoint || (allowAuto && entry.auto === true)))
-}
-/** D4 verdict records carry the attempt number they adjudicate: {decisionPoint:'D4', attempt: 2, ...} */
-function hasD4ForAttempt(scope, attempt) {
-  return Array.isArray(scope?.interactions) && scope.interactions.some(entry =>
-    entry && (entry.auto === true || (entry.decisionPoint === 'D4' && entry.attempt === attempt)))
-}
-function decisionStackIds(scope) {
-  return Array.isArray(scope?.decisionStack)
-    ? scope.decisionStack.filter(entry => entry && typeof entry.id === 'string').map(entry => entry.id)
-    : []
-}
-/** D2 records carry the subproblem id(s) they cover: {decisionPoint:'D2', scope:['SP1'], ...} */
-function hasSubproblemD2(scope, subproblem) {
-  if (!subproblem || !Array.isArray(scope?.interactions)) return true
-  return scope.interactions.some(entry => entry && entry.decisionPoint === 'D2' &&
-    (Array.isArray(entry.scope) ? entry.scope.includes(subproblem) : entry.subproblem === subproblem))
-}
-function interactionContractViolations(run, ledger, to, reason, subproblem) {
-  if (ledger.schemaVersion !== SCHEMA_VERSION) return []
-  const scope = ledger.scope ?? {}
-  if (scope.contractExempt === true) return []
-  const violations = []
-  const transitional = to !== undefined
-  const earlyStop = ['BLOCKED', 'CANCELLED'].includes(run.status)
-  const statusOrder = ['TRIAGE', 'RESEARCH', 'SCOPE_FROZEN', 'INPUT_PROFILED', 'CLAIMS_REGISTERED', 'CANDIDATES_READY', 'ATTEMPT', 'EXECUTE', 'VERIFY', 'REVISE', 'FORK']
-  const reached = (target) => transitional
-    ? to === target
-    : (statusOrder.indexOf(target) <= statusOrder.indexOf(run.status) && !earlyStop)
-  if (reached('SCOPE_FROZEN')) {
-    if (!hasDecisionRecord(scope, 'D0')) violations.push('D0 restatement interaction record missing (ledger.scope.interactions)')
-    if (!hasDecisionRecord(scope, 'D1')) violations.push('D1 routing interaction record missing (ledger.scope.interactions)')
-    if (!hasDecisionRecord(scope, 'D-R', { allowAuto: false })) violations.push('D-R literature-research interaction record missing (literature survey precedes restatement; auto-authorization is not accepted)')
-  }
-  if (reached('CLAIMS_REGISTERED') && !hasDecisionRecord(scope, 'D2-G')) violations.push('D2-G global-assumptions interaction record missing (global assumptions must be confirmed before claims registration)')
-  const candidatesGate = reached('CANDIDATES_READY')
-  if (candidatesGate && !hasDecisionRecord(scope, 'D-R', { allowAuto: false })) violations.push('D-R literature-research interaction record missing (backstop check)')
-  const afterCandidates = ['CANDIDATES_READY', 'ATTEMPT', 'EXECUTE', 'VERIFY', 'REVISE', 'FORK', ...FINAL_STATES]
-  const enteringAttemptFromCandidates = transitional ? (to === 'ATTEMPT' && run.status === 'CANDIDATES_READY') : (run.currentAttempt >= 1)
-  if (enteringAttemptFromCandidates) {
-    if (transitional && !subproblem) violations.push('ATTEMPT from CANDIDATES_READY requires --subproblem <id>')
-    if (!hasDecisionRecord(scope, 'D3')) violations.push('D3 direction-selection interaction record missing')
-    if (transitional && subproblem && !hasSubproblemD2(scope, subproblem)) violations.push(`D2 assumption interaction record missing for subproblem ${subproblem} (run the gate with --subproblem <id>)`)
-  }
-  const enteringTerminalFromVerify = transitional
-    ? (FINAL_STATES.includes(to) && run.status === 'VERIFY')
-    : (FINAL_STATES.includes(run.status) && !['BLOCKED', 'CANCELLED'].includes(run.status))
-  if (enteringTerminalFromVerify && !hasD4ForAttempt(scope, run.currentAttempt)) violations.push(`D4 verdict interaction record for attempt ${run.currentAttempt} missing`)
-  if (transitional && (to === 'REVISE' || (to === 'RESEARCH' && run.status === 'VERIFY'))) {
-    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) {
-    if (scope.robustnessExempt !== true) {
-      const robos = Array.isArray(ledger.obligations) ? ledger.obligations.filter(o => o && o.kind === 'robustness' && o.required !== false) : []
-      const allPassed = robos.length > 0 && robos.every(o => o.status === 'PASS')
-      if (!allPassed) violations.push(`terminal state requires ALL ${robos.length} required robustness obligations to be PASS (or scope.robustnessExempt: true)`)
-    }
-    const subs = Array.isArray(ledger.subproblems) ? ledger.subproblems : []
-    if (subs.length > 0) {
-      const done = (sp) => sp.status === 'DONE' || sp.status === 'CLOSED'
-      const unfinished = subs.filter(sp => !done(sp))
-      if (unfinished.length > 0) violations.push(`terminal state requires every subproblem DONE (open: ${unfinished.map(sp => sp.id).join(', ')})`)
-      const depGaps = subs.filter(sp => done(sp) && Array.isArray(sp.dependencies) && sp.dependencies.some(dep => {
-        const d = subs.find(x => x.id === dep); return d === undefined || !done(d)
-      }))
-      if (depGaps.length > 0) violations.push(`subproblem dependencies incomplete: ${depGaps.map(sp => sp.id).join(', ')}`)
-    }
-    if (scope.cleanupPassed !== true) violations.push('terminal state requires scope.cleanupPassed: true (run the cleanup checklist in run-directory.md)')
-  }
-  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')
-  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 = []
-  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, warnings }
-  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')
-  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)) {
-      diagnostics.push(`interaction contract: ${violation}`)
-    }
-    if (run.currentAttempt >= 1) {
-      const reportPath = join(root, 'attempts', String(run.currentAttempt), 'report.md')
-      try {
-        const reportText = await readFile(reportPath, 'utf8')
-        for (const section of ['问题重述', '问题分析', '模型假设', '模型建立与求解', '验证', '鲁棒性', '评价与改进', '参考文献']) {
-          if (!reportText.includes(section)) warnings.push(`attempt ${run.currentAttempt} report.md missing runlog digest section: ${section}`)
-        }
-      } catch {
-        warnings.push(`attempt ${run.currentAttempt} report.md unreadable (runlog digest required)`)
-      }
-    }
-    for (const assumption of Array.isArray(ledger.assumptions) ? ledger.assumptions : []) {
-      const revised = assumption && (assumption.status === 'revised' || (Array.isArray(assumption.revisionHistory) && assumption.revisionHistory.length > 0))
-      if (!revised) continue
-      for (const claim of Array.isArray(ledger.claims) ? ledger.claims : []) {
-        const depends = claim && Array.isArray(claim.assumptions) && claim.assumptions.includes(assumption.id)
-        if (depends && claim.status === 'VERIFIED' && (!Array.isArray(claim.evidenceIds) || claim.evidenceIds.length === 0)) {
-          warnings.push(`claim ${claim.id} depends on revised assumption ${assumption.id} but has no post-revision evidence`)
-        }
-      }
-    }
-  }
-  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 and has NO escape hatch.
- */
-export async function gateTransition(root, { to, reason, subproblem }, 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, subproblem)
-    const exempt = ledger.scope?.contractExempt === true
-    if (to === 'CANDIDATES_READY' && !exempt) {
-      const sourcesPath = join(root, 'research', 'sources.jsonl')
-      try {
-        if (!(await readFile(sourcesPath, 'utf8')).trim()) violations.push('research/sources.jsonl is empty (pre-modeling literature survey artifacts are mandatory)')
-      } catch {
-        violations.push('research/sources.jsonl missing (pre-modeling literature survey artifacts are mandatory)')
-      }
-    }
-    if (FINAL_STATES.includes(to) && !['BLOCKED', 'CANCELLED'].includes(to) && !exempt) {
-      const reportPath = join(root, 'attempts', String(run.currentAttempt), 'report.md')
-      try {
-        await readFile(reportPath, 'utf8')
-      } catch {
-        violations.push(`attempts/${run.currentAttempt}/report.md missing (write the runlog report before a terminal transition)`)
-      }
-    }
-    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)
-    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 === 'gate') {
-    const result = await gateTransition(root, { to: options.to, reason: options.reason, subproblem: options.subproblem })
-    if (!result.allowed) process.exitCode = 1
-    return result
-  }
-  if (command === 'transition') {
-    const gate = await gateTransition(root, { to: options.to, reason: options.reason, subproblem: options.subproblem })
-    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
-    return result
-  }
-  if (command === 'recover') return recoverRun(root)
-  if (command === 'status') return statusRun(root)
-  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 })
+#!/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'
+
+import { validateCoverage } from './report-contract.mjs'
+
+export const SCHEMA_VERSION = 3
+export const SUPPORTED_SCHEMA_VERSIONS = [1, 2, 3]
+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 }),
+  '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', 'EVALUATE', 'CORRECTION_REQUIRED', '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: ['RESEARCH', 'SCOPE_FROZEN', ...STOP_TRANSITIONS],
+  RESEARCH: ['SCOPE_FROZEN', 'CANDIDATES_READY', ...STOP_TRANSITIONS],
+  SCOPE_FROZEN: ['INPUT_PROFILED', ...STOP_TRANSITIONS],
+  INPUT_PROFILED: ['CLAIMS_REGISTERED', ...STOP_TRANSITIONS],
+  CLAIMS_REGISTERED: ['RESEARCH', 'CANDIDATES_READY', ...STOP_TRANSITIONS],
+  CANDIDATES_READY: ['ATTEMPT', ...STOP_TRANSITIONS],
+  ATTEMPT: ['EXECUTE', ...STOP_TRANSITIONS],
+  EXECUTE: ['VERIFY', ...STOP_TRANSITIONS],
+  VERIFY: ['EVALUATE', 'REVISE', 'RESEARCH', 'FORK', ...FINAL_STATES],
+  EVALUATE: ['CORRECTION_REQUIRED', 'REVISE', 'CONDITIONAL', ...STOP_TRANSITIONS],
+  CORRECTION_REQUIRED: ['REVISE', ...STOP_TRANSITIONS],
+  REVISE: ['ATTEMPT', ...STOP_TRANSITIONS],
+  FORK: ['ATTEMPT', ...STOP_TRANSITIONS],
+})
+const TASK_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const RUN_KEYS_V2 = ['schemaVersion', 'taskId', 'mode', 'status', 'eventSequence', 'currentAttempt', 'bestCandidateId', 'budget', 'createdAt', 'updatedAt']
+const RUN_KEYS = ['schemaVersion', 'taskId', 'mode', 'status', 'eventSequence', 'currentAttempt', 'bestCandidateId', 'budget', 'createdAt', 'updatedAt', 'lineageId', 'parentRunId', 'revision', 'inputSnapshotHash', 'evidenceGraphHash']
+const IMMUTABLE_RUN_KEYS = ['schemaVersion', 'taskId', 'mode', 'budget', 'createdAt', 'lineageId', 'parentRunId', 'revision']
+const LEDGER_KEYS_V2 = ['schemaVersion', 'taskId', 'scope', 'assumptions', 'claims', 'obligations', 'subproblems', 'candidates', 'issues']
+const LEDGER_KEYS = [...LEDGER_KEYS_V2, 'requirements', 'evidence', 'verifications', 'failures']
+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') {
+  const keys = run?.schemaVersion >= 3 ? RUN_KEYS : RUN_KEYS_V2
+  addDiagnostic(diagnostics, exactKeys(run, keys), `${prefix} must contain exactly the contracted fields`)
+  if (!isObject(run)) return
+  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`)
+  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`)
+  if (run.schemaVersion >= 3) {
+    addDiagnostic(diagnostics, typeof run.lineageId === 'string' && run.lineageId.length > 0, `${prefix}.lineageId must be a nonempty string`)
+    addDiagnostic(diagnostics, run.parentRunId === null || typeof run.parentRunId === 'string', `${prefix}.parentRunId must be a string or null`)
+    addDiagnostic(diagnostics, nonnegativeInteger(run.revision), `${prefix}.revision must be a nonnegative integer`)
+    addDiagnostic(diagnostics, run.inputSnapshotHash === null || typeof run.inputSnapshotHash === 'string', `${prefix}.inputSnapshotHash must be a string or null`)
+    addDiagnostic(diagnostics, run.evidenceGraphHash === null || typeof run.evidenceGraphHash === 'string', `${prefix}.evidenceGraphHash must be a string or null`)
+  }
+}
+
+function validateLedgerShape(ledger, diagnostics) {
+  const keys = ledger?.schemaVersion >= 3 ? LEDGER_KEYS : LEDGER_KEYS_V2
+  addDiagnostic(diagnostics, exactKeys(ledger, keys), 'ledger must contain exactly the contracted fields')
+  if (!isObject(ledger)) return
+  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')
+  const arrays = ['assumptions', 'claims', 'obligations', 'subproblems', 'candidates', 'issues']
+  if (ledger.schemaVersion >= 3) arrays.push('requirements', 'evidence', 'verifications', 'failures')
+  for (const key of arrays) 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, 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}`)
+  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, contract }, 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,
+      lineageId: taskId, parentRunId: null, revision: 0, inputSnapshotHash: null, evidenceGraphHash: null,
+    }
+    const ledger = {
+      schemaVersion: SCHEMA_VERSION, taskId,
+      scope: { independentAuditPassed: false, interactions: [], decisionStack: [], robustnessExempt: false, ...(contract === false ? { contractExempt: true } : {}) },
+      assumptions: [], claims: [], obligations: [], subproblems: [], candidates: [], issues: [],
+      requirements: [], evidence: [], verifications: [], failures: [],
+    }
+    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 graphItem(graph, collection, id, label) {
+  const items = Array.isArray(graph?.[collection]) ? graph[collection] : []
+  const item = items.find(value => value?.id === id)
+  if (!item) throw new Error('unknown ' + label + ' id: ' + id)
+  return item
+}
+
+function linkedVerifications(graph, obligation) {
+  const ids = Array.isArray(obligation.verificationIds) ? obligation.verificationIds : []
+  const values = Array.isArray(graph?.verifications) ? graph.verifications : []
+  return ids.map(id => values.find(value => value?.id === id)).filter(Boolean)
+}
+
+export function aggregateObligation(graph, id) {
+  const obligation = graphItem(graph, 'obligations', id, 'obligation')
+  if (obligation.status === 'WAIVED') return 'WAIVED'
+  if (obligation.stale === true || obligation.status === 'STALE') return 'STALE'
+  if (obligation.status === 'BLOCKED') return 'BLOCKED'
+  const verifications = linkedVerifications(graph, obligation)
+  if (verifications.some(value => value.verdict === 'FAIL')) return 'BLOCKED'
+  const required = Number.isInteger(obligation.minimumEvidenceCount) && obligation.minimumEvidenceCount > 0
+    ? obligation.minimumEvidenceCount
+    : 1
+  const independentKeys = new Set()
+  for (const verification of verifications) {
+    if (verification.verdict === 'PASS' && typeof verification.independenceKey === 'string' && verification.independenceKey.trim() !== '') independentKeys.add(verification.independenceKey)
+  }
+  if (independentKeys.size >= required) return 'SATISFIED'
+  return 'OPEN'
+}
+
+export function aggregateClaim(graph, id) {
+  const claim = graphItem(graph, 'claims', id, 'claim')
+  if (claim.stale === true || claim.verdict === 'STALE') return 'STALE'
+  if (claim.verdict === 'REFUTED') return 'REFUTED'
+  const obligationIds = Array.isArray(claim.obligationIds) ? claim.obligationIds : []
+  if (obligationIds.length === 0) return claim.verdict === 'SUPPORTED' ? 'SUPPORTED' : 'INCONCLUSIVE'
+  const statuses = obligationIds.map(obligationId => aggregateObligation(graph, obligationId))
+  if (statuses.some(status => status === 'BLOCKED')) return 'INCONCLUSIVE'
+  if (statuses.some(status => status === 'STALE')) return 'STALE'
+  if (statuses.some(status => status === 'WAIVED')) return 'CONDITIONAL'
+  return statuses.every(status => status === 'SATISFIED') ? 'SUPPORTED' : 'INCONCLUSIVE'
+}
+
+export function classifyGate(graph, targetState) {
+  const blockers = []
+  const conditionals = []
+  for (const obligation of Array.isArray(graph?.obligations) ? graph.obligations : []) {
+    if (obligation.required === false) continue
+    const status = aggregateObligation(graph, obligation.id)
+    if (status === 'BLOCKED' || status === 'STALE') blockers.push({ id: obligation.id, status, reason: 'required obligation is not valid' })
+    else if (status === 'WAIVED') conditionals.push({ id: obligation.id, status, reason: 'user waiver' })
+    else if (status !== 'SATISFIED') {
+      if (targetState === 'CONDITIONAL') conditionals.push({ id: obligation.id, status, reason: 'required evidence is incomplete' })
+      else blockers.push({ id: obligation.id, status, reason: 'required obligation is not satisfied' })
+    }
+  }
+  for (const claim of Array.isArray(graph?.claims) ? graph.claims : []) {
+    const verdict = aggregateClaim(graph, claim.id)
+    if (verdict === 'REFUTED' || verdict === 'STALE') blockers.push({ id: claim.id, verdict, reason: 'claim is refuted or stale' })
+    else if (verdict === 'CONDITIONAL') conditionals.push({ id: claim.id, verdict, reason: 'claim scope is conditional' })
+    else if (verdict === 'INCONCLUSIVE') {
+      if (targetState === 'CONDITIONAL') conditionals.push({ id: claim.id, verdict, reason: 'claim evidence is incomplete' })
+      else blockers.push({ id: claim.id, verdict, reason: 'claim is not supported' })
+    }
+  }
+  return { allowed: blockers.length === 0 && (targetState !== 'SOLVED' || conditionals.length === 0), blockers, conditionals, requiredNextState: blockers.length > 0 ? 'REVISE' : (conditionals.length > 0 ? 'CONDITIONAL' : targetState) }
+}
+
+/** The v3 interaction contract: decision records, layered verdicts, and the robustness gate. */
+function hasDecisionRecord(scope, decisionPoint, { allowAuto = true } = {}) {
+  return Array.isArray(scope?.interactions) && scope.interactions.some(entry =>
+    entry && (entry.decisionPoint === decisionPoint || (allowAuto && entry.auto === true)))
+}
+/** D4 verdict records carry the attempt number they adjudicate: {decisionPoint:'D4', attempt: 2, ...} */
+function hasD4ForAttempt(scope, attempt) {
+  return Array.isArray(scope?.interactions) && scope.interactions.some(entry =>
+    entry && (entry.auto === true || (entry.decisionPoint === 'D4' && entry.attempt === attempt)))
+}
+function decisionStackIds(scope) {
+  return Array.isArray(scope?.decisionStack)
+    ? scope.decisionStack.filter(entry => entry && typeof entry.id === 'string').map(entry => entry.id)
+    : []
+}
+/** D2 records carry the subproblem id(s) they cover: {decisionPoint:'D2', scope:['SP1'], ...} */
+function hasSubproblemD2(scope, subproblem) {
+  if (!subproblem || !Array.isArray(scope?.interactions)) return true
+  return scope.interactions.some(entry => entry && entry.decisionPoint === 'D2' &&
+    (Array.isArray(entry.scope) ? entry.scope.includes(subproblem) : entry.subproblem === subproblem))
+}
+function interactionContractViolations(run, ledger, to, reason, subproblem) {
+  if (ledger.schemaVersion !== SCHEMA_VERSION) return []
+  const scope = ledger.scope ?? {}
+  if (scope.contractExempt === true) return []
+  const violations = []
+  const transitional = to !== undefined
+  const earlyStop = ['BLOCKED', 'CANCELLED'].includes(run.status)
+  const statusOrder = ['TRIAGE', 'RESEARCH', 'SCOPE_FROZEN', 'INPUT_PROFILED', 'CLAIMS_REGISTERED', 'CANDIDATES_READY', 'ATTEMPT', 'EXECUTE', 'VERIFY', 'EVALUATE', 'CORRECTION_REQUIRED', 'REVISE', 'FORK']
+  const reached = (target) => transitional
+    ? to === target
+    : (statusOrder.indexOf(target) <= statusOrder.indexOf(run.status) && !earlyStop)
+  if (reached('SCOPE_FROZEN')) {
+    if (!hasDecisionRecord(scope, 'D0')) violations.push('D0 restatement interaction record missing (ledger.scope.interactions)')
+    if (!hasDecisionRecord(scope, 'D1')) violations.push('D1 routing interaction record missing (ledger.scope.interactions)')
+    if (!hasDecisionRecord(scope, 'D-R', { allowAuto: false })) violations.push('D-R literature-research interaction record missing (literature survey precedes restatement; auto-authorization is not accepted)')
+  }
+  if (reached('CLAIMS_REGISTERED') && !hasDecisionRecord(scope, 'D2-G')) violations.push('D2-G global-assumptions interaction record missing (global assumptions must be confirmed before claims registration)')
+  const candidatesGate = reached('CANDIDATES_READY')
+  if (candidatesGate && !hasDecisionRecord(scope, 'D-R', { allowAuto: false })) violations.push('D-R literature-research interaction record missing (backstop check)')
+  const afterCandidates = ['CANDIDATES_READY', 'ATTEMPT', 'EXECUTE', 'VERIFY', 'REVISE', 'FORK', ...FINAL_STATES]
+  const enteringAttemptFromCandidates = transitional ? (to === 'ATTEMPT' && run.status === 'CANDIDATES_READY') : (run.currentAttempt >= 1)
+  if (enteringAttemptFromCandidates) {
+    if (transitional && !subproblem) violations.push('ATTEMPT from CANDIDATES_READY requires --subproblem <id>')
+    if (!hasDecisionRecord(scope, 'D3')) violations.push('D3 direction-selection interaction record missing')
+    if (transitional && subproblem && !hasSubproblemD2(scope, subproblem)) violations.push(`D2 assumption interaction record missing for subproblem ${subproblem} (run the gate with --subproblem <id>)`)
+  }
+  const enteringTerminalFromVerify = transitional
+    ? (FINAL_STATES.includes(to) && run.status === 'VERIFY')
+    : (FINAL_STATES.includes(run.status) && !['BLOCKED', 'CANCELLED'].includes(run.status))
+  if (enteringTerminalFromVerify && !hasD4ForAttempt(scope, run.currentAttempt)) violations.push(`D4 verdict interaction record for attempt ${run.currentAttempt} missing`)
+  if (transitional && (to === 'REVISE' || (to === 'RESEARCH' && run.status === 'VERIFY'))) {
+    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) {
+    if (to === 'SOLVED' && scope.robustnessExempt !== true) {
+      const robos = Array.isArray(ledger.obligations) ? ledger.obligations.filter(o => o && o.kind === 'robustness' && o.required !== false) : []
+      const allSatisfied = robos.length > 0 && robos.every(o => o.status === 'SATISFIED' || (ledger.schemaVersion < 3 && o.status === 'PASS'))
+      if (!allSatisfied) violations.push(`terminal state requires ALL ${robos.length} required robustness obligations to be SATISFIED (or scope.robustnessExempt: true)`)
+    }
+    const subs = Array.isArray(ledger.subproblems) ? ledger.subproblems : []
+    if (subs.length > 0) {
+      const done = (sp) => sp.status === 'DONE' || sp.status === 'CLOSED'
+      const unfinished = subs.filter(sp => !done(sp))
+      if (unfinished.length > 0) violations.push(`terminal state requires every subproblem DONE (open: ${unfinished.map(sp => sp.id).join(', ')})`)
+      const depGaps = subs.filter(sp => done(sp) && Array.isArray(sp.dependencies) && sp.dependencies.some(dep => {
+        const d = subs.find(x => x.id === dep); return d === undefined || !done(d)
+      }))
+      if (depGaps.length > 0) violations.push(`subproblem dependencies incomplete: ${depGaps.map(sp => sp.id).join(', ')}`)
+    }
+    if (scope.cleanupPassed !== true) violations.push('terminal state requires scope.cleanupPassed: true (run the cleanup checklist in run-directory.md)')
+  }
+  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')
+  const graphClaims = ledger.schemaVersion >= 3 && ledger.claims.some(item => Object.hasOwn(item, 'verdict') || Object.hasOwn(item, 'obligationIds'))
+  if (graphClaims) {
+    const gate = classifyGate(ledger, 'SOLVED')
+    if (gate.blockers.length > 0) throw new Error('required obligations remain open: ' + gate.blockers.map(item => item.id).join(', '))
+    if (gate.conditionals.length > 0) throw new Error('SOLVED cannot accept conditional claims: ' + gate.conditionals.map(item => item.id).join(', '))
+  } else if (ledger.obligations.some(item => item.required !== false && item.status !== 'PASS' && item.status !== 'SATISFIED')) {
+    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 = []
+  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, warnings }
+  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')
+  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)) {
+      diagnostics.push(`interaction contract: ${violation}`)
+    }
+    if (run.currentAttempt >= 1) {
+      const reportPath = join(root, 'attempts', String(run.currentAttempt), 'report.md')
+      try {
+        const reportText = await readFile(reportPath, 'utf8')
+        for (const section of ['问题重述', '问题分析', '模型假设', '模型建立与求解', '验证', '鲁棒性', '评价与改进', '参考文献']) {
+          if (!reportText.includes(section)) warnings.push(`attempt ${run.currentAttempt} report.md missing runlog digest section: ${section}`)
+        }
+      } catch {
+        warnings.push(`attempt ${run.currentAttempt} report.md unreadable (runlog digest required)`)
+      }
+    }
+    for (const assumption of Array.isArray(ledger.assumptions) ? ledger.assumptions : []) {
+      const revised = assumption && (assumption.status === 'revised' || (Array.isArray(assumption.revisionHistory) && assumption.revisionHistory.length > 0))
+      if (!revised) continue
+      for (const claim of Array.isArray(ledger.claims) ? ledger.claims : []) {
+        const depends = claim && Array.isArray(claim.assumptions) && claim.assumptions.includes(assumption.id)
+        if (depends && claim.status === 'VERIFIED' && (!Array.isArray(claim.evidenceIds) || claim.evidenceIds.length === 0)) {
+          warnings.push(`claim ${claim.id} depends on revised assumption ${assumption.id} but has no post-revision evidence`)
+        }
+      }
+    }
+  }
+  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)
+}
+
+async function coverageGate(root, ledger, to) {
+  const gatedStates = new Set(['EVALUATE', 'SOLVED', 'CONDITIONAL'])
+  if (!gatedStates.has(to) || ledger.schemaVersion < 3 || !Array.isArray(ledger.requirements) || ledger.requirements.length === 0) return { blockers: [], conditionals: [], violations: [] }
+  const path = join(root, 'answer-coverage.json')
+  let raw
+  try { raw = JSON.parse(await readFile(path, 'utf8')) } catch (error) {
+    const message = error.code === 'ENOENT' ? 'answer-coverage.json missing' : 'answer-coverage.json invalid: ' + error.message
+    return { blockers: [{ id: 'coverage', reason: message }], conditionals: [], violations: [message] }
+  }
+  const entries = Array.isArray(raw) ? raw : raw.entries
+  const result = validateCoverage(entries)
+  const blockers = result.blockers.map(id => ({ id, reason: 'requirement coverage is ' + id }))
+  const conditionals = result.conditionals.map(id => ({ id, reason: 'partial requirement coverage is ' + id }))
+  if (to === 'SOLVED' && conditionals.length > 0) {
+    blockers.push(...conditionals)
+    conditionals.length = 0
+  }
+  return { blockers, conditionals, violations: [...blockers, ...conditionals].map(item => item.reason) }
+}
+
+/**
+ * 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 and has NO escape hatch.
+ */
+export async function gateTransition(root, { to, reason, subproblem }, 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, subproblem)
+    const coverage = await coverageGate(root, ledger, to)
+    violations.push(...coverage.violations)
+    const blockers = [
+      ...violations.map(reason => ({ id: 'interaction', reason })),
+      ...coverage.blockers,
+    ]
+    const conditionals = [...coverage.conditionals]
+    const exempt = ledger.scope?.contractExempt === true
+    if (to === 'CANDIDATES_READY' && !exempt) {
+      const sourcesPath = join(root, 'research', 'sources.jsonl')
+      try {
+        if (!(await readFile(sourcesPath, 'utf8')).trim()) violations.push('research/sources.jsonl is empty (pre-modeling literature survey artifacts are mandatory)')
+      } catch {
+        violations.push('research/sources.jsonl missing (pre-modeling literature survey artifacts are mandatory)')
+      }
+    }
+    if (FINAL_STATES.includes(to) && !['BLOCKED', 'CANCELLED'].includes(to) && !exempt) {
+      const reportPath = join(root, 'attempts', String(run.currentAttempt), 'report.md')
+      try {
+        await readFile(reportPath, 'utf8')
+      } catch {
+        violations.push(`attempts/${run.currentAttempt}/report.md missing (write the runlog report before a terminal transition)`)
+      }
+    }
+    return { allowed: blockers.length === 0 && conditionals.length === 0, violations, blockers, conditionals, requiredNextState: blockers.length > 0 ? 'REVISE' : (conditionals.length > 0 ? 'CONDITIONAL' : to), status: run.status }
+  }, 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 === 'gate') {
+    const result = await gateTransition(root, { to: options.to, reason: options.reason, subproblem: options.subproblem })
+    if (!result.allowed) process.exitCode = 1
+    return result
+  }
+  if (command === 'transition') {
+    const gate = await gateTransition(root, { to: options.to, reason: options.reason, subproblem: options.subproblem })
+    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
+    return result
+  }
+  if (command === 'recover') return recoverRun(root)
+  if (command === 'status') return statusRun(root)
+  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 })