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

STATUS — phase samever (step-back to older base when canonical == head version)

SSOT: /srv/cc-ci/cc-ci-plan/plan-phase-samever-older-base-fallback.md. State files: this + BACKLOG-samever.md, REVIEW-samever.md (Adversary), JOURNAL-samever.md. DECISIONS.md shared.

Phase

Started 2026-06-17. Gates: M1 (implemented + unit-tested), M2 (proven in real CI).

Current status

M1: PASS (REVIEW-samever.md @2026-06-17T04:27Z — cold-verified, teeth hold, no regression). M2: IN PROGRESS — real-CI demonstration on cc-ci. Plan: custom-html cold-on-latest twice (run A promotes canonical→latest 1.13.0+1.31.1; run B = nightly steady state → step-back to 1.11.0+1.29.0, base<latest); PR form (head==canonical → step-back); version-bump UNAFFECTED (canonical older→head); discourse #4 unaffected; spot-check.

M1 — WHAT is claimed

resolve_upgrade_base now reads the head's published version and steps back to a genuinely older published base when the last-green warm-canonical version equals the head version — never a same-version no-op, never a needless skip when an older base exists.

Resolution chain (override / EXPECTED_NA / upgrade∉stages short-circuits unchanged):

1. explicit UPGRADE_BASE_VERSION override → unchanged.
2. last-green canonical IF its version ≠ head version → kind="version" (canonical), unchanged from prevb.
3. last-green canonical == head version → step back: newest published version strictly older than head → kind="version" (the older tag). Reason starts "step-back: …".
4. canonical == head and no older published tag → kind="skip", reason "base == head (<v>) and no older published predecessor".
5. no canonical → main-tip ref / skip paths unchanged. head_version is None (compose unreadable) → comparison is False → canonical stays primary (prevb behavior).

M1 — WHERE (commit + paths)

• Implementation commit: b29bb3f (feat(samever): …), on main.
• runner/run_recipe_ci.py — resolve_upgrade_base(..., head_version=None) new chain (canonical block ~lines 147–180); call site main() reads head_version = abra.head_compose_version(recipe) (~line 1023) and passes it.
• runner/harness/abra.py — head_compose_version(recipe) (regex coop-cloud\.[^.\s]*\.version=([^\s"']+) over the head checkout's compose.yml; matches quoted + unquoted labels; does NOT match .chaos-version).
• runner/warm_reconcile.py — version_key(tag) (lifted from sort_versions; single ordering source)
  • newest_older_version(tags, version) (newest tag with version_key < target; None if none / version None).
• tests/unit/test_upgrade_base.py — 5 new tests (13 total).

M1 — HOW to verify (cold, from a clean clone)

1. Unit suite (the gate):

   nix shell nixpkgs#python311Packages.pytest -c pytest tests/unit/test_upgrade_base.py -v
   

   EXPECTED: 13 passed. New tests:

   • test_canonical_equals_head_steps_back_to_newest_older — canonical==head==10.8.0+26.6.3, tags [10.6.0+26.5.0, 10.8.0+26.6.3, 10.7.1+26.6.2, 10.7.0+26.6.0, not-a-version] → plan.version == "10.7.1+26.6.2" (strictly older; asserts version_key(plan.version) < version_key(head)), kind=="version", reason contains "step-back". main never consulted.
   • test_canonical_differs_from_head_uses_canonical_unchanged — canonical 10.7.1+26.6.2 ≠ head 10.8.0+26.6.3 → version==10.7.1+26.6.2, reason "last-green"; recipe_tags NOT consulted.
   • test_canonical_equals_head_no_older_published_skips — canonical==head==1.0.0+3.5.3, tags [1.0.0+3.5.3] only → kind=="skip", reason contains "no older published predecessor".
   • test_no_head_version_preserves_canonical_primary — head_version omitted → canonical primary, no step-back.
   • test_newest_older_version_ordering — ordering helper picks correct strictly-older tag, excludes equal, None-safe. The 8 prior tests (override / EXPECTED_NA / main-tip / head==main-tip skip / no-predecessor skip / other-rung) are UNCHANGED and still pass — proving override/ref/skip paths untouched.

2. Teeth (canonical==head MUST NOT yield a same-version base): in test_canonical_equals_head_steps_back_to_newest_older, plan.version != head_version and the version_key(plan.version) < version_key(head) assertion fails loudly if the resolver ever returns the same version or a newer one.

3. Compose-label parse (the head-version reader): the regex extracts 10.8.0+26.6.3 from a quoted label and 3.5.3+1.24.2-rootless from an unquoted one, and returns no match for a .chaos-version label (verified — see JOURNAL). Real labels confirmed on cc-ci: keycloak 10.8.0+26.6.3, gitea 3.5.3+1.24.2-rootless, discourse 1.0.0+3.5.3.

4. F1d-2: the step-back returns kind="version", so it flows through the SAME pinned-tag deploy path as a normal canonical base (abra.recipe_checkout pins the tag on disk) — no new deploy code.

Note (pre-existing, NOT introduced by this gate): tests/unit/test_meta.py::test_generated_doc_table_in_sync and tests/unit/test_warm_reconcile.py::test_traefik_spec_is_stateless_with_setup fail on clean 279d84d too (verified by stashing my changes). Out of scope for samever.

Blocked

(none)