diag3d 0.2.0__tar.gz

diag3d-0.2.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

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

@@ -0,0 +1,86 @@
+name: Scientific tests and package
+on:
+  push:
+  pull_request:
+  workflow_call:
+    inputs:
+      expected_tag:
+        type: string
+        default: ''
+permissions:
+  contents: read
+env:
+  OMP_NUM_THREADS: '1'
+  OPENBLAS_NUM_THREADS: '1'
+  POLARS_MAX_THREADS: '2'
+  PYTHONUTF8: '1'
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install '.[dev,gallery]'
+      - run: python -m compileall -q src
+      - run: python -m ruff check src tests experiments tools
+      - run: python -m pytest -q
+      - run: python tools/security_scan.py --history
+      - name: Installed wheel and sdist smoke test on this Python
+        run: |
+          python -m build --outdir "$RUNNER_TEMP/dist"
+          python tools/test_distribution.py "$RUNNER_TEMP"/dist/*
+  windows:
+    runs-on: windows-latest
+    env:
+      PYTHONUTF8: '0'  # the default code page, so encoding regressions surface here
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install ".[dev,gallery]"
+      - run: python -m pytest -q
+  build:
+    needs: [test, windows]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install 'build>=1.2,<2' 'twine>=6,<8'
+      - name: Build wheel from sdist with a reproducible timestamp
+        run: |
+          export SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)
+          python -m build
+      - run: python -m twine check --strict dist/*
+      - name: Validate distribution contents and version
+        env:
+          EXPECTED_TAG: ${{ inputs.expected_tag }}
+        run: |
+          if [ -n "$EXPECTED_TAG" ]; then
+            python tools/check_distribution.py --tag "$EXPECTED_TAG"
+          else
+            python tools/check_distribution.py
+          fi
+      - name: Analyze using clean wheel and sdist installations
+        run: python tools/test_distribution.py dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 30

diag3d-0.2.0/.github/workflows/prepare-release.yml

@@ -0,0 +1,83 @@
+name: Prepare release
+# Creates the version tag and a DRAFT GitHub Release with notes taken from CHANGELOG.md.
+# Nothing is published: publishing the draft (a deliberate human action) fires the
+# Release workflow, which stages on TestPyPI, publishes to PyPI through trusted
+# publishing and attaches the verified artifacts.
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Stable version to release, e.g. 0.2.0 (must equal src/diag3d/_version.py on main)'
+        type: string
+        required: true
+permissions:
+  contents: read
+env:
+  OMP_NUM_THREADS: '1'
+  OPENBLAS_NUM_THREADS: '1'
+  POLARS_MAX_THREADS: '2'
+  PYTHONUTF8: '1'
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - name: Require main, a stable version, a matching _version.py and a changelog entry
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          test "$GITHUB_REF" = "refs/heads/main"
+          [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          grep -qx "__version__ = \"$VERSION\"" src/diag3d/_version.py
+          grep -q "^## $VERSION " CHANGELOG.md
+          if git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null; then
+            echo "Tag v$VERSION already exists"; exit 1
+          fi
+      - run: python -m pip install ".[dev,gallery]"
+      - run: python -m compileall -q src
+      - run: python -m ruff check src tests experiments tools
+      - run: python -m pytest -q
+      - run: python tools/security_scan.py --history
+      - name: Build and audit the distributions
+        run: |
+          export SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)
+          python -m build
+          python -m twine check --strict dist/*
+          python tools/check_distribution.py --tag "v${{ inputs.version }}"
+      - name: Extract release notes from CHANGELOG.md
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          python - <<'EOF'
+          import os, re, pathlib
+          version = os.environ["VERSION"]
+          text = pathlib.Path("CHANGELOG.md").read_text(encoding="utf-8")
+          match = re.search(rf"^## {re.escape(version)}[^\n]*\n(.*?)(?=^## |\Z)", text, re.S | re.M)
+          body = match.group(1).strip() if match else ""
+          if not body:
+              raise SystemExit("No changelog section for this version")
+          notes = (f"{body}\n\n## Installation\n\n```bash\npip install diag3d=={version}\n"
+                   "```\n\nmacOS: `brew tap falhezaimi/tap && brew install diag3d`\n\n"
+                   "Wheel, sdist and SHA256SUMS are attached after PyPI publication is verified.\n")
+          pathlib.Path("release_notes.md").write_text(notes, encoding="utf-8")
+          EOF
+      - name: Create the annotated tag and a draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ inputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "v$VERSION" -m "Diag3D $VERSION"
+          git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "refs/tags/v$VERSION"
+          gh release create "v$VERSION" --draft --verify-tag --title "Diag3D $VERSION" \
+            --notes-file release_notes.md
+          echo "Draft release v$VERSION created; stage it with the Release workflow, then publish the draft."

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

@@ -0,0 +1,146 @@
+name: Release
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Approved stable tag to stage on TestPyPI, e.g. v0.2.0; select the same tag as ref'
+        type: string
+        required: true
+  release:
+    types: [published]
+permissions:
+  contents: read
+concurrency:
+  group: release-${{ github.event.release.tag_name || inputs.tag }}
+  cancel-in-progress: false
+env:
+  OMP_NUM_THREADS: '1'
+  OPENBLAS_NUM_THREADS: '1'
+  POLARS_MAX_THREADS: '2'
+jobs:
+  gate:
+    if: github.event_name == 'workflow_dispatch' || (!github.event.release.prerelease && !github.event.release.draft)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require an explicit stable version tag and matching ref
+        env:
+          TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: |
+          [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          test "$GITHUB_REF" = "refs/tags/$TAG"
+  validate:
+    needs: gate
+    uses: ./.github/workflows/ci.yml
+    with:
+      expected_tag: ${{ github.event.release.tag_name || inputs.tag }}
+  staging-status:
+    needs: validate
+    runs-on: ubuntu-latest
+    outputs:
+      already_staged: ${{ steps.status.outputs.already_staged }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-dist
+          path: dist/
+      - id: status
+        run: python tools/index_release.py stage-check --index testpypi
+      - name: Reject an existing production version
+        if: github.event_name == 'release'
+        run: python tools/index_release.py unused --index pypi
+  testpypi:
+    needs: staging-status
+    # Explicit opt-in: nothing is uploaded unless the repository enables staging.
+    if: needs.staging-status.outputs.already_staged != 'true' && vars.TESTPYPI_RELEASE_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/diag3d
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: false
+          print-hash: true
+          attestations: true
+  verify-testpypi:
+    needs: [staging-status, testpypi]
+    if: ${{ !cancelled() && vars.TESTPYPI_RELEASE_ENABLED == 'true' && needs.staging-status.result == 'success' && (needs.testpypi.result == 'success' || needs.testpypi.result == 'skipped') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-dist
+          path: dist/
+      - run: python tools/index_release.py verify --index testpypi
+  pypi:
+    needs: verify-testpypi
+    if: ${{ !cancelled() && needs.verify-testpypi.result == 'success' && github.event_name == 'release' && vars.PYPI_RELEASE_ENABLED == 'true' }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/diag3d
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          skip-existing: false
+          print-hash: true
+          attestations: true
+  verify-production:
+    needs: pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-dist
+          path: dist/
+      - run: python tools/index_release.py verify --index pypi
+  release-assets:
+    needs: verify-production
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-dist
+          path: dist/
+      - name: Attach the verified distributions and checksums
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          cd dist
+          sha256sum *.whl *.tar.gz > SHA256SUMS
+          gh release upload "$TAG" *.whl *.tar.gz SHA256SUMS

diag3d-0.2.0/.gitignore

@@ -0,0 +1,32 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+wheelhouse/
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+.DS_Store
+gallery/
+/validation/
+benchmark_outputs/
+results/
+.industry_cache/
+examples/industry_data/
+*.log
+
+/Diag3D-v0.2-research-evidence.html
+
+lifecycle_output/
+.pypirc
+.venv*/
+*.whl
+*.tar.gz

diag3d-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# Architecture
+
+The authoritative 0.2.0.dev0 development tree is created from the supplied v0.1 implementation. Legacy modules remain; research modules are additive and import the established Plotly/report shell.
+
+| Module | Responsibility and principal interfaces |
+|---|---|
+| `research/types.py` | Typed `PredictionRecord`, columnar `PredictionBatch`, `FoldPlan`, `OOFResult`, `ErrorField`, `FailureRegion`, `RegionMetrics`, `PersistenceResult`, `StabilityResult`, `CrossModelRegionAnalysis`, `SupportDiagnostics`, `FailureCharacterization`, `EvidenceScore`, `RepairExperimentResult`, `AnalysisResult` |
+| `research/config.py` | Validated analysis limits, score weights, characterization thresholds |
+| `research/oof.py` | Input validation, immutable reused fold plan, seeded cloned estimators, train-fold transforms, OOF predictions, train-relative support |
+| `research/fields.py` | Uniform/quantile 1D/2D binning, weighted empirical loss aggregation, support mask; `ErrorFieldEstimator` protocol |
+| `research/discovery.py` | Connected components, threshold lineages, core/extent geometry, Jaccard deduplication; `DiscoveryStrategy` protocol |
+| `research/stability.py` | Conditional row/group bootstrap and held-out fold rediscovery |
+| `research/diagnostics.py` | Cross-model disagreement, support interpretation, explicit taxonomy, exposed weighted ranking |
+| `research/analyzer.py` | `FailureAnalyzer.fit_analyze`, default model factories, bounded orchestration, reproducibility metadata |
+| `research/repairs.py` | Nested training-only selection; weighting, interaction, alternative estimator and resampling experiments |
+| `research/explorer.py` | Offline 1D/3D evidence figures, exact exposed cell boundaries, model/overlay controls, report sections and region inspection |
+| `research/benchmarks.py` | Six deterministic mechanisms, planted masks/bounds, localization evaluation |
+| `experiments/` | Reproducible full suite, seed/grid sensitivity and null audit |
+| `cli.py` | Seven commands; new `analyze` delegates to `FailureAnalyzer` |
+
+`AnalysisResult` retains numeric fields, OOF batches and typed regional evidence. `.visualize()` returns a Plotly figure; `.report(path)` writes standalone HTML; `.save(directory)` also writes strict JSON and observation-level OOF CSV. JSON export has no pickled estimators or executable payloads.
+
+## Preserved v0.1 architecture
+
+- `dataset.py`: strict CSV loading, Polars frames, deterministic row caps and original Dataset API.
+- `profiling.py`, `diagnostics.py`, `relationships.py`: column profiling, diagnostic flags, VIF, dependence and exploratory pair screening.
+- `modeling.py`: original single-held-out baseline result and metrics.
+- `visualization.py`, `surfaces.py`, `spatial.py`: relationship clouds, residual/disagreement landscapes, support-masked response surfaces and coordinate views.
+- `reporting.py`: offline Plotly bundling, responsive report shell, lazy rendering and camera controls.
+- `utils.py`, `config.py`: shared formatting, errors, limits and centralized version.
+
+The original 2,713 source lines were inspected. Machine-readable public class/function inventory is in `docs/v01_inventory.json`. The original archive's 79 tests passed before changes. Generated legacy industry galleries and downloaded datasets are excluded from source; their 12 asset checks remain optional and skip when the assets are absent. The other 67 baseline tests remain active.
+
+## Source provenance
+
+| Input | Role | SHA-256 |
+|---|---|---|
+| `Diag3D-v0.1.0(1).zip` | Implementation foundation | `d2cb469745008c968cf7a2917e232b6dd15ee298a9a392c238ffe0a5c89ce6a6` |
+| `Diag3D-packaging-candidate.zip` | Reference for dynamic versioning, artifact exclusions, metadata and release separation | `21eb9c15ce47fff942ffc23ff71ba7088229083069ee96e13158d82d212065e2` |
+
+No recovered research-reset source was substituted. Packaging reference science modules were not copied over v0.1. Public samples are recreated from generators or fetched with documented attribution; research data, caches, model binaries and generated galleries are not committed.
+
+## Performance and extension boundaries
+
+Fold indices, observation-level OOF losses and support transforms are computed once and reused. Uniform/quantile field aggregation uses bincount and bounded grids. Nearest-neighbor queries avoid materializing n×n distance matrices, although high-dimensional nearest-neighbor search can still be expensive. Estimator `n_jobs` is configurable; folds run sequentially to bound memory and BLAS thread pools are capped. Feature count, pair count, grid resolution, candidate count and bootstrap replicates are bounded.
+
+Bootstrap currently recalculates grids per candidate/replicate, preserving simple auditable logic at additional cost. It does not cache results to disk. The field/discovery protocols allow compatible grid strategies; custom geometry would also require changing matching, membership and visualization contracts. Categorical discovery, classification, arbitrary-dimensional regions, persistent homology and full model-refit bootstrap are not implemented.
+
+
+## Null-validation modules
+
+The existing v0.2 tree is extended by `calibration.py`, `nulls.py`, `refit.py`, `nested.py`, and optional `figures.py`. Public methods are `FailureAnalyzer.calibrate`, `refit_bootstrap`, and `validate_repairs`. Null maxima repeat the complete configured search; duplicate bootstrap identities never cross folds; strategy selection accepts outer-training data only. Typed results retain replicate maxima, p calculations, refit geometries and outer-fold predictions. See [detailed architecture](docs/architecture.md).
+
+
+## Lifecycle layer (`src/diag3d/lifecycle/`)
+
+| Module | Responsibility |
+|---|---|
+| `findings.py` | `Finding` (observation vs hypothesis, rule/version, evidence, counts, threshold, status incl. `not_evaluable`) |
+| `predictions.py` | `PredictionTable` keyed by `(sample_id, model, repeat, fold, seed, role, checkpoint)`; loaders; alignment |
+| `run.py` | `Run` directory: manifest, events, split, predictions, findings, artifacts; atomic writes; lock |
+| `preflight.py` | Data-quality and split-design checks; no model fitting |
+| `monitor.py` | `TrainingMonitor` events, checkpoint checks, LightGBM callback |
+| `investigate.py` | Bounded advisory follow-up checks with audit records |
+| `posthoc.py` | Frozen-prediction diagnostics; `oof_from_predictions` bridge to `FailureAnalyzer.analyze_oof` |
+| `splits.py` | `SplitManifest`: explicit or verified per-fold membership |
+| `report.py`, `figures.py` | Redacted outputs, `export_error_glb` (via the canonical `model_space/glb.py` exporter), optional Matplotlib figures |
+| `workflow.py` | `preflight_run`, `posthoc_run`, `reproduce_posthoc` |
+
+`research/oof.assemble_oof` is shared by fitted and imported predictions. See [docs/lifecycle.md](docs/lifecycle.md).

diag3d-0.2.0/BEFORE_AFTER.md

@@ -0,0 +1,29 @@
+# Before / after explorer comparison
+
+| Aspect | Existing v0.2 research explorer | New model-space explorer |
+|---|---|---|
+| Entry | Static research report with embedded local-error scenes | Immediate shared 3D environment |
+| Primary identity | Failure-region evidence | Pre-run and post-run spatial model exploration, with research evidence integrated |
+| Navigation | Report sections | DATA → MODEL → PREDICTION → ERROR → FAILURE → REPAIR |
+| Data before training | Separate legacy diagnostic report | Same viewport, missingness/support/target/correlation/shift inspection |
+| Supplied y/y_pred | Residual visualization command | Full CSV model-space workflow, no model file |
+| Camera and selection | Separate scenes and controls | One stateful camera and persistent row/region identity |
+| Failure evidence | Existing model/overlay/region controls | Same evidence in a compact inspector, exact union outlines and explicit source model |
+| Repair | Reported numerical experiments | Actual outer-prediction endpoint replay and guardrail table |
+| Classification | No calibrated discovery engine | Class/probability/confidence/error exploration; inference limitation explicit |
+| Fitted models | Existing research estimator API | Optional adapter for model queries and selected linear/tree explanations |
+| Browser validation | Prior pixel rendering unverified | Chromium/WebGL tested, including mobile sizing and zero external requests |
+
+The original evidence report remains separately available. Its only code change is renaming a colliding browser observer variable; numerical evidence and discovery logic are unchanged.
+
+## Existing research scene
+
+![Original research explorer layout](docs/model-space/00-research-explorer-before.png)
+
+## Unified failure space
+
+![New failure space](docs/model-space/05-failure.png)
+
+## Validated repair endpoint
+
+![New repair space](docs/model-space/07-repair-after.png)

diag3d-0.2.0/BENCHMARK_RESULTS.md

@@ -0,0 +1,72 @@
+# Actual synthetic benchmark results
+
+Executed locally with version 0.2.0.dev0, seed 42, 2,400 observations per case, five validation folds, 20 conditional bootstrap replicates, ten grid bins, minimum cell support 4 and region support 20. All values below come from actual runs. No ground-truth masks are supplied to the detector.
+
+## Localization and stability
+
+| Case | Best IoU | Precision | Recall | Samples | Error lift | Persistence | Bootstrap | Eligible-fold recurrence | Diagnostic candidate |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---|
+| A | 0.9955 | 1.0000 | 0.9955 | 220 | 4.490× | 100% | 100% | 100% (5/5 eligible) | SHARED_STRUCTURAL_FAILURE |
+| B | 1.0000 | 1.0000 | 1.0000 | 68 | 17.556× | 100% | 100% | 100% (5/5 eligible) | DATA_SPARSE_FAILURE |
+| C | 1.0000 | 1.0000 | 1.0000 | 384 | 5.099× | 100% | 100% | 100% (5/5 eligible) | SHARED_STRUCTURAL_FAILURE |
+| D | 1.0000 | 1.0000 | 1.0000 | 449 | 3.778× | 100% | 65% | 100% (1/5 eligible) | EXTRAPOLATION_FAILURE |
+| F | 0.9955 | 1.0000 | 0.9955 | 220 | 4.487× | 100% | 100% | 100% (5/5 eligible) | MODEL_SPECIFIC_FAILURE |
+
+IoU is observation-membership Jaccard. Benchmark scoring chooses the best-IoU candidate; the detector never sees ground truth. In D, the broader extent is F-02; the top-ranked severe core covers approximately half the true region. The 1/1 eligible-fold result in D must not be described as recurrence across all five folds.
+
+## Primary acceptance: A
+
+- Planted rectangle: 0.2 < x1 < 0.8 and 0.2 < x2 < 0.8; 221 true observations.
+- Detected F-01: exact union of nine adjacent cells, with enclosing bounds x1 [0.200173, 0.799691], x2 [0.199706, 0.799040]; 220 observations.
+- Source-model MAE 3.8363, global MAE 0.8543, lift 4.4904×; local relative density 1.0652 and training-neighbor distance ratio 0.9629.
+- Threshold lineage spans all six thresholds from 1.25× to 4×, with 20/20 bootstrap detections and 5/5 eligible fold detections.
+- Shared-error candidate among two deliberately restricted Ridge baselines. These are two estimators from one family, not two independent model families.
+- Report includes the computed surface, support/disagreement/persistence overlays, exact cell edges and region inspection. A static figure is generated by `experiments/plot_acceptance.py`.
+
+## Distinct secondary signatures
+
+- B: relative density 0.0634, training-neighbor distance ratio 3.476; sparse support is the primary category.
+- D: range-exceedance fraction 100%, training-neighbor distance ratio 4.012; extrapolation is primary.
+- F: regional Ridge MAE 4.5995 versus HGB 0.1995; affected model is Ridge.
+- C: high irreducible noise is detected as shared dense error. The taxonomy cannot causally distinguish noise from structural misspecification; this is a known limitation.
+
+## Grouped leakage: E
+
+| Validation | MAE | RMSE | R² |
+|---|---:|---:|---:|
+| Random KFold | 0.110541 | 0.138239 | 0.999261 |
+| GroupKFold | 6.044717 | 7.660880 | -1.269610 |
+
+Group-aware MAE is 54.68 times random-CV MAE. There is no unique planted geometric region in E, so localization precision/recall/IoU are not reported.
+
+## Nested repair experiments on A
+
+Geometry is rediscovered in each outer training fold through inner OOF prediction. Outer test outcomes do not select that geometry. Metrics pool fold-specific regimes. The second Ridge estimator is the predeclared alternative in this benchmark.
+
+| Strategy | Global MAE before → after | Regional MAE before → after | Outside MAE before → after | Success criteria met |
+|---|---:|---:|---:|---|
+| targeted_weighting | 0.8557 → 1.3664 | 3.8321 → 2.2773 | 0.5553 → 1.2745 | False |
+| interaction_augmentation | 0.8557 → 0.0994 | 3.8321 → 0.0928 | 0.5553 → 0.1001 | True |
+| alternative_estimator | 0.8557 → 0.8543 | 3.8321 → 3.8363 | 0.5553 → 0.5534 | False |
+| support_rebalancing | 0.8557 → 1.3659 | 3.8321 → 2.2793 | 0.5553 → 1.2737 | False |
+
+Weighting and rebalancing improve the selected regime while degrading the rest of the model, and are therefore rejected. Interaction augmentation improves all three metrics. This validates this synthetic procedure only, not general remediation effectiveness.
+
+## Failed attempts and remaining weaknesses
+
+- The first implementation chose only the severity-support core: D IoU was 0.5011. A broader excess-error representative improved D to 1.0 but degraded A and F to 0.4944. The final method retains both materially distinct representatives; core and extent remain correlated candidates. This development used the same benchmark suite, so it is not an independent methodological comparison.
+- F has 4 candidates with IoU <0.1 to the planted mask, out of 11 candidates. These include boundary effects and spurious candidates; they are not discarded to improve the report.
+- A grid/seed sensitivity check (seeds 17,43,101; grids 8,10,13; 1,600 rows) gives best-IoU range 0.704–1.000. Axis alignment matters.
+- Null-data audit uses five homoscedastic linear datasets (no planted localized failure). Results below demonstrate that recurrence does not establish significance.
+
+| Null seed | Candidate count | Highest priority score | Candidates with bootstrap and fold recurrence ≥0.6 |
+|---|---:|---:|---:|
+| 0 | 1 | 47.76 | 1 |
+| 1 | 1 | 21.83 | 0 |
+| 2 | 4 | 45.42 | 2 |
+| 3 | 1 | 19.69 | 0 |
+| 4 | 2 | 32.21 | 0 |
+
+**Next research priority:** independent discovery/confirmation evaluation with null-calibrated thresholds and explicit false-discovery/power assessment.
+
+Raw measured summaries: `docs/validation/benchmark_results.json` and `docs/validation/sensitivity_results.json`. Regenerate full reports and prediction records with the experiments runner.

diag3d-0.2.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+## 0.2.0 — first public release (2026-09-24)
+
+First release on PyPI as `diag3d` (`pip install diag3d`).
+
+Fixed: the training monitor recorded prediction part paths as OS-native strings and
+consolidated them by looking for a forward-slash prefix, so on Windows no part was ever
+registered and analysing a run failed with `KeyError: 'final'`. Parts are now recorded
+as POSIX paths and matched by file name; a regression test and a Windows CI job cover it.
+The killed-writer recovery test now uses a portable process kill.
+
+Fixed on Windows: run manifests, findings and explorer assets are read as UTF-8 regardless
+of the platform code page (they were always written as UTF-8), research outputs are written
+as UTF-8, and the `diag3d` CLI and the lifecycle examples no longer crash when the console or
+a redirected pipe cannot encode a character such as `→` or `ρ`: the echo degrades to `?`
+while every file stays UTF-8. The Windows CI job runs under the default code page.
+
+Added `diag3d.baselines`: reference baselines (`linear`, `rf`, `hgb`, and `xgb`, `lgbm`,
+`mlp` when their optional packages are installed) fitted on every partition of one
+explicit split manifest with shared preprocessing, documented default parameters,
+deterministic seeds, fit/predict wall-clock timings and environment metadata, returning
+a validated `PredictionTable`. Added `diag3d.lifecycle.partitions` (training rows versus
+evaluation rows of a manifest on a caller's row order) and widened the documented public
+surface of `diag3d.lifecycle` (`docs/public_api.md`).
+
+Release engineering: a "Prepare release" workflow creates the version tag and a draft
+GitHub Release with notes from this changelog; the release workflow stages on TestPyPI
+and publishes to PyPI through trusted publishing with attestations, verifies the
+published files and attaches them to the release; the build backend is pinned exactly so
+a rebuild of the tagged commit reproduces the validated bytes; a Homebrew tap
+(`falhezaimi/homebrew-tap`) is maintained separately.
+
+## Unreleased — consolidation into main
+
+Merged the model-space explorer (PR #1), GLB export (PR #4) and release readiness
+(PR #2), with safeguards ported from PR #3. One GLB exporter (the explorer's) replaces
+the lifecycle point-cloud exporter, which mirrored scenes and mis-encoded colours.
+The training monitor records observed fold membership and stores it as the run's split
+manifest. Run schema 2.1 records conventions for nested CV (outer loop only), multiple
+evaluation datasets (one linked dataset per table) and checkpoint units (declared).
+
+## Unreleased — lifecycle foundation audit
+
+Training membership is no longer inferred from fold labels unless a complement design
+(K-fold, repeated/group K-fold, leave-one-group-out) is declared and verified; other
+designs need an explicit `SplitManifest`, otherwise dependent checks are `not_evaluable`.
+Run schema 2.0 (split manifest, part-based prediction tables with dataset links, model
+registry, per-diagnostic Diag3D version, writer ids on events; 1.x readable read-only).
+Fixed: future/buffer rows counted as training data; complement taken across repeats;
+missing inputs reported as `pass` (small subgroups, single-role splits, missing times);
+test-set samples accepted under non-test roles during training; investigator reference
+defaulting to all samples; row-order-dependent results; int64 fingerprint collisions;
+duplicate CSV headers accepted; ECE bin edges off at exact boundaries; `status()` ignoring
+session order and Ctrl-C; resumed writers corrupting a torn event line and overwriting a
+crashed session's prediction parts; ~1 GB memory spike when finishing long runs.
+Added `r2_mean_over_repeats`, `tools/lifecycle_mutations.py` (20/20 mutations caught), 44 adversarial tests.
+
+## Unreleased — lifecycle diagnostics (version string remains 0.2.0.dev0)
+
+Added `diag3d.lifecycle`: shared `Finding` records; validated long-format `PredictionTable`
+with composite keys, explicit column mapping and CSV/Parquet/NPZ/structured-NPY loading
+(pickle/joblib only with `trusted=True`); directory `Run` store with versioned manifest,
+append-only events, atomic writes, fingerprints and a single-writer lock; `preflight`;
+`TrainingMonitor` with a LightGBM callback, test-label guard and bounded memory; bounded
+`Investigator`; `analyze_predictions` for frozen predictions; redacted Markdown/JSON/CSV
+outputs; `.glb` export with a companion manifest; optional Matplotlib figures. New CLI
+commands `preflight`, `posthoc`, `run-show`. `FailureAnalyzer.analyze_oof` runs region
+discovery on imported OOF predictions without fitting.
+
+Fixed: `python -m diag3d.cli analyze` failed with "No such command" (the `__main__` guard
+preceded the command). `r2_of_mean_prediction` is now `None` for a constant target instead
+of scikit-learn's 1.0/0.0.
+
+## Unreleased — release preparation
+
+- Preserve the unapproved `0.2.0.dev0` research version and single version source.
+- Validate both distributions, clean installations and installed OOF analysis.
+- Add stable-tag OIDC release automation with exact TestPyPI artifact verification,
+  duplicate-version rejection and an explicit production enable gate.
+- Extend source/history inspection and document Trusted Publishing, dependency
+  groups and the complete maintainer release procedure.
+
+## 0.2.0.dev0
+
+Implemented the research reset from v0.1: typed OOF failure-region engine, supported empirical error grids, threshold persistence, bootstrap/fold recurrence, cross-model/support diagnostics, transparent characterization and ranking, nested repair experiments, synthetic benchmarks, evidence explorer, research CLI/report, and development packaging. Preserved the legacy CSV API/commands and report infrastructure. Production publication remains disabled.
+
+## 0.2.0.dev0 — null-validation development snapshot
+
+Adds search-wide empirical calibration, six negative controls, model-refit bootstrap, training-only nested strategy selection, explicit repair guardrails, statistical explorer overlays, publication figures and measured false-positive/detection experiments. Retains the prior implementation and its regression coverage. Production publication remains disabled.
+
+## Model-space development snapshot — 2026-09-21
+
+- Added a unified Data/Model/Prediction/Error/Failure/Repair explorer and offline session contract.
+- Added CSV supplied-output reports, pre-run diagnostics, optional fitted-model adapters and evidence-backed repair replay.
+- Preserved the existing numerical research engine and original reporting APIs.
+- Fixed a duplicate observer declaration in the research HTML.
+- Added three redistributable demos, browser screenshots, source audit, architecture/UX specifications and 25 Python tests.

diag3d-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# Contributing
+
+Install `python -m pip install -e '.[dev]'`. Run `python -m pytest -q`, `python -m ruff check src tests experiments tools`, `python -m compileall -q src`, and the synthetic benchmark runner. Add tests for scientific invariants, leakage boundaries, stability and meaningful failure modes. Preserve failed benchmarks. Explain changes to estimands, fold design, overlap definitions or ranking formulas in `docs/research_method.md`.
+
+Do not commit datasets, generated reports, model artifacts, credentials, caches or environments. Production publishing and stable tags are disabled during the research reset. Discuss methodological claims with evidence and relevant prior art; do not infer causation from regional error alone.

diag3d-0.2.0/FLAGSHIP_DEMO.md

@@ -0,0 +1,18 @@
+# Flagship walkthrough — 28 seconds
+
+Open `gallery/model-space/regression.html` in a WebGL-capable desktop browser. Press **28s walkthrough**. A 1600×1000 recording provides readable axes and evidence; 1920×1080 is also suitable. The controls keep the same camera and selection as the layers change.
+
+| Time | Visual | Suggested narration |
+|---|---|---|
+| 0–4 s | Raw benchmark points in feature space | “Start with an ordinary machine-learning results table.” |
+| 4–8 s | Prediction field and residual lines appear | “Enter the relationship between observations and predictions.” |
+| 8–12 s | Prediction geometry | “See the response your model produces where data provide support.” |
+| 12–16 s | Error height and color | “Turn error into a spatial structure.” |
+| 16–18 s | Exact failure outlines | “Locate a recurring failure region.” |
+| 18–22 s | Region selected; calibration/refit inspector | “Inspect its support, recurrence and statistical assumptions.” |
+| 22–25.5 s | Original outer-test predictions | “A repair is chosen using training-side validation.” |
+| 25.5–28 s | Selected repair predictions and smaller residuals | “Then inspect the change on untouched outer-test observations.” |
+
+The exported MP4 is assembled from actual rendered browser captures of these states, with discrete cuts; it is not a continuous screen recording. The HTML button runs the interactive sequence for a fresh recording. No interpolated intermediate predictions are represented as a trained model.
+
+For a public caption, retain “synthetic interaction benchmark” and “research development version.” Do not generalize its 220/221 localization, 50/50 refit recurrence or large repair gain to real datasets. Keep the unresolved null-calibration caveat available in the linked evidence.