Advance the research runtime, adaptive inference, and safe shadow control plane

.github/workflows/runtime-quality-gates.yml

@@ -0,0 +1,133 @@
+name: Runtime quality gates
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: runtime-quality-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  runtime-parity:
+    name: Runtime parity (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install focused test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest flask pillow
+          python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+
+      - name: Compile runtime surfaces
+        run: |
+          python -m py_compile \
+            source/chat_app.py \
+            source/chat_web_app.py \
+            source/model_variants.py \
+            source/multimodel_memory.py \
+            source/route_policy_explorer.py \
+            source/route_policy_protocol.py \
+            source/route_policy_ledger.py \
+            source/route_policy_lab.py \
+            source/route_policy_shadow_registry.py \
+            source/route_policy_study_cli.py \
+            source/route_policy_protocol_cli.py \
+            source/route_policy_shadow_cli.py \
+            source/generate_studio_runtime_manifest.py \
+            source/multimodel_runtime.py \
+            source/qwen_supermix_pipeline.py \
+            source/supermix_multimodel_web_app.py \
+            source/supermix_multimodel_desktop_app.py \
+            runtime_python/chat_app.py \
+            runtime_python/chat_web_app.py \
+            runtime_python/model_variants.py
+
+      - name: Check self-contained runtime snapshot
+        run: python source/sync_runtime_model_variants.py --check
+
+      - name: Check Studio distribution contract
+        run: python source/generate_studio_runtime_manifest.py --check
+
+      - name: Run runtime and routing regression tests
+        run: |
+          python -m pytest -q test_runtime_model_variants_parity.py test_runtime_compute_controls.py
+          python -m pytest -q test_cognitive_leap_ultra_expert.py test_v51_materialize_demo.py
+          python -m pytest -q test_route_policy_explorer.py test_route_policy_protocol.py test_route_policy_ledger.py test_route_policy_lab.py test_route_policy_shadow_registry.py test_route_policy_study_cli.py test_route_policy_protocol_cli.py test_route_policy_shadow_cli.py test_route_policy_shadow_web_status.py test_studio_runtime_manifest.py test_multimodel_memory_tools.py
+          python -m pytest -q test_multimodel_runtime.py
+          python -m pytest -q test_supermix_multimodel_web_app.py
+          python -m pytest -q test_training_improvements.py
+
+      - name: Freeze and smoke-test protocol console
+        if: runner.os == 'Windows'
+        shell: powershell
+        run: |
+          python -m pip install pyinstaller
+          New-Item -ItemType Directory -Path build\ci_route_study -Force | Out-Null
+          python -m PyInstaller --noconfirm --clean --onefile --console --name SupermixRouteStudy --paths source --distpath dist\ci_route_study --workpath build\ci_route_study\work --specpath build\ci_route_study source\route_policy_protocol_cli.py
+          $payload = (& .\dist\ci_route_study\SupermixRouteStudy.exe --example --compact) | ConvertFrom-Json
+          if ($payload.schema_version -ne 'route-study-protocol-preflight-v1') { throw 'Frozen protocol schema mismatch' }
+          if ($payload.protocol.activation_available -ne $false) { throw 'Frozen protocol unexpectedly enables activation' }
+          if ($payload.charter.randomness.assignment_performed -ne $false) { throw 'Frozen protocol unexpectedly assigns a route' }
+          $bundlePath = Join-Path $PWD 'build\ci_route_study\review-bundle.json'
+          & .\dist\ci_route_study\SupermixRouteStudy.exe --example-bundle --output $bundlePath
+          if ($LASTEXITCODE -ne 0) { throw 'Frozen review-bundle build failed' }
+          $bundle = Get-Content -LiteralPath $bundlePath -Raw | ConvertFrom-Json
+          if ($bundle.schema_version -ne 'route-study-review-bundle-v1') { throw 'Frozen review-bundle schema mismatch' }
+          if ($bundle.source_study_plans.Count -ne 2) { throw 'Frozen review bundle lost source strata' }
+          $audit = (& .\dist\ci_route_study\SupermixRouteStudy.exe --audit-bundle $bundlePath --compact) | ConvertFrom-Json
+          if ($audit.verification_level -ne 'full_source_bound_reconstruction') { throw 'Frozen review bundle did not fully reconstruct' }
+          if ($audit.source_plan_reconstruction_performed -ne $true) { throw 'Frozen review bundle skipped source reconstruction' }
+          if ($audit.activation_available -ne $false) { throw 'Frozen review bundle unexpectedly enables activation' }
+
+          New-Item -ItemType Directory -Path build\ci_route_shadow -Force | Out-Null
+          python -m PyInstaller --noconfirm --clean --onefile --console --name SupermixRouteShadow --paths source --distpath dist\ci_route_shadow --workpath build\ci_route_shadow\work --specpath build\ci_route_shadow source\route_policy_shadow_cli.py
+          $registryPath = Join-Path $PWD 'build\ci_route_shadow\shadow.sqlite3'
+          $seedPath = Join-Path $PWD 'build\ci_route_shadow\private-seed.json'
+          $sealRaw = & .\dist\ci_route_shadow\SupermixRouteShadow.exe seal --registry $registryPath --bundle $bundlePath --seed-output $seedPath --compact
+          if ($LASTEXITCODE -ne 0) { throw 'Frozen shadow campaign seal failed' }
+          $seed = (Get-Content -LiteralPath $seedPath -Raw | ConvertFrom-Json).seed_material_base64url
+          if ($sealRaw -match [regex]::Escape($seed)) { throw 'Frozen shadow seal leaked private seed material' }
+          $seal = $sealRaw | ConvertFrom-Json
+          if ($seal.execution_enabled -ne $false) { throw 'Frozen shadow seal unexpectedly enables execution' }
+          $campaignId = $seal.public_package.campaign_seal.seal.campaign_id
+          $clusterPath = Join-Path $PWD 'build\ci_route_shadow\cluster.json'
+          @{ cluster_identifier = 'ci-shadow-cluster-1' } | ConvertTo-Json -Compress | Set-Content -LiteralPath $clusterPath -Encoding utf8
+          $commit = (& .\dist\ci_route_shadow\SupermixRouteShadow.exe commit --registry $registryPath --campaign $campaignId --seed-input $seedPath --cluster-input $clusterPath --compact) | ConvertFrom-Json
+          if ($commit.chosen_arm_revealed -ne $false) { throw 'Frozen shadow commitment revealed an arm early' }
+          $closure = (& .\dist\ci_route_shadow\SupermixRouteShadow.exe close --registry $registryPath --campaign $campaignId --compact) | ConvertFrom-Json
+          if ($closure.closure.frozen_commitment_count -ne 1) { throw 'Frozen shadow closure count mismatch' }
+          $revealRaw = & .\dist\ci_route_shadow\SupermixRouteShadow.exe reveal --registry $registryPath --campaign $campaignId --seed-input $seedPath --compact
+          if ($revealRaw -match [regex]::Escape($seed)) { throw 'Frozen shadow reveal CLI leaked seed material' }
+          $reveal = $revealRaw | ConvertFrom-Json
+          if ($reveal.seed_material_returned -ne $false) { throw 'Frozen shadow reveal returned seed material' }
+          $verify = (& .\dist\ci_route_shadow\SupermixRouteShadow.exe verify --registry $registryPath --campaign $campaignId --compact) | ConvertFrom-Json
+          if (($verify.complete -ne $true) -or ($verify.matched -ne 1) -or ($verify.mismatched -ne 0)) { throw 'Frozen shadow assignment reconstruction failed' }
+          $registryHashBeforeStatus = (Get-FileHash -LiteralPath $registryPath -Algorithm SHA256).Hash
+          $status = (& .\dist\ci_route_shadow\SupermixRouteShadow.exe status --registry $registryPath --campaign $campaignId --compact) | ConvertFrom-Json
+          if ($status.campaigns[0].state -ne 'reveal_verification_complete') { throw 'Frozen shadow registry state mismatch' }
+          if ($status.read_only -ne $true) { throw 'Frozen shadow registry status is not explicitly read-only' }
+          if ($status.activation_available -ne $false) { throw 'Frozen shadow registry unexpectedly enables activation' }
+          $registryHashAfterStatus = (Get-FileHash -LiteralPath $registryPath -Algorithm SHA256).Hash
+          if ($registryHashAfterStatus -ne $registryHashBeforeStatus) { throw 'Frozen shadow status mutated durable registry bytes' }

ARCHITECTURE.md

@@ -1,6 +1,7 @@
-# Architecture Guide: Supermix_27
+# Architecture Guide: Supermix
 
-This document provides an in-depth technical overview of the Supermix_27 model architecture, training pipeline, and design decisions.
+This document provides an in-depth technical overview of the Supermix model
+architecture, training pipeline, runtime surfaces, and design decisions.
 
 ---
 
@@ -35,10 +36,122 @@ This document provides an in-depth technical overview of the Supermix_27 model a
 ```
 
 The project is split into three main deployment surfaces:
-- **`source/`**: All training scripts, model definitions, dataset builders, and benchmarks.
-- **`runtime_python/`**: A self-contained copy of the inference-critical files with the production checkpoint.
+- **`source/`**: Active training code and the packaged multimodel Supermix Studio
+  runtime, including the route evidence/control plane.
+- **`runtime_python/`**: A legacy self-contained compatibility runtime. Its
+  generated `model_variants.py` stays synchronized, but it is not the active
+  multimodel Studio packaging tree.
 - **`web_static/`**: A static HTML/JS interface for GitHub Pages deployment (metadata retrieval only, no `.pth` inference).
 
+The Windows Studio build packages
+`source/supermix_multimodel_desktop_app.py` and includes a separate
+`SupermixRouteStudy.exe` review console plus a separate
+`SupermixRouteShadow.exe` commitment/reveal console.
+`source/studio_runtime_manifest.json` binds the active entrypoints, route schema
+versions, and module digests so source-only drift is detected before packaging.
+
+The route-study control plane has four intentionally separate artifact classes:
+
+1. an adjacent-route rehearsal plan for one prompt-specific post-filter support
+   stratum;
+2. a prompt-free stateful protocol draft that inventories one or more compatible
+   strata without assigning or executing them;
+3. a `route-study-review-bundle-v1` portable review bundle containing the full
+   canonical source plans and closed builder options;
+4. a shadow-only whole-policy assignment registry that consumes a fully
+   reconstructable review bundle without writing the executed-decision ledger.
+
+Bundle verification reconstructs the protocol byte-for-byte from its source
+plans. Standalone protocol audit remains structural because the compact draft
+does not embed those plans. Neither verification level supplies authenticity,
+a trusted timestamp, causal identification, random assignment, or permission to
+activate; those remain separate external gates.
+
+The shadow registry is implemented by `source/route_policy_shadow_registry.py`
+and stored separately at `memory/route-policy-shadow-registry.sqlite3`; it does
+not share tables or lifecycle semantics with `route-policy-ledger.sqlite3`. A
+campaign design binding freezes one sticky session-cluster assignment unit and
+exactly two whole-policy arms at 5,000 basis points each:
+`incumbent_source_policy` binds the complete source-policy cohort, while
+`candidate_target_policy` binds the complete target-policy class. The
+prompt-specific route actions carried by source strata describe where support
+exists; they are not treatment arms and are never pooled into a whole-policy
+assignment set.
+
+Those bindings are declarative policy-class manifests, not executable-code
+attestations. V1 also treats the private cluster identifier as an opaque byte
+string after input validation; it does not prove cluster-map membership or
+canonicalize aliases. Executable artifact binding and cluster-map governance
+remain separate prerequisites outside this registry.
+
+The commitment/reveal flow is deliberately one way:
+
+1. `seal` fully reconstructs the review bundle, generates 256 seed bits from the
+   operating-system CSPRNG, binds the seed commitment into a committed copy of
+   the bundle, and writes a public campaign seal;
+2. the seed material is written first to a separately handled private capsule
+   and is absent from the registry before reveal;
+3. `commit` derives a study-scoped cluster pseudonym internally and appends only
+   an opaque assignment-reveal commitment, withholding the chosen arm;
+4. `close` freezes the commitment count and prevents further enrollment;
+5. only then can `reveal` persist the public seed opening, after which `verify`
+   reconstructs the frozen assignments and checks their commitments.
+
+Registry artifacts use a strict, JCS-informed canonical JSON subset: duplicate
+keys and non-finite values fail closed, registry numbers are I-JSON-safe
+integers, and object keys are ASCII for portable ordering. RFC 5869
+extract-and-expand derives context-separated identity and assignment keys;
+HMAC-SHA-256 derives pseudonyms and whole-policy draw buckets. These mechanics
+make local reconstruction deterministic. They do not prove unbiased enrollment,
+independent seed custody, nonce-grinding resistance, anonymity, cluster
+independence, non-anticipation, finite carryover, or a valid interference model.
+
+All registry mutations require `SupermixRouteShadow.exe`. The Studio server
+exposes only `GET /api/route_shadow_registry/status`, so the browser can verify
+and display campaign state and the event chain but cannot seal, enroll, close,
+reveal, or verify assignments. The executed route ledger rejects shadow and
+rehearsal flags plus reserved shadow commitment namespaces. Any non-null
+executed assignment evidence must use the closed
+`route-execution-assignment-v1:<sha256>` namespace, so the registry's bare
+commitment digest cannot pass logging-support validation. This is a local type
+boundary, not authenticated provenance against a hostile caller.
+
+The Studio server defaults to the loopback interface (`127.0.0.1`); listening
+on another interface is an explicit operator choice and does not add
+authentication. The browser response is always `Cache-Control: no-store`.
+Within one process, an audited status snapshot is reused only while the durable
+database and non-empty WAL stat signature are unchanged; any observed change or
+concurrent-write race forces another full read-only audit.
+
+SQLite `BEGIN IMMEDIATE` transactions, append-only triggers, immutable closure
+and reveal rows, campaign-order indexes, and a domain-separated event hash chain
+protect normal local operation. Read-only snapshots audit those schema objects,
+verify an exact schema-definition fingerprint, reconstruct every stored artifact,
+and require the event inventory to match the evidence tables. Assignment
+verification preflights the frozen closure, public seed opening, and each
+commitment projection; processed mismatches remain verification failures. This
+remains a local file controlled by the host: there is no signer,
+trusted clock, external witness, verifiable-data-structure receipt, consistency
+or inclusion proof, or transparency service. The registry never invokes a
+model, chooses a live route, records an executed propensity, performs causal
+inference, activates a policy, or enables automatic promotion.
+
+`runtime_python/model_variants.py` is a generated snapshot of the canonical
+architecture registry. After changing `source/model_variants.py`, refresh and
+verify the standalone runtime with:
+
+```bash
+python source/sync_runtime_model_variants.py
+python source/sync_runtime_model_variants.py --check
+```
+
+The v51 prediction-stability verifier uses top-1 persistence plus confidence
+range to decide an inference-only early exit. It also computes a top-k
+Jensen-Shannon drift diagnostic over consecutive full-prefix output
+distributions, retaining all non-top-k mass in one bucket. That value is
+non-causal, shadow telemetry: it is exposed by the benchmark but is not an exit
+condition, router input, or activation signal.
+
 ---
 
 ## ChampionNet Backbone

CONTRIBUTING.md

@@ -1,6 +1,7 @@
-# Contributing to Supermix_27
+# Contributing to Supermix
 
-Thank you for your interest in contributing to Supermix_27! This guide explains how to get started, the code conventions we follow, and how to submit your changes.
+Thank you for contributing to Supermix. This guide covers the active source,
+legacy compatibility, test, and packaging contracts.
 
 ---
 
@@ -19,7 +20,7 @@ Thank you for your interest in contributing to Supermix_27! This guide explains
 ### Repository Structure
 
 ```
-Supermix_27/
+Supermix/
 ├── source/                     # Training, model definitions, dataset builders
 │   ├── run.py                  # ChampionNet backbone definition
 │   ├── model_variants.py       # All classifier head variants
@@ -28,9 +29,9 @@ Supermix_27/
 │   ├── device_utils.py         # Cross-platform device selection
 │   ├── benchmark.py            # Evaluation benchmarks
 │   └── build_*.py              # Dataset construction scripts
-├── runtime_python/             # Self-contained inference runtime
-│   ├── chat_web_app.py         # Production web server
-│   └── *.pth                   # Production checkpoint
+├── runtime_python/             # Legacy self-contained compatibility runtime
+├── source/supermix_multimodel_web_app.py     # Active Studio web runtime
+├── source/supermix_multimodel_desktop_app.py # Active packaged Studio entrypoint
 ├── web_static/                 # GitHub Pages static UI
 ├── MODEL_CARD_V28.md           # Model card with benchmarks
 ├── ARCHITECTURE.md             # Technical architecture deep-dive
@@ -58,7 +59,14 @@ Supermix_27/
 
 4. **Register in `finetune_chat.py`**: Add your variant to the `--model_size` choices.
 
-5. **Update documentation**: Add your variant to `MODEL_CARD_V28.md` and `ARCHITECTURE.md`.
+5. **Refresh the standalone runtime snapshot**:
+
+   ```bash
+   python source/sync_runtime_model_variants.py
+   python source/sync_runtime_model_variants.py --check
+   ```
+
+6. **Update documentation**: Add your variant to `MODEL_CARD_V28.md` and `ARCHITECTURE.md`.
 
 ### Adding a New Dataset
 
@@ -116,18 +124,32 @@ docs(model_card): fill in v28 benchmark results
 
 ## Testing
 
-Currently the project does not have a formal test suite. When contributing:
+The project has a formal pytest suite and focused runtime quality workflow. When contributing:
+
+1. Run the focused tests for the files you changed, then run the full suite:
+
+   ```bash
+   python -m pytest -q
+   ```
+
+2. For active Studio runtime or route-control changes, verify the checked
+   distribution contract and generated model-variant snapshot:
+
+   ```bash
+   python source/generate_studio_runtime_manifest.py --check
+   python source/sync_runtime_model_variants.py --check
+   ```
 
-1. **Smoke test** your changes by running a short training session:
+3. **Smoke test** training-specific changes with a short training session:
    ```bash
    python source/finetune_chat.py --data source/conversation_data.smoke_manifest.json \
        --data_manifest source/conversation_data.smoke_manifest.json \
        --model_size <your_variant> --epochs 1 --batch_size 32
    ```
 
-2. **Verify weight loading** from existing checkpoints to ensure backward compatibility.
+4. **Verify weight loading** from existing checkpoints to ensure backward compatibility.
 
-3. **Run benchmarks** if applicable:
+5. **Run benchmarks** if applicable:
    ```bash
    python source/benchmark.py
    ```