Module rig 

Rig lifecycle actions (04-01, RIG-01): up / down / status — serde models OUT, no printing (the TUI rides this layer in Phase 6). Extended by 04-02 (reset/logs), 04-03 (trial), 04-04 (snapshot/restore, RIG-04).

Every action takes [&dyn ComposeRunner] (the Task-1 seam) so the full decision tree is unit-testable without docker. rig_up additionally takes an OPTIONAL gateway probe: the dispatch derives the rig’s gateway URL (gateway_url_from) and builds a HEADER-LESS client pointed at it — the commissioned wait probes /StatusPing on the RIG’s own port, never the profile’s gateway.

Uncommissioned is DATA, not failure (research Pattern 4)

A fresh-volume rig terminally reports "up, uncommissioned" — exit 0 with the wizard URL inside warnings (the version-command degradation precedent). There is NO headless commissioning (verified: no commissioning endpoints in 83-api); the wait deadline only covers STARTING→RUNNING on an already-commissioned volume.

The wait reuses poll.rs VERBATIM (locked)

crate::poll is THE wait engine — its retry set is LOCKED and untouched. Probe translation (research Pattern 4): RUNNING → Done; other states → Pending; GatewayNotCommissioned → the probe ITSELF catches it and returns Pending with the wizard hint (never aborts); Network/GatewayRestarting propagate for poll’s native retry; Auth can’t fire (the probe is header-less).

Structs

RestoreResult

ign rig restore output model (04-04, RIG-04) — all keys always.

RigDownResult

ign rig down output model.

RigLogsResult

ign rig logs output model (04-02, RIG-02): only the count — the lines themselves already streamed through the sink (the third sanctioned stdout exception; the dispatch owns the printing, the logs -f precedent).

RigResetResult

ign rig reset output model (04-02, all keys always).

RigStatusResult

ign rig status output model — an ALLOWLIST, never a compose config/inspect passthrough (the resolved config contains GATEWAY_ADMIN_PASSWORD etc.; research anti-pattern).

RigUpResult

ign rig up output model (all keys always present).

SnapshotResult

ign rig snapshot output model (04-04, RIG-04) — all keys always.

StatusPublisher

One published-port row in status output (allowlist only).

StatusService

One service row in status output (allowlist only).

TrialBanners

The banners cross-check block of TrialStatusResult (all keys always; a failed banners fetch degrades to nulls + a warning — the trial endpoint is the primary truth).

TrialResetResult

ign rig trial reset output model (04-03, RIG-03): the ladder’s outcome — which rung landed, and the before/after flip (the flip is REQUIRED for success; a bare 2xx never suffices).

TrialStatusResult

ign rig trial status output model (04-03, RIG-02): the trial endpoint re-exposed under unit-explicit keys (the two-layer naming LOCK) + the banners cross-check. All keys always present.

Constants

DEFAULT_WAIT_TIMEOUT_S

Default wait budget for BOTH up --wait-timeout and the commissioned probe deadline (research Pitfall 3: healthchecks block --wait, and image pulls add minutes).

RESTORE_TOKEN_WARNING

The token-clobber warning (Pitfall 5, 83-api primary source): tokens stored under CORE config are “modified/cleared often by gwbk restores” — post-restore, stored profiles 401. It rides DATA (agents must see it), never stderr-only.

RESTORE_WAIT_FLOOR_S

The restore wait FLOOR: the gateway RESTARTS after a restore (Pitfall 6), so the post-restore RUNNING wait never gets a shorter deadline than this — an explicit --timeout 30 cannot buy an unknown-state mid-restart report (the RESTART_FLOOR precedent, restore edition).

Functions

gateway_url_from

Derive the rig’s gateway URL from the resolved port mappings — the DOCUMENTED HEURISTIC: the first mapping targeting the gateway’s http port (8088) wins, then its https port (443), else nothing. data carries what was derived (gateway_url), so agents can see the heuristic’s answer.

rig_down

ign rig down: version gate → down --remove-orphans (volumes KEPT — the -v teardown half belongs to rig reset, 04-02).

rig_logs

ign rig logs (04-02, RIG-02): compose log PASSTHROUGH — a raw line stream through sink, never an envelope-wrapped body. Compose log lines are not gateway JSON objects; wrapping would corrupt them, so rig logs --json is the SAME passthrough in every render mode (contrast logs -f --json, whose entries ARE gateway NDJSON — the second exception). Follow mode rides the runner’s STREAMING shape (piped stdout forwarded as it arrives until EOF/child exit; Ctrl-C kills the foreground process group — README §Streaming, the logs -f precedent). Compose stderr (diagnostics) goes to OUR stderr via tracing::warn — never the data sink.

rig_reset

ign rig reset (04-02, RIG-01): the guarded teardown + bring-up cycle — NO stale project/trial state survives. The CLI guard (--yes, exit 2 before ANY resolution) lives in the dispatch (the sessions-terminate/project-delete layering); this action is the decision-complete cycle behind it:

rig_restore

ign rig restore (04-04, RIG-04): the guarded inverse —

rig_snapshot

ign rig snapshot (04-04, RIG-04): repeatable state, composed HONESTLY —

rig_status

ign rig status: version gate → ps LDJSON → volume ls → port occupancy — serialized as an ALLOWLIST (services’ state/health/ publishers, volume names, identity). Exit 0 even when the rig is down: state is data.

rig_up

ign rig up: version gate → port pre-flight → up -d --wait → commissioned wait (poll.rs) with uncommissioned-as-data semantics.

trial_reset

ign rig trial reset (04-03, RIG-03): the evidence-chosen LADDER — tier 0 (token-auth POST /trial through the existing client, one cheap call) falls through to tier 1 (the native OIDC login → session+CSRF POST, crate::client::idp, live-verified end-to-end on 8.3.3 with the expired:true → false flip).

trial_status

ign rig trial status (04-03, RIG-02): the trial endpoint is the PRIMARY truth; the trial banner (type: "trial") is the cross-check, its active flag computed per Pitfall 7 (severity=="info" && expireTime>now_ms — never the reverse derivation). A failed banners fetch degrades to nulls + a warning (the trial endpoint already answered; the cross-check is advisory). gateway is a client pointed at the RIG’s URL — these endpoints answer unauthenticated (live-verified both rigs), so a fresh rig with no token reports its trial state fine.