dsh-math-modeling-agent 0.3.1 → 0.4.1

package/README.md

@@ -71,6 +71,10 @@ NOT_CHECKED → DERIVED → EXECUTED → VERIFIED → INDEPENDENTLY_VERIFIED →
 
 工具只是产生证据的方式，可以替换，工作流不变。
 
+本插件保留原 GitHub 项目的核心行为：问题/附件探查、子问题顺序求解、Modeler → Analyzer → Correction 迭代、逐轮日志和可恢复运行；对应关系见 `skills/math-modeling-agent/references/original-project-parity.md`。
+
+数学计算后端扩展位于 `skills/math-modeling-agent/scripts/computation/`：它只负责探测可调用后端、生成能力快照和校验计算记录，不捆绑 Mathematica/SageMath 等外部引擎。
+
 - **Python** 可选（推荐）：需要计算时在运行目录内创建隔离环境（数值计算、数据分析、优化、仿真、绘图、独立重算）
 - **Lean** 可选：形式化验证；不自动安装；**形式命题被证明 ≠ 现实主张被证明**
 - **Wolfram** 可选：符号计算、解析推导、恒等式验证
@@ -108,7 +112,7 @@ D3 方向/D4 裁决），`run-state.mjs gate` 在每次状态转移前强制校
 安装：
 
 ```bash
-dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.3.1
+dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.4.1
 dsh --profile web --dump-config   # 检查组合层（应看到 dsh-math-modeling-agent-skills 行）
 dsh web                          # 重启以加载插件
 ```
@@ -118,6 +122,17 @@ dsh web                          # 重启以加载插件
 不要用 `npm install` 代替，那会装到错误位置。如本机镜像源同步滞后，可显式走官方源：
 `dsh plugin --profile web add dsh-math-modeling-agent --registry=https://registry.npmjs.org/`）
 
+维护者在发布后应分别核对 GitHub 解包目录、npm tarball 解包目录和 profile
+安装目录：
+
+```bash
+node skills/math-modeling-agent/scripts/distribution-parity.mjs <source-root> <candidate-root>
+```
+
+该命令比较 package.json `files` allowlist 内所有文件的 SHA-256；它不把 AI
+解题中的偶发失败当作分发失败。`dsh --profile web --dump-config` 用于检查组合，
+但新版 DSH 可能重写 profile 的空 `cordis.yml`，不是严格只读操作。
+
 开始建模——直接描述任务即可。每个环节都是人与 LLM 的深度信息交换：LLM 给出带依据链的
 完整分析（题面原句/数据证据/文献/显式判断标记），你纠正、补充背景或提供自己的参考文献，
 LLM 更新并展示差异。建模前必须先做文献调研（AI 检索原理与方法文献，你可增删），每个候选

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-math-modeling-agent",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Evidence-driven mathematical modeling and verification skills for DeepSeek Harness",
   "type": "module",
   "files": [

package/skills/math-modeling-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: math-modeling-agent
-description: This skill should be used when the user asks to "建立数学模型", "解决数学建模题", "继续上次建模", "寻找新的建模方向", "solve this modeling problem", or needs an evidence-backed mathematical model with computation, research, verification, per-attempt reports, and resumable state.
-whenToUse: Use for open-ended mathematical modeling, prediction, optimization, estimation, simulation, mechanism, decision, or multi-part contest problems; do not use for auditing an already completed artifact without changing it.
+description: 当用户要求分析数学建模题、读取题目附件、建立预测/优化/估计/仿真模型、比较建模方向、执行数值验证、进行鲁棒性分析或继续已有建模项目时使用。
+whenToUse: 用于开放式数学建模、预测、优化、估计、仿真、机制分析、决策和多小问竞赛题；已有成果的独立审计改用 math-modeling-audit，不在此处静默改写被审计成果。
 user-invocable: true
 ---
 
@@ -17,7 +17,7 @@ Accept problem text, attachments, or an existing run directory.
 
 Interaction model (references/interaction-protocol.md): execution details stay autonomous (file names, tool adapters, state fields), but every model-shaping decision is a DEEP three-beat exchange — LLM presents a complete analysis with its evidence chain, the user responds with substance (corrections, background, their own references), the LLM updates the artifact and shows the delta. Decision points: D0 six-section restatement / D1 routing once per task, D-R literature research before any candidate is built, D2 assumptions and D3 direction per subproblem, D2' on mid-subproblem discoveries, D4 verdict per round. Show the runlog digest in the chat after every round (references/report-contract.md); announce one status line before every transition; the user may interrupt at any time.
 
-Return a concise current status, supported claims, unresolved obligations, attempt delta, artifact path, and next action or final report.
+Return a concise current status, supported claims, unresolved obligations, attempt delta, artifact path, and next action or final report. The legacy Modeler → Analyzer → Correction behavior mapping is recorded in `references/original-project-parity.md`.
 
 ## Default workflow
 
@@ -47,6 +47,19 @@ Return a concise current status, supported claims, unresolved obligations, attem
 - Continue only when a round closes an obligation, adds reproducible evidence, removes a blocker, tightens uncertainty, or refutes a candidate.
 - The run directory stays clean at every moment, and every failed path is preserved in its own folder (references/run-directory.md).
 
+## Computation tool extension
+
+When a computation is required, first call the bundled backend probe:
+`python scripts/computation/probe_backends.py`
+(or the `.ps1` entrypoint when Python is unavailable). Choose only a backend
+reported callable; record the primary route and fallback. Use
+`scripts/computation/backend_inventory.py` with a run-local `--state-file`
+when a persistent capability snapshot is needed. For reproducible/file or
+high-assurance work, initialize and validate
+`scripts/computation/computation_record.py`. These scripts discover and record
+external backends; they are not mathematical engines and their successful
+execution is not proof.
+
 ## Tool degradation
 
 Python is recommended but not required for installation. Lean and Wolfram are optional. If a required tool is unavailable, weaken the claim and report the missing obligation; never pretend execution or formal verification occurred.

package/skills/math-modeling-agent/references/original-project-parity.md

@@ -0,0 +1,19 @@
+# Original GitHub workflow parity
+
+The DSH bundle is a faithful workflow migration of the original
+MathModelingAgent project, not a replacement of its useful behavior.
+
+| Original GitHub behavior | DSH realization |
+|---|---|
+| PDF/problem extraction in `code/agent.py` | intake D0 and the subproblem DAG |
+| Excel attachment profiling in `code/data_analyzer.py` | INPUT_PROFILED and the run input manifest |
+| sequential subproblem solving | dependency-ordered SPi loop |
+| Modeler → Analyzer → Correction loop in `code/prompts.py` | explorer/modeler → verifier/analyzer → corrector/revise |
+| per-round thinking and run logs | attempts/<n>/report.md, events.jsonl, and chat runlog digest |
+| acceptance/rejection and stagnation control | D4 verdict, progress test, REVISE/FORK, and resumable non-SOLVED states |
+| hash-based cache and resume | run-local artifacts, evidence links, and state recovery |
+
+The migration deliberately replaces private chain-of-thought storage with
+human-readable reasoning, evidence, and reproducible artifacts. The roles and
+loop semantics remain; only the execution substrate changes from the legacy
+Python CLI to DSH skills and state files.

package/skills/math-modeling-agent/references/subagent-dispatch.md

@@ -7,8 +7,9 @@ produce reports and evidence. Never let a subagent mutate run-state directly.
 
 | Class | Role (lineage) | When | Count |
 |---|---|---|---|
-| explorer | parallel candidate exploration (legacy Modeler) | CANDIDATES_READY, >= 2 independent directions | 1 per direction |
-| verifier | blind re-verification (legacy Analyzer/Correction) | before terminal: key numeric/feasibility claims | Standard: 1 per task; High-Assurance: 1 per claim |
+| explorer | parallel candidate exploration (original Modeler lineage) | CANDIDATES_READY, >= 2 independent directions | 1 per direction |
+| verifier | blind re-verification (original Analyzer lineage) | before terminal: key numeric/feasibility claims | Standard: 1 per task; High-Assurance: 1 per claim |
+| corrector | apply accepted critique and produce the next attempt (original Correction lineage) | after a failed/conditional verdict | 1 per selected direction |
 | auditor | artifact-only audit (math-modeling-audit skill) | before SOLVED | High-Assurance: mandatory; else optional |
 
 ## Brief template (self-contained; subagents see no parent context)

package/skills/math-modeling-agent/references/tool-policy.md

@@ -22,6 +22,17 @@ e.g. "本阶段用 Python+OSQP 做约束优化；Wolfram 对本题非必需，
 The problem never silently depends on a single tool: every phase names its
 backend, its fallback, and the degradation path when the backend fails.
 
+## Computation backend extension
+
+Before selecting an external computation backend, run
+`scripts/computation/probe_backends.py` (or its PowerShell compatibility entry)
+and use only the live capability result. Persist a backend snapshot with
+`scripts/computation/backend_inventory.py` and an explicit run-local
+`--state-file` when the phase needs a stable inventory. Use
+`scripts/computation/computation_record.py` for reproducible/file or
+high-assurance computation. A probe, inventory, or record validation does not
+prove a mathematical claim.
+
 ## Python
 
 Use `scripts/python-environment.mjs`. Prefer uv, then an existing Python runtime plus venv. Keep the environment under the run directory. Install only required normalized PyPI package names; VCS URLs, local wheels, or arbitrary indexes require explicit user approval. Record lock, seed, command, workdir, timeout, stdout/stderr, exit code, and generated files.

package/skills/math-modeling-agent/references/workflow.md

@@ -8,7 +8,7 @@
 
 ## States
 
-TRIAGE → SCOPE_FROZEN → INPUT_PROFILED → CLAIMS_REGISTERED → CANDIDATES_READY → ATTEMPT → EXECUTE → VERIFY.
+TRIAGE → RESEARCH → SCOPE_FROZEN → INPUT_PROFILED → CLAIMS_REGISTERED → CANDIDATES_READY → ATTEMPT → EXECUTE → VERIFY.
 
 VERIFY may move to REVISE, RESEARCH, FORK, an independent audit, or one terminal status:
 SOLVED, PARTIAL, CONDITIONAL, INCONCLUSIVE, REFUTED, INFEASIBLE, UNIDENTIFIABLE, BLOCKED, CANCELLED.
@@ -19,16 +19,17 @@ SOLVED, PARTIAL, CONDITIONAL, INCONCLUSIVE, REFUTED, INFEASIBLE, UNIDENTIFIABLE,
 - **逐问层**（SPi 循环）：子问题分析 → 子问题假设 Si（D2-SPi）→ ATTEMPT 建模求解 → VERIFY 该问验证 → 该问鲁棒性（扰动计划→交互→执行）→ D4 裁决 → REVISE（本问修订）或进入 SPi+1（reason: "SPi 完成，进入 SPi+1"）。
 - **收束层**：跨问联动检查（终态 gate 校验全部子问题 DONE + 依赖满足）→ 全题鲁棒性汇总 → 终态硬门 → SOLVED + final-report（整体叙事，非拼凑）。
 
-## Pre-modeling literature research (v2.6, mandatory)
+## Pre-modeling literature research (mandatory)
 
-CLAIMS_REGISTERED → RESEARCH → CANDIDATES_READY. Before any candidate is
-built, run the D-R exchange (interaction-protocol.md): search principles and
-methods by direction, write research/sources.jsonl, attach a literature column
-to the candidate matrix. Every direction must be traceable to at least one
-source — engineering background, methodology paper, textbook, or official
-documentation; a literature-free direction must be explicitly marked
+TRIAGE → RESEARCH → D-R → SCOPE_FROZEN. After the initial task triage and
+before D0 restatement is frozen, run the D-R exchange
+(interaction-protocol.md): search principles, engineering background, and
+methods by direction; write research/sources.jsonl; attach a literature
+column to the candidate matrix. Every direction must be traceable to at least
+one source. A literature-free direction must be explicitly marked
 "原创方向" with its derivation basis. Never search for solutions to the
-specific contest problem.
+specific contest problem. Mid-solve evidence gaps use a recorded
+RESEARCH backtrack, not an implicit bypass of the initial research phase.
 
 ## Interaction gates (v2)
 

package/skills/math-modeling-agent/scripts/computation/README.md

@@ -0,0 +1,20 @@
+# DSH computation tool extension
+
+These entrypoints are adapted from the user-provided
+`math-science-computation` toolkit. They are computation-support tools, not
+mathematical engines: they discover callable external backends, persist a
+local capability snapshot, and validate reproducible computation records.
+
+## Entrypoints
+
+- `probe_backends.py` / `probe_backends.ps1`: read-only discovery of
+  Wolfram/Mathematica, primecount, SageMath, Python, and Python library
+  availability. External probes are bounded and return structured failures.
+- `backend_inventory.py` / `backend_inventory.ps1`: read or refresh a
+  capability snapshot. Pass a run-local `--state-file`/`-StateFile`; do not
+  use an implicit shared machine-wide path.
+- `computation_record.py`: initialize or validate a reproducibility record
+  for every probeable backend, including primecount.
+
+The external backend remains responsible for the actual mathematical
+calculation. A successful probe or record validation is not a proof.

package/skills/math-modeling-agent/scripts/computation/backend-inventory.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex.invalid/math-science-computation/backend-inventory.schema.json",
+  "title": "Math and science computation local backend inventory",
+  "type": "object",
+  "required": [
+    "inventory_schema_version",
+    "created_at_utc",
+    "updated_at_utc",
+    "local",
+    "mcp",
+    "invalidations"
+  ],
+  "properties": {
+    "inventory_schema_version": { "const": "1.0" },
+    "created_at_utc": { "type": "string", "format": "date-time" },
+    "updated_at_utc": { "type": "string", "format": "date-time" },
+    "local": {
+      "type": "object",
+      "required": ["schema_version", "probed_at_utc", "host", "mathematica", "primecount", "sagemath", "python"],
+      "properties": {
+        "schema_version": { "const": "1.0" },
+        "probed_at_utc": { "type": "string", "format": "date-time" },
+        "host": {
+          "type": "object",
+          "required": ["system", "architecture"],
+          "properties": {
+            "system": { "enum": ["Windows", "Darwin", "Linux"] },
+            "architecture": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": true
+        },
+        "mathematica": { "type": "object" },
+        "primecount": { "type": "object" },
+        "sagemath": { "type": "object" },
+        "python": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+    "mcp": {
+      "type": "object",
+      "required": ["authority", "persisted_status", "required_action"],
+      "properties": {
+        "authority": { "const": "current_session_tool_discovery_and_call" },
+        "persisted_status": { "const": "historical_only" },
+        "required_action": { "type": "string" },
+        "mathematica": {
+          "type": "object",
+          "required": ["server_name", "protocol_version", "server_version", "wolfram_language_version", "observed_at_utc", "evidence"],
+          "properties": {
+            "server_name": { "type": "string", "minLength": 1 },
+            "protocol_version": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+            "server_version": { "type": "string", "minLength": 1 },
+            "wolfram_language_version": { "type": "string", "minLength": 1 },
+            "observed_at_utc": { "type": "string", "format": "date-time" },
+            "evidence": { "const": "initialize_handshake_and_evaluator" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "invalidations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["backend", "reason", "recorded_at_utc"],
+        "properties": {
+          "backend": { "enum": ["mathematica", "primecount", "sagemath", "python"] },
+          "reason": { "enum": ["user_requested", "path_missing", "execution_failed", "version_mismatch"] },
+          "recorded_at_utc": { "type": "string", "format": "date-time" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/skills/math-modeling-agent/scripts/computation/backend_inventory.ps1

@@ -0,0 +1,351 @@
+[CmdletBinding()]
+param(
+    [ValidateSet('ReadOrCreate', 'Refresh', 'Invalidate', 'RecordMcp')]
+    [string]$Mode = 'ReadOrCreate',
+    [string]$StateFile = '',
+    [ValidateSet('all', 'mathematica', 'primecount', 'sagemath', 'python')]
+    [string[]]$Backend = @('all'),
+    [string]$ReasonCode = '',
+    [int]$MaxAgeHours = 168,
+    [string]$ProbeScript = (Join-Path $PSScriptRoot 'probe_backends.ps1'),
+    [string]$ProbeJsonFile = '',
+    [string]$PythonCommand = 'python',
+    [string]$SageCommand = '',
+    [string]$WslDistro = '',
+    [string]$WslSageCommand = 'sage',
+    [string]$PrimecountCommand = '',
+    [string]$McpServerName = '',
+    [string]$McpProtocolVersion = '',
+    [string]$McpServerVersion = '',
+    [string]$McpWolframLanguageVersion = '',
+    [string]$McpObservedAtUtc = ''
+)
+
+$ErrorActionPreference = 'Stop'
+$stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
+if ($Mode -eq 'Invalidate' -and $ReasonCode -notmatch '^[a-z][a-z0-9_]{0,31}$') {
+    throw "Invalidate mode requires a bounded lowercase reason code."
+}
+
+function Get-DefaultStateFile {
+    if ($env:MATH_SCIENCE_BACKEND_INVENTORY) {
+        return $env:MATH_SCIENCE_BACKEND_INVENTORY
+    }
+    return (Join-Path (Join-Path (Join-Path ([IO.Path]::GetTempPath()) 'DSH') 'math-science-computation') 'backend-inventory.json')
+}
+
+function Get-HostIdentity {
+    $system = if ([Runtime.InteropServices.RuntimeInformation]::IsOSPlatform([Runtime.InteropServices.OSPlatform]::Windows)) {
+        'Windows'
+    }
+    elseif ([Runtime.InteropServices.RuntimeInformation]::IsOSPlatform([Runtime.InteropServices.OSPlatform]::OSX)) {
+        'Darwin'
+    }
+    else {
+        'Linux'
+    }
+    $rawArchitecture = [Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString().ToLowerInvariant()
+    $architecture = switch ($rawArchitecture) {
+        'x64' { 'x86_64' }
+        'amd64' { 'x86_64' }
+        'arm64' { 'arm64' }
+        'x86' { 'x86' }
+        default { $rawArchitecture }
+    }
+    return [ordered]@{ system = $system; architecture = $architecture; powershell_edition = $PSVersionTable.PSEdition }
+}
+
+function Read-Inventory {
+    param([Parameter(Mandatory = $true)][string]$Path)
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    try {
+        $inventory = Get-Content -Raw -LiteralPath $Path | ConvertFrom-Json -AsHashtable
+        if ($inventory.inventory_schema_version -ne '1.0' -or $inventory.local.schema_version -ne '1.0') {
+            return $null
+        }
+        return $inventory
+    }
+    catch {
+        return $null
+    }
+}
+
+function Invoke-LocalProbe {
+    if ($ProbeJsonFile) {
+        return (Get-Content -Raw -LiteralPath $ProbeJsonFile | ConvertFrom-Json -AsHashtable)
+    }
+    if (-not (Test-Path -LiteralPath $ProbeScript -PathType Leaf)) {
+        throw "Backend probe script is unavailable."
+    }
+
+    $probeArguments = @{
+        PythonCommand = $PythonCommand
+        SageCommand = $SageCommand
+        WslDistro = $WslDistro
+        WslSageCommand = $WslSageCommand
+        PrimecountCommand = $PrimecountCommand
+    }
+    $raw = & $ProbeScript @probeArguments
+    if ($LASTEXITCODE -notin @($null, 0)) {
+        throw "Backend probe failed with a nonzero exit code."
+    }
+    return (($raw -join "`n") | ConvertFrom-Json -AsHashtable)
+}
+
+function New-Inventory {
+    param([Parameter(Mandatory = $true)][hashtable]$Local)
+
+    $now = [DateTime]::UtcNow.ToString('o')
+    return [ordered]@{
+        inventory_schema_version = '1.0'
+        created_at_utc = $now
+        updated_at_utc = $now
+        local = $Local
+        mcp = [ordered]@{
+            authority = 'current_session_tool_discovery_and_call'
+            persisted_status = 'historical_only'
+            required_action = 'Build a current-session overlay and live-check only the selected MCP backend.'
+        }
+        invalidations = @()
+    }
+}
+
+function New-McpObservation {
+    $required = [ordered]@{
+        server_name = $McpServerName
+        protocol_version = $McpProtocolVersion
+        server_version = $McpServerVersion
+        wolfram_language_version = $McpWolframLanguageVersion
+    }
+    $missing = @($required.GetEnumerator() | Where-Object { -not $_.Value.Trim() } | ForEach-Object Key)
+    if ($missing.Count -gt 0) {
+        throw ('RecordMcp requires: ' + ($missing -join ', '))
+    }
+    if ($McpProtocolVersion -notmatch '^\d{4}-\d{2}-\d{2}$') {
+        throw 'MCP protocol version must use the negotiated YYYY-MM-DD form.'
+    }
+    $observedAt = if ($McpObservedAtUtc) { $McpObservedAtUtc } else { [DateTime]::UtcNow.ToString('o') }
+    try { [void][DateTimeOffset]::Parse($observedAt) }
+    catch { throw 'MCP observation time must be an ISO-8601 timestamp.' }
+    return [ordered]@{
+        server_name = $McpServerName
+        protocol_version = $McpProtocolVersion
+        server_version = $McpServerVersion
+        wolfram_language_version = $McpWolframLanguageVersion
+        observed_at_utc = $observedAt
+        evidence = 'initialize_handshake_and_evaluator'
+    }
+}
+
+function Write-InventoryAtomic {
+    param(
+        [Parameter(Mandatory = $true)][hashtable]$Inventory,
+        [Parameter(Mandatory = $true)][string]$Path
+    )
+
+    $parent = Split-Path -Parent $Path
+    if (-not $parent) {
+        $parent = (Get-Location).Path
+        $Path = Join-Path $parent $Path
+    }
+    [IO.Directory]::CreateDirectory($parent) | Out-Null
+    $temporary = Join-Path $parent ('.backend-inventory-' + [Guid]::NewGuid().ToString('N') + '.tmp')
+    try {
+        $json = $Inventory | ConvertTo-Json -Depth 12
+        [IO.File]::WriteAllText($temporary, $json, [Text.UTF8Encoding]::new($false))
+        [IO.File]::Move($temporary, $Path, $true)
+    }
+    finally {
+        if (Test-Path -LiteralPath $temporary -PathType Leaf) {
+            Remove-Item -LiteralPath $temporary -Force -ErrorAction SilentlyContinue
+        }
+    }
+}
+
+function Get-MissingBackendPaths {
+    param([Parameter(Mandatory = $true)][hashtable]$Inventory)
+
+    $missing = [Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase)
+    foreach ($installation in @($Inventory.local.mathematica.installations)) {
+        if ($installation.executable -and -not (Test-Path -LiteralPath $installation.executable -PathType Leaf)) {
+            [void]$missing.Add('mathematica')
+        }
+    }
+    $checks = @(
+        @('mathematica', $Inventory.local.mathematica.wolframscript.path),
+        @('primecount', $Inventory.local.primecount.path),
+        @('sagemath', $Inventory.local.sagemath.native.path),
+        @('python', $Inventory.local.python.path)
+    )
+    foreach ($check in $checks) {
+        if ($check[1] -and -not (Test-Path -LiteralPath $check[1] -PathType Leaf)) {
+            [void]$missing.Add([string]$check[0])
+        }
+    }
+    return @($missing)
+}
+
+function Test-InventoryExpired {
+    param([Parameter(Mandatory = $true)][hashtable]$Inventory)
+
+    if ($MaxAgeHours -le 0) {
+        return $false
+    }
+    try {
+        $updated = [DateTimeOffset]::Parse([string]$Inventory.updated_at_utc)
+        return ([DateTimeOffset]::UtcNow - $updated).TotalHours -ge $MaxAgeHours
+    }
+    catch {
+        return $true
+    }
+}
+
+function Test-InventoryHostMismatch {
+    param([Parameter(Mandatory = $true)][hashtable]$Inventory)
+
+    $current = Get-HostIdentity
+    $stored = $Inventory.local.host
+    if (-not $stored) {
+        return $true
+    }
+    return ($stored.system -ne $current.system -or $stored.architecture -ne $current.architecture)
+}
+
+function Merge-Backends {
+    param(
+        [Parameter(Mandatory = $true)][hashtable]$Inventory,
+        [Parameter(Mandatory = $true)][hashtable]$FreshLocal,
+        [Parameter(Mandatory = $true)][string[]]$Names
+    )
+
+    $selected = if ($Names -contains 'all') {
+        @('mathematica', 'primecount', 'sagemath', 'python')
+    }
+    else {
+        @($Names | Select-Object -Unique)
+    }
+    foreach ($name in $selected) {
+        $Inventory.local[$name] = $FreshLocal[$name]
+    }
+    $Inventory.local.probed_at_utc = $FreshLocal.probed_at_utc
+    $Inventory.local.host = $FreshLocal.host
+    $Inventory.updated_at_utc = [DateTime]::UtcNow.ToString('o')
+    return $Inventory
+}
+
+function Write-Result {
+    param(
+        [Parameter(Mandatory = $true)][hashtable]$Inventory,
+        [Parameter(Mandatory = $true)][string]$CacheStatus,
+        [string[]]$RefreshedBackends = @(),
+        [string[]]$InvalidPaths = @(),
+        [bool]$BackendStarted = $false,
+        [string]$WriteError = ''
+    )
+
+    $stopwatch.Stop()
+    $output = [ordered]@{
+        inventory_schema_version = $Inventory.inventory_schema_version
+        snapshot_updated_at_utc = $Inventory.updated_at_utc
+        cache = [ordered]@{
+            status = $CacheStatus
+            state_file = $StateFile
+            elapsed_ms = $stopwatch.ElapsedMilliseconds
+            backend_started = $BackendStarted
+            refreshed_backends = @($RefreshedBackends)
+            invalid_path_backends = @($InvalidPaths)
+            write_error = $WriteError
+        }
+        local = $Inventory.local
+        mcp = [ordered]@{
+            status = 'session_probe_required'
+            authority = 'current_session_tool_discovery_and_call'
+            note = 'The persisted snapshot is not evidence that an MCP tool is callable in this session.'
+            recorded_mathematica_observation = $Inventory.mcp.mathematica
+        }
+    }
+    $output | ConvertTo-Json -Depth 12 -Compress
+}
+
+if (-not $StateFile) {
+    $StateFile = Get-DefaultStateFile
+}
+$StateFile = [IO.Path]::GetFullPath($StateFile)
+$inventory = Read-Inventory -Path $StateFile
+$missingBackends = @()
+
+if ($Mode -eq 'RecordMcp') {
+    $observation = New-McpObservation
+    $backendStarted = $false
+    if (-not $inventory) {
+        $freshLocal = Invoke-LocalProbe
+        if ($freshLocal.schema_version -ne '1.0') { throw 'Unsupported backend probe schema.' }
+        if ($freshLocal.mathematica -is [Collections.IDictionary] -and $freshLocal.mathematica.Contains('mcp')) {
+            [void]$freshLocal.mathematica.Remove('mcp')
+        }
+        $inventory = New-Inventory -Local $freshLocal
+        $backendStarted = $true
+    }
+    $inventory.mcp.mathematica = $observation
+    $inventory.updated_at_utc = [DateTime]::UtcNow.ToString('o')
+    Write-InventoryAtomic -Inventory $inventory -Path $StateFile
+    Write-Result -Inventory $inventory -CacheStatus 'mcp_recorded' -BackendStarted $backendStarted
+    exit 0
+}
+
+if ($Mode -eq 'ReadOrCreate' -and $inventory) {
+    $missingBackends = @(Get-MissingBackendPaths -Inventory $inventory)
+    if ($missingBackends.Count -eq 0 -and -not (Test-InventoryExpired -Inventory $inventory) -and -not (Test-InventoryHostMismatch -Inventory $inventory)) {
+        Write-Result -Inventory $inventory -CacheStatus 'hit' -BackendStarted $false
+        exit 0
+    }
+}
+
+$freshLocal = Invoke-LocalProbe
+if ($freshLocal.schema_version -ne '1.0') {
+    throw "Unsupported backend probe schema."
+}
+if ($freshLocal.mathematica -is [Collections.IDictionary] -and $freshLocal.mathematica.Contains('mcp')) {
+    [void]$freshLocal.mathematica.Remove('mcp')
+}
+
+$refreshed = @('mathematica', 'primecount', 'sagemath', 'python')
+$cacheStatus = 'created'
+if (-not $inventory) {
+    $inventory = New-Inventory -Local $freshLocal
+}
+else {
+    $cacheStatus = 'refreshed'
+    if ($Mode -eq 'Invalidate') {
+        $targets = if ($Backend -contains 'all') { @('mathematica', 'primecount', 'sagemath', 'python') } else { @($Backend) }
+        $inventory.invalidations = @($inventory.invalidations) + @($targets | ForEach-Object {
+            [ordered]@{ backend = $_; reason = $ReasonCode; recorded_at_utc = [DateTime]::UtcNow.ToString('o') }
+        })
+        if ($inventory.invalidations.Count -gt 20) {
+            $inventory.invalidations = @($inventory.invalidations | Select-Object -Last 20)
+        }
+        $refreshed = $targets
+    }
+    elseif ($Mode -eq 'Refresh') {
+        $refreshed = if ($Backend -contains 'all') { @('mathematica', 'primecount', 'sagemath', 'python') } else { @($Backend) }
+    }
+    elseif ($missingBackends.Count -gt 0) {
+        $refreshed = $missingBackends
+    }
+    $inventory = Merge-Backends -Inventory $inventory -FreshLocal $freshLocal -Names $refreshed
+}
+
+$writeError = ''
+try {
+    Write-InventoryAtomic -Inventory $inventory -Path $StateFile
+}
+catch {
+    $writeError = $_.Exception.GetType().Name
+    $cacheStatus = 'write_failed'
+}
+Write-Result -Inventory $inventory -CacheStatus $cacheStatus -RefreshedBackends $refreshed -InvalidPaths $missingBackends -BackendStarted $true -WriteError $writeError
+if ($writeError) { exit 1 }
+exit 0