cc-ci/machine-docs/JOURNAL-settings.md

JOURNAL — phase settings (WHY / reasoning; Adversary does not read before verdict)

2026-06-17 — bootstrap + M1 design

Phase: server-level settings.toml + SKIP_CANONICALS_FOR_UPGRADE + release-tag-first no-canonical fallback. Plan: /srv/cc-ci/cc-ci-plan/plan-phase-settings-ci-server-config.md.

Why a new harness/settings.py (not extending an env-var module)

Checked for an existing cc-ci config mechanism first (plan §2.A "extend rather than spawn a parallel one"). The server config today is scattered ad-hoc env reads (os.environ.get for MAX_TESTS, CCCI_RUNS_DIR, CCCI_REPO, STAGES, CCCI_QUICK, …) — there is no central config module/class to extend (grep for tomllib|settings\.toml|class Settings → none). So a small dedicated loader IS the minimal, extensible home rather than threading another env var. Stdlib tomllib (py3.12 on the server, confirmed). One [upgrade] table, one key now; _SCHEMA is the single source of defaults+validation so adding a key/table later is a one-line change.

Settings file path: /etc/cc-ci/settings.toml (override $CCCI_SETTINGS)

The harness runs from /etc/cc-ci in BOTH execution contexts (nightly sweep sets CCCI_REPO=/etc/cc-ci and cds there; the Drone recipe-CI runner runs from its checkout but an absolute host path is read identically by both). /etc/cc-ci is a git checkout kept current by git pull + nixos-rebuild on deploy — an untracked settings.toml there survives pulls (git pull never deletes untracked files) and sits next to the tracked settings.toml.example. Chose this over /srv/cc-ci/settings.toml (the plan's suggestion) because /srv/cc-ci is the orchestrator path, ambiguous on the server; /etc/cc-ci is unambiguous and discoverable. The loader is graceful if the file/dir is absent → defaults.

Why the canonical-present path (incl. samever step-back) is byte-for-byte unchanged

Guardrail §4: default false must be a no-op for current behavior. Structure: if rec and rec.version and not flag: → the entire existing prevb/samever block runs verbatim (canonical ≠ head → canonical; canonical == head → step-back older tag, else skip). Only when there is no canonical in play (rec falsy, OR flag true) do we enter the new _no_canonical_base. So with flag false + a canonical, nothing changes; the step-back's "no older predecessor → skip" is preserved (NOT routed to main-tip), which is correct — routing it to main-tip could reintroduce the same-version no-op samever exists to prevent. The plan §2.C "unified chain ... (==head)" is satisfied by the step-back already taking the same release-tag helper as step 1; I deliberately did NOT add a main-tip tail to the step-back skip, to keep samever's guarantee intact. This is the one place where a literal reading of §2.C ("==head → ... → main-tip → skip") and the §4 no-op guardrail + samever's intent point slightly differently; I chose the conservative path that preserves both samever and the no-op guardrail. If the Adversary reads §2.C literally and wants the step-back-no-older case to fall to main-tip, that is a one-line change — but I believe it would be a regression (vacuous upgrade), so it's recorded here.

Why _no_canonical_base guards on head_version before calling recipe_tags

newest_older_version(tags, None) returns None, but evaluating recipe_tags(recipe) eagerly would shell out to git -C <per-run recipe dir> tag even when head_version is None (e.g. callers/tests that don't pass it). Guarding if head_version else None avoids a needless/erroring git call and preserves the prevb behavior for the no-head_version caller shape (→ main-tip).

Why wrong-type raises but malformed/absent doesn't

Plan M1: "malformed file handled" (graceful) AND "wrong type errors clearly". Reconciled: absent / unreadable / TOML-syntax-error → WARN + all-defaults (a red file degrades to today's behavior, can't crash CI). A syntactically-valid file with a known key of the wrong type → TypeError (a typo'd value should be loud, not silently mis-parsed). bool-is-int-subclass handled: 1/0 for a bool key is rejected, not coerced.

Pre-existing, OUT OF SCOPE: dashboard lint drift on main

scripts/lint.sh reports dashboard/dashboard.py + tests/unit/test_dashboard.py would be reformatted by the pinned ruff — confirmed present at HEAD f68f1c5 (git show HEAD:... through pinned ruff), NOT in my diff. Not touched by this phase (narrow scope). Recorded in DECISIONS as an observation. My 5 phase files are format-clean + ruff check clean.

Verification (commands + output)

• nix shell nixpkgs#python311Packages.pytest -c pytest tests/unit/test_upgrade_base.py tests/unit/test_settings.py -q → 32 passed.
• full unit suite pytest tests/unit/ -q → 315 passed.
• ruff check runner/ tests/unit/ bridge/ dashboard/ → All checks passed.
• ruff format --check (pinned) on my 5 files → all formatted.

2026-06-17 — M2 prep (read-only; not advancing past M1 gate)

Server canonical registry (/var/lib/ci-warm/<recipe>/canonical.json, status all idle):

• WITH canonical (16): cryptpad, custom-html, custom-html-tiny, drone, ghost, gitea, hedgedoc, immich, lasuite-docs, lasuite-drive, lasuite-meet, mailu, matrix-synapse, n8n, plausible, uptime-kuma.
• warm dir but NO canonical.json (candidates for M2 evidence (a) "recipe without a canonical → newest release tag < head"): keycloak, alerts, traefik.

M2 plan (after M1 PASS):

• (a) pick a no-canonical recipe WITH published release tags (keycloak has many) → show resolve_upgrade_base returns a release-tag base, not raw main-tip. Likely via a harness dry-run / targeted invocation on the server reading the live settings (absent file → default false).
• (b) drop a scratch /etc/cc-ci/settings.toml with skip_canonicals_for_upgrade = true, show a canonical-bearing recipe (e.g. gitea/ghost) now resolves to the release-tag base (canonical bypassed), then remove the scratch file → restore default false.
• Deploy: ensure /etc/cc-ci is at the phase commit (git pull); settings.py is pure-python loaded at runtime from the checkout, so no nixos-rebuild needed for the harness to pick it up (the cc-ci-run wrapper execs python on the checkout's runner/). Confirm on server.

2026-06-17 — M1 PASS + M2 verified live, claimed

M1 Adversary cold-PASS (REVIEW-settings.md @17:00Z, no VETO). Advanced to M2. Deployed phase commit to /etc/cc-ci via git pull --ff-only (HEAD 99d6bbc); no nixos-rebuild needed (pure runner python read at runtime; the nightly sweep runs from /etc/cc-ci and Drone reads the same absolute settings path). Added scripts/show-upgrade-base.py — a faithful, lightweight live probe that calls the DEPLOYED resolve_upgrade_base against live settings + canonical registry + recipe tags, avoiding a heavy per-recipe deploy/test/teardown while still proving the real resolution decision on the server. Chose this over full cc-ci-run runner/run_recipe_ci.py runs (samever's approach) because my change is purely in base RESOLUTION, not tier execution — the BasePlan is the whole claim.

Evidence-(b) recipe choice: scanned all 16 canonical recipes; only gitea has canonical≠head (3.5.3 vs 3.6.0), making it the cleanest bypass demo — flag false reads the canonical ("last-green (warm canonical, status=idle)"), flag true bypasses to the release-tag path ("no-canonical fallback: newest release tag older than head 3.6.0..."). The resolved version is 3.5.3 both ways (the canonical happens to equal the newest predecessor tag), so the REASON string is the proof of bypass — honest and matches the plan wording "ALSO resolve to that release-tag base (canonical bypassed)". All other recipes are in steady state (canon==head) where step-back and the fallback share the same helper and so coincide. Server restored to steady state (settings.toml absent → false).