pear-sim 0.1.0__tar.gz

pear_sim-0.1.0/.gitattributes

@@ -0,0 +1,12 @@
+* text=auto
+
+# Source and evidence inputs must have byte-stable working-tree line endings on
+# macOS, Linux, and Windows because raw source SHA-256 is part of the evidence binding.
+*.json text eol=lf
+*.md text eol=lf
+*.py text eol=lf
+*.svg text eol=lf
+*.toml text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.lock text eol=lf

pear_sim-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,214 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  PEAR_SIM_UV_VERSION: "0.11.28"
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04]
+        python-version: ["3.11.15", "3.13.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: ${{ env.PEAR_SIM_UV_VERSION }}
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install locked environment
+        run: uv sync --locked --extra dev
+      - name: Unit and converter tests
+        run: uv run pytest
+      - name: Static checks
+        run: uv run ruff check .
+      - name: CLI smoke test
+        run: uv run pear-sim simulate examples/buck.yaml --out runs/buck --json
+      - name: Complementary PWM and human-report smoke
+        run: |
+          uv run pear-sim render examples/synchronous_buck_complementary.yaml --out artifacts/synchronous-buck --json
+          uv run pear-sim simulate examples/synchronous_buck_complementary.yaml --out runs/synchronous-buck --json
+          uv run pear-sim report runs/synchronous-buck --out reports/synchronous-buck --schematic artifacts/synchronous-buck/schematic.svg --json
+      - name: Three-phase SPWM, harmonics, and human-report smoke
+        run: |
+          uv run pear-sim render examples/inverter_three_phase_spwm.yaml --out artifacts/inverter-spwm --json
+          uv run pear-sim simulate examples/inverter_three_phase_spwm.yaml --out runs/inverter-spwm --json
+          uv run pear-sim report runs/inverter-spwm --out reports/inverter-spwm --schematic artifacts/inverter-spwm/schematic.svg --json
+      - name: Verified-run comparison smoke
+        run: >-
+          uv run pear-sim compare runs/buck runs/buck
+          --profile examples/buck_compare_profile.json
+          --out comparisons/buck-self --json
+      - name: Bounded parameter-sweep smoke
+        run: >-
+          uv run pear-sim sweep parameter examples/buck.yaml
+          --request examples/buck_parameter_sweep.json
+          --out sweeps/buck-parameter --json
+      - name: Canonical boost boundary evidence smoke
+        run: >-
+          uv run pear-sim sweep boost-boundary examples/boost.yaml
+          --ratios 0.9,1,1.1 --out sweeps/boost-boundary --json
+      - name: Canonical inverting buck-boost boundary evidence smoke
+        run: >-
+          uv run pear-sim sweep inverting-buck-boost-boundary
+          examples/inverting_buck_boost.yaml
+          --ratios 0.9,1,1.1 --out sweeps/inverting-buck-boost-boundary --json
+
+
+  test-other-os:
+    # Windows, macOS and ARM minutes are free on public repositories and billed
+    # extra (or unavailable) on private ones, so these platforms run once the
+    # repo is public.
+    if: ${{ !github.event.repository.private }}
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-2025, macos-15, ubuntu-24.04-arm]
+        python-version: ["3.13.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: ${{ env.PEAR_SIM_UV_VERSION }}
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install locked environment
+        run: uv sync --locked --extra dev
+      - name: Unit and converter tests
+        run: uv run pytest
+      - name: Static checks
+        run: uv run ruff check .
+      - name: CLI smoke test
+        run: uv run pear-sim simulate examples/buck.yaml --out runs/buck --json
+      - name: Complementary PWM and human-report smoke
+        run: |
+          uv run pear-sim render examples/synchronous_buck_complementary.yaml --out artifacts/synchronous-buck --json
+          uv run pear-sim simulate examples/synchronous_buck_complementary.yaml --out runs/synchronous-buck --json
+          uv run pear-sim report runs/synchronous-buck --out reports/synchronous-buck --schematic artifacts/synchronous-buck/schematic.svg --json
+      - name: Three-phase SPWM, harmonics, and human-report smoke
+        run: |
+          uv run pear-sim render examples/inverter_three_phase_spwm.yaml --out artifacts/inverter-spwm --json
+          uv run pear-sim simulate examples/inverter_three_phase_spwm.yaml --out runs/inverter-spwm --json
+          uv run pear-sim report runs/inverter-spwm --out reports/inverter-spwm --schematic artifacts/inverter-spwm/schematic.svg --json
+      - name: Verified-run comparison smoke
+        run: >-
+          uv run pear-sim compare runs/buck runs/buck
+          --profile examples/buck_compare_profile.json
+          --out comparisons/buck-self --json
+      - name: Bounded parameter-sweep smoke
+        run: >-
+          uv run pear-sim sweep parameter examples/buck.yaml
+          --request examples/buck_parameter_sweep.json
+          --out sweeps/buck-parameter --json
+      - name: Canonical boost boundary evidence smoke
+        run: >-
+          uv run pear-sim sweep boost-boundary examples/boost.yaml
+          --ratios 0.9,1,1.1 --out sweeps/boost-boundary --json
+      - name: Canonical inverting buck-boost boundary evidence smoke
+        run: >-
+          uv run pear-sim sweep inverting-buck-boost-boundary
+          examples/inverting_buck_boost.yaml
+          --ratios 0.9,1,1.1 --out sweeps/inverting-buck-boost-boundary --json
+
+  examples:
+    # Every shipped example must still load and run: examples are documentation
+    # that agents copy, and an example that rots silently teaches the wrong format.
+    timeout-minutes: 20
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: ${{ env.PEAR_SIM_UV_VERSION }}
+          python-version: "3.13.13"
+          enable-cache: true
+      - name: Install locked environment
+        run: uv sync --locked --extra dev
+      - name: Lint and run every example
+        run: |
+          for model in examples/*.yaml; do
+            name=$(basename "$model" .yaml)
+            uv run pear-sim lint "$model"
+            uv run pear-sim simulate "$model" --out "runs/$name" --lean > /dev/null
+          done
+
+  rust-core:
+    # The optional compiled kernel (rust/pear-sim-core): build it, then check
+    # it against SciPy, the exact solution and the reference engine on every
+    # example it supports.
+    timeout-minutes: 30
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: ${{ env.PEAR_SIM_UV_VERSION }}
+          python-version: "3.13.13"
+          enable-cache: true
+      - name: Install locked environment
+        run: uv sync --locked --extra dev
+      - name: Build the kernel
+        run: uvx --from "maturin==1.16.0" maturin build --release --locked -m rust/pear-sim-core/Cargo.toml -o rust-dist
+      - name: Install the kernel
+        run: uv pip install rust-dist/*.whl
+      - name: Kernel tests
+        run: uv run --no-sync pytest tests/test_rust_core.py "tests/test_batch.py::test_rust_batch_ranks_like_the_reference_engine" "tests/test_sensitivity.py::test_sensitivity_on_the_compiled_kernel_matches_the_reference"
+      - name: Every supported example on both engines
+        run: |
+          uv run --no-sync python scripts/rust_parity.py --tolerance 1e-12 --mode lean
+          uv run --no-sync python scripts/rust_parity.py --tolerance 1e-12 --mode full
+
+  ngspice-oracle:
+    # Independent-engine evidence: the differential tests skip silently when no
+    # ngspice binary is present, so this job installs one and makes them run.
+    timeout-minutes: 15
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: ${{ env.PEAR_SIM_UV_VERSION }}
+          python-version: "3.13.13"
+          enable-cache: true
+      - name: Install ngspice
+        run: sudo apt-get update && sudo apt-get install -y ngspice
+      - name: Install locked environment
+        run: uv sync --locked --extra dev
+      - name: Differential tests against ngspice (none may skip)
+        run: uv run pytest tests/test_ngspice_oracle.py -rs | tee ngspice.log && ! grep -q SKIPPED ngspice.log
+
+  secrets-scan:
+    timeout-minutes: 10
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+      - name: gitleaks (full history)
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Fallback: the API asset path can work while releases/download returns 504.
+          # The checksum below runs on whichever file was obtained — never skip it.
+          curl -sSfL --retry 5 --retry-all-errors --retry-delay 5 -o gitleaks.tar.gz https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz \
+            || gh release download v8.30.1 -R gitleaks/gitleaks -p gitleaks_8.30.1_linux_x64.tar.gz -O gitleaks.tar.gz --clobber
+          echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  gitleaks.tar.gz" | sha256sum -c -
+          tar -xzf gitleaks.tar.gz gitleaks
+          ./gitleaks git --redact --verbose .

pear_sim-0.1.0/.github/workflows/numerical-evidence.yml

@@ -0,0 +1,105 @@
+name: numerical-evidence
+
+# Cost policy (2026-07-21): this workflow produces the retained canonical-buck numerical evidence
+# matrix on three OSes (30-minute jobs, macOS at a 10x billing multiplier). It
+# is evidence *production*, not regression — a configured workflow was never a
+# claim that a bundle passed — so it runs only on demand.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: numerical-evidence-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  BLIS_NUM_THREADS: "1"
+  MKL_NUM_THREADS: "1"
+  NUMEXPR_NUM_THREADS: "1"
+  OMP_NUM_THREADS: "1"
+  OPENBLAS_NUM_THREADS: "1"
+  PYTHONHASHSEED: "0"
+  PEAR_SIM_UV_VERSION: "0.11.28"
+  VECLIB_MAXIMUM_THREADS: "1"
+
+jobs:
+  platform-evidence:
+    name: m22-${{ matrix.artifact_system }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            artifact_system: Linux
+          - os: macos-15
+            artifact_system: macOS
+          - os: windows-2025
+            artifact_system: Windows
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: ${{ env.PEAR_SIM_UV_VERSION }}
+          python-version: "3.12.13"
+          enable-cache: true
+      - name: Install locked environment
+        run: uv sync --locked --extra dev
+      - name: Run full canonical-buck numerical evidence profile
+        run: uv run pear-sim verify numerics buck-boundary examples/buck_dcm.yaml --profile full-v1 --source-revision "${{ github.sha }}" --out numerical-evidence --json
+      - name: Upload native numerical evidence
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: m22-${{ matrix.artifact_system }}
+          path: numerical-evidence/
+          if-no-files-found: warn
+          retention-days: 30
+
+  aggregate-platforms:
+    name: m22-cross-platform-aggregate
+    needs: platform-evidence
+    if: ${{ always() }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: ${{ env.PEAR_SIM_UV_VERSION }}
+          python-version: "3.12.13"
+          enable-cache: true
+      - name: Install locked environment
+        run: uv sync --locked --extra dev
+      - name: Download Linux evidence
+        if: always()
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: m22-Linux
+          path: platform-inputs/Linux
+      - name: Download macOS evidence
+        if: always()
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: m22-macOS
+          path: platform-inputs/Darwin
+      - name: Download Windows evidence
+        if: always()
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: m22-Windows
+          path: platform-inputs/Windows
+      - name: Aggregate native platform evidence
+        if: always()
+        run: uv run pear-sim verify platforms platform-inputs/Linux platform-inputs/Darwin platform-inputs/Windows --require Linux,Darwin,Windows --out cross-platform-evidence --json
+      - name: Upload cross-platform aggregate
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: m22-cross-platform
+          path: cross-platform-evidence/
+          if-no-files-found: warn
+          retention-days: 30

pear_sim-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: release
+
+# Manual: builds both distributions, checks their versions agree, and publishes
+# them to PyPI through trusted publishing. Nothing here runs on push.
+#
+# Each PyPI project has its own GitHub environment: PyPI refuses two pending
+# trusted publishers with the same (repository, workflow, environment), so
+# pear-sim publishes from `pypi` and pear-sim-mcp from `pypi-mcp`. Both
+# environments only deploy from main.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.11.28"
+          python-version: "3.13.13"
+      - name: Versions agree
+        run: |
+          core=$(uv run --no-project python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          shim=$(uv run --no-project python -c "import tomllib;print(tomllib.load(open('packaging/pear-sim-mcp/pyproject.toml','rb'))['project']['version'])")
+          pin=$(uv run --no-project python -c "import tomllib;print(tomllib.load(open('packaging/pear-sim-mcp/pyproject.toml','rb'))['project']['dependencies'][0])")
+          server=$(uv run --no-project python -c "import json;d=json.load(open('server.json'));print(d['version'], d['packages'][0]['version'])")
+          test "$core" = "$shim" && test "$pin" = "pear-sim[mcp]==$core" && test "$server" = "$core $core"
+      - name: Build
+        run: |
+          uv build --out-dir dist/core
+          uv build packaging/pear-sim-mcp --out-dir dist/mcp
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-core:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.11.28"
+      - name: Publish pear-sim
+        run: uv publish dist/core/*
+
+  # pear-sim-mcp pins pear-sim==<version>, so it goes up only after pear-sim.
+  publish-mcp:
+    needs: publish-core
+    runs-on: ubuntu-24.04
+    environment: pypi-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.11.28"
+      - name: Publish pear-sim-mcp
+        run: uv publish dist/mcp/*

pear_sim-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+runs/
+dist/
+.pear-sim/
+evals/mcp/results/
+rust/pear-sim-core/target/
+rust/pear-sim-core/dist/
+rust-dist/

pear_sim-0.1.0/AGENTS.md

@@ -0,0 +1,85 @@
+# PEARSim agent guide
+
+This repository is an executable early alpha of a clean-room, headless power-electronics simulator. Preserve correctness, diagnostics, and reproducibility before adding breadth or performance shortcuts.
+
+## Local workflow
+
+No Docker is required.
+
+```bash
+uv sync --locked --extra dev
+uv run pytest
+uv run ruff check .
+uv run pear-sim lint examples/buck.yaml --json
+uv run pear-sim simulate examples/buck.yaml --out runs/buck --json
+```
+
+On Windows PowerShell the same `uv` commands apply. A standard `venv` plus `pip install -e ".[dev]"` is an acceptable fallback.
+
+## Source map
+
+- `src/pear_sim/spec/model.py`: model loading, parameter resolution, semantic validation.
+- `src/pear_sim/spec/units.py`: supported engineering units and dimensional checks.
+- `src/pear_sim/core/circuit.py`: circuit stamping, topology compilation, diode active set, probes, and power balance.
+- `src/pear_sim/core/solver.py`: PWM event queue, hybrid integration, natural events, and result sampling.
+- `src/pear_sim/analysis/harmonics.py`: opt-in event-aligned dense-output Fourier/THD observation.
+- `src/pear_sim/analysis/three_phase_modulation.py`: strict SPWM command/event mapping and bounded human projection.
+- `src/pear_sim/analysis/mode_coverage.py`: conservative topology recognition and accepted-mode observations.
+- `src/pear_sim/api/capabilities.py`: versioned, fail-closed capability declarations for agent clients.
+- `src/pear_sim/evidence/expectations.py` and `src/pear_sim/evidence/evidence_io.py`: strict KPI expectation evaluation over manifest-verified runs.
+- `src/pear_sim/evidence/benchmark_harness.py`: topology-neutral retained-point execution, fail-closed errors, summaries, and artifact manifests; it must not import production physics or oracle equations.
+- `src/pear_sim/benchmarks/affine.py`: independently tested matrix-exponential primitives for already-derived affine oracle equations; topology matrices remain local to each oracle.
+- `src/pear_sim/benchmarks/buck_boundary.py`: independent periodic canonical-buck CCM/BCM/DCM oracle and comparison gates.
+- `src/pear_sim/benchmarks/boost_boundary.py`: independent periodic canonical-boost CCM/BCM/DCM oracle and comparison gates.
+- `src/pear_sim/benchmarks/inverting_buck_boost_boundary.py`: independent periodic oracle and signed-output gates for the exact canonical ideal inverting buck-boost.
+- `src/pear_sim/evidence/sweep.py`: bounded, retained-run canonical buck, boost, and exact inverting-buck-boost boundary sweep orchestration.
+- `src/pear_sim/evidence/run_compare.py`: fail-closed same-physics/same-measurement comparison of verified run bundles; no fuzzy mappings.
+- `src/pear_sim/evidence/parameter_sweep.py`: bounded, retained one-dimensional parameter experiments with optional expectations evaluation.
+- `src/pear_sim/evidence/batch.py`: many-design screening (Latin hypercube, grid or list), ranking against a declared objective and constraints, full re-run of finalists.
+- `src/pear_sim/evidence/sensitivity.py`: global sensitivity (Morris screening, Sobol indices with bootstrap intervals) on the batch machinery; estimators checked against closed forms.
+- `src/pear_sim/evidence/parallel_points.py`: concurrent point workers with outcomes in declaration order (used by every batch producer).
+- `src/pear_sim/reporting/benchmark_report.py`: deterministic offline human projection of recorded sweep evidence.
+- `src/pear_sim/evidence/numerical_evidence.py`: bounded `full-v1` numerical matrix producer for the exact canonical buck.
+- `src/pear_sim/evidence/platform_evidence.py`: strict native Linux/Darwin/Windows evidence verification and aggregation.
+- `src/pear_sim/reporting/numerical_report.py`: offline presentation-only projection of recorded numerical evidence.
+- `src/pear_sim/reporting/report.py`: bounded, offline human report projection; it must not recompute producer metrics.
+- `src/pear_sim/analysis/steady_state.py`: periodic steady state via Newton shooting on the production cycle map.
+- `src/pear_sim/analysis/small_signal.py`: two-topology state-space averaging, control-to-output Bode, declared-compensator loop-gain margins.
+- `src/pear_sim/evidence/stability.py`: retained stability bundles with blocking convergence/CCM/margin gates.
+- `src/pear_sim/api/cli.py`: stable agent-facing process contract.
+- `schema/model.schema.json`: normative structural schema for `pear-sim/v0.1`.
+- `schema/expectations.schema.json`: structural schema for `pear-sim/expectations/v0.1`.
+- `schema/numerical-profile.schema.json`, `schema/platform-evidence.schema.json`, and
+  `schema/cross-platform-evidence.schema.json`: normative canonical-buck numerical and cross-platform evidence structures.
+- `schema/boost-boundary-evidence.schema.json`: closed canonical-boost evidence structures.
+- `schema/inverting-buck-boost-boundary-evidence.schema.json`: closed exact canonical inverting-buck-boost evidence structures.
+- `schema/compare-profile.schema.json` and `schema/run-comparison.schema.json`: verified-run comparison input and evidence structures.
+- `schema/parameter-sweep-request.schema.json`, `schema/parameter-sweep-summary.schema.json`, and `schema/parameter-sweep-evidence.schema.json`: bounded one-dimensional experiment structures.
+- `docs/model-format.md`: current human-readable model contract.
+- `docs/m2-agent-evidence.md`: capability, expectation-evidence, and buck-boundary sweep contract.
+- `docs/m2-numerical-evidence.md`: canonical-buck numerical profile, artifacts, CI, status, and claim boundary.
+- `docs/m2-boost-boundary-evidence.md`: canonical-boost topology, oracle, gates, artifacts, and claim boundary.
+- `docs/benchmark-harness.md`: shared benchmark mechanics, oracle-independence boundary, and requirements for another retained family.
+- `docs/m3-spwm.md`: offline-midpoint SPWM, harmonic, artifact, and claim-boundary contract.
+- `validation/manifest.json`: planned validation claims and gates; a listed case is not automatically implemented.
+
+## Required discipline
+
+1. Do not silently regularize invalid ideal circuits with hidden `gmin`, leakage, or parasitics.
+2. Keep capacitor voltages and inductor currents continuous across ordinary switch events.
+3. Scheduled events sharing a timestamp must be applied atomically and deterministically.
+4. New components require unit checks, documented polarity/equations, a positive test, and an invalid-case test.
+5. Any model-schema change must update the JSON Schema, `docs/model-format.md`, examples, and tests in the same change.
+6. Never weaken a validation threshold merely to make a regression pass. Diagnose the numerical or modeling cause.
+7. Keep GPL/AGPL/mixed-license simulators outside the native runtime; use them only through explicit optional process adapters after license review.
+8. Do not copy proprietary source, models, icons, manuals, or text from any commercial simulator. Independent-engine evidence uses open engines (ngspice) and closed forms.
+
+## Current claim boundary
+
+The machine-readable claim boundary is the capability registry
+(`uv run pear-sim capabilities --json`, source `src/pear_sim/api/capabilities.py`):
+every capability is `supported`, `experimental` or `unsupported`, with its
+scope and evidence. Treat an unknown capability as unsupported, retain
+`fail`/`not_run` evidence instead of hiding it, and keep README limitations and
+the registry accurate as capabilities evolve. Agreement with another simulator
+is verification, not validation against hardware; never describe it otherwise.