Release: development → main (442 commits) — G5 of the runbook, HOLD at G4b

.env.example

@@ -0,0 +1,48 @@
+# views-models — credential schema (NAMES ONLY; NEVER commit real values)
+#
+# HOW TO USE
+#   cp .env.example .env      # .env is gitignored — verified
+#   then fill the values from the Appwrite console (and the data-source providers).
+#   Check completeness at any time:  python tools/check_credentials.py
+#
+# WHERE VALUES COME FROM (as of 2026-07-27): the Appwrite console + the data-source
+# providers. There is not yet a durable secrets source of truth — that is a tracked
+# investigation (see reports/security/appwrite_credentials_audit.md and the
+# "secrets-management architecture" GitHub issue). Do NOT invent an interim scheme here.
+#
+# Legend:  [SECRET] = a real credential, guard carefully.  [id] = non-secret identifier.
+#
+# QUOTE ANY VALUE CONTAINING A SPACE.  (#293)
+# This file is not only read by python-dotenv — `postprocessors/un_fao/run.sh` **sources** it as a
+# bash script. An unquoted value with a space is parsed as an assignment plus a command:
+#
+#     APPWRITE_UNFAO_BUCKET_NAME=UNFAO Bucket     ->  sets ...NAME=UNFAO, then runs `Bucket`
+#     APPWRITE_UNFAO_BUCKET_NAME="UNFAO Bucket"   ->  correct
+#
+# The *_NAME coordinates below are the ones that carry spaces in practice. Quoting them costs
+# nothing and prevents a silently truncated identifier. Quoted form is shown as the example value.
+
+# ── Appwrite — REQUIRED to publish a forecast to the shelf (rusty_bucket --prediction_store)
+#    and for the un_fao postprocessor. This is the set run-0 needs.
+APPWRITE_ENDPOINT=                          # [id] Appwrite server URL
+APPWRITE_DATASTORE_PROJECT_ID=              # [id] Appwrite project id
+APPWRITE_DATASTORE_API_KEY=                 # [SECRET] the write credential
+APPWRITE_PROD_FORECASTS_BUCKET_ID=          # [id] the shelf bucket (production_forecasts)
+APPWRITE_PROD_FORECASTS_BUCKET_NAME=""      # [id] QUOTE IT — this value contains a space
+APPWRITE_PROD_FORECASTS_COLLECTION_ID=      # [id] metadata collection
+APPWRITE_PROD_FORECASTS_COLLECTION_NAME=""  # [id] QUOTE IT — this value contains a space
+APPWRITE_METADATA_DATABASE_ID=              # [id] metadata database
+APPWRITE_METADATA_DATABASE_NAME=""          # [id] QUOTE IT — this value contains a space
+
+# ── Appwrite — the FAO-facing store (unfao_bucket). Needed by the un_fao postprocessor
+#    and the faoapi serving side.
+APPWRITE_UNFAO_BUCKET_ID=                    # [id]
+APPWRITE_UNFAO_BUCKET_NAME=""                # [id] QUOTE IT — this value contains a space
+APPWRITE_UNFAO_COLLECTION_ID=                # [id]
+APPWRITE_UNFAO_COLLECTION_NAME=""            # [id] QUOTE IT — this value contains a space
+APPWRITE_UNFAO_APPROVED_FILE_IDS=            # [id] curation allow-list (may be empty)
+APPWRITE_UNFAO_QUARANTINED_FILE_IDS=         # [id] curation quarantine list (may be empty)
+
+# ── Other platform secrets referenced by code (data ingest; NOT needed for a --saved
+#    run-0, but required for fresh data fetches). Confirm scope before relying on these.
+VIEWS_DATAFACTORY=                           # datafactory access (confirm exact meaning)

.github/workflows/bootstrap.yml

@@ -0,0 +1,145 @@
+name: Bootstrap
+
+# `./bootstrap.sh` runs in CI against a fixture registry and a fake secret (#311).
+#
+# Why this job exists, and it is the point rather than a nicety. Prose describing setup
+# rots silently: nothing fails when it stops being true, and the person who discovers that
+# is the one least equipped to fix it — a new starter, on day one. A setup path verified
+# once, on one laptop, rots exactly the same way.
+#
+# This job is the only thing standing between "the setup script works" and "the setup
+# script worked in July". It uses a FIXTURE registry and a FAKE secret, so it needs no
+# credentials and no network, which is what lets it run on every push instead of never.
+
+on:
+  push:
+    branches: [main, development]
+  pull_request:
+    branches: [main, development]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  bootstrap:
+    name: bootstrap.sh against a fixture
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'   # tomllib; bootstrap.sh checks this itself and says so
+
+      - name: Build a fixture registry and a fake secret
+        run: |
+          set -euo pipefail
+          mkdir -p fixture
+          cat > fixture/coordinate_registry.toml <<'TOML'
+          [connection.APPWRITE_ENDPOINT]
+          class = "connection"
+          value = "https://fixture.invalid/v1"
+
+          [connection.APPWRITE_DATASTORE_PROJECT_ID]
+          class = "connection"
+          value = "fixture-project"
+
+          [target.APPWRITE_UNFAO_BUCKET_ID]
+          class = "target"
+          value = "unfao_bucket"
+
+          [target.APPWRITE_CRAFD_BUCKET_ID]
+          class = "target"
+          status = "planned — a reserved name with no value (a FIXTURE shape; the real registry has none since v1.4.0)"
+          TOML
+          # The fake secret. Never a real one: this repo is public and so are its logs.
+          echo 'APPWRITE_DATASTORE_API_KEY=FAKE-CI-SECRET-NOT-A-REAL-CREDENTIAL' > .env
+
+      - name: Run bootstrap.sh — no arguments
+        env:
+          APPWRITE_REGISTRY: ${{ github.workspace }}/fixture/coordinate_registry.toml
+        run: ./bootstrap.sh
+
+      - name: Run it again — idempotence is what makes it testable
+        env:
+          APPWRITE_REGISTRY: ${{ github.workspace }}/fixture/coordinate_registry.toml
+        run: |
+          set -euo pipefail
+          before="$(sha256sum .env)"
+          ./bootstrap.sh
+          after="$(sha256sum .env)"
+          [ "$before" = "$after" ] || {
+            echo "::error::bootstrap.sh modified .env on a re-run — it must be idempotent"; exit 1; }
+          echo "second run left .env byte-identical"
+
+      - name: A missing registry must fail, and name the cause
+        env:
+          APPWRITE_REGISTRY: /nonexistent/coordinate_registry.toml
+        run: |
+          set -uo pipefail
+          # `status=$?` after a plain assignment never runs here. GitHub invokes every
+          # step as `bash -e`, and `set -uo pipefail` does NOT clear `-e`, so a failing
+          # command substitution aborts the step before the status is read. Every
+          # scenario below asserts a NON-ZERO exit, so all four were unreachable: this
+          # workflow has been red since the day it landed and never tested anything.
+          # `|| status=$?` keeps the failure local while leaving `-e` on for genuinely
+          # unexpected failures elsewhere in the step.
+          status=0
+          out="$(./bootstrap.sh 2>&1)" || status=$?
+          echo "$out"
+          [ "$status" -ne 0 ] || { echo "::error::a missing registry must be fatal (#308)"; exit 1; }
+          echo "$out" | grep -q "APPWRITE_REGISTRY=" || {
+            echo "::error::the failure must name the override variable"; exit 1; }
+          echo "failed correctly, naming the cause"
+
+      - name: A .env declaring a registry-owned coordinate must fail
+        env:
+          APPWRITE_REGISTRY: ${{ github.workspace }}/fixture/coordinate_registry.toml
+        run: |
+          set -uo pipefail
+          echo 'APPWRITE_ENDPOINT=https://wrong.invalid' >> .env
+          status=0
+          out="$(./bootstrap.sh 2>&1)" || status=$?
+          echo "$out"
+          [ "$status" -ne 0 ] || { echo "::error::two writers to one name must be fatal (#309)"; exit 1; }
+          echo "$out" | grep -q "APPWRITE_ENDPOINT" || {
+            echo "::error::the failure must name the conflicting variable"; exit 1; }
+          echo "failed correctly, naming the variable"
+
+      - name: A missing secret must fail rather than hang
+        env:
+          APPWRITE_REGISTRY: ${{ github.workspace }}/fixture/coordinate_registry.toml
+        run: |
+          set -uo pipefail
+          rm -f .env
+          # stdin is not a terminal here, which is the case that would hang if bootstrap
+          # prompted unconditionally. A hung CI job is a worse failure than a red one.
+          status=0
+          out="$(timeout 30 ./bootstrap.sh < /dev/null 2>&1)" || status=$?
+          echo "$out"
+          [ "$status" -ne 124 ] || { echo "::error::bootstrap.sh HUNG waiting for input"; exit 1; }
+          [ "$status" -ne 0 ]   || { echo "::error::a missing secret must be fatal"; exit 1; }
+          echo "failed correctly without hanging"
+
+      - name: The secret must never reach the log
+        env:
+          APPWRITE_REGISTRY: ${{ github.workspace }}/fixture/coordinate_registry.toml
+        run: |
+          set -uo pipefail
+          # RESTORE the secret first. The previous step deletes .env, and without this the
+          # run would exit at the stdin check having never handled a secret at all — the
+          # grep below would then pass because the string was never in scope, not because
+          # redaction works. A check that cannot fail is worse than no check.
+          echo 'APPWRITE_DATASTORE_API_KEY=FAKE-CI-SECRET-NOT-A-REAL-CREDENTIAL' > .env
+          status=0
+          out="$(./bootstrap.sh 2>&1)" || status=$?
+          [ "$status" -eq 0 ] || {
+            echo "$out"
+            echo "::error::this step must exercise the secret-present path; bootstrap failed instead"
+            exit 1; }
+          if grep -q "FAKE-CI-SECRET-NOT-A-REAL-CREDENTIAL" <<< "$out"; then
+            echo "::error::bootstrap.sh rendered the secret value — it must report presence only"
+            exit 1
+          fi
+          echo "secret handled and never rendered"

.github/workflows/cic_sync_check.yml

@@ -0,0 +1,57 @@
+name: CIC Sync Check
+on:
+  pull_request:
+    branches: [main, development]
+
+jobs:
+  cic-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check CIC-governed files have matching CIC updates
+        run: |
+          set -uo pipefail
+
+          BASE="${{ github.event.pull_request.base.sha }}"
+
+          declare -A CIC_MAP
+          CIC_MAP["tools/catalogs/create_catalogs.py"]="docs/CICs/CatalogExtractor.md"
+          CIC_MAP["tools/scaffold/build_model_scaffold.py"]="docs/CICs/ModelScaffoldBuilder.md"
+          CIC_MAP["tools/scaffold/build_ensemble_scaffold.py"]="docs/CICs/EnsembleScaffoldBuilder.md"
+          CIC_MAP["tools/scaffold/build_package_scaffold.py"]="docs/CICs/PackageScaffoldBuilder.md"
+          CIC_MAP["tools/partitions/domain.py"]="docs/CICs/PartitionBoundaries.md"
+          CIC_MAP["tools/partitions/fileops.py"]="docs/CICs/PartitionFileOps.md"
+          CIC_MAP["tools/partitions/bump.py"]="docs/CICs/PartitionBump.md"
+          CIC_MAP["run_integration_tests.sh"]="docs/CICs/IntegrationTestRunner.md"
+          # The tools/liveness shared contract: the verdict->exit-code map and the
+          # crash-containing runner ARE the contract (per-surface modules are not).
+          CIC_MAP["tools/liveness/report.py"]="docs/CICs/LivenessChecks.md"
+          CIC_MAP["tools/liveness/__main__.py"]="docs/CICs/LivenessChecks.md"
+
+          CHANGED_FILES=$(git diff --name-only "$BASE"...HEAD)
+
+          MISSING=()
+          for source in "${!CIC_MAP[@]}"; do
+            cic="${CIC_MAP[$source]}"
+            if echo "$CHANGED_FILES" | grep -qx "$source"; then
+              if ! echo "$CHANGED_FILES" | grep -qx "$cic"; then
+                MISSING+=("$source -> $cic")
+              fi
+            fi
+          done
+
+          if [ "${#MISSING[@]}" -gt 0 ]; then
+            echo "::error::CIC-governed files changed without updating their CIC contract:"
+            for m in "${MISSING[@]}"; do
+              echo "  $m"
+            done
+            echo ""
+            echo "Update the CIC document to reflect behavioral changes (ADR-006)."
+            echo "If the change is purely cosmetic (whitespace, comments), add [cic-skip] to the PR title."
+            exit 1
+          fi
+
+          echo "CIC sync check passed."

.github/workflows/roster_configs_load.yml

@@ -0,0 +1,54 @@
+name: Roster Configs Load
+
+# C-259 exit: tests/test_roster_configs_load.py constructs each of the 8 HydraNet
+# roster configs through HydraNetConfig for real. test_roster_conformance.py compares
+# 184 config values against a reference dict and never builds the object — which is
+# how two production ensemble members sat unloadable from August to September while
+# every test passed (#404, #458 §1b). The load test is the guard for that, and it
+# `importorskip("views_hydranet")`, so in run_tests.yml — which installs only
+# pipeline-core — it has always SKIPPED. This job is where it runs.
+#
+# Why a separate job, like runtime_smoke.yml:
+#   * run_tests.yml's install is pinned on purpose (its header says why). Adding a
+#     package there is a change to what "the suite is green" means for every PR.
+#   * The dependency set here is tiny and different, and a red here means one thing:
+#     a roster config does not load.
+#
+# What it installs, and why: views-hydranet --no-deps, plus torch from the CPU-only
+# index. Importing config_initializer is torch-free, but CONSTRUCTING a config is not —
+# get_config -> validate_loss_reg -> views_hydranet/utils/utils.py:7 imports torch
+# (found 2026-09-15 by running this job locally: all 8 configs failed with
+# ModuleNotFoundError before torch was added). The CPU wheel is what a validator
+# needs; the CUDA build views-hydranet's metadata would resolve to is several times
+# larger and buys nothing here. pipeline-core and views-frames are not needed on this
+# path and are not installed.
+#
+# Why a RELEASED pin and not a git ref: runtime_smoke.yml was pinned to a pre-fix
+# commit for five weeks and stayed green while every baseline model was broken (C-106,
+# #460). A released version tracks what the models actually install. Keep the ==pin
+# below in step with the 8 models' `views-hydranet~=` floor when either moves: 0.1.0 at
+# #462 (2026-09-15), 0.1.1 at #484 (2026-09-19, require_cuda).
+on:
+  push:
+    branches: [main, development]
+  pull_request:
+    branches: [main, development]
+
+jobs:
+  roster-configs-load:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install the config layer (CPU-only torch — a validator imports it; see header)
+        run: |
+          pip install pytest "numpy<3" "pydantic>=2,<3"
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install --no-deps "views-hydranet==0.1.1"
+
+      - name: Roster configs load — every member constructs through HydraNetConfig
+        run: pytest tests/test_roster_configs_load.py -v

.github/workflows/run_tests.yml

@@ -9,14 +9,33 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
 
+      # PINNED, and the pin is the point. This was `pip install views_pipeline_core pytest`,
+      # unpinned, so CI silently tested against whatever PyPI served that day: no past green
+      # run recorded which version it had actually proved.
+      #
+      # 3.3.0 (published 2026-09-19). 3.2.0 was the first release a config_maturity.py source
+      # runs on (pipeline-core #495, #497; why PR #444 broke 14 models while this suite, then
+      # on 3.0.1, stayed green). 3.3.0 adds: the queryset loader raises with an install hint
+      # instead of returning None (their #514 -- tools/catalogs/update_readme.py isolates that
+      # call, #478); ADR-064 refuses a DataFrame prediction carrying an entity absent from the
+      # input's last month; wandb <1.0 and views-frames <3, so this venv resolves wandb 0.30
+      # and views-frames 2.0.0 -- the same resolution the ensembles get, since they pin
+      # neither. The ensembles declare >=3.0.0,<4.0.0, so 3.3.0 is inside what production
+      # installs.
+      #
+      # Bump this deliberately, together with the ensembles' requirements.txt floors, never
+      # on its own -- CI testing a version production does not install is the skew this pin
+      # removes. Named trigger for the NEXT bump: at 4.0 viewser becomes an optional extra
+      # (their ADR-063); anything here that reaches viewser through pipeline-core without
+      # installing the extra stops importing.
       - name: Install dependencies
-        run: pip install views_pipeline_core pytest
+        run: pip install "views_pipeline_core==3.3.0" pytest packaging
 
       - name: Run tests
         run: pytest

.github/workflows/runtime_smoke.yml

@@ -0,0 +1,49 @@
+name: Runtime Smoke
+
+# C-106 exit: the main `run_tests.yml` suite verifies declarations (config,
+# structure, contracts) but never executes a model. This job runs ONE real
+# model config through the real config -> catalog -> model path and asserts the
+# produced forecast honors the config (sample count, shape, no NaN/Inf,
+# determinism) — the runtime signal that config-green cannot give.
+#
+# It is deliberately DECOUPLED from the main suite's dependency situation:
+#   * It does NOT install views_pipeline_core, so it dodges the published-core
+#     skew (C-42/C-73) that keeps run_tests.yml red (C-80). The baseline model
+#     layer + catalog import zero pipeline-core (verified 2026-07-20).
+#   * views_baseline / views_frames are installed --no-deps (numpy/pandas only),
+#     pinned for reproducibility so a red smoke means a views-models regression,
+#     not sibling drift. Bump the pins deliberately.
+#
+# views-baseline now installs from PyPI at a released version rather than a git ref,
+# which is what the earlier note here asked for once it started publishing releases.
+# views-frames moves with it only because 1.0.2 requires >=1.10.2,<2 and the old
+# v1.8.1 pin no longer satisfies that.
+#
+# This also closes a real gap. The git pin was b53fc41 (2026-07-20), 35 commits
+# behind v1.0.2, and its catalog.py still read the `targets` key at 7 sites — the key
+# views-pipeline-core retired in 507ae11 on 2026-08-02. So this job asserted against
+# code no model could run: it went green for the five weeks in which every baseline
+# model was broken by that retirement (the breakage is views-models#445).
+on:
+  push:
+    branches: [main, development]
+  pull_request:
+    branches: [main, development]
+
+jobs:
+  runtime-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install runtime deps (no pipeline-core — dodges the published-core skew)
+        run: |
+          pip install pytest numpy pandas
+          pip install --no-deps "views-frames==1.11.0" "views-baseline==1.0.2"
+
+      - name: Runtime smoke — execute a model train+forecast, assert output honors config
+        run: pytest tests/test_runtime_smoke.py -v