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

STATUS — phase settings

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.

DONE

All Definition-of-Done items Adversary-verified with fresh PASSes (no standing VETO), 2026-06-17:

• M1 PASS — REVIEW-settings.md @17:00Z (claim fed2678 / code cd19c1b): settings loader (stdlib tomllib, defaults, graceful absent/malformed, warn-and-ignore unknown, TypeError on wrong type) + SKIP_CANONICALS_FOR_UPGRADE wired into resolve_upgrade_base + release-tag-first no-canonical fallback reusing samever's helper; 32 + 315 unit pass; scope narrow; stdlib-only; no secrets.
• M2 PASS — REVIEW-settings.md @17:35Z (claim a9ff941 / deployed /etc/cc-ci@99d6bbc, byte-identical runner to cd19c1b): live on cc-ci — keycloak (no canonical) → release tag 10.7.1+26.6.2 not main-tip; gitea (canonical) unchanged last-green under default false; scratch true bypasses gitea's canonical to the release-tag path; restored to false; harness file-pickup proven via the real /etc/cc-ci/settings.toml.

Server in steady state: /etc/cc-ci/settings.toml ABSENT (default false), checkout clean @99d6bbc.

Gate: M1 PASS (Adversary @2026-06-17T17:00Z, REVIEW-settings.md) · M2 CLAIMED (see below)

M1 commit: cd19c1b (feat: settings loader + flag + fallback + unit tests) — Adversary cold-PASS, no VETO. M2 deployed: 99d6bbc on /etc/cc-ci. Tree clean, pushed to origin/main.

WHAT is claimed (M1 — implemented + unit-tested)

1. Settings loader runner/harness/settings.py — stdlib tomllib, one [upgrade] table with skip_canonicals_for_upgrade (bool, default false). _SCHEMA (table→{key:(type,default)}) is the single source of defaults + validation. Graceful on absent/unreadable/malformed file (WARN + all-defaults — never crashes); unknown table/key → warn-and-ignore; present known key of wrong type → TypeError. Path = $CCCI_SETTINGS else /etc/cc-ci/settings.toml. Tracked settings.toml.example documents the key (no secrets).
2. SKIP_CANONICALS_FOR_UPGRADE wired into resolve_upgrade_base (runner/run_recipe_ci.py): when true, the canonical (version) branch is skipped entirely → no-canonical fallback. Guard: if rec and rec.get("version") and not skip_canonicals:. Scope = upgrade base only (promotion / --quick untouched).
3. Release-tag-first no-canonical fallback _no_canonical_base (runner/run_recipe_ci.py), always-on: (1) newest release tag with version strictly older than head_version — reuses warm_reconcile.newest_older_version(warm_reconcile.recipe_tags(recipe), head_version); (2) raw main-tip — only if no prior release tag; (3) skip. (Guarded: tag lookup skipped when head_version is falsy → main-tip, preserving prevb behavior for that caller.)

HOW to verify (re-runnable from a fresh clone)

All commands from the repo root of a clone at cd19c1b (or later). Unit tests need pytest from nixpkgs:

# 1. Full upgrade-base matrix + settings loader tests
nix shell nixpkgs#python311Packages.pytest -c pytest tests/unit/test_upgrade_base.py tests/unit/test_settings.py -v
# 2. Whole unit suite (regression — nothing else broke)
nix shell nixpkgs#python311Packages.pytest -c pytest tests/unit/ -q
# 3. Lint (my files) — ruff check + format
nix shell nixpkgs#ruff -c ruff check runner/ tests/unit/test_settings.py tests/unit/test_upgrade_base.py
nix shell nixpkgs#ruff -c ruff format --check runner/harness/settings.py runner/run_recipe_ci.py tests/unit/test_settings.py tests/unit/test_upgrade_base.py settings.toml.example
# 4. Default is false WITHOUT any file (this server unchanged):
nix shell nixpkgs#python311Packages.pytest -c python3 -c "import sys; sys.path.insert(0,'runner'); from harness import settings; print(settings.load('/no/such/file.toml').skip_canonicals_for_upgrade)"
#   -> False

EXPECTED outcome

• (1) → 32 passed. Key cases proving the matrix:
  • test_flag_false_canonical_present_unchanged — flag false + canonical (≠head) → canonical, last-green reason, tags/main NOT consulted (byte-for-byte prevb).
  • test_no_canonical_prefers_release_tag_over_main_tip — flag false + no canonical → version=10.7.1+26.6.2 (newest tag < head 10.8.0+26.6.3), main NOT consulted; reason contains no-canonical fallback/release tag.
  • test_no_canonical_no_older_tag_falls_back_to_main_tip — no older tag → ref=main-tip.
  • test_no_canonical_no_tag_no_main_skips — neither → skip.
  • test_flag_true_bypasses_canonical_into_release_tag_fallback — flag true + canonical present → resolves to release tag 10.7.1+26.6.2, NOT the canonical 10.6.0+26.5.0.
  • test_flag_true_canonical_present_no_older_tag_uses_main — flag true routes through the FULL chain → main-tip.
  • test_canonical_equals_head_steps_back_to_newest_older / ..._no_older_published_skips — samever step-back unchanged (older→version; none→skip, NOT main-tip).
  • loader: test_absent_file_yields_defaults, test_malformed_toml_degrades_to_defaults, test_wrong_type_errors_clearly, test_int_not_accepted_for_bool, test_unknown_key/table_warns_and_ignored, test_env_var_path_override, test_flag_true_read/_false_read.
• (2) → 315 passed (full suite, no regression).
• (3) → All checks passed! and ... already formatted.
• (4) → False (default with no file → this server behaves as today).

WHERE

• runner/harness/settings.py (loader, DEFAULT_PATH = /etc/cc-ci/settings.toml, Settings, load(), get()).
• settings.toml.example (repo root, tracked).
• runner/run_recipe_ci.py: resolve_upgrade_base (flag guard) + new _no_canonical_base helper; import settings as settings_mod.
• tests/unit/test_settings.py (loader, 13 tests), tests/unit/test_upgrade_base.py (matrix, +8 new tests).

NOTE (pre-existing, out of scope — see DECISIONS)

scripts/lint.sh (pinned ruff) flags dashboard/dashboard.py + tests/unit/test_dashboard.py as needing reformat — confirmed present at HEAD f68f1c5, NOT in this phase's diff. Not fixed here (narrow scope). My 5 phase files are ruff-clean + format-clean.

---

Gate: M2 CLAIMED, awaiting Adversary @2026-06-17T17:25Z

M1 is Adversary-PASS (REVIEW-settings.md verdict @17:00Z, fed2678/cd19c1b). M2 = verified live on cc-ci.

Deployed: /etc/cc-ci at 99d6bbc (pushed to origin/main; the deployed checkout the nightly sweep runs from, and the absolute path the Drone recipe-CI runner reads). No nixos-rebuild needed — the change is pure runner Python loaded at runtime from the checkout. Live settings file /etc/cc-ci/settings.toml is ABSENT → default false (server steady state restored after the test).

WHAT is claimed (M2)

• The live server harness reads the settings file from the host path /etc/cc-ci/settings.toml (absent → default false), confirmed by the flag value flipping with the file's presence.
• (a) A recipe without a canonical (keycloak, no canonical.json) resolves its upgrade base to the newest release tag < head (10.7.1+26.6.2), NOT the raw main-tip.
• (b) With SKIP_CANONICALS_FOR_UPGRADE = true (scratch file), a canonical-bearing recipe (gitea, canonical 3.5.3+1.24.2-rootless) resolves to the release-tag base (canonical BYPASSED) — proven by the reason changing from last-green (warm canonical, status=idle) to no-canonical fallback: newest release tag older than head 3.6.0+1.24.2-rootless. Scratch file then removed → restored to false (reason back to last-green (warm canonical)).
• Default false ⇒ this server's canonical-bearing path is unchanged (gitea false → last-green base).

HOW to verify (cold, on the server, from /etc/cc-ci or your own clone)

The probe runs the EXACT deployed resolve_upgrade_base against live settings + live canonical registry (/var/lib/ci-warm/<r>/canonical.json) + live recipe tags (~/.abra/recipes/<r>). Faithful, no deploy/teardown.

ssh cc-ci
cd /etc/cc-ci && git rev-parse --short HEAD          # 99d6bbc (or later)
ls /etc/cc-ci/settings.toml                          # ABSENT -> default false

# CASE 1 — flag false (default, no file): (a) keycloak, plus gitea unchanged
HOME=/root cc-ci-run scripts/show-upgrade-base.py keycloak gitea

# CASE 2 — flag true (scratch), then RESTORE
printf '[upgrade]\nskip_canonicals_for_upgrade = true\n' > /etc/cc-ci/settings.toml
HOME=/root cc-ci-run scripts/show-upgrade-base.py gitea keycloak
rm -f /etc/cc-ci/settings.toml                       # restore default false
HOME=/root cc-ci-run scripts/show-upgrade-base.py gitea

EXPECTED (verbatim BasePlan lines observed @17:20–17:25Z)

• CASE 1 (false):
  • keycloak → BasePlan(kind='version', version='10.7.1+26.6.2', ref='', reason='no-canonical fallback: newest release tag older than head 10.8.0+26.6.3') (canonical=None; newest_release_tag<head=10.7.1+26.6.2; NOT main-tip 12ac6db8…)
  • gitea → BasePlan(kind='version', version='3.5.3+1.24.2-rootless', ref='', reason='last-green (warm canonical, status=idle)') (canonical=3.5.3 present → used)
• CASE 2 (true):
  • gitea → BasePlan(kind='version', version='3.5.3+1.24.2-rootless', ref='', reason='no-canonical fallback: newest release tag older than head 3.6.0+1.24.2-rootless') (canonical 3.5.3 present but BYPASSED — reason is the release-tag path)
  • keycloak → same as CASE 1 (no canonical either way)
• RESTORE (file removed → false):
  • gitea → reason back to last-green (warm canonical, status=idle); flag reads False.

WHERE

• Deployed code: /etc/cc-ci @ 99d6bbc (origin/main). Probe: scripts/show-upgrade-base.py.
• Live registry: /var/lib/ci-warm/{keycloak (none),gitea}/canonical.json. Recipe tags: ~/.abra/recipes/{keycloak,gitea}. Settings path: /etc/cc-ci/settings.toml (absent now).

Server left in steady state: /etc/cc-ci/settings.toml ABSENT (default false), checkout clean @99d6bbc.

→ On a fresh Adversary PASS of M2 (with M1 PASS standing), I will write ## DONE.