Integrate the ten-step expansion wave (9 of 10 branches)

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - name: Check out repository
@@ -21,6 +21,7 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
 
       - name: Install package
         run: python -m pip install -e ".[dev]"
@@ -36,3 +37,60 @@ jobs:
 
       - name: Compile source
         run: python -m compileall -q gpu_stack tests
+
+  verify:
+    name: Verify profile (full)
+    # Gate on the matrix so red commits do not consume verify/build runners.
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+
+      # --gate-timeout 0 disables per-gate timeouts (0 is treated as "no limit"
+      # by _gate_timeout in cli_verify.py). The full profile re-runs pytest by
+      # design; the read-only variant stays a local/release-time check (see
+      # RELEASING.md) so CI does not run the suite a sixth time.
+      - name: Run verify --profile full
+        run: python -m gpu_stack.cli verify --profile full --gate-timeout 0
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tools
+        run: python -m pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error

.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Release
+
+# Triggered only on version tags (e.g. v0.24.0).
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tools
+        run: python -m pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # IMPORTANT: Before this job can succeed you must complete the one-time
+  # PyPI setup described in RELEASING.md:
+  #   1. Create the project on PyPI (https://pypi.org/manage/projects/).
+  #   2. Add a Trusted Publisher on PyPI:
+  #      repository owner = <your-github-org-or-user>
+  #      repository name  = gpu_stack-
+  #      workflow name    = release.yml
+  #      environment name = pypi
+  #   3. Create a GitHub environment named "pypi" in the repository settings
+  #      (Settings > Environments) and, if desired, restrict deployments to
+  #      version tags or require a manual approval gate.
+  #
+  # Until those steps are completed, this job will fail at the OIDC token
+  # exchange step, which is safe -- nothing will be published accidentally.
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Only publish on actual version tags, never on branch pushes.
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    # The "pypi" environment must exist in GitHub repository settings.
+    # Configure it to require manual approval or restrict to tag patterns
+    # to prevent accidental publishes.
+    environment: pypi
+
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI via trusted publishing
+        # Pinned to an immutable commit SHA because this job holds id-token
+        # permissions; bump deliberately when upgrading.
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        # No API token needed -- authentication is via OIDC trusted publishing.
+        # The PyPI project and trusted publisher must be configured first
+        # (see the comment block above this job).

CHANGELOG.md

@@ -8,6 +8,33 @@ As of April 18, 2026 the user asked for roughly five files per response. Keep th
 
 ## Current physical deepening notes
 
+* Integrated the ten-step expansion wave (nine of ten branches; the SEMF
+  plus quark-decomposition branch remains a draft pending test
+  reconciliation). New surfaces: a sourced DGX H100 power BOM with an
+  assumption-labeled full-TCO pack that resolves econ.cost.per_token end
+  to end (3.738e-9 at the EIA 2024 industrial tariff, missing=0,
+  75 trace steps); sourced Pythia-160M and commercial-tariff packs
+  (8 sourced packs total); opt-in resolver fallback and 2-3 variable
+  simultaneous-system solving with trace explanations; Monte Carlo
+  uncertainty propagation in gpu_stack.uncertainty; a registry-backed
+  dependency-cone browser on the docs site with an export-graph-json
+  CLI (706 nodes, 1011 edges); a docs-stats verify gate (the full
+  profile is now five gates); CI verify parity, Python 3.13, and a
+  tag-gated release path; archived agent-memory ledgers under archive/;
+  and a closed metadata tail (with_sp_units 1428 to 1493,
+  with_references 1324 to 1493, equations_with_references 878 to 959,
+  equations_with_unit_check 799 to 893). The docs-stats gate caught all
+  ten stale README/site coverage numbers at integration and they were
+  refreshed from live output. Scenario-audit now reports 99 issues
+  across 8 packs by design: three open sourced cost frontiers each keep
+  their ~33 missing economics roots visible while the closure pack
+  resolves 4 of 4 targets. Full pytest passed `841 passed in 256.30s`
+  (one expected RuntimeWarning from the uncertainty failure-count
+  test); full verifier passed `5/5 gates passed in 260.02s`; read-only
+  full verifier passed `5/5 gates passed in 262.07s`; audit gate PASS;
+  impeccable detect on docs/ reports only the known CLI-flag em-dash
+  false positive.
+
 * Finalized the portfolio form-and-deliverable polish wave. The docs site
   moved to the three-font system from `DESIGN.md` (IBM Plex Sans reading
   copy, Pixelify Sans chrome and headings, IBM Plex Mono commands), gained
@@ -40,8 +67,9 @@ As of April 18, 2026 the user asked for roughly five files per response. Keep th
   `4/4 gates passed in 95.58s`; final source-clean check reported
   `cache_dirs=0 pyc_files=0 pytest_cache_dirs=0 ruff_cache_dirs=0`.
 * Finalized the physical root-debt boundary hardening wave. Runtime capped
-  live workers at six, so bounded write lanes were tracked through
-  `AGENT_GITLOG.md`. MOSFET, interconnect, lithography source/species, and
+  live workers at six, so bounded write lanes were tracked through a
+  pseudo-git coordination ledger (now archived at `archive/AGENT_GITLOG.md`).
+  MOSFET, interconnect, lithography source/species, and
   medium-response source surfaces gained boundary hardening; process geometry,
   SEMF/nuclear coefficients, source-plasma drive, medium intercomponent,
   root-debt, import, CLI, and boundary index/smoke-pack coverage were added or

HANDOFF.md

@@ -67,7 +67,7 @@ read `SESSION_STATE.md` and `VISIBLE_BACKLOG.md` first.
 Physical root-debt boundary hardening is now the previous verified handoff.
 
 - Runtime capped live workers at six, so the wave used bounded write lanes and
-  `AGENT_GITLOG.md` as a pseudo-git coordination ledger.
+  a pseudo-git coordination ledger (now archived in `archive/AGENT_GITLOG.md`).
 - Source changes landed in MOSFET, interconnect, lithography source/species,
   and medium-response surfaces.
 - Coverage expanded around process geometry, SEMF/nuclear coefficients,

IMPROVEMENT_MAP.md

@@ -1,9 +1,33 @@
 # gpu_stack improvement map
 
-Audit date: 2026-04-18 (original), live snapshot refreshed 2026-05-06.
+Audit date: 2026-04-18 (original), live snapshot refreshed 2026-06-10.
 
 ## Latest Verified Wave
 
+Portfolio form-and-deliverable polish is implemented, verified, and
+source-clean. Session memory files moved to `archive/`.
+
+- Scope: docs site typography and metadata, README example accuracy, ledger
+  reconciliation, and historical session-memory consolidation under `archive/`.
+- Docs site: three-font system (IBM Plex Sans / Pixelify Sans / IBM Plex Mono),
+  absolute Open Graph metadata, null-guarded panel renders, darkened eyebrow
+  labels.
+- README example fixes: dependency-cone sort by name; `evaluate_targets` uses
+  real variable name `training.tokens_per_sec`.
+- Moved `AGENT_DIARY.md`, `AGENT_WORKLOG.md`, `AGENT_GITLOG.md`,
+  `CODEX 5-5 START HERE.md`, `AGENT_REST_BREAKS/`, and `rest_breaks/` to
+  `archive/` to reduce root inventory noise.
+- Full pytest: `670 passed in 157.12s`.
+- Audit gate: PASS; systems 16, variables 1517, constants 24, equations 959,
+  root inputs 619, leaves 253, cycles 0, hard failures 0, large scope files 0,
+  large project files 0.
+- Full verifier: `4/4 gates passed in 157.32s`.
+- Read-only full verifier: `4/4 gates passed in 157.18s`.
+- Final source-clean check:
+  `cache_dirs=0 pyc_files=0 pytest_cache_dirs=0 ruff_cache_dirs=0`.
+
+## Previous Verified Wave
+
 Live next-work compass and scenario-audit missing-family ergonomics are
 implemented, verified, read-only verified, and source-clean.
 
@@ -29,7 +53,7 @@ Physical root-debt boundary hardening is implemented, verified, read-only
 verified, and source-clean.
 
 - Runtime capped live workers at six; bounded write lanes were tracked through
-  `AGENT_GITLOG.md`.
+  a pseudo-git coordination ledger (now archived at `archive/AGENT_GITLOG.md`).
 - MOSFET, interconnect, lithography source/species, and medium-response source
   surfaces gained boundary hardening.
 - Process geometry, SEMF/nuclear coefficients, source-plasma drive, medium
@@ -47,6 +71,8 @@ verified, and source-clean.
 
 ## Current snapshot
 
+Snapshot date: 2026-06-10.
+
 | Metric | Value |
 |---|---:|
 | Systems / scopes | 16 |
@@ -70,9 +96,9 @@ verified, and source-clean.
 | Variables with multiple defining relations, role-tagged | 53 |
 | Inequalities that simplify to `True` in `as_sympy()` | 0 |
 | Scope files at or above 700 lines | 0 |
-| Project Python files at or above 700 lines | 7 |
+| Project Python files at or above 700 lines | 0 |
 | Hard audit failures | 0 |
-| Collected pytest tests | 639 |
+| Collected pytest tests | 670 |
 
 ## Previous Verified Wave
 
@@ -182,7 +208,7 @@ Phase 3 modularization finished in pass 39. Every file in the original split map
 | `memory_cell.py` | 700 | DONE (pass 31) | `memory_sram.py`, `memory_dram.py`, `memory_flipflop.py` |
 | `parallelism.py` | 703 | DONE (pass 39) | `parallelism_batching.py`, `parallelism_zero_fsdp.py`, `parallelism_pipeline.py`, `parallelism_moe.py` |
 
-Phase 4 scenario resolver landed in pass 26 (`gpu_stack.core.resolver` plus `gpu_stack.resolve`). Phase 5 preset framework landed in pass 27 (`gpu_stack.core.presets` plus `gpu_stack.presets.*`). Phase 2 metadata helpers landed in pass 30 (`Registry.by_kind`, `Registry.by_extensivity`, `Registry.coverage`, and post-load `auto_classify_kinds`). Current compact metrics: 1517 variables, 959 equations, 619 roots, 639 collected tests. A CLI entry point landed in pass 32 (`gpu-stack stats`, `list-presets`, `resolve`). Scenario presets now include `dense_training_cost_fixture`, the first sourced/calibrated scenario pack, tin/EUV source scaffolding, SEMF calibration scaffolding, `scenarios.euv_tin120_lpp_source_context_assumption`, `scenario-report --missing-families`, `resolve --missing-families`, `Preset.evaluate_targets(...)`, `ScenarioReport`, `ScenarioTargetReport`, `MissingFamilySummary`, `scenario-report --json`, `scenario-audit`, `scenario-audit --missing-families`, `SCENARIO_TARGET_SETS`, `scenario_targets_for(...)`, and the `next-work` continuation compass.
+Phase 4 scenario resolver landed in pass 26 (`gpu_stack.core.resolver` plus `gpu_stack.resolve`). Phase 5 preset framework landed in pass 27 (`gpu_stack.core.presets` plus `gpu_stack.presets.*`). Phase 2 metadata helpers landed in pass 30 (`Registry.by_kind`, `Registry.by_extensivity`, `Registry.coverage`, and post-load `auto_classify_kinds`). Current compact metrics: 1517 variables, 959 equations, 619 roots, 670 collected tests. A CLI entry point landed in pass 32 (`gpu-stack stats`, `list-presets`, `resolve`). Scenario presets now include `dense_training_cost_fixture`, the first sourced/calibrated scenario pack, tin/EUV source scaffolding, SEMF calibration scaffolding, `scenarios.euv_tin120_lpp_source_context_assumption`, `scenario-report --missing-families`, `resolve --missing-families`, `Preset.evaluate_targets(...)`, `ScenarioReport`, `ScenarioTargetReport`, `MissingFamilySummary`, `scenario-report --json`, `scenario-audit`, `scenario-audit --missing-families`, `SCENARIO_TARGET_SETS`, `scenario_targets_for(...)`, and the `next-work` continuation compass.
 
 The remaining work from the original plan is:
 
@@ -206,8 +232,8 @@ Next highest-impact frontier: keep the scenario-artifact surface stable while ex
 | Constraint preservation | Current audit reports 0 inequalities that simplify to `True` in `as_sympy()`. The old SRAM margin collapses are now regression targets instead of live failures. | Constraints must stay inspectable as the graph grows, especially around branch conditions, approximation validity, and feasibility checks. | P1 |
 | Metadata coverage | The core supports references, unit checking, variable kinds, extensivity, shape, and dimensional expressions. The loaded model now uses most of it: 1324 non-constant variables have references, 1428 have `sp_units`, and 799 equations opt into dimensional checks. | Coverage is now broad across the model layer; the remaining gaps are visible and can be closed as focused slices. | P0 |
 | Calibration depth | There are still 619 root inputs across the graph, meaning variables with no value-defining identity, approximation, or selected variant. The first sourced/calibrated scenario pack is landed, full-verified, and source-clean. | The next frontier is reducing manual scenario assignments and making pack provenance/evaluation behavior reproducible. | P0 |
-| File cohesion | Current audit reports 0 scope files and 7 project Python files at or above 700 lines after lithography source-plasma, focused-beam, medium-response, and medium-density helper splits. | Reviewability, onboarding, and targeted regression testing stay tractable as scopes accumulate more subdomains. | Watch |
-| Verification surface | The bundle has timeout-protected smoke validation (`import`, `demo`, `compileall` or read-only syntax checking, graph health), package metadata, and 639 collected pytest tests behind the `verify` profiles; the fast profile now includes resolver tests plus the neutron-sensitive source-plasma trace test directly, and `--read-only` suppresses bytecode/pytest-cache artifacts where practical. | The project can keep growing symbolically, but regression risk will grow faster than coverage. | P0 |
+| File cohesion | Current audit reports 0 scope files and 0 project Python files at or above 700 lines after all helper splits including the portfolio-polish wave. | Reviewability, onboarding, and targeted regression testing stay tractable as scopes accumulate more subdomains. | Watch |
+| Verification surface | The bundle has timeout-protected smoke validation (`import`, `demo`, `compileall` or read-only syntax checking, graph health), package metadata, and 670 collected pytest tests behind the `verify` profiles; the fast profile now includes resolver tests plus the neutron-sensitive source-plasma trace test directly, and `--read-only` suppresses bytecode/pytest-cache artifacts where practical. | The project can keep growing symbolically, but regression risk will grow faster than coverage. | P0 |
 | User-facing evaluation | A conservative global resolver exists and computes targets from assignments through selected value relations, with symbolic-boundary missing reporting, constraint checks, approximation-validity checks, and optional strict CLI exits for violated feasibility. Scenario-report, root-debt, and `resolve --missing-families` diagnostics now share family/category grouping. The verified artifact surface includes `Preset.evaluate_targets(...)`, `ScenarioReport`, `ScenarioTargetReport`, `MissingFamilySummary`, `scenario-report --json`, and `scenario-audit` over sourced scenario packs with text/JSON output plus `--fail-on-issues`. It does not yet solve simultaneous systems or optimize over scenario choices. | The current API can run scenarios and emit structured artifacts; the highest-impact next step is selector control, broader pack reproducibility, and concise diagnostics. | P0 |
 | Packaging hygiene | Earlier artifacts included `__pycache__` output. A reproducible source-only build path still needs to be formalized. | Clean packaging matters once the repo starts moving between machines, agents, and CI. | P2 |