fix(boot): typed AircDiscovery + BootMode + conditional manifest (Slice A.2.1)

[joelteply]

Summary

Replaces Slice A (PR #1527, closed via convergent R1+R2+R3 BLOCK) with the architectural change Slice A's three patch-fixes were imitating. Compresses three drifting representations of substrate boot state (Option<(PathBuf, RoomId)> + flat EXPECTED_MODULES const + heuristic seed detection) into one typed primitive each consumer matches exhaustively. The drift problem dies structurally — not because we wrote a louder doc-comment this time, but because the contradictions are no longer expressible.

Card: 4075b9a4-7251-4405-84e5-9033e2213dff
Supersedes: PR #1527

Closes (with structural fixes, not patches)

R1#1 (BLOCKING) — EXPECTED_MODULES contradicted --mode=inference-only

verify_registration(&discovery, mode) now computes the required set conditionally. MODULES_PERSONA_HOSTING is only required when AIRC is Healthy AND mode.requires_persona_hosting(). The PR title "supports inference-only" is true by construction.

R2#1 (BLOCKING) — AIRC_DAEMON_SOCKET env var bypassed liveness

discover() aggregator runs Status RPC liveness probe. Failure promotes to AircDiscovery::Degraded { reason: StaleSocket(path, underlying_err), partial: ... } instead of the soft-fallback to Uuid::nil() that let stale sockets through.

R2#2 (BLOCKING) — implicit non-persona-use fallback

Explicit --mode=<full-citizen|inference-only|fail-fast> flag (default FullCitizen). The operator states intent; the substrate doesn't guess from personas/ directory contents.

R2#3 + R3#3 (BLOCKING) — hand-maintained manifest drift

ALL_KNOWN_MODULES = MODULES_CORE ∪ MODULES_PERSONA_HOSTING is a build-time invariant checked by three drift-catcher unit tests. The "louder doc-comment" non-fix is gone. A.2.2 layers an insta snapshot of runtime.registry().module_names() on top.

R2 NIT — A2 panic filter mutes only signal

A2 panic filter restored (suppresses misleading stderr trace only; catch_unwind safety net unchanged). New boot banner line Boot mode: <label> (<description>) surfaces operator's chosen mode immediately. Voice subsystem 🔊 ready / 🔇 unavailable status line lands in A.2.2.

The compression principle this enacts

Before: three pieces of code answered "what is the substrate's boot state":

• Option<(PathBuf, RoomId)> tuple
• EXPECTED_MODULES: &[&str] flat const
• inline seed-presence heuristic in ipc/mod.rs

Each could drift against the other two. Slice A added a fourth representation (the hard-fail check) without compressing — that's how it produced PR claims contradicting its own implementation.

A.2.1 collapses to ONE typed state (AircDiscovery), ONE explicit operator-intent flag (BootMode), ONE function answering "what's required for THIS state" (required_modules(&discovery, mode)). Every consumer reaches through the same primitive. The "different consumers disagree about what state is" failure mode is no longer expressible.

Architectural seam for B'

AircDiscovery::Healthy/Degraded/Unreachable is the first instance of the three-variant health shape that every category sidecar (renderer, voice, inference, foundry) will inherit in B'. The substrate-wide controls (for each category: health(), PressureBroker admission, Ares-the-dispatcher's allocation cognition) operate uniformly across categories because each category's state surface looks the same. A.2.1's discipline is the foundation: the same compression that closes R1#1 here is what makes Ares possible later.

Substrate-level tests (not demos)

Module	Tests	What it pins
airc::discovery_state	4	Healthy/Degraded/Unreachable transitions; StaleSocket carries path AND underlying error
runtime::boot_mode	12	Canonical/alias/case-insensitive parsing; requires_persona_hosting/requires_voice queries; extract_boot_mode against equals-form/space-form/absent/dangling argv
runtime::runtime::conditional_modules_tests	7	required_modules dispatch across (Healthy, Degraded) × (FullCitizen, InferenceOnly, FailFast), plus three drift catchers (all_known_modules_is_union_of_subsets, core_and_persona_hosting_are_disjoint, required_modules_returns_exactly_one_of_two_sets)

Total: 23/23 pass. Each primitive exercisable in isolation — no demo bin, no binary boot, no live AIRC daemon. The compression makes them testable; the tests make the compression honest. This is exactly the [[test-fixtures-are-system-primitives]] pattern at the boundary layer.

A.2.2 layers cross-substrate integration tests on top (StubAircCitizen + tempdir continuum_root + start_server end-to-end across the mode × discovery × seed matrix).

End-to-end (release binary)

Will be exercised after CI green:

• --mode=full-citizen + AIRC healthy → All N required modules registered, Paige hosts, airc msg round-trip
• --mode=full-citizen + AIRC unreachable → exit 1, typed reason from Unreachable.reason()
• --mode=full-citizen + AIRC_DAEMON_SOCKET=<stale.sock> → exit 1 with StaleSocket { path, underlying }
• --mode=inference-only + AIRC unreachable → boots cleanly, INFO line names operator intent
• --mode=fail-fast + libonnxruntime missing → exit 1

Out of scope (folded into A.2.2 + B')

A.2.2:

• Context trait discovery() + boot_mode() accessors
• PersonaContext / AgentContext / StubContext impl
• tests/substrate_boot_contract.rs integration matrix
• tests/ort_panic_filter.rs with serial_test::serial
• tests/expected_modules_snapshot.rs insta snapshot
• Voice subsystem 🔊 ready / 🔇 unavailable status line
• runtime/mode/get + runtime/mode/set commands — expose BootMode via the universal Commands surface so widgets, personas, and remote continuums all read/change runtime mode through the same primitive. Same for runtime/discovery/get. The compression extends to the control surface: one typed value, one command pair, every actor uses the same primitive.

B':

• Generalization of AircDiscovery's three-variant pattern to RendererHealth / InferenceHealth / VoiceHealth
• CategorySidecar trait + uniform health() / allocate_lane() / shutdown()
• Sidecar process pattern (renderer/voice/inference/foundry as separate binaries)
• Ares-the-persona dispatcher (the master control citizen)

Doctrine alignment (substantive, not as cover)

• [[no-fallbacks-ever]] — typed discovery + explicit mode eliminate every silent-substitution path Slice A retained
• [[every-error-is-an-opportunity-to-battle-harden]] — the three drift catchers ARE the rigging
• [[substrate-is-a-good-citizen-on-the-host]] — boot banner names the mode; degraded states have human-actionable typed reasons
• [[host-the-seemingly-impossible]] — substrate publishes what it CAN do honestly; --mode=full-citizen is a promise, not a hope

References

• Closed predecessor: PR fix(boot): substrate refuses to lie when degraded (Slice A) #1527, reviewer transcripts in airc 2026-06-04
• docs/architecture/CBAR-SUBSTRATE-ARCHITECTURE.md
• docs/architecture/PERSONA-COGNITION-PIPELINE.md
• CLAUDE.md COMPRESSION PRINCIPLE — one logical decision, one place

🤖 Generated with Claude Code