dsh-math-modeling-agent 0.2.8 → 0.4.1

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

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

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+"""Read, refresh, or invalidate the cross-platform backend inventory."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import re
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+BACKENDS = ("mathematica", "primecount", "sagemath", "python")
+REASON_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
+MCP_PROTOCOL_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def normalized_architecture() -> str:
+    value = platform.machine().lower()
+    return {
+        "amd64": "x86_64",
+        "x64": "x86_64",
+        "aarch64": "arm64",
+        "arm64": "arm64",
+        "i386": "x86",
+        "i686": "x86",
+        "x86": "x86",
+    }.get(value, value or "unknown")
+
+
+def default_state_file() -> Path:
+    override = os.environ.get("MATH_SCIENCE_BACKEND_INVENTORY")
+    if override:
+        return Path(override).expanduser()
+    return Path(tempfile.gettempdir(), "DSH", "math-science-computation", "backend-inventory.json")
+
+
+def read_inventory(path: Path) -> dict | None:
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        local = data.get("local") if isinstance(data, dict) else None
+        mcp = data.get("mcp") if isinstance(data, dict) else None
+        if (
+            not isinstance(data, dict)
+            or not isinstance(local, dict)
+            or not isinstance(mcp, dict)
+            or data.get("inventory_schema_version") != "1.0"
+            or local.get("schema_version") != "1.0"
+        ):
+            return None
+        return data
+    except (OSError, json.JSONDecodeError, TypeError):
+        return None
+
+
+def invoke_probe(args: argparse.Namespace) -> dict:
+    if args.probe_json_file:
+        return json.loads(Path(args.probe_json_file).read_text(encoding="utf-8"))
+    probe_script = Path(args.probe_script)
+    if not probe_script.is_file():
+        raise RuntimeError("Backend probe script is unavailable.")
+    command = [
+        sys.executable,
+        str(probe_script),
+        "--python-command",
+        args.python_command,
+        "--wsl-sage-command",
+        args.wsl_sage_command,
+    ]
+    for option, value in (
+        ("--sage-command", args.sage_command),
+        ("--wsl-distro", args.wsl_distro),
+        ("--primecount-command", args.primecount_command),
+    ):
+        if value:
+            command.extend([option, value])
+    process = subprocess.run(command, text=True, capture_output=True, check=False, timeout=60)
+    if process.returncode != 0:
+        message = (process.stderr or process.stdout).strip()
+        raise RuntimeError(f"Backend probe failed with exit code {process.returncode}: {message}")
+    return json.loads(process.stdout)
+
+
+def new_inventory(local: dict) -> dict:
+    now = utc_now()
+    return {
+        "inventory_schema_version": "1.0",
+        "created_at_utc": now,
+        "updated_at_utc": now,
+        "local": local,
+        "mcp": {
+            "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": [],
+    }
+
+
+def mcp_observation(args: argparse.Namespace) -> dict:
+    values = {
+        "server_name": args.mcp_server_name,
+        "protocol_version": args.mcp_protocol_version,
+        "server_version": args.mcp_server_version,
+        "wolfram_language_version": args.mcp_wolfram_language_version,
+    }
+    missing = [name for name, value in values.items() if not value.strip()]
+    if missing:
+        raise SystemExit("RecordMcp requires: " + ", ".join(missing))
+    if not MCP_PROTOCOL_PATTERN.fullmatch(values["protocol_version"]):
+        raise SystemExit("MCP protocol version must use the negotiated YYYY-MM-DD form.")
+    observed_at = args.mcp_observed_at_utc or utc_now()
+    try:
+        datetime.fromisoformat(observed_at.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise SystemExit("MCP observation time must be an ISO-8601 timestamp.") from exc
+    return {
+        **values,
+        "observed_at_utc": observed_at,
+        "evidence": "initialize_handshake_and_evaluator",
+    }
+
+
+def write_inventory_atomic(inventory: dict, path: Path) -> None:
+    path = path.expanduser().resolve()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.parent / f".backend-inventory-{uuid.uuid4().hex}.tmp"
+    try:
+        temporary.write_text(json.dumps(inventory, ensure_ascii=False, indent=2), encoding="utf-8")
+        os.replace(temporary, path)
+    finally:
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def missing_backend_paths(inventory: dict) -> list[str]:
+    local = inventory["local"]
+    missing: set[str] = set()
+    for installation in local.get("mathematica", {}).get("installations", []):
+        executable = installation.get("executable")
+        if executable and not Path(executable).is_file():
+            missing.add("mathematica")
+    checks = (
+        ("mathematica", local.get("mathematica", {}).get("wolframscript", {}).get("path")),
+        ("primecount", local.get("primecount", {}).get("path")),
+        ("sagemath", local.get("sagemath", {}).get("native", {}).get("path")),
+        ("python", local.get("python", {}).get("path")),
+    )
+    for name, value in checks:
+        if value and not Path(value).is_file():
+            missing.add(name)
+    return [name for name in BACKENDS if name in missing]
+
+
+def inventory_expired(inventory: dict, max_age_hours: int) -> bool:
+    if max_age_hours <= 0:
+        return False
+    try:
+        updated = datetime.fromisoformat(inventory["updated_at_utc"].replace("Z", "+00:00"))
+        return (datetime.now(timezone.utc) - updated.astimezone(timezone.utc)).total_seconds() >= max_age_hours * 3600
+    except (KeyError, TypeError, ValueError):
+        return True
+
+
+def host_changed(inventory: dict) -> bool:
+    host = inventory.get("local", {}).get("host")
+    if not isinstance(host, dict):
+        return True
+    return host.get("system") != platform.system() or host.get("architecture") != normalized_architecture()
+
+
+def selected_backends(names: list[str]) -> list[str]:
+    if "all" in names:
+        return list(BACKENDS)
+    return [name for name in BACKENDS if name in names]
+
+
+def merge_backends(inventory: dict, fresh_local: dict, names: list[str]) -> dict:
+    for name in selected_backends(names):
+        inventory["local"][name] = fresh_local[name]
+    inventory["local"]["probed_at_utc"] = fresh_local["probed_at_utc"]
+    inventory["local"]["host"] = fresh_local.get("host", {})
+    inventory["updated_at_utc"] = utc_now()
+    return inventory
+
+
+def emit_result(
+    inventory: dict,
+    state_file: Path,
+    started: float,
+    cache_status: str,
+    refreshed: list[str] | None = None,
+    invalid_paths: list[str] | None = None,
+    backend_started: bool = False,
+    write_error: str = "",
+) -> None:
+    output = {
+        "inventory_schema_version": inventory["inventory_schema_version"],
+        "snapshot_updated_at_utc": inventory["updated_at_utc"],
+        "cache": {
+            "status": cache_status,
+            "state_file": str(state_file),
+            "elapsed_ms": int((time.perf_counter() - started) * 1000),
+            "backend_started": backend_started,
+            "refreshed_backends": refreshed or [],
+            "invalid_path_backends": invalid_paths or [],
+            "write_error": write_error,
+        },
+        "local": inventory["local"],
+        "mcp": {
+            "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.get("mcp", {}).get("mathematica"),
+        },
+    }
+    print(json.dumps(output, ensure_ascii=False, separators=(",", ":")))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--mode", choices=("ReadOrCreate", "Refresh", "Invalidate", "RecordMcp"), default="ReadOrCreate")
+    parser.add_argument("--state-file", default="")
+    parser.add_argument("--backend", choices=("all", *BACKENDS), nargs="+", default=["all"])
+    parser.add_argument("--reason-code", default="")
+    parser.add_argument("--max-age-hours", type=int, default=168)
+    parser.add_argument("--probe-script", default=str(Path(__file__).with_name("probe_backends.py")))
+    parser.add_argument("--probe-json-file", default="")
+    parser.add_argument("--python-command", default=sys.executable)
+    parser.add_argument("--sage-command", default="")
+    parser.add_argument("--wsl-distro", default="")
+    parser.add_argument("--wsl-sage-command", default="sage")
+    parser.add_argument("--primecount-command", default="")
+    parser.add_argument("--mcp-server-name", default="")
+    parser.add_argument("--mcp-protocol-version", default="")
+    parser.add_argument("--mcp-server-version", default="")
+    parser.add_argument("--mcp-wolfram-language-version", default="")
+    parser.add_argument("--mcp-observed-at-utc", default="")
+    return parser
+
+
+def main() -> int:
+    started = time.perf_counter()
+    args = build_parser().parse_args()
+    if args.mode == "Invalidate" and not REASON_PATTERN.fullmatch(args.reason_code):
+        raise SystemExit("Invalidate mode requires a bounded lowercase reason code.")
+    state_file = Path(args.state_file).expanduser() if args.state_file else default_state_file()
+    state_file = state_file.resolve()
+    inventory = read_inventory(state_file)
+    missing: list[str] = []
+
+    if args.mode == "RecordMcp":
+        observation = mcp_observation(args)
+        backend_started = False
+        if inventory is None:
+            fresh_local = invoke_probe(args)
+            if fresh_local.get("schema_version") != "1.0":
+                raise SystemExit("Unsupported backend probe schema.")
+            fresh_local.get("mathematica", {}).pop("mcp", None)
+            inventory = new_inventory(fresh_local)
+            backend_started = True
+        inventory["mcp"]["mathematica"] = observation
+        inventory["updated_at_utc"] = utc_now()
+        write_inventory_atomic(inventory, state_file)
+        emit_result(inventory, state_file, started, "mcp_recorded", backend_started=backend_started)
+        return 0
+
+    if args.mode == "ReadOrCreate" and inventory:
+        missing = missing_backend_paths(inventory)
+        if not missing and not inventory_expired(inventory, args.max_age_hours) and not host_changed(inventory):
+            emit_result(inventory, state_file, started, "hit")
+            return 0
+
+    fresh_local = invoke_probe(args)
+    if fresh_local.get("schema_version") != "1.0":
+        raise SystemExit("Unsupported backend probe schema.")
+    fresh_local.get("mathematica", {}).pop("mcp", None)
+
+    refreshed = list(BACKENDS)
+    cache_status = "created"
+    if inventory is None:
+        inventory = new_inventory(fresh_local)
+    else:
+        cache_status = "refreshed"
+        if args.mode in {"Refresh", "Invalidate"}:
+            refreshed = selected_backends(args.backend)
+        elif missing and not host_changed(inventory):
+            refreshed = missing
+        if args.mode == "Invalidate":
+            inventory["invalidations"] = (inventory.get("invalidations", []) + [
+                {"backend": name, "reason": args.reason_code, "recorded_at_utc": utc_now()}
+                for name in refreshed
+            ])[-20:]
+        inventory = merge_backends(inventory, fresh_local, refreshed)
+
+    write_error = ""
+    try:
+        write_inventory_atomic(inventory, state_file)
+    except OSError as exc:
+        write_error = type(exc).__name__
+        cache_status = "write_failed"
+    emit_result(inventory, state_file, started, cache_status, refreshed, missing, True, write_error)
+    return 1 if write_error else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())