phaseprobe 0.2.0__py3-none-any.whl

phaseprobe/api.py

@@ -0,0 +1,64 @@
+"""Practical Python API for supplied step-level or trajectory-level adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from phaseprobe.config import CONFIG_SCHEMA_VERSION, ProbeConfig, canonical_json, parse_config
+from phaseprobe.engine import (
+    Adapter,
+    ProbeOutcome,
+    SimulationResult,
+    run_check,
+    run_perturb,
+    run_scan,
+    simulate,
+)
+
+
+def _coerce_config(adapter: Adapter, config: ProbeConfig | Mapping[str, object]) -> ProbeConfig:
+    if isinstance(config, ProbeConfig):
+        return config
+    data = dict(config)
+    data.setdefault("schema_version", CONFIG_SCHEMA_VERSION)
+    data.setdefault("model", adapter.name)
+    data.setdefault("seed", 0)
+    return parse_config(canonical_json(data), "Python API configuration")
+
+
+def run_simulation(
+    adapter: Adapter, config: ProbeConfig | Mapping[str, object]
+) -> SimulationResult:
+    """Run one supplied adapter without registering it globally."""
+
+    return simulate(_coerce_config(adapter, config), adapter=adapter)
+
+
+def run_parameter_scan(
+    adapter: Adapter, config: ProbeConfig | Mapping[str, object]
+) -> ProbeOutcome:
+    """Run the shared bounded one-dimensional scan with a supplied adapter."""
+
+    return run_scan(_coerce_config(adapter, config), adapter=adapter)
+
+
+def run_perturbation(adapter: Adapter, config: ProbeConfig | Mapping[str, object]) -> ProbeOutcome:
+    """Run the shared bounded initial-state perturbation search."""
+
+    return run_perturb(_coerce_config(adapter, config), adapter=adapter)
+
+
+def run_invariant_check(
+    adapter: Adapter, config: ProbeConfig | Mapping[str, object]
+) -> ProbeOutcome:
+    """Run the shared declared CI policy and invariant evaluation."""
+
+    return run_check(_coerce_config(adapter, config), adapter=adapter)
+
+
+__all__ = [
+    "run_invariant_check",
+    "run_parameter_scan",
+    "run_perturbation",
+    "run_simulation",
+]

phaseprobe/artifacts.py

@@ -0,0 +1,124 @@
+"""Bounded run-directory persistence and artifact manifests."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from phaseprobe.config import canonical_json
+from phaseprobe.engine import ProbeOutcome, SimulationResult
+from phaseprobe.replay import fixture_payload
+from phaseprobe.reporting import html_report, json_report
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65_536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactBundle:
+    """Paths written for one bounded PhaseProbe execution."""
+
+    run_directory: Path
+    run_json: Path
+    findings_json: Path
+    replay_json: Path
+    trace_jsonl: Path
+    report_html: Path
+    manifest_json: Path
+
+
+def _trace_lines(label: str, result: SimulationResult) -> list[str]:
+    lines: list[str] = []
+    for point in result.trace:
+        payload = {
+            "series": label,
+            "step": point.step,
+            "time": point.time,
+            "state": list(point.state),
+            "observations": dict(point.observations),
+        }
+        lines.append(canonical_json(payload))
+    return lines
+
+
+def write_artifacts(outcome: ProbeOutcome, output_root: Path) -> ArtifactBundle:
+    """Write finite evidence files and a hash manifest under one run directory."""
+
+    output_root.mkdir(parents=True, exist_ok=True)
+    signature = hashlib.sha256(canonical_json(outcome.as_dict()).encode("utf-8")).hexdigest()[:8]
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    run_directory = output_root / f"{timestamp}-{signature}"
+    suffix = 1
+    while run_directory.exists():
+        run_directory = output_root / f"{timestamp}-{signature}-{suffix}"
+        suffix += 1
+    run_directory.mkdir()
+
+    run_json = run_directory / "run.json"
+    findings_json = run_directory / "findings.json"
+    replay_json = run_directory / "replay.json"
+    trace_jsonl = run_directory / "trace.jsonl"
+    report_html = run_directory / "report.html"
+    manifest_json = run_directory / "manifest.json"
+
+    data = outcome.as_dict()
+    run_json.write_text(json_report(data), encoding="utf-8")
+    findings_json.write_text(
+        json.dumps(
+            {
+                "schema_version": "2.0",
+                "status": outcome.status,
+                "finding": dict(outcome.finding) if outcome.finding is not None else None,
+                "reproducible": outcome.reproducible,
+            },
+            allow_nan=False,
+            indent=2,
+            sort_keys=True,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    replay_json.write_text(
+        json.dumps(fixture_payload(outcome), allow_nan=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    trace_lines = _trace_lines("baseline", outcome.baseline)
+    if outcome.changed is not None:
+        trace_lines.extend(_trace_lines("changed", outcome.changed))
+    trace_jsonl.write_text("\n".join(trace_lines) + "\n", encoding="utf-8")
+    report_html.write_text(html_report(data), encoding="utf-8")
+
+    files = [run_json, findings_json, replay_json, trace_jsonl, report_html]
+    manifest = {
+        "schema_version": "2.0",
+        "run_id": run_directory.name,
+        "bounded_trace": {
+            "baseline_points": len(outcome.baseline.trace),
+            "changed_points": len(outcome.changed.trace) if outcome.changed is not None else 0,
+            "configured_cap_per_series": outcome.baseline.settings.trace_cap,
+        },
+        "files": {
+            path.name: {"bytes": path.stat().st_size, "sha256": _sha256(path)} for path in files
+        },
+    }
+    manifest_json.write_text(
+        json.dumps(manifest, allow_nan=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return ArtifactBundle(
+        run_directory=run_directory,
+        run_json=run_json,
+        findings_json=findings_json,
+        replay_json=replay_json,
+        trace_jsonl=trace_jsonl,
+        report_html=report_html,
+        manifest_json=manifest_json,
+    )

phaseprobe/cli.py

@@ -0,0 +1,242 @@
+"""PhaseProbe command-line interface and stable exit semantics."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from phaseprobe import __version__
+from phaseprobe.artifacts import ArtifactBundle, write_artifacts
+from phaseprobe.config import EXAMPLE_FILES, ProbeConfig, load_config, load_example
+from phaseprobe.engine import ProbeOutcome, run_check, run_perturb, run_scan
+from phaseprobe.errors import (
+    ConfigurationError,
+    ExitCode,
+    IntegrityError,
+    NumericalFailure,
+    PhaseProbeError,
+)
+from phaseprobe.generate import generate_regression_test
+from phaseprobe.replay import verify_replay
+from phaseprobe.reporting import json_report, regenerate_reports, terminal_report
+
+
+def _add_config_source(parser: argparse.ArgumentParser) -> None:
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--config", type=Path, help="versioned JSON configuration")
+    source.add_argument(
+        "--example", choices=sorted(EXAMPLE_FILES), help="built-in deterministic example"
+    )
+    parser.add_argument(
+        "--output-root",
+        type=Path,
+        default=Path(".phaseprobe") / "runs",
+        help="bounded run directory root (default: .phaseprobe/runs)",
+    )
+    parser.add_argument("--json", action="store_true", help="emit versioned JSON to stdout")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the public CLI parser."""
+
+    parser = argparse.ArgumentParser(
+        prog="phaseprobe",
+        description="Find bounded simulation transitions and turn them into regression tests.",
+    )
+    parser.add_argument("--version", action="version", version=f"phaseprobe {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    scan = commands.add_parser("scan", help="scan one parameter for adjacent qualitative changes")
+    _add_config_source(scan)
+    scan.add_argument(
+        "--fail-on-finding",
+        action="store_true",
+        help="return exit 1 when a transition is found",
+    )
+
+    perturb = commands.add_parser(
+        "perturb", help="search bounded initial-state perturbations with twin trajectories"
+    )
+    _add_config_source(perturb)
+    perturb.add_argument(
+        "--fail-on-finding",
+        action="store_true",
+        help="return exit 1 when a sensitive perturbation is found",
+    )
+
+    check = commands.add_parser("check", help="run a declared policy for CI enforcement")
+    _add_config_source(check)
+
+    replay = commands.add_parser("replay", help="re-execute an integrity-protected replay fixture")
+    replay.add_argument("fixture", type=Path)
+    replay.add_argument("--json", action="store_true")
+
+    generate = commands.add_parser(
+        "generate-test", help="generate fixed-template pytest from validated evidence"
+    )
+    generate.add_argument("fixture", type=Path)
+    generate.add_argument("--output-directory", type=Path, default=Path("tests") / "generated")
+    generate.add_argument("--json", action="store_true")
+
+    report = commands.add_parser(
+        "report", help="regenerate terminal, JSON, and offline HTML evidence"
+    )
+    report.add_argument("run_directory", type=Path)
+    report.add_argument("--format", choices=("terminal", "json", "html", "all"), default="all")
+    return parser
+
+
+def _config_from_args(args: argparse.Namespace) -> ProbeConfig:
+    config_path = getattr(args, "config", None)
+    example = getattr(args, "example", None)
+    if isinstance(config_path, Path):
+        return load_config(config_path)
+    if isinstance(example, str):
+        return load_example(example)
+    raise ConfigurationError("a configuration or built-in example is required")
+
+
+def _with_artifacts(outcome: ProbeOutcome, bundle: ArtifactBundle) -> dict[str, object]:
+    data = outcome.as_dict()
+    data["artifacts"] = {
+        "run_directory": str(bundle.run_directory),
+        "replay": str(bundle.replay_json),
+        "html_report": str(bundle.report_html),
+        "manifest": str(bundle.manifest_json),
+    }
+    return data
+
+
+def _run_evidence_command(
+    args: argparse.Namespace, execute: Callable[[ProbeConfig], ProbeOutcome]
+) -> int:
+    config = _config_from_args(args)
+    outcome = execute(config)
+    output_root = args.output_root
+    if not isinstance(output_root, Path):
+        raise ConfigurationError("output root must be a path")
+    bundle = write_artifacts(outcome, output_root)
+    data = _with_artifacts(outcome, bundle)
+    if bool(getattr(args, "json", False)):
+        sys.stdout.write(json_report(data))
+    else:
+        print(terminal_report(data, replay=str(bundle.replay_json)))
+        print(f"HTML report: {bundle.report_html}")
+    if outcome.policy_failed:
+        return int(ExitCode.POLICY_FAILED)
+    if bool(getattr(args, "fail_on_finding", False)) and outcome.finding is not None:
+        return int(ExitCode.POLICY_FAILED)
+    return int(ExitCode.OK)
+
+
+def _replay_command(args: argparse.Namespace) -> int:
+    fixture = args.fixture
+    if not isinstance(fixture, Path):
+        raise ConfigurationError("fixture must be a path")
+    verification = verify_replay(fixture)
+    data = verification.as_dict()
+    if bool(getattr(args, "json", False)):
+        sys.stdout.write(json_report(data))
+    else:
+        print(str(data["status"]))
+        print()
+        print(f"Model: {verification.model}")
+        print(f"Comparison mode: {verification.mode}")
+        for comparison in verification.comparisons:
+            if verification.mode == "exact":
+                print(
+                    f"{comparison['series']}: classification="
+                    f"{comparison['classification_match']}, "
+                    f"trace-hash={comparison['trace_hash_match']}, "
+                    f"model-identity={comparison['model_identity_match']}"
+                )
+            else:
+                matched = all(
+                    value is True for key, value in comparison.items() if key.endswith("_match")
+                )
+                print(f"{comparison['series']}: declared tolerances={matched}")
+    return int(ExitCode.OK if verification.ok else ExitCode.POLICY_FAILED)
+
+
+def _generate_command(args: argparse.Namespace) -> int:
+    fixture = args.fixture
+    output_directory = args.output_directory
+    if not isinstance(fixture, Path) or not isinstance(output_directory, Path):
+        raise ConfigurationError("fixture and output directory must be paths")
+    generated = generate_regression_test(fixture, output_directory)
+    data: dict[str, object] = {
+        "schema_version": "2.0",
+        "status": "PYTEST REGRESSION GENERATED",
+        "test": str(generated.test_path),
+        "fixture": str(generated.fixture_path),
+    }
+    if bool(getattr(args, "json", False)):
+        sys.stdout.write(json_report(data))
+    else:
+        print("PYTEST REGRESSION GENERATED")
+        print()
+        print(f"Test: {generated.test_path}")
+        print(f"Replay fixture: {generated.fixture_path}")
+    return int(ExitCode.OK)
+
+
+def _report_command(args: argparse.Namespace) -> int:
+    run_directory = args.run_directory
+    report_format = args.format
+    if not isinstance(run_directory, Path) or not isinstance(report_format, str):
+        raise ConfigurationError("invalid report arguments")
+    json_path, html_path = regenerate_reports(run_directory)
+    parsed = json.loads((run_directory / "run.json").read_text(encoding="utf-8"))
+    if not isinstance(parsed, dict):
+        raise ConfigurationError("run.json must contain an object")
+    data: dict[str, object] = parsed
+    if report_format in {"terminal", "all"}:
+        print(terminal_report(data, replay=str(run_directory / "replay.json")))
+    if report_format in {"json", "all"}:
+        if report_format == "json":
+            sys.stdout.write(json_report(data))
+        else:
+            print(f"JSON report: {json_path}")
+    if report_format in {"html", "all"}:
+        print(f"HTML report: {html_path}")
+    return int(ExitCode.OK)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI and translate expected defects into the documented exit contract."""
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "scan":
+            return _run_evidence_command(args, run_scan)
+        if args.command == "perturb":
+            return _run_evidence_command(args, run_perturb)
+        if args.command == "check":
+            return _run_evidence_command(args, run_check)
+        if args.command == "replay":
+            return _replay_command(args)
+        if args.command == "generate-test":
+            return _generate_command(args)
+        if args.command == "report":
+            return _report_command(args)
+        raise ConfigurationError(f"unknown command {args.command!r}")
+    except NumericalFailure as exc:
+        print(f"NUMERICAL FAILURE: {exc}", file=sys.stderr)
+        return int(ExitCode.NUMERICAL_FAILURE)
+    except (ConfigurationError, IntegrityError, ValueError, OSError) as exc:
+        print(f"INVALID INPUT: {exc}", file=sys.stderr)
+        return int(ExitCode.INVALID_INPUT)
+    except PhaseProbeError as exc:
+        print(f"PHASEPROBE ERROR: {exc}", file=sys.stderr)
+        return int(ExitCode.INTERNAL_ERROR)
+    except Exception as exc:  # pragma: no cover - final CLI containment boundary
+        print(f"INTERNAL PHASEPROBE DEFECT: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return int(ExitCode.INTERNAL_ERROR)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

phaseprobe/config.py

@@ -0,0 +1,132 @@
+"""Versioned JSON configuration loading and deterministic serialization."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Any, cast
+
+from phaseprobe.errors import ConfigurationError
+
+CONFIG_SCHEMA_VERSION = "2.0"
+SUPPORTED_CONFIG_SCHEMA_VERSIONS = frozenset({"1.0", CONFIG_SCHEMA_VERSION})
+_DOTTED_MODULE = re.compile(r"^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*$")
+_IDENTIFIER = re.compile(r"^[A-Za-z_]\w*$")
+
+
+def canonical_json(value: object) -> str:
+    """Serialize configuration data deterministically for hashing and replay."""
+
+    return json.dumps(value, allow_nan=False, separators=(",", ":"), sort_keys=True)
+
+
+def _as_object(value: Any, context: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise ConfigurationError(f"{context} must be a JSON object")
+    return cast(dict[str, object], value)
+
+
+@dataclass(frozen=True, slots=True)
+class ProbeConfig:
+    """Validated top-level configuration with typed access helpers."""
+
+    data: Mapping[str, object]
+    source: str
+
+    @property
+    def model(self) -> str:
+        value = self.data.get("model")
+        if not isinstance(value, str) or not value:
+            raise ConfigurationError("model must be a non-empty string")
+        return value
+
+    @property
+    def seed(self) -> int:
+        value = self.data.get("seed", 0)
+        if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+            raise ConfigurationError("seed must be a non-negative integer")
+        return value
+
+    def section(self, name: str, *, required: bool = True) -> Mapping[str, object]:
+        value = self.data.get(name)
+        if value is None and not required:
+            return {}
+        if not isinstance(value, dict):
+            raise ConfigurationError(f"{name} must be a JSON object")
+        return cast(Mapping[str, object], value)
+
+    def string(self, name: str, default: str | None = None) -> str:
+        value = self.data.get(name, default)
+        if not isinstance(value, str):
+            raise ConfigurationError(f"{name} must be a string")
+        return value
+
+
+def parse_config(text: str, source: str) -> ProbeConfig:
+    """Parse and validate a versioned JSON configuration."""
+
+    try:
+        parsed: Any = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ConfigurationError(f"invalid JSON in {source}: {exc}") from exc
+    data = _as_object(parsed, source)
+    version = data.get("schema_version")
+    if version not in SUPPORTED_CONFIG_SCHEMA_VERSIONS:
+        raise ConfigurationError(
+            f"unsupported configuration schema {version!r}; supported versions are "
+            f"{sorted(SUPPORTED_CONFIG_SCHEMA_VERSIONS)!r}"
+        )
+    config = ProbeConfig(data=data, source=source)
+    _ = config.model
+    _ = config.seed
+    adapter = data.get("adapter")
+    if adapter is not None:
+        values = _as_object(adapter, "adapter")
+        kind = values.get("kind")
+        module = values.get("module")
+        factory = values.get("factory")
+        if kind != "python":
+            raise ConfigurationError("adapter.kind must be 'python'")
+        if not isinstance(module, str) or _DOTTED_MODULE.fullmatch(module) is None:
+            raise ConfigurationError("adapter.module must be an absolute dotted Python module name")
+        if not isinstance(factory, str) or _IDENTIFIER.fullmatch(factory) is None:
+            raise ConfigurationError("adapter.factory must be a Python identifier")
+    return config
+
+
+def load_config(path: Path) -> ProbeConfig:
+    """Load a UTF-8 JSON configuration from a user-selected path."""
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigurationError(f"cannot read configuration {path}: {exc}") from exc
+    return parse_config(text, str(path))
+
+
+EXAMPLE_FILES: Mapping[str, str] = {
+    "logistic": "logistic-scan.json",
+    "logistic-negative": "logistic-negative.json",
+    "lorenz": "lorenz-perturb.json",
+    "lorenz-negative": "lorenz-negative.json",
+    "predator-prey": "predator-prey-check.json",
+    "predator-prey-negative": "predator-prey-negative.json",
+    "toggle": "toggle-perturb.json",
+    "toggle-negative": "toggle-negative.json",
+}
+
+
+def load_example(name: str) -> ProbeConfig:
+    """Load one of the immutable examples embedded in the installed wheel."""
+
+    filename = EXAMPLE_FILES.get(name)
+    if filename is None:
+        choices = ", ".join(sorted(EXAMPLE_FILES))
+        raise ConfigurationError(f"unknown example {name!r}; choose one of: {choices}")
+    package = resources.files("phaseprobe.data.examples")
+    text = package.joinpath(filename).read_text(encoding="utf-8")
+    return parse_config(text, f"built-in example {name}")

phaseprobe/data/__init__.py

@@ -0,0 +1 @@
+"""Packaged PhaseProbe data."""

phaseprobe/data/examples/__init__.py

@@ -0,0 +1 @@
+"""Deterministic built-in example configurations."""

phaseprobe/data/examples/logistic-negative.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": "1.0",
+  "model": "logistic-map",
+  "seed": 17,
+  "parameters": {"r": 3.2},
+  "model_config": {"initial_state": {"x": 0.2}},
+  "simulation": {
+    "steps": 128,
+    "burn_in": 1500,
+    "dt": 1.0,
+    "sample_every": 1,
+    "trace_cap": 128,
+    "hard_state_limit": 10.0
+  },
+  "tolerances": {"period": 1e-9},
+  "scan": {
+    "parameter": "r",
+    "start": 3.2,
+    "stop": 3.4,
+    "points": 5,
+    "refine_iterations": 6,
+    "repeatability": 2
+  },
+  "classification_rule": "Finite-period tail classifier used by the positive logistic example.",
+  "refinement_rule": "Refine only if an adjacent qualitative class change is observed.",
+  "invalid_state_policy": "Abort on invalid integration."
+}

phaseprobe/data/examples/logistic-scan.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": "1.0",
+  "model": "logistic-map",
+  "seed": 17,
+  "parameters": {"r": 3.448},
+  "model_config": {"initial_state": {"x": 0.2}},
+  "simulation": {
+    "steps": 256,
+    "burn_in": 500000,
+    "dt": 1.0,
+    "sample_every": 1,
+    "trace_cap": 256,
+    "hard_state_limit": 10.0
+  },
+  "tolerances": {"period": 1e-9},
+  "scan": {
+    "parameter": "r",
+    "start": 3.448,
+    "stop": 3.452,
+    "points": 3,
+    "refine_iterations": 12,
+    "repeatability": 2
+  },
+  "classification_rule": "Smallest detected period in {1,2,4,8,16} whose retained tail repeats within absolute tolerance; otherwise unresolved/aperiodic.",
+  "refinement_rule": "First adjacent coarse class change, followed by up to twelve deterministic binary probes. Refinement stops rather than relabeling a midpoint that reproduces neither stable endpoint class.",
+  "invalid_state_policy": "Abort as invalid integration on NaN, infinity, overflow, dimension mismatch, or hard-state-limit breach."
+}

phaseprobe/data/examples/lorenz-negative.json

@@ -0,0 +1,30 @@
+{
+  "schema_version": "1.0",
+  "model": "lorenz",
+  "seed": 23,
+  "parameters": {"sigma": 10.0, "rho": 28.0, "beta": 2.6666666666666665},
+  "model_config": {"initial_state": {"x": 1.0, "y": 1.0, "z": 1.0}},
+  "simulation": {
+    "steps": 1000,
+    "burn_in": 0,
+    "dt": 0.005,
+    "sample_every": 2,
+    "trace_cap": 500,
+    "hard_state_limit": 1000.0
+  },
+  "tolerances": {"state_bound": 100.0},
+  "perturb": {
+    "dimension": "x",
+    "start": 1e-8,
+    "stop": 0.0001,
+    "points": 5,
+    "scale": "log",
+    "predicate": "finite-time-divergence",
+    "divergence_threshold": 1000.0,
+    "refine_iterations": 4,
+    "repeatability": 2
+  },
+  "classification_rule": "Finite-time lobe visitation only.",
+  "refinement_rule": "No refinement when the declared separation threshold is not reached.",
+  "invalid_state_policy": "Abort on invalid integration."
+}

phaseprobe/data/examples/lorenz-perturb.json

@@ -0,0 +1,30 @@
+{
+  "schema_version": "1.0",
+  "model": "lorenz",
+  "seed": 23,
+  "parameters": {"sigma": 10.0, "rho": 28.0, "beta": 2.6666666666666665},
+  "model_config": {"initial_state": {"x": 1.0, "y": 1.0, "z": 1.0}},
+  "simulation": {
+    "steps": 8000,
+    "burn_in": 0,
+    "dt": 0.005,
+    "sample_every": 2,
+    "trace_cap": 4000,
+    "hard_state_limit": 1000.0
+  },
+  "tolerances": {"state_bound": 100.0},
+  "perturb": {
+    "dimension": "x",
+    "start": 1e-8,
+    "stop": 0.0001,
+    "points": 5,
+    "scale": "log",
+    "predicate": "finite-time-divergence",
+    "divergence_threshold": 1.0,
+    "refine_iterations": 8,
+    "repeatability": 2
+  },
+  "classification_rule": "Report retained finite-time lobe visitation; the finding predicate is Euclidean twin-trajectory separation, not a qualitative-class change.",
+  "refinement_rule": "Evaluate ascending logarithmic perturbations; refine a non-trigger/trigger bracket when one exists and repeat the smallest trigger.",
+  "invalid_state_policy": "Abort on NaN, infinity, overflow, or declared hard-state-limit breach."
+}