fix(bootstrap): compare release versions semantically against the installed one #36

Merged

ochenstarik-ui merged 1 commit from fix/version-comparison into main

2026-08-10 18:12:39 +00:00

ochenstarik-ui commented

2026-08-10 18:05:58 +00:00

(Migrated from github.com)

Problem

The update guard compared the archive version with PROGRAM_VERSION using shell string ordering. Both halves were wrong.

PROGRAM_VERSION is a constant describing the bootstrap source tree (0.2.0-dev), never the deployed component. The cross-role compatibility check compared it with a manifest field such as v0.1.0-alpha.9; those can never be equal, so update-control on a host that also runs the agent always failed. The downgrade guard compared the same mismatched pair and passed only by accident, because v sorts above 0 in ASCII.

String ordering is also wrong for the version scheme in use:

0.1.0-alpha.10 < 0.1.0-alpha.9   ->  true

so the next release after the ninth would have been rejected as a downgrade.

Change

record the installed version per role at install and update time, and compare against that instead of PROGRAM_VERSION;
order versions with sort -V after stripping the leading v;
treat an unknown peer version as a warning rather than a failure, because installations predating version recording have nothing to compare against;
guard all of it in the bootstrap contract test: six ordering cases plus checks that the lexicographic comparison is not restored and that both install paths record a version.

Verification

bash -n and BOOTSTRAP_CONTRACT=PASS locally.

Each defect was deliberately reintroduced to confirm the guard catches it:

Reintroduced defect	Result
lexicographic comparison against `PROGRAM_VERSION`	caught
`sort` without `-V`	caught
missing `record_installed_version agent`	caught

Ordering cases checked: alpha.9 < alpha.10, alpha.10 !< alpha.9, equal versions not less, v-prefix insensitivity, alpha.9 < 0.2.0, 0.2.0 !< alpha.9.

🤖 Generated with Claude Code

## Problem The update guard compared the archive version with `PROGRAM_VERSION` using shell string ordering. Both halves were wrong. `PROGRAM_VERSION` is a constant describing the bootstrap source tree (`0.2.0-dev`), never the deployed component. The cross-role compatibility check compared it with a manifest field such as `v0.1.0-alpha.9`; those can never be equal, so `update-control` on a host that also runs the agent always failed. The downgrade guard compared the same mismatched pair and passed only by accident, because `v` sorts above `0` in ASCII. String ordering is also wrong for the version scheme in use: ``` 0.1.0-alpha.10 < 0.1.0-alpha.9 -> true ``` so the next release after the ninth would have been rejected as a downgrade. ## Change - record the installed version per role at install and update time, and compare against that instead of `PROGRAM_VERSION`; - order versions with `sort -V` after stripping the leading `v`; - treat an unknown peer version as a warning rather than a failure, because installations predating version recording have nothing to compare against; - guard all of it in the bootstrap contract test: six ordering cases plus checks that the lexicographic comparison is not restored and that both install paths record a version. ## Verification `bash -n` and `BOOTSTRAP_CONTRACT=PASS` locally. Each defect was deliberately reintroduced to confirm the guard catches it: | Reintroduced defect | Result | |---|---| | lexicographic comparison against `PROGRAM_VERSION` | caught | | `sort` without `-V` | caught | | missing `record_installed_version agent` | caught | Ordering cases checked: `alpha.9 < alpha.10`, `alpha.10 !< alpha.9`, equal versions not less, `v`-prefix insensitivity, `alpha.9 < 0.2.0`, `0.2.0 !< alpha.9`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)