docs: a fresh bootstrap writes both pairs equal, not a missing converged_*

The previous commit's test and README described a freshly bootstrapped
machine as lacking converged_* and rendering 'not recorded'. That pins the
wrong contract: #61 states plainly that "on a fresh machine both pairs are
written with equal values", and rule 2 only suppresses converged_* churn on
a later same-version re-run.

So two identical lines mean bootstrapped-and-never-re-converged, and a
manifest missing the pair is partial or hand-edited rather than fresh --
no writer produces it. The graceful degradation stays for that case, still
without backfilling from birth, which would invent a convergence that never
happened.

The reader itself was already correct; this fixes the fixture and the prose
that claimed otherwise.

Found in review of #74.

Refs #64
This commit is contained in:
dan-claude-bot 2026-07-20 00:34:26 +00:00
parent 91a8905a71
commit d3577b9954
3 changed files with 31 additions and 11 deletions

View file

@ -33,7 +33,10 @@ on the way to cutting its first release, and this file starts there.
nothing else depends on it. The reader is keyed to #61's documented schema
(`schema`, `bootstrapped_by`/`_at`, `converged_by`/`_at`) and fixtures pin
that exact spelling, so the integration cannot land silently broken; birth
and latest stay separate rather than one being inferred from the other. Named `platform` and not `status` on purpose:
and latest stay separate rather than one being inferred from the other. A
fresh machine writes both pairs equal, so two identical lines read as
"never re-converged"; a manifest missing the pair is partial rather than
fresh, and says so instead of backfilling from birth. Named `platform` and not `status` on purpose:
`users status` and `runner status` cross-check recorded against live state
and print `DRIFT`, and a command that records nothing cannot drift — which
also leaves `rig status` free for the machine-wide roll-up. Known

View file

@ -774,10 +774,19 @@ bootstrapped` on every machine; nothing else in the command depends on it.
is birth (`bootstrapped_by`/`bootstrapped_at`, first-write-wins, pinned
forever) and `CONVERGED` is latest (`converged_by`/`converged_at`, updated only
when the converging version actually differs). That distinction is what answers
"is this machine still converged by a rig that predates the fix?" — so
`CONVERGED` reads `not recorded` rather than being backfilled from birth on a
box that has only ever been bootstrapped once. A manifest whose `schema=` this
rig does not know is named as such instead of being half-read in silence.
"is this machine still converged by a rig that predates the fix?".
A **fresh machine writes both pairs with equal values**, so two identical lines
mean "bootstrapped and never re-converged since" — not a missing record. A
later re-converge by a different rig moves `CONVERGED` and leaves `BOOTSTRAP`
untouched, which is the whole point of keeping them apart.
`CONVERGED not recorded` therefore does **not** describe a freshly
bootstrapped box; no writer produces a manifest without the pair. It means the
file is partial or hand-edited, and the value is deliberately not backfilled
from `BOOTSTRAP` — inferring a convergence that never happened would be worse
than saying so. Likewise a manifest whose `schema=` this rig does not know is
named as such instead of being half-read in silence.
**Known limitation — `CPU` and `MEMORY` inside a container-style guest are
unverified.** `CPU` and `MEMORY` are read straight from `/proc/cpuinfo` and

View file

@ -1023,12 +1023,20 @@ check "platform: reads #61's converged_by/at" 0 "CONVERGED 0.6.0, 2026-08-02T09
env RIG_MANIFEST="$PLATWORK/manifest" RIG_ROLE_MARKER="$PLATWORK/absent" "$ROOT/bin/rig" platform
check "platform: reads #61's bootstrapped_by/at" 0 "BOOTSTRAP 0.4.0, 2026-07-19T14:24:51Z" \
env RIG_MANIFEST="$PLATWORK/manifest" RIG_ROLE_MARKER="$PLATWORK/absent" "$ROOT/bin/rig" platform
# Birth and latest stay SEPARATE: #61 rule 2 writes converged_* only when the
# version actually differs, so its absence on a freshly bootstrapped box is a
# legitimate state — it must not be silently backfilled from bootstrapped_*.
printf 'schema=1\nbootstrapped_by=0.4.0\nbootstrapped_at=2026-07-19T14:24:51Z\n' > "$PLATWORK/manifest-birth"
check "platform: unconverged box says so, never infers from birth" 0 "CONVERGED not recorded" \
env RIG_MANIFEST="$PLATWORK/manifest-birth" RIG_ROLE_MARKER="$PLATWORK/absent" "$ROOT/bin/rig" platform
# A FRESH bootstrap carries both pairs with EQUAL values — #61 is explicit
# ("On a fresh machine both pairs are written with equal values"); rule 2 only
# suppresses converged_* churn on a later same-version re-run. So equal dates
# are the never-re-converged case and must render as themselves, not be
# special-cased into looking unset.
printf 'schema=1\nbootstrapped_by=0.4.0\nbootstrapped_at=2026-07-19T14:24:51Z\nconverged_by=0.4.0\nconverged_at=2026-07-19T14:24:51Z\n' > "$PLATWORK/manifest-fresh"
check "platform: a fresh bootstrap shows both pairs equal (#61)" 0 "CONVERGED 0.4.0, 2026-07-19T14:24:51Z" \
env RIG_MANIFEST="$PLATWORK/manifest-fresh" RIG_ROLE_MARKER="$PLATWORK/absent" "$ROOT/bin/rig" platform
# A manifest missing converged_* is therefore NOT a fresh box — no writer
# produces that — so it is partial or hand-edited. Degrade loudly rather than
# backfilling from birth, which would invent a convergence that never happened.
printf 'schema=1\nbootstrapped_by=0.4.0\nbootstrapped_at=2026-07-19T14:24:51Z\n' > "$PLATWORK/manifest-partial"
check "platform: a partial manifest says so, never infers from birth" 0 "CONVERGED not recorded" \
env RIG_MANIFEST="$PLATWORK/manifest-partial" RIG_ROLE_MARKER="$PLATWORK/absent" "$ROOT/bin/rig" platform
# A newer schema renders what it recognises and says the rest is unreadable,
# rather than pretending a partial read is the whole truth.
printf 'schema=2\nbootstrapped_by=9.9.9\nbootstrapped_at=2027-01-01T00:00:00Z\n' > "$PLATWORK/manifest-v2"