phaseprobe 0.2.0__tar.gz

phaseprobe-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,35 @@
+name: Bug report
+description: Report a reproducible PhaseProbe defect.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    attributes:
+      label: Result first
+      description: What happened, and what should have happened?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Minimal reproduction
+      description: Include the command and a minimal non-sensitive configuration.
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: PhaseProbe and Python versions
+      placeholder: "phaseprobe 0.1.0; Python 3.12.13"
+    validations:
+      required: true
+  - type: dropdown
+    attributes:
+      label: Operating system
+      options: [Windows, Linux, Other]
+    validations:
+      required: true
+  - type: checkboxes
+    attributes:
+      label: Safety
+      options:
+        - label: I removed credentials, private model data, and personal information.
+          required: true

phaseprobe-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Private security report
+    url: https://github.com/aliengineering-byte/phaseprobe/security/advisories/new
+    about: Report vulnerabilities without exposing exploit details publicly.

phaseprobe-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Propose a focused simulation-testing improvement.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    attributes:
+      label: Testing job
+      description: Which transition, replay, evidence, or regression-testing job is missing?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Proposed evidence
+      description: Describe positive cases, negative controls, scientific terminology, and validation.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Alternatives and prior art
+      description: Link relevant tools or primary papers and explain the remaining gap.
+    validations:
+      required: true

phaseprobe-0.2.0/.github/ISSUE_TEMPLATE/good_first_accessibility.yml

@@ -0,0 +1,17 @@
+name: "Good first issue: report accessibility"
+description: Improve keyboard, contrast, and semantic HTML evidence without external assets.
+title: "[Good first issue] Improve offline report accessibility"
+labels: ["good first issue", "documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Audit the self-contained HTML report for semantic headings, table captions, contrast, print layout, and screen-reader labels. Add tests and before/after screenshots. Keep the report script-free, offline, and free of CDN resources.
+  - type: checkboxes
+    attributes:
+      label: Contributor checklist
+      options:
+        - label: I will document the audit method and measured changes.
+          required: true
+        - label: I will preserve HTML escaping and offline operation.
+          required: true

phaseprobe-0.2.0/.github/ISSUE_TEMPLATE/good_first_pendulum.yml

@@ -0,0 +1,17 @@
+name: "Good first issue: damped pendulum adapter"
+description: Add a small deterministic adapter with positive/negative controls.
+title: "[Good first issue] Add a damped-pendulum adapter"
+labels: ["good first issue", "example"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Implement a typed damped-pendulum adapter, an energy-decay invariant, a positive transition/check, a negative control, a primary citation, deterministic tests, replay coverage, and documentation. Do not label numerical damping as physical evidence without a solver-refinement comparison.
+  - type: checkboxes
+    attributes:
+      label: Contributor checklist
+      options:
+        - label: I will add configuration, tolerances, invalid-state policy, and bounded trace retention.
+          required: true
+        - label: I will add positive, negative-control, replay, and generated-test coverage.
+          required: true

phaseprobe-0.2.0/.github/ISSUE_TEMPLATE/good_first_schema.yml

@@ -0,0 +1,17 @@
+name: "Good first issue: JSON Schema fixtures"
+description: Publish schema documents and compatibility fixtures for config/replay/report JSON.
+title: "[Good first issue] Add JSON Schema validation fixtures"
+labels: ["good first issue", "tooling"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Add repository-owned JSON Schema documents for configuration, replay, and report version 1.0. Include valid and invalid fixtures, cross-platform tests, migration notes, and no new runtime dependency.
+  - type: checkboxes
+    attributes:
+      label: Contributor checklist
+      options:
+        - label: I will preserve existing version and integrity semantics.
+          required: true
+        - label: I will add actionable failure diagnostics and tests.
+          required: true

phaseprobe-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Outcome
+
+Describe the user-visible testing outcome first.
+
+## Scientific interpretation
+
+- What does the evidence establish?
+- What does it not establish?
+- Which primary sources support model or algorithm claims?
+
+## Validation
+
+- [ ] `python -m ruff format --check .`
+- [ ] `python -m ruff check .`
+- [ ] `python -m mypy src tests`
+- [ ] `python -m pytest --cov=phaseprobe`
+- [ ] Positive case and negative control
+- [ ] Replay and generated pytest execution
+- [ ] Package build and clean packed-install smoke
+- [ ] `python scripts/check_links.py`
+- [ ] `python scripts/hygiene.py`
+
+List exact commands and measured results. Do not include private paths, credentials, PDFs, or fabricated evidence.

phaseprobe-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "release/**"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  core-only:
+    name: core / ${{ matrix.os }} / Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -m "not scipy"
+      - run: python -m phaseprobe --version
+      - run: python -m phaseprobe scan --example logistic-negative
+
+  scipy-extra:
+    name: scipy / ${{ matrix.os }} / Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev,scipy]"
+      - run: python -m ruff format --check .
+      - run: python -m ruff check .
+      - run: python -m mypy src tests
+      - run: python -m pytest --cov=phaseprobe --cov-report=term
+      - run: python -m phaseprobe perturb --config examples/scipy/lorenz-negative.json
+      - run: python -m phaseprobe check --config examples/scipy/predator-prey.json
+
+  package-and-hygiene:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - run: python scripts/audit_package.py
+      - run: python -m venv .cache/packed-smoke
+      - run: .cache/packed-smoke/bin/python -m pip install dist/*.whl
+      - run: .cache/packed-smoke/bin/python -m phaseprobe --version
+      - run: .cache/packed-smoke/bin/python -m phaseprobe scan --example logistic-negative
+      - run: .cache/packed-smoke/bin/python -c "import importlib.util; assert importlib.util.find_spec('numpy') is None; assert importlib.util.find_spec('scipy') is None"
+      - run: python -m venv .cache/scipy-smoke
+      - run: .cache/scipy-smoke/bin/python -m pip install "$(find dist -name '*.whl')[scipy]"
+      - run: .cache/scipy-smoke/bin/python -m phaseprobe check --config examples/scipy/predator-prey.json
+      - run: python scripts/check_links.py
+      - run: python scripts/hygiene.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: phaseprobe-packages
+          path: dist/*
+          if-no-files-found: error

phaseprobe-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Tagged release validation
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  validate-tagged-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - run: python scripts/audit_package.py
+      - run: python -m venv .cache/tag-core-smoke
+      - run: .cache/tag-core-smoke/bin/python -m pip install dist/*.whl
+      - run: .cache/tag-core-smoke/bin/python -m phaseprobe --version
+      - run: .cache/tag-core-smoke/bin/python -m phaseprobe scan --example logistic
+      - run: python -m venv .cache/tag-scipy-smoke
+      - run: .cache/tag-scipy-smoke/bin/python -m pip install "$(find dist -name '*.whl')[scipy]"
+      - run: .cache/tag-scipy-smoke/bin/python -m phaseprobe check --config examples/scipy/predator-prey.json
+      - run: python scripts/hygiene.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: phaseprobe-${{ github.ref_name }}
+          path: dist/*
+          if-no-files-found: error

phaseprobe-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+.research_private/
+.venv/
+.tools/
+.cache/
+.phaseprobe/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

phaseprobe-0.2.0/AGENTS.md

@@ -0,0 +1,11 @@
+# PhaseProbe contributor instructions
+
+- Work exclusively inside the PhaseProbe repository root; never inspect or modify neighboring projects or workspaces.
+- Use the public author identity `Ali` only: no surname, personal email, workstation paths, credentials, or provider configuration in tracked files.
+- Keep scientific language precise: distinguish finite-time trajectory divergence, sensitive dependence, numerical instability, invariant violation, qualitative regime change, bifurcation evidence, stochastic variation, invalid integration, and solver failure. Never claim exact or formal results beyond the implemented evidence.
+- Support Windows and Linux on Python 3.10+ with no runtime LLM, API key, GPU, Docker, account, telemetry, or hosted service.
+- Keep copyrighted books, PDFs, extracted text, research notes, caches, environments, tools, build output, and run output out of Git.
+- Required validation: `python -m ruff format --check .`, `python -m ruff check .`, `python -m mypy src tests`, `python -m pytest`, `python -m build`, packed-install smoke test, quick start, examples, replay, generated-test execution, privacy/secret/large-file scans, and clean Git status.
+- Do not fabricate tests, performance, scientific evidence, benchmark results, users, or adoption claims.
+- Do not publish to PyPI without separate authorization.
+- Release only after all local gates pass; then use the authenticated `aliengineering-byte` GitHub account, pass CI, create the intended new annotated semantic-version tag and release, and verify a fresh unauthenticated clone. Never rewrite a published tag.

phaseprobe-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,83 @@
+# Architecture
+
+PhaseProbe separates simulation semantics from search, evidence, and test materialization.
+
+```text
+JSON config / built-in example
+            |
+            v
+       typed adapter ----> fixed step OR whole trajectory
+            |                         |
+            v                         v
+ bounded engine ----> finite validation ----> capped trace + SHA-256 integrity
+      |     |
+      |     +---- scan / perturb / check policy
+      v
+ outcome ----> run artifacts ----> replay verification ----> fixed pytest template
+      |
+      +---- terminal / JSON / self-contained HTML
+```
+
+## Modules
+
+- `config.py` emits schema `2.0`, keeps schema `1.0` readable, validates explicit Python adapter
+  references without importing them, loads packaged examples, and emits canonical JSON.
+- `types.py` defines the step-level `ModelAdapter`, trajectory-level `TrajectoryAdapter`, state
+  shape, trace point/trace, replay mode, and invariant result.
+- `models/` contains four independent reference adapters. They are examples, not engine special cases.
+- `adapters/scipy.py` optionally imports NumPy/SciPy and wraps only public `solve_ivp` behavior.
+- `adapters/loader.py` imports a user-selected dotted module and calls its named factory only at
+  execution time.
+- `engine.py` dispatches step versus trajectory execution and owns shared NaN/Inf/hard-limit
+  checks, bounded retention, scanning, perturbation, bracket refinement, repeatability
+  confirmation, and CI policy evaluation.
+- `artifacts.py` creates one finite run directory and hashes each evidence file.
+- `replay.py` reads v1 exact fixtures and emits v2 fixtures with explicit `exact` or `tolerance`
+  comparison, always after SHA-256 integrity validation.
+- `generate.py` uses a fixed code template and sanitized names. It never evaluates configuration text.
+- `reporting.py` renders terminal, JSON, and offline HTML with explicit limitations.
+- `cli.py` maps the six public commands to stable exit codes.
+
+## Adapter design and dispatch
+
+The engine deliberately does not require NumPy. A state is a tuple of finite floats; this keeps
+serialization and perturbation explicit. Existing adapters implement `ModelAdapter.step`, and
+their behavior is unchanged. Whole-trajectory solvers implement `TrajectoryAdapter.simulate` and
+return `SimulationTrace`; the engine never manufactures a fake fixed-step loop around them.
+Observations are scalar mappings and cannot carry arbitrary executable objects.
+
+Resolution order is explicit: a Python API caller may supply an adapter instance; otherwise a
+built-in model name resolves from the immutable registry; otherwise a schema-v2 `adapter` section
+may name an absolute dotted module and factory. Loading that factory executes trusted user code.
+Configuration validation alone checks syntax and does not import the module.
+
+An adapter supplies scientific judgment: initial conditions, state advance, observables, qualitative classification, and invariants. The engine supplies operational judgment: search bounds, retention, failure containment, hashes, artifacts, and policy exits.
+
+## Determinism and replay boundary
+
+PhaseProbe controls seeds, canonical configuration serialization, fixed command order, search
+grids, state perturbations, trace retention, and artifact hashing. An external adapter remains
+responsible for solver settings, thread behavior, native library versions, and hardware-sensitive
+arithmetic.
+
+Step adapters default to exact classification/model-identity/trace-hash replay. Adaptive SciPy
+adapters require tolerance replay: the fixture carries declared state/observable/invariant/grid/
+endpoint/event tolerances and expected solver success. The original trace hash remains as artifact
+integrity evidence but is not required to match numerically across environments.
+
+## Artifact safety
+
+Trace points are capped per series. Run IDs combine UTC time and an evidence digest. Replay fixtures carry a schema version and SHA-256 over every unsigned field. Generated tests copy a validated fixture into `tests/generated/fixtures/` and contain only a sanitized identifier plus a fixed relative path.
+
+## Extension checklist
+
+1. Give the adapter a stable explicit `identity` version and serialize configuration separately
+   from callable code.
+2. Make `initial_state` deterministic for the declared seed.
+3. Return the same state dimension after every step.
+4. Define classifier thresholds in configuration tolerances.
+5. Distinguish mathematical invariants from diagnostic bounds in invariant details.
+6. Select `exact` only where byte-identical retained values are justified; otherwise declare a
+   complete tolerance policy.
+7. Add positive, negative-control, invalid-state, repeatability, and replay tests.
+8. Cite a primary technical source for the model and document solver limitations.

phaseprobe-0.2.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes are documented here. PhaseProbe follows semantic versioning.
+
+## 0.2.0 — 2026-08-02
+
+- Added the backward-compatible `TrajectoryAdapter` protocol and shared engine dispatch; all v0.1
+  step adapters and examples continue unchanged.
+- Added optional `phaseprobe[scipy]` support with a typed public `SolveIVPAdapter`, controlled
+  evaluation grids, scalar/vector tolerances, methods, maximum step, named events, observables,
+  classifiers, invariants, invalid-value checks, bounded retention, and solver/environment evidence.
+- Added schema-v2 `exact` and `tolerance` replay while keeping schema-v1 exact fixtures readable.
+  Tolerance fixtures preserve state, observable, classifier, invariant threshold, grid, endpoint,
+  event, solver-success, version, and platform evidence without claiming byte-identical replay.
+- Added genuine SciPy Lorenz finite-time divergence and predator–prey first-integral examples,
+  negative controls, refinement evidence, HTML evidence, and generated pytest fixtures.
+- Added explicit safe-shape Python module/factory loading, core-without-SciPy tests, optional import
+  diagnostics, a Windows/Linux core/SciPy CI matrix, current SciPy audit, security/limitations docs,
+  demo assets, and an unposted upstream visibility proposal.
+- Base installation remains dependency-free. NumPy and SciPy are optional; no PyPI publication was
+  performed.
+
+## 0.1.0 — 2026-08-01
+
+- Added `scan`, `perturb`, `check`, `replay`, `generate-test`, and `report` commands.
+- Added typed adapters for logistic map, Lorenz, Lotka–Volterra predator–prey, and a mutually repressing genetic toggle.
+- Added deterministic seeds, canonical configuration, fixed-step execution, invalid-integration diagnostics, capped trace retention, and exact trace hashes.
+- Added transition brackets, bounded initial-state search, repeatability confirmation, replay fixtures with integrity hashes, and fixed-template pytest generation.
+- Added terminal, versioned JSON, and self-contained offline HTML evidence.
+- Added Windows/Linux CI, packaging and packed-install checks, documentation/hygiene gates, and repository-native demo assets.

phaseprobe-0.2.0/CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use PhaseProbe, cite the software release."
+title: "PhaseProbe"
+type: software
+authors:
+  - name: "Ali"
+version: 0.2.0
+date-released: 2026-08-02
+url: "https://github.com/aliengineering-byte/phaseprobe"
+repository-code: "https://github.com/aliengineering-byte/phaseprobe"
+license: Apache-2.0
+abstract: "PhaseProbe finds bounded qualitative simulation transitions and turns reproducible evidence into replay fixtures and pytest regressions."
+keywords:
+  - simulation testing
+  - reproducibility
+  - dynamical systems
+  - regression testing

phaseprobe-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of conduct
+
+PhaseProbe contributors must make technical collaboration safe, respectful, and evidence-led.
+
+Welcome people regardless of background or identity. Discuss ideas and code rather than personal characteristics. Give reproducible evidence, acknowledge uncertainty, accept correction, and avoid harassment, threats, sexualized conduct, discrimination, doxxing, or sustained disruption.
+
+Maintainers may edit or remove contributions and restrict participation when behavior harms the community. Report conduct concerns privately through the repository’s security/contact path; do not include sensitive personal information in a public issue. Reports will be reviewed fairly and with as much confidentiality as practical.
+
+Good-faith disagreement about scientific methods is welcome. Fabricated evidence, misrepresentation of certainty, or retaliation against someone raising a reproducibility concern is not.

phaseprobe-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+Contributions are welcome when they preserve PhaseProbe’s narrow testing job and scientific language.
+
+## Setup
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\python -m pip install -e ".[dev]"
+# Linux:   .venv/bin/python -m pip install -e ".[dev]"
+python -m ruff format --check .
+python -m ruff check .
+python -m mypy src tests
+python -m pytest --cov=phaseprobe
+```
+
+Install `.[dev,scipy]` to run the optional trajectory-adapter suite. Core-only jobs intentionally
+install `.[dev]` and run tests marked `not scipy`; SciPy jobs run the full suite. The committed
+`uv.lock` resolves the supported Python-dependent SciPy lines reproducibly.
+
+Before a pull request, also run `python -m build`, `python -m twine check dist/*`,
+`python scripts/audit_package.py`, install the base wheel and SciPy extra into separate clean
+environments, execute both quick starts, run `python scripts/check_links.py`, and run
+`python scripts/hygiene.py`.
+
+## Scientific changes
+
+New adapters or classifiers must include:
+
+- equation or model definition and a primary technical citation;
+- deterministic positive case and negative control;
+- seed, solver/iteration settings, tolerances, burn-in, observation window, and invalid-state policy;
+- an explanation of what the classifier establishes and what it does not;
+- replay and generated-test coverage;
+- solver-refinement or convergence evidence where numerical integration matters.
+
+Trajectory adapters must serialize explicit configuration without callable source, select an
+honest exact/tolerance replay mode, and test solver failure, invalid values, retention, and any
+supported event behavior.
+
+Do not call finite-time divergence a Lyapunov exponent, a numerical bracket an exact bifurcation point, or a bounded search result globally minimal.
+
+## Pull requests
+
+Keep changes focused, update documentation and `CHANGELOG.md`, and report exact validation commands. Never add copyrighted books, PDFs, extracted private text, credentials, personal email addresses, telemetry, runtime API/LLM/GPU/Docker requirements, or unsupported performance/adoption claims.
+
+At least three starter tasks are available as structured good-first-issue templates: add a damped-pendulum adapter, add JSON Schema validation fixtures, and improve HTML-report accessibility.