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

REVIEW — phase settings (Adversary)

SSOT: /srv/cc-ci/cc-ci-plan/plan-phase-settings-ci-server-config.md Gates: M1 (loader + flag + release-tag-first fallback, unit-tested) · M2 (verified live on server)

Status: awaiting Builder bootstrap. No STATUS-settings.md / claim yet as of 2026-06-17T16:45Z. dash phase is DONE (M1+M2 PASS, commit 7507cf4) — this is the next phase.

Baseline captured (pre-change, for the "false = byte-for-byte unchanged" guardrail)

Cold-read of the code I'll be verifying against (no anchoring — code + plan only):

• resolve_upgrade_base is in runner/run_recipe_ci.py:112. Current no-canonical chain: canonical(version, w/ samever step-back) → main-tip (recipe_branch_commit "main") → skip. The plan (§2.C) inserts newest release tag < head BEFORE main-tip on every no-canonical path.
• The samever helper to reuse: warm_reconcile.newest_older_version(tags, version) (runner/warm_reconcile.py:161) — newest version-tag strictly older than version, keyed on version_key. The fallback MUST reuse this (no divergent version ordering) per §2.C / M1.
• recipe_tags(recipe) = git -C <recipe_dir> tag (warm_reconcile.py:267) — tag source.
• NO existing TOML config module today: CI-server config is scattered os.environ.get(...) (CCCI_*, ABRA_DIR, MAX_TESTS, etc.). No settings.toml tracked. So a NEW minimal loader is justified (verify: minimal, extensible, stdlib tomllib only, defaults baked in, graceful on absent/malformed file/unknown key).

Verification checklist I will run when M1 is CLAIMED

• Default is false → this server's upgrade-base resolution byte-for-byte unchanged.
• flag false + canonical present → canonical (unchanged).
• flag false + NO canonical → newest release tag < head (NOT main-tip).
• no canonical AND no older release tag → main-tip.
• none → skip.
• flag true → canonical lookup BYPASSED → same release-tag-first fallback.
• absent file / absent key → default false; malformed file → no crash, clear handling.
• fallback REUSES samever's helper (no parallel version-ordering impl).
• scope narrow: promotion + --quick warm-reattach UNTOUCHED by the flag.
• loader cannot crash the harness on a bad/absent file.

Verdicts

M1: PASS @2026-06-17T17:00Z (claim fed2678 / code cd19c1b) — cold-verified

Verified from my own clone, fresh shell, against plan §2/§3/§5 + the code — not the Builder's narrative. Read JOURNAL only AFTER writing this verdict (contextualization only).

Tests (re-run cold):

• test_upgrade_base.py + test_settings.py → 32 passed.
• Full unit suite → 315 passed (no regression).
• ruff check → All checks passed!; ruff format → 4 files already formatted.

Independent probes (I patched the I/O boundaries myself — did NOT rely on Builder's fixtures):

• Loader (real TOML files written to /tmp): absent/empty/absent-key → False; true→True, false→False; malformed TOML → WARN + False (no crash); string value → TypeError (clear msg); int 1 for bool → TypeError (no silent truthy coercion — good); unknown key + unknown table → warn-and-ignore, valid key still honored; [upgrade] as scalar → warn + defaults. $CCCI_SETTINGS path override honored. Real get() with no /etc/cc-ci/settings.toml (absent on host) → False.
• Resolver matrix (my own monkeypatch of canonical/recipe_tags/main/flag):
  • false + canonical(≠head) → canonical unchanged; tags & main provably NOT consulted (raised if so).
  • false + no canonical → newest release tag < head (10.7.1+26.6.2), main NOT consulted.
  • false + no canonical + only-head tag → main-tip. false + nothing → skip.
  • true + canonical present → BYPASS → release tag 10.7.1, NOT canonical 10.5.0.
  • true + canonical + no older tag → routes full chain → main-tip.

Guardrails checked:

• Default false / no-op for the default path: canonical-present resolution (this server's steady state) is byte-for-byte unchanged — proven by the probe that asserts tags/main are never consulted. NOTE: the no-canonical fallback IS intentionally changed even under false (release-tag-first), per plan §2.C "always-on … improves this server too" and M1's mandated test …prefers_release_tag_over_main_tip. That is the spec, not a regression — it only fires for recipes with no canonical (un-promoted), giving a real release base instead of a WIP main-tip.
• Reuses samever helper: fallback calls warm_reconcile.newest_older_version(recipe_tags(r), head) — the SAME single-source ordering helper as the step-back. No divergent version ordering.
• Narrow scope: skip_canonicals is read ONLY at run_recipe_ci.py:154 in resolve_upgrade_base. promote_canonical / should_promote_canonical / --quick (951/965/1102) do not touch it.
• Stdlib only: loader imports os, sys, tomllib, dataclasses — no third-party.
• No secrets: settings.toml.example is config + docs only, default false, explicit "NO SECRETS".
• Cannot crash harness: any bad/absent file degrades to defaults (WARN); only a present wrong-TYPE value raises (loud, intended).

No defects. No VETO. M1 cold-PASS. → M2 (live server) may be claimed.

M2: PASS @2026-06-17T17:35Z (claim a9ff941 / deployed /etc/cc-ci @99d6bbc) — cold live-verified

Verified live on cc-ci from a fresh ssh, against plan §3-M2 / §5. I gathered the raw facts FIRST (predicted the outcomes), then ran the real deployed resolver myself, and controlled the scratch file so I own the restore.

Deployment integrity: deployed /etc/cc-ci HEAD = 99d6bbc (on origin/main); git diff cd19c1b 99d6bbc -- runner/ is EMPTY — the deployed runner logic is byte-identical to the code I cold-PASSed at M1. Only docs + scripts/show-upgrade-base.py were added. The probe is faithful: it calls the real run_recipe_ci.resolve_upgrade_base with live registry / live tags / live head version (read the script — no mock).

Raw facts I confirmed independently before running the probe:

• /etc/cc-ci/settings.toml ABSENT (steady state → default false).
• keycloak: NO /var/lib/ci-warm/keycloak/canonical.json; tags include 10.7.1+26.6.2 and head 10.8.0+26.6.3 → newest tag < head = 10.7.1+26.6.2.
• gitea: canonical 3.5.3+1.24.2-rootless (status idle); head 3.6.0+1.24.2-rootless; newest tag < head = 3.5.3.

Live probe (I ran it myself, all from the real /etc/cc-ci/settings.toml DEFAULT_PATH, NOT env):

• CASE 1 (file absent → false):
  • keycloak (no canonical) → version 10.7.1+26.6.2, reason no-canonical fallback: newest release tag older than head 10.8.0+26.6.3 — a real published predecessor, NOT main-tip. ✓ (a)
  • gitea (canonical present) → version 3.5.3+1.24.2-rootless, reason last-green (warm canonical, status=idle) — canonical USED, unchanged. ✓ (server default path byte-for-byte unchanged)
• CASE 2 (scratch file → true):
  • flag reads True from /etc/cc-ci/settings.toml → gitea's canonical 3.5.3 is BYPASSED: reason flips to no-canonical fallback: newest release tag older than head 3.6.0+1.24.2-rootless (resolves to release tag, not the canonical lookup). The reason change is the proof of bypass. ✓ (b)
  • keycloak → unchanged (no canonical either way).
• RESTORE (I removed the scratch file): gitea reason back to last-green (warm canonical, status=idle), flag False. Server left in steady state: /etc/cc-ci/settings.toml ABSENT, checkout clean @99d6bbc.

Harness file-pickup proven: the live flag value flipped False → True → False purely from the presence/absence of the real host file /etc/cc-ci/settings.toml — the M2 "harness picks up the file" requirement, demonstrated on the actual deployed path (not $CCCI_SETTINGS).

No defects. No VETO. M2 cold live-PASS. Both M1 + M2 have fresh Adversary PASSes — Builder cleared to write ## DONE.