codex-bot-andresmgsl/box
1
0
Fork 0
forked from heavy-duty/box
Code Pull requests Activity

feat: mark 'bootstrapped' after a rig hook box watched succeed

Browse source 
converged anything. This takes the checkpoint one step later: after the rig
bootstrap hook has run and box has WATCHED IT SUCCEED, the box is converged
and untouched. 'box restore <box> bootstrapped' keeps the tenant role and
undoes only what happened after it, which is the undo an operator reaches
for far more often and which otherwise costs a ~10-minute re-mint.

The policy is #128's, shared rather than copied: snapshot_pristine and the
new snapshot_bootstrapped are thin wrappers over one snapshot_mark, so the
never-fatal contract and the 'dir' skip exist in exactly one place. What
does not generalise is the prose — the two marks name different moments —
so each wrapper owns its own narration.

Deliberately conditional where 'pristine' is unconditional. 'pristine' marks
a MOMENT every fresh mint has; 'bootstrapped' marks an EVENT, and a blank
box has no such event, so it gets no mark rather than a byte-identical
duplicate of 'pristine' at twice the disk cost. A FAILED hook gets none
either: the failure message already sends the operator to 'box shell', which
is a run box does not watch, so box hands over 'box snapshot <box>
bootstrapped' instead of labelling a convergence it never saw.

The label is therefore documented as one-directional on every surface: its
presence means the hook converged untouched, its absence means nothing at
all. Same durability caveats restated everywhere it appears — it dies with
the box on 'box rm', and no filesystem rollback reaches off-box state
(heavy-duty/rig#62).

Closes #130

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
dan-claude-bot 2026-07-20 11:09:23 +00:00
parent 64127b34e6
commit 050c90966e
5 changed files with 356 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

27
CHANGELOG.md
View file

@ -112,6 +112,33 @@ which records not just what changed but what each drill run proved.
class), which under `pipefail` could have narrated the wrong inheritance
shape on a clone that does carry a `pristine`.
- **A mint that converges a tenant role marks a `bootstrapped` snapshot after
the hook succeeds** (#130, the half #104 deferred and #128 argued out) —
`pristine` throws the tenant role away; `bootstrapped` keeps it and throws
away only what you did afterwards, which is the undo an operator reaches for
far more often and which otherwise costs a ~10-minute re-mint. Same policy
as `pristine`, sharing one function with it (`snapshot_mark`) so the
never-fatal contract exists in exactly one place: default on,
`BOX_SNAPSHOT_BOOTSTRAPPED=0` opts out, a `dir` pool skips it loudly — with
two marks that disk objection is twice the size, so a CoW-less host is not
asked to pay for one full root copy per mint, let alone two — and a failed
snapshot warns without failing a good mint. **Deliberately conditional where
`pristine` is unconditional**: `pristine` marks a *moment* every fresh mint
has, `bootstrapped` marks an *event* — a rig hook box ran and watched
succeed — and a blank box has no such event, so it gets no mark rather than
a byte-identical duplicate of `pristine` at twice the cost. When the hook
**fails**, box takes no mark either and says so where the operator is
looking: the failure message now hands over `box snapshot <box>
bootstrapped` to take after the by-hand re-run, because box will not label a
convergence it did not watch. So the label is documented as one-directional
on every surface — its **presence** means the hook converged and nothing has
touched the box since; its **absence** means nothing at all (a blank
template, a `dir` pool, an opt-out, or a hand-converged box). Same durability
caveats as `pristine`, restated rather than referenced: it dies with the box
on `box rm` (`box export` is the durable path), and no filesystem rollback
reaches off-box state such as a tailnet device record or a runner
registration (heavy-duty/rig#62).
### Changed
- **`state:needs-human` no longer waits on the cron to become true** (#141)

38
README.md
View file

@ -374,6 +374,42 @@ multi-GB copy rather than a near-free copy-on-write mark, so the mint
installs by default precisely so snapshots are cheap. `BOX_SNAPSHOT_PRISTINE=0`
skips the mark on any host.
### `bootstrapped` — the same undo, one step later
A mint whose template names a bootstrap role marks a second snapshot,
`bootstrapped` ([#130](https://github.com/heavy-duty/box/issues/130)), once
`rig bootstrap` has run and box has **watched it succeed**. That is the box
converged and not yet touched — the state you actually wanted back most of
the time.
```sh
box restore work bootstrapped # keep the tenant role, undo what you did to it
box restore work pristine # throw the tenant role away too
```
Same rules as `pristine`: default on, never fatal, skipped loudly on a `dir`
pool (with two marks that disk cost is twice the size, so a CoW-less host is
not asked to pay it), and `BOX_SNAPSHOT_BOOTSTRAPPED=0` skips it anywhere.
The same two caveats apply, unchanged: it **dies with the box** on `box rm`
(`box export` is the durable path), and it **cannot reach off-box state** —
a tailnet device record, a runner registration (rig#62).
**Read the label in one direction only.** Its _presence_ means the mint-time
hook converged and nothing has touched the box since. Its _absence_ means
nothing at all, because box only marks a hook it watched:
- A **blank** box runs no hook, so there is no convergence to mark. It gets
none — `pristine` and `bootstrapped` would be the same disk state at twice
the cost, and a label claiming a convergence that never happened is worse
than no label.
- A box whose hook **failed** gets none either. box tells you to re-run the
role by hand through `box shell`, and a by-hand run happens in a shell box
does not watch — so box hands you `box snapshot <box> bootstrapped` to take
at the moment it is true, rather than inventing a fact.
- A `dir`-pool host and `BOX_SNAPSHOT_BOOTSTRAPPED=0` both skip it.
`box info <box>` is what actually tells you which labels a box has.
## Survive the host: `box export` / `box import`
Snapshots live _inside_ a box, and `box rm` deletes the box **and** its
@ -441,6 +477,8 @@ box restore <box> <snap> [--force]
# roll back to a snapshot — destructive, asks first
# 'pristine' is auto-marked at mint: back to
# pristine Debian + box's seed, before rig ran
# 'bootstrapped' too, if a rig hook converged:
# the role kept, everything since undone
box export <box> [<file>] [--instance-only]
# one portable file (snapshots incl.) — survives rm & host
box import <file> [--name <box>]

157
bin/box
View file

@ -311,6 +311,22 @@ none (copying a snapshot). On a 'dir'-backend host, where a snapshot is a
full copy rather than a CoW mark, the mint skips it and says so.
BOX_SNAPSHOT_PRISTINE=0 skips it anywhere.
A mint whose template names a bootstrap role marks a second snapshot,
'bootstrapped' (#130), once the rig hook has run and box has watched it
SUCCEED — the box converged and not yet touched. It is the cheaper undo:
'pristine' throws the tenant role away, 'bootstrapped' keeps it and throws
away only what you did afterwards. Same rules: never fatal, skipped on a
'dir' pool, and BOX_SNAPSHOT_BOOTSTRAPPED=0 skips it anywhere.
It is deliberately NOT unconditional the way 'pristine' is. A blank box
runs no hook, so there is no convergence to mark and it gets none — the
label marks an event, not a mint. And if the hook FAILS, box tells you to
re-run it by hand and takes no mark afterwards: a by-hand run happens in a
shell box does not watch, so box will not label a convergence it never saw.
It names 'box snapshot <box> bootstrapped' at that moment instead. So read
the label one way only: its PRESENCE means the hook converged untouched;
its ABSENCE means nothing at all.
box new --name scratch # blank, the default
box new --name work --template claude-box
box new --name lean --template claude-box --cpu 2 --memory 3GiB
@ -393,8 +409,14 @@ have.
box snapshot work authed
One label is taken for you: every fresh mint marks 'pristine' after
cloud-init and before rig's tenant role runs (#104) — see 'box help restore'.
Two labels are taken for you (see 'box help restore'): every fresh mint
marks 'pristine' after cloud-init and before rig's tenant role runs (#104),
and a mint with a bootstrap role marks 'bootstrapped' after box has watched
that role converge (#130). 'bootstrapped' is skipped where there was no hook
to watch — a blank box, or a hook box told you to re-run by hand — so its
absence proves nothing. Take it yourself in that case:
box snapshot work bootstrapped
Snapshots do not outlive their box: 'box rm' deletes a box and every
snapshot it has. They are an undo, not a backup — 'box export' is the
@ -424,6 +446,25 @@ a backup — it dies with the box on 'box rm'; 'box export' is what survives.
A box minted with --from has no 'pristine' of its own unless it inherited
one from its source, because a clone has no pristine moment to capture.
'bootstrapped' is the other label box takes for you (#130), and it is the
one you probably want more often: it is the box AFTER the tenant role
converged and before you touched it.
box restore work bootstrapped # keep the role, undo what you did to it
box restore work pristine # throw the role away too
The same two caveats apply to it exactly as written above — it dies with the
box on 'box rm' ('box export' is what survives), and it cannot undo anything
that left the box, a tailnet join or a runner registration among them
(heavy-duty/rig#62).
Its absence proves NOTHING. box takes it only after a rig hook it ran and
watched succeed, so a blank box has none, a 'dir'-pool host has none, and a
box whose hook failed and was re-run by hand through 'box shell' has none
either — box will not label a convergence it did not watch. 'box info <box>'
tells you which labels a box actually has; take the mark yourself any time
with 'box snapshot <box> bootstrapped'.
Destructive, so it asks first — naming the snapshot it is rolling back to,
because the whole risk is picking the wrong label. --force (-f) skips the
prompt; with no TTY to ask on it refuses rather than assuming yes.
@ -1118,14 +1159,29 @@ storage_driver() {
printf '%s' "$driver"
}
# Take the 'pristine' snapshot, or say loudly why not. Default ON: the value
# of this mark only exists if it is already there on the bad day, and nobody
# takes it by hand at the one moment it is true. The escape hatch is the
# BOX_LAUNCH_TIMEOUT shape — an environment knob, not another flag on 'new'.
snapshot_pristine() {
local instance="$1" name="$2" driver
if [ "${BOX_SNAPSHOT_PRISTINE:-1}" = 0 ]; then
echo "box: skipping the 'pristine' snapshot (BOX_SNAPSHOT_PRISTINE=0)."
# The shared policy behind every mark box takes for you (#104, #130):
# read the opt-out, read the storage driver, refuse to double the disk cost on
# a pool with no copy-on-write, and NEVER fail a mint over a checkpoint.
#
# It lives once on purpose. What generalises here is the MECHANISM, and the
# never-fatal contract inside it is exactly the property that must not be got
# subtly different in two places — one function, one place to review it, one
# place a future third mark inherits it from. What does NOT generalise is the
# PROSE: 'pristine' and 'bootstrapped' name different moments and are worth
# different sentences, so each wrapper below owns its own narration and passes
# it in. Two thin wrappers over one policy is the honest split; a single
# stringly-parameterised function taking five sentences would not be.
#
# The opt-out variable name is DERIVED from the label (BOX_SNAPSHOT_PRISTINE,
# BOX_SNAPSHOT_BOOTSTRAPPED) so the message can never drift from the knob the
# operator actually has to set.
#
# snapshot_mark <instance> <name> <label> <enabled> <what-this-state-is>
snapshot_mark() {
local instance="$1" name="$2" label="$3" enabled="$4" what="$5" driver knob
knob="BOX_SNAPSHOT_$(printf '%s' "$label" | tr '[:lower:]' '[:upper:]')"
if [ "$enabled" = 0 ]; then
echo "box: skipping the '$label' snapshot ($knob=0)."
return 0
fi
driver="$(storage_driver)"
@ -1134,31 +1190,70 @@ snapshot_pristine() {
# (:294) there is no CoW at all: the snapshot is a full copy of the root,
# several GB and minutes, on EVERY mint. Skip it there — but loudly, and
# naming the by-hand command, because a silent skip teaches an operator to
# expect a mark that will not be there.
# expect a mark that will not be there. With two marks the objection is
# twice the size, so the skip covers both: a 'dir' host is not asked to pay
# for one full root copy per mint, let alone two.
if [ "$driver" = dir ]; then
echo "box: NOT taking the 'pristine' snapshot — this host's storage pool is the 'dir'" >&2
echo "box: NOT taking the '$label' snapshot — this host's storage pool is the 'dir'" >&2
echo "box: driver, which has no copy-on-write, so the mark would be a full multi-GB copy" >&2
echo "box: of the root disk on every mint rather than the near-free btrfs one." >&2
echo "box: take it by hand if you want it here: box snapshot $name pristine" >&2
echo "box: take it by hand if you want it here: box snapshot $name $label" >&2
echo "box: or fix the host (btrfs is what 'box setup-host' installs by default)." >&2
return 0
fi
# Neither probe answered — an unusual host, or a tier that cannot read the
# pool. Proceed, and say what was assumed. The two mistakes are not
# symmetric: a snapshot taken on a 'dir' host wastes disk the operator can
# see in 'box info' and delete, while a snapshot NOT taken is the pristine
# moment gone for good, which is the whole thing this exists to prevent.
[ -n "$driver" ] || echo "box: could not read the storage driver — taking 'pristine' anyway," \
"assuming copy-on-write (BOX_SNAPSHOT_PRISTINE=0 to skip)." >&2
echo "box: marking 'pristine' — the guest after cloud-init, before rig converges anything."
if ! incus snapshot create "$instance" pristine </dev/null; then
# see in 'box info' and delete, while a snapshot NOT taken is the moment
# gone for good, which is the whole thing this exists to prevent.
[ -n "$driver" ] || echo "box: could not read the storage driver — taking '$label' anyway," \
"assuming copy-on-write ($knob=0 to skip)." >&2
echo "box: marking '$label' — $what"
if ! incus snapshot create "$instance" "$label" </dev/null; then
# An undo is not the mint's product: a mint that worked must not be
# failed by a checkpoint that didn't.
echo "box: WARNING — could not take the 'pristine' snapshot (incus said why above)." >&2
echo "box: the box is fine; it just has no pristine mark. The mint continues." >&2
echo "box: WARNING — could not take the '$label' snapshot (incus said why above)." >&2
echo "box: the box is fine; it just has no $label mark. The mint continues." >&2
return 0
fi
echo "box: roll back to it any time with: box restore $name pristine"
echo "box: roll back to it any time with: box restore $name $label"
}
# Take the 'pristine' snapshot, or say loudly why not. Default ON: the value
# of this mark only exists if it is already there on the bad day, and nobody
# takes it by hand at the one moment it is true. The escape hatch is the
# BOX_LAUNCH_TIMEOUT shape — an environment knob, not another flag on 'new'.
snapshot_pristine() {
snapshot_mark "$1" "$2" pristine "${BOX_SNAPSHOT_PRISTINE:-1}" \
"the guest after cloud-init, before rig converges anything."
}
# Take the 'bootstrapped' snapshot (#130), after the rig hook box RAN and
# WATCHED SUCCEED. Same default, same opt-out shape, same never-fatal
# contract as 'pristine' — it is the same policy, one function up.
#
# The label is deliberately CONDITIONAL where 'pristine' is unconditional, and
# the asymmetry is the point rather than an oversight. 'pristine' marks a
# MOMENT that every fresh mint has, so it is taken on every fresh mint.
# 'bootstrapped' marks an EVENT — "a tenant role converged, and nothing has
# happened since" — and a blank box has no such event. Minting the label there
# anyway would either duplicate 'pristine' byte for byte (nothing ran between
# them, so it is the same disk state at twice the cost, which is precisely the
# doubling the 'dir' skip above exists to refuse) or, worse, assert a
# convergence that never happened. So a hookless box gets nothing, and the
# label's presence is itself information: this box had a role and box saw it
# converge.
#
# Read only in that direction. PRESENCE means the mint-time hook succeeded and
# the box has not been touched since; ABSENCE means nothing at all — a blank
# template, a 'dir' pool, an opt-out, or a role converged by hand afterwards
# (see cmd_new's hook-failure path, which hands the operator the command
# because box cannot honestly take a mark for a run it did not watch). Nothing
# in box may treat a missing 'bootstrapped' as evidence a box is unconverged.
snapshot_bootstrapped() {
snapshot_mark "$1" "$2" bootstrapped \
"${BOX_SNAPSHOT_BOOTSTRAPPED:-1}" \
"the tenant role converged, and nothing has touched the box since."
}
cmd_new() {
@ -1451,8 +1546,26 @@ cmd_new() {
echo "box: rig bootstrap $T_BOOTSTRAP_ROLE FAILED in $name." >&2
echo "box: the box is up and the seed is intact — the role converges, so re-run it:" >&2
echo " box shell $name # then: sudo rig bootstrap $T_BOOTSTRAP_ROLE" >&2
# The mark box cannot take for you (#130), said HERE because here is
# the only moment the operator is looking. 'bootstrapped' means "box
# ran the hook and watched it succeed" — a by-hand re-run happens in a
# shell box does not watch, so box cannot know when (or whether) it
# converged, and a mark taken on a guess would be a label asserting a
# convergence box never saw. That is the same lie #104 refused on the
# clone path. So: hand over the command instead of inventing the fact.
echo "box: no 'bootstrapped' mark was taken — box only marks a hook it watched succeed," >&2
echo " and a by-hand re-run happens in a shell it does not watch. Take it yourself once" >&2
echo " the role converges, at the moment it is true:" >&2
echo " box snapshot $name bootstrapped" >&2
echo "box: 'box restore $name pristine' is still there if you would rather start the role over." >&2
die "the tenant role did not converge — the box is incomplete, so refusing to call it ready"
fi
# The hook RAN and box WATCHED it succeed — so right here the box is
# converged and untouched, the state an operator re-mints ten minutes
# for when they break a tenant role but not the OS under it. Never
# fatal, same as 'pristine': a mint that worked is not failed by a
# checkpoint that didn't.
snapshot_bootstrapped "$instance" "$name"
fi
fi
# The login hint belongs to the claude-box template — read the EFFECTIVE

15
docs/box-design.md
View file

@ -55,6 +55,21 @@ has none, and box refuses to label a worked-in state as pristine. On a `dir`
pool the mark would be a full copy rather than a CoW one, so the mint skips
it loudly.
A second, **`bootstrapped`**, is marked one step later (#130) — after the rig
hook has run and box has *watched it succeed*. Same policy, literally the same
function: default on, never fatal, skipped on `dir`, opt-out via
`BOX_SNAPSHOT_BOOTSTRAPPED=0`. Where the two differ is deliberate.
`pristine` marks a **moment** every fresh mint has, so it is unconditional;
`bootstrapped` marks an **event**, so it is not. A blank box has no hook and
therefore no event — marking it anyway would duplicate `pristine` byte for
byte at twice the disk cost, or assert a convergence that never happened. A
failed hook gets no mark either: box tells the operator to re-run the role
through `box shell`, which is a run box does not watch, so it hands over `box
snapshot <n> bootstrapped` instead of guessing. The consequence is a label
that is only ever read one way — **presence** means "converged and untouched";
**absence** means nothing, and nothing in box may treat a missing
`bootstrapped` as evidence a box is unconverged.
Snapshots are in-box state: `box rm` deletes a box *and* its snapshots, and a
clone still lives on the same host. The off-host mechanism is `box export` /
`box import` (#70) — one portable backup tarball, snapshots included by

142
test/cli.sh
View file

@ -524,7 +524,7 @@ rm -f "$CLONEBR"
# snapshot_pristine and run them against a stubbed incus, so every branch is
# actually executed on a host with no daemon.
PRISFN="$(mktemp)"
awk '/^storage_driver\(\) \{/,/^\}/;/^snapshot_pristine\(\) \{/,/^\}/' "$ROOT/bin/box" > "$PRISFN"
awk '/^storage_driver\(\) \{/,/^\}/;/^snapshot_mark\(\) \{/,/^\}/;/^snapshot_pristine\(\) \{/,/^\}/' "$ROOT/bin/box" > "$PRISFN"
check "pristine: the functions extracted from bin/box (guards the awk)" 0 "BOX_SNAPSHOT_PRISTINE" cat "$PRISFN"
check "pristine: the extracted functions are valid bash" 0 "" bash -n "$PRISFN"
@ -630,6 +630,146 @@ check "pristine: 'box help restore' documents the mark and its off-box blind spo
check "pristine: 'box help new' documents the mark and the opt-out" 0 "BOX_SNAPSHOT_PRISTINE" \
bash -c '"'"$ROOT"'/bin/box" help new'
# ---------------------------------------------------------------------------
# The 'bootstrapped' mark (#130, the deferred half of #104). Where 'pristine'
# marks a MOMENT every fresh mint has, this marks an EVENT: a rig hook box ran
# and WATCHED SUCCEED. So the two load-bearing facts are opposite in shape —
# 'pristine' is pinned as unconditional, this one is pinned as gated, and the
# gate is what keeps the label from asserting a convergence that never
# happened. Position and gating are pinned by line order (a daemon-free run
# cannot mint); the policy half is DRIVEN against a stubbed incus, exactly as
# the pristine block above drives it.
# ---------------------------------------------------------------------------
# shellcheck disable=SC2016 # the $-strings are literals in the target file
check "bootstrapped: the mark is taken in the fresh-mint branch" 0 "" bash -c '
awk "/^cmd_new\(\) \{/,/^\}/" "'"$ROOT"'/bin/box" | grep -q "snapshot_bootstrapped \"\$instance\""'
# AFTER the hook: a mark taken before it would be 'pristine' under a name that
# claims convergence — the same lie #104 refused on the clone path.
# shellcheck disable=SC2016 # the $-strings are literals in the target file
check "bootstrapped: the mark orders AFTER the rig bootstrap hook" 0 "" bash -c '
fn="$(awk "/^cmd_new\(\) \{/,/^\}/" "'"$ROOT"'/bin/box")"
run="$(printf "%s\n" "$fn" | grep -Fn "rig bootstrap \"\$T_BOOTSTRAP_ROLE\" </dev/null" | head -1 | cut -d: -f1)"
snap="$(printf "%s\n" "$fn" | grep -n "snapshot_bootstrapped " | head -1 | cut -d: -f1)"
[ -n "$run" ] && [ -n "$snap" ] && [ "$run" -lt "$snap" ]'
# GATED on T_BOOTSTRAP_ROLE — the blank-template asymmetry, chosen. A hookless
# box has no convergence to mark; marking one anyway would either duplicate
# 'pristine' byte for byte at twice the disk cost or assert an event that did
# not happen. This is the exact inverse of the pristine guard above, and both
# must hold at once.
# shellcheck disable=SC2016 # the $-strings are literals in the target file
check "bootstrapped: the mark IS gated on a tenant role (the blank asymmetry)" 0 "" bash -c '
fn="$(awk "/^cmd_new\(\) \{/,/^\}/" "'"$ROOT"'/bin/box")"
guard="$(printf "%s\n" "$fn" | grep -n "if \[ -n \"\$T_BOOTSTRAP_ROLE\" \]" | head -1 | cut -d: -f1)"
snap="$(printf "%s\n" "$fn" | grep -n "snapshot_bootstrapped " | head -1 | cut -d: -f1)"
[ -n "$guard" ] && [ -n "$snap" ] && [ "$guard" -lt "$snap" ]'
# NOT after a FAILED hook. The failure branch ends in a 'die', so the mark is
# unreachable from it — pinned by asserting the mark sits after that die, i.e.
# on the far side of a branch that never returns.
# shellcheck disable=SC2016 # the $-strings are literals in the target file
check "bootstrapped: a FAILED hook dies before ever reaching the mark" 0 "" bash -c '
fn="$(awk "/^cmd_new\(\) \{/,/^\}/" "'"$ROOT"'/bin/box")"
d="$(printf "%s\n" "$fn" | grep -n "die \"the tenant role did not converge" | head -1 | cut -d: -f1)"
snap="$(printf "%s\n" "$fn" | grep -n "snapshot_bootstrapped " | head -1 | cut -d: -f1)"
[ -n "$d" ] && [ -n "$snap" ] && [ "$d" -lt "$snap" ]'
# ...and the operator is HANDED the command at the one moment they are
# looking. This is the answer to the sharpest objection in #130: the mark is
# absent exactly on the boxes whose convergence needed intervention, so the
# failure path must name the by-hand command rather than leave a silent hole.
# shellcheck disable=SC2016 # the $-strings are literals in the target file
check "bootstrapped: the hook-failure message hands over the by-hand command" 0 "" bash -c '
awk "/^cmd_new\(\) \{/,/^\}/" "'"$ROOT"'/bin/box" \
| grep -q "box snapshot \$name bootstrapped"'
# The clone branch takes neither mark. Reuses #104's extraction shape.
CLONEBR2="$(mktemp)"
awk '/if \[ -n "\$from" \]; then/,/^ else$/' "$ROOT/bin/box" > "$CLONEBR2"
check "bootstrapped: the clone branch extracted from bin/box (guards the awk)" 0 "incus copy" cat "$CLONEBR2"
check "bootstrapped: a --from clone takes no 'bootstrapped' either" 1 "" \
grep -q "snapshot_bootstrapped" "$CLONEBR2"
rm -f "$CLONEBR2"
# The never-fatal contract lives ONCE. Two marks share one policy function on
# purpose: the failure handling is the part that must not be got subtly
# different in two places. If a future change copy-pastes the policy instead of
# calling it, this bites. (The other create is cmd_snapshot's, the by-hand
# verb, which is deliberately fatal — an explicit 'box snapshot' that fails
# must fail.)
check "bootstrapped: exactly one auto-mark policy — 'incus snapshot create' twice in bin/box" 0 "2" \
bash -c 'grep -c "incus snapshot create" "'"$ROOT"'/bin/box"'
# The policy half, DRIVEN. Same stub shape as pris() above, one label over.
BOOTFN="$(mktemp)"
awk '/^storage_driver\(\) \{/,/^\}/;/^snapshot_mark\(\) \{/,/^\}/;/^snapshot_bootstrapped\(\) \{/,/^\}/' \
"$ROOT/bin/box" > "$BOOTFN"
check "bootstrapped: the functions extracted from bin/box (guards the awk)" 0 "snapshot_bootstrapped" cat "$BOOTFN"
check "bootstrapped: the extracted functions are valid bash" 0 "" bash -n "$BOOTFN"
boot() { # boot <driver> <instance> [VAR=VAL...]
local driver="$1" instance="$2"; shift 2
# shellcheck disable=SC2016 # the body is the stub's source, expanded by the
# inner bash from the environment 'env' sets up — never by this shell.
env "$@" DRIVER="$driver" INSTANCE="$instance" BOOTFN="$BOOTFN" bash -c '
incus() {
case "$*" in
"profile device get box-net root pool") printf "boxpool\n" ;;
"storage show boxpool")
[ "$DRIVER" = none ] && return 1
printf "name: boxpool\ndriver: %s\n" "$DRIVER" ;;
"storage list --format csv")
[ "$DRIVER" = none ] && return 1
printf "boxpool,%s,,0,CREATED\n" "$DRIVER" ;;
"snapshot create inst-x bootstrapped") printf "STUB: snapshot created\n" ;;
"snapshot create fail-x bootstrapped") printf "STUB: incus refused\n" >&2; return 1 ;;
*) printf "STUB: unexpected incus call: %s\n" "$*" >&2; return 1 ;;
esac
}
. "$BOOTFN"
snapshot_bootstrapped "$INSTANCE" boxname
' 2>&1
}
boot_took_mark() { boot "$@" | grep -q "STUB: snapshot created"; }
check "bootstrapped: btrfs (the designed backend) takes the mark" 0 "STUB: snapshot created" \
boot btrfs inst-x
check "bootstrapped: btrfs names the restore command for the operator" 0 "box restore boxname bootstrapped" \
boot btrfs inst-x
# The 'dir' skip, and with two marks the disk objection is twice the size: a
# CoW-less host must not be asked to pay for one full root copy per mint, let
# alone two. Same refusal, same loudness, same by-hand command.
check "bootstrapped: a 'dir' pool SKIPS the mark (no CoW — it would be a full copy)" 0 "NOT taking" \
boot dir inst-x
check "bootstrapped: the dir skip is loud and names the by-hand command" 0 "box snapshot boxname bootstrapped" \
boot dir inst-x
check "bootstrapped: the dir skip never reaches incus snapshot create" 1 "" \
boot_took_mark dir inst-x
check "bootstrapped: an unreadable pool takes the mark anyway (the asymmetry)" 0 "STUB: snapshot created" \
boot none inst-x
check "bootstrapped: ...and says what it assumed rather than pretending it knew" 0 "could not read the storage driver" \
boot none inst-x
check "bootstrapped: BOX_SNAPSHOT_BOOTSTRAPPED=0 skips it anywhere" 0 "BOX_SNAPSHOT_BOOTSTRAPPED=0" \
boot btrfs inst-x BOX_SNAPSHOT_BOOTSTRAPPED=0
check "bootstrapped: the opt-out never reaches incus snapshot create" 1 "" \
boot_took_mark btrfs inst-x BOX_SNAPSHOT_BOOTSTRAPPED=0
# The opt-out knob name is DERIVED from the label, so the message can never
# drift from the variable an operator actually has to set — and one label's
# knob must not silently disable the other's.
check "bootstrapped: the opt-out is a per-label knob — PRISTINE=0 does not silence it" 0 "" \
boot_took_mark btrfs inst-x BOX_SNAPSHOT_PRISTINE=0
check "bootstrapped: a failed snapshot warns and returns 0 (never fails a good mint)" 0 "WARNING" \
boot btrfs fail-x
rm -f "$BOOTFN"
# The label is one-directional and the docs must say so: its PRESENCE means the
# hook converged untouched, its ABSENCE means nothing at all. Without that
# sentence a missing mark reads as "unconverged", which is exactly the false
# coverage #130 warns about.
check "bootstrapped: 'box help restore' refuses to let absence imply anything" 0 "absence proves NOTHING" \
bash -c '"'"$ROOT"'/bin/box" help restore'
check "bootstrapped: 'box help restore' repeats the off-box blind spot for it too" 0 "cannot undo anything" \
bash -c '"'"$ROOT"'/bin/box" help restore'
check "bootstrapped: 'box help new' documents the mark and the opt-out" 0 "BOX_SNAPSHOT_BOOTSTRAPPED" \
bash -c '"'"$ROOT"'/bin/box" help new'
check "bootstrapped: 'box help snapshot' names the by-hand fallback" 0 "box snapshot work bootstrapped" \
bash -c '"'"$ROOT"'/bin/box" help snapshot'
# ---------------------------------------------------------------------------
# The restricted tier (#74). box_tier() is the decision the whole tier hangs
# on, so it is DRIVEN, not grepped: extracted from bin/box, sourced, and run