dsh-math-modeling-agent 0.3.1 → 0.4.1

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())

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

@@ -0,0 +1,361 @@
+#!/usr/bin/env python3
+"""Initialize and validate reproducible mathematics/science computation records."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA_VERSION = "1.0"
+BACKENDS = {"mathematica", "primecount", "sagemath", "python", "other"}
+AVAILABILITY = {"available", "unavailable", "unknown", "not-applicable"}
+PRECISION_MODES = {"exact", "machine", "arbitrary", "interval", "mixed"}
+EVIDENCE_LEVELS = {
+    "proof-certificate",
+    "formal-verification",
+    "exact-check",
+    "bounded-check",
+    "numerical-evidence",
+}
+HEX_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+
+
+class RecordError(ValueError):
+    """A computation record is invalid."""
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def write_json(path: Path, value: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(value, ensure_ascii=False, indent=2) + "\n"
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=path.parent
+    )
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary_name, path)
+    except BaseException:
+        try:
+            Path(temporary_name).unlink()
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def relative_inside(path: Path, base_dir: Path, label: str) -> str:
+    resolved_path = path.resolve()
+    resolved_base = base_dir.resolve()
+    try:
+        relative = resolved_path.relative_to(resolved_base)
+    except ValueError as exc:
+        raise RecordError(f"{label} must be inside the record base directory") from exc
+    return relative.as_posix()
+
+
+def resolve_safe_relative(base_dir: Path, raw_path: Any, label: str) -> Path:
+    if not isinstance(raw_path, str) or not raw_path.strip():
+        raise RecordError(f"{label} must be a nonempty relative path")
+    candidate = Path(raw_path)
+    if candidate.is_absolute():
+        raise RecordError(f"{label} must not be absolute")
+    resolved_base = base_dir.resolve()
+    resolved = (resolved_base / candidate).resolve()
+    try:
+        resolved.relative_to(resolved_base)
+    except ValueError as exc:
+        raise RecordError(f"{label} escapes the base directory") from exc
+    return resolved
+
+
+def require_mapping(parent: dict[str, Any], key: str, label: str) -> dict[str, Any]:
+    value = parent.get(key)
+    if not isinstance(value, dict):
+        raise RecordError(f"{label}.{key} must be an object")
+    return value
+
+
+def require_nonempty_string(parent: dict[str, Any], key: str, label: str) -> str:
+    value = parent.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise RecordError(f"{label}.{key} must be a nonempty string")
+    return value.strip()
+
+
+def require_string_list(parent: dict[str, Any], key: str, label: str) -> list[str]:
+    value = parent.get(key)
+    if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
+        raise RecordError(f"{label}.{key} must be a list of strings")
+    return value
+
+
+def validate_hash(raw_hash: Any, label: str) -> str:
+    if not isinstance(raw_hash, str) or not HEX_SHA256.fullmatch(raw_hash):
+        raise RecordError(f"{label} must be a lowercase SHA-256 hex digest")
+    return raw_hash
+
+
+def init_record(task_file: Path, record_path: Path, force: bool) -> None:
+    task_file = task_file.resolve()
+    record_path = record_path.resolve()
+    if not task_file.is_file():
+        raise RecordError(f"task file does not exist: {task_file}")
+    record_path.parent.mkdir(parents=True, exist_ok=True)
+    if record_path.exists() and not force:
+        raise RecordError(f"record already exists: {record_path}; pass --force to replace it")
+    task_relative = relative_inside(task_file, record_path.parent, "task file")
+
+    record = {
+        "schema_version": SCHEMA_VERSION,
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "task": {
+            "file": task_relative,
+            "sha256": sha256_file(task_file),
+            "object": "",
+            "deliverables": [],
+        },
+        "mathematical_context": {
+            "assumptions": [],
+            "domain": "",
+            "precision": {
+                "mode": "exact",
+                "working_digits": None,
+                "target_tolerance": "",
+            },
+        },
+        "implementation_discovery": {
+            backend: {
+                "candidate_implementations": [],
+                "existence_evidence": "",
+                "local_availability": "unknown",
+                "availability_evidence": "",
+            }
+            for backend in ("mathematica", "primecount", "sagemath", "python")
+        },
+        "decision": {
+            "selected_backend": "",
+            "backend_version": "",
+            "selection_reason": "",
+            "fallback_reason": "",
+        },
+        "execution": {
+            "status": "planned",
+            "interface": "",
+            "command_or_input": "",
+            "code_artifact": "",
+        },
+        "artifacts": [],
+        "result": {
+            "status": "pending",
+            "summary": "",
+            "result_artifact": "",
+        },
+        "verification": {
+            "methods": [],
+            "evidence_level": "",
+            "residual_or_error": "",
+            "limitations": [],
+        },
+    }
+    write_json(record_path, record)
+    print(json.dumps({"ok": True, "record": str(record_path)}, ensure_ascii=False))
+
+
+def validate_record(record_path: Path, base_dir: Path | None) -> dict[str, Any]:
+    record_path = record_path.resolve()
+    if not record_path.is_file():
+        raise RecordError(f"record does not exist: {record_path}")
+    base = (base_dir or record_path.parent).resolve()
+    if not base.is_dir():
+        raise RecordError(f"base directory does not exist: {base}")
+
+    try:
+        record = json.loads(record_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RecordError(f"cannot read record JSON: {exc}") from exc
+    if not isinstance(record, dict):
+        raise RecordError("record root must be an object")
+    if record.get("schema_version") != SCHEMA_VERSION:
+        raise RecordError(f"schema_version must be {SCHEMA_VERSION}")
+
+    task = require_mapping(record, "task", "record")
+    require_nonempty_string(task, "object", "task")
+    deliverables = require_string_list(task, "deliverables", "task")
+    if not deliverables:
+        raise RecordError("task.deliverables must contain at least one item")
+    task_path = resolve_safe_relative(base, task.get("file"), "task.file")
+    if not task_path.is_file():
+        raise RecordError(f"task.file does not exist: {task_path}")
+    task_hash = validate_hash(task.get("sha256"), "task.sha256")
+    if sha256_file(task_path) != task_hash:
+        raise RecordError("task.sha256 does not match task.file")
+
+    context = require_mapping(record, "mathematical_context", "record")
+    require_string_list(context, "assumptions", "mathematical_context")
+    require_nonempty_string(context, "domain", "mathematical_context")
+    precision = require_mapping(context, "precision", "mathematical_context")
+    mode = require_nonempty_string(precision, "mode", "mathematical_context.precision")
+    if mode not in PRECISION_MODES:
+        raise RecordError(f"mathematical_context.precision.mode must be one of {sorted(PRECISION_MODES)}")
+    working_digits = precision.get("working_digits")
+    if working_digits is not None and (not isinstance(working_digits, int) or working_digits <= 0):
+        raise RecordError("mathematical_context.precision.working_digits must be null or a positive integer")
+    target_tolerance = precision.get("target_tolerance")
+    if not isinstance(target_tolerance, str):
+        raise RecordError("mathematical_context.precision.target_tolerance must be a string")
+    if mode != "exact" and not target_tolerance.strip():
+        raise RecordError("numerical precision modes require mathematical_context.precision.target_tolerance")
+
+    discovery = require_mapping(record, "implementation_discovery", "record")
+    for backend in ("mathematica", "primecount", "sagemath", "python"):
+        entry = require_mapping(discovery, backend, "implementation_discovery")
+        candidates = entry.get("candidate_implementations")
+        if not isinstance(candidates, list) or any(not isinstance(item, str) for item in candidates):
+            raise RecordError(
+                f"implementation_discovery.{backend}.candidate_implementations must be a list of strings"
+            )
+        require_nonempty_string(entry, "existence_evidence", f"implementation_discovery.{backend}")
+        availability = require_nonempty_string(
+            entry, "local_availability", f"implementation_discovery.{backend}"
+        )
+        if availability not in AVAILABILITY:
+            raise RecordError(
+                f"implementation_discovery.{backend}.local_availability must be one of {sorted(AVAILABILITY)}"
+            )
+        require_nonempty_string(
+            entry, "availability_evidence", f"implementation_discovery.{backend}"
+        )
+
+    decision = require_mapping(record, "decision", "record")
+    selected_backend = require_nonempty_string(decision, "selected_backend", "decision")
+    if selected_backend not in BACKENDS:
+        raise RecordError(f"decision.selected_backend must be one of {sorted(BACKENDS)}")
+    require_nonempty_string(decision, "backend_version", "decision")
+    require_nonempty_string(decision, "selection_reason", "decision")
+    require_nonempty_string(decision, "fallback_reason", "decision")
+    if selected_backend in discovery:
+        selected_entry = discovery[selected_backend]
+        if selected_entry.get("local_availability") != "available":
+            raise RecordError("the selected backend must have local_availability=available")
+
+    execution = require_mapping(record, "execution", "record")
+    if require_nonempty_string(execution, "status", "execution") != "complete":
+        raise RecordError("execution.status must be complete")
+    require_nonempty_string(execution, "interface", "execution")
+    require_nonempty_string(execution, "command_or_input", "execution")
+    code_artifact = require_nonempty_string(execution, "code_artifact", "execution")
+
+    artifacts = record.get("artifacts")
+    if not isinstance(artifacts, list) or not artifacts:
+        raise RecordError("artifacts must be a nonempty list")
+    roles: set[str] = set()
+    artifact_paths: set[str] = set()
+    verified_artifacts = []
+    for index, artifact in enumerate(artifacts):
+        label = f"artifacts[{index}]"
+        if not isinstance(artifact, dict):
+            raise RecordError(f"{label} must be an object")
+        role = require_nonempty_string(artifact, "role", label)
+        raw_path = require_nonempty_string(artifact, "path", label)
+        expected_hash = validate_hash(artifact.get("sha256"), f"{label}.sha256")
+        artifact_path = resolve_safe_relative(base, raw_path, f"{label}.path")
+        if not artifact_path.is_file():
+            raise RecordError(f"{label}.path does not exist: {artifact_path}")
+        actual_hash = sha256_file(artifact_path)
+        if actual_hash != expected_hash:
+            raise RecordError(f"{label}.sha256 does not match {raw_path}")
+        roles.add(role)
+        artifact_paths.add(Path(raw_path).as_posix())
+        verified_artifacts.append(
+            {"role": role, "path": Path(raw_path).as_posix(), "sha256": actual_hash}
+        )
+    if "code" not in roles or "result" not in roles:
+        raise RecordError("artifacts must include both code and result roles")
+    if Path(code_artifact).as_posix() not in artifact_paths:
+        raise RecordError("execution.code_artifact must name a hashed artifact")
+
+    result = require_mapping(record, "result", "record")
+    if require_nonempty_string(result, "status", "result") != "complete":
+        raise RecordError("result.status must be complete")
+    require_nonempty_string(result, "summary", "result")
+    result_artifact = require_nonempty_string(result, "result_artifact", "result")
+    if Path(result_artifact).as_posix() not in artifact_paths:
+        raise RecordError("result.result_artifact must name a hashed artifact")
+
+    verification = require_mapping(record, "verification", "record")
+    methods = require_string_list(verification, "methods", "verification")
+    if not methods or any(not method.strip() for method in methods):
+        raise RecordError("verification.methods must contain at least one nonempty method")
+    evidence_level = require_nonempty_string(
+        verification, "evidence_level", "verification"
+    )
+    if evidence_level not in EVIDENCE_LEVELS:
+        raise RecordError(f"verification.evidence_level must be one of {sorted(EVIDENCE_LEVELS)}")
+    residual_or_error = verification.get("residual_or_error")
+    if not isinstance(residual_or_error, str):
+        raise RecordError("verification.residual_or_error must be a string")
+    if mode != "exact" and not residual_or_error.strip():
+        raise RecordError("numerical precision modes require verification.residual_or_error")
+    require_string_list(verification, "limitations", "verification")
+
+    return {
+        "ok": True,
+        "record": str(record_path),
+        "base_dir": str(base),
+        "selected_backend": selected_backend,
+        "evidence_level": evidence_level,
+        "verified_artifacts": verified_artifacts,
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Initialize or validate a computation-record.json file."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="initialize a record from a task file")
+    init_parser.add_argument("--task-file", required=True, type=Path)
+    init_parser.add_argument("--record", required=True, type=Path)
+    init_parser.add_argument("--force", action="store_true")
+
+    validate_parser = subparsers.add_parser("validate", help="validate a completed record")
+    validate_parser.add_argument("--record", required=True, type=Path)
+    validate_parser.add_argument("--base-dir", type=Path)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "init":
+            init_record(args.task_file, args.record, args.force)
+            return 0
+        result = validate_record(args.record, args.base_dir)
+        print(json.dumps(result, ensure_ascii=False))
+        return 0
+    except (OSError, RecordError) as exc:
+        print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())