Hardpoints
Accepted, 1.0 built for stt and tts (ADR 0059): a hardpoint is a typed runtime slot (stt, tts, wake, decision, brain, voice, avatar, render, room, memory, retrieval) with one owner and one effective binding per scope; an implementation is a hardpoint Catalog entry whose hardpoint.toml declares its slot, contract range, provenance, transport, capabilities, memory peak, latency budget and fallback; the loadout binds it under [hardpoints] ([adapters] stays an alias for the deprecation window); the owner qualifies it with the slot's probe (nothing audible) before claiming ready, falls back to the built-in as degraded on failure, and reports it on readiness and the Admin's Hardpoints card. stt and tts open first.
Living doc, checked against the code 2026-11-14
hardpoint.v1 — a typed runtime slot, the implementation a user binds into it, and the qualification before ready
- Status: accepted; 1.0 built for
sttandtts. It implements ADR 0059 §2. This file is the meta-contract; the slots’ own contracts are hardpoint.stt.v1 and hardpoint.tts.v1. - Registry:
crates/voice_gateway/src/hardpoint.rs. It holds the[hardpoints]loadout table, admission of acatalog/hardpoints/<id>/hardpoint.toml, qualification before ready, and what the Admin’s Hardpoints page reads (GetHardpoints). - Not built: the Catalog index pin (
digest_mismatch), thereadinessowners on the wire, live p50 and p90 per slot, and the per-implementation Admin switch. - Scope: a slot is a closed, owner-defined place where exactly one runtime dependency is mounted per scope: an STT, a TTS, a wake detector, the decision model, the brain, a voice, an avatar, a renderer, a room device, a memory store or a retrieval provider. An implementation is a Catalog entry that declares which slot and contract range it fills. The slot’s owner admits it, qualifies it, binds it and reports it. The Catalog and the Admin never bind.
- The plugin point: a
hardpointCatalog entry with ahardpoint.toml, and one line under the loadout’s[hardpoints].
The slots (v1)
| slot | owner | interface contract | built-in | apply | budget leg (turn-budget.v1) |
|---|---|---|---|---|---|
stt |
gateway | hardpoint.stt.v1 (today’s SttAdapter) |
parakeet-silero |
session bind | speech_end_to_commit |
tts |
gateway | hardpoint.tts.v1 (today’s TtsAdapter) |
qwen3-worker |
session bind | first_text_to_first_audio |
wake |
gateway invocation runtime | typed detections | the wake worker | startup | speech_end_to_commit |
decision |
gateway | decision.v1 | the decision model’s endpoint | startup | speech_end_to_commit |
brain |
gateway | Pi’s RPC line protocol | Pi | session bind | commit_to_first_text |
voice |
persona | voice-profile-manifest.v1 | the persona’s profiles | session bind | none |
avatar |
each frontend | avatar-action.v1, avatar-puppet.v1 | the 2D fox, VRM, Live2D | live | visual_paint |
render |
each frontend | panel-card.v1, visual.v1 | the conversation window, the panel kit | connection | visual_paint |
room |
gateway | ADR 0034’s verbs out and events in | roomctl, homectl |
startup | none (its own receipt’s ack.ms) |
memory |
gateway | ADR 0031’s record v2, recall and propose | runtime/operator_memory |
startup | tool_round |
retrieval |
gateway | ADR 0007’s bounded, cited evidence | the retrieval index | session bind | commit_to_first_text |
Only stt and tts are open: they take your own implementation today. The other nine slots have names only, and a
manifest for one is refused slot_not_open. Any other slot opens in a minor version; until then its seam is unchanged.
The manifest (hardpoint.toml)
# <catalog root>/hardpoints/my-tts/hardpoint.toml
id = "my-tts"
slot = "tts"
contract = "hardpoint.tts >= 1.0, < 2"
provenance = "user" # built_in | first_party | user
transport = "wyoming" # in_process (built-ins only) | process_stdio | unix_socket | http_loopback | wyoming
endpoint = "tcp://127.0.0.1:10250" # or command = "bin/serve" for process_stdio
capabilities = ["audio_out"] # ADR 0050 §2's set plus audio_in, audio_out
memory_peak_mb = 900 # projected; a model load still needs the operator's ok
budget_ms = { p50 = 400, p90 = 850 } # against the slot's turn-budget leg
probe = "default" # the slot's own qualification probe
fallback = "qwen3-worker" # a built-in, or "none"
| field | rule |
|---|---|
id |
the entry’s Catalog id; unique per slot |
slot |
one value of the slot table, opened in the build |
contract |
a range that overlaps what the build speaks, or the entry is refused contract_unsupported |
provenance |
user for anything the operator installs; a user entry is never in_process |
transport |
how the owner reaches it; this build drives wyoming for tts and http_loopback (the STT worker wire) for stt, and refuses any other pair transport_not_allowed |
endpoint |
a loopback address: an implementation stays on the gateway’s host |
capabilities |
closed; a slot that receives PCM needs audio_in, and one that produces it needs audio_out |
memory_peak_mb |
shown beside the shared host’s budget; it never authorizes a load |
budget_ms |
what the implementation claims; qualification measures it |
fallback |
what the owner binds when this one fails qualification or goes unavailable |
reference_voices |
optional, tts only: up to four voice names the server falls back to; the voice check after a bind compares the configured voice with each (hardpoint.tts.v1) |
The entry is not yet pinned by digest through the Catalog index; digest_mismatch is reserved for that check.
Binding
[hardpoints]
tts = "my-tts"
stt = "parakeet-silero"
There is exactly one effective binding per slot per scope. A missing slot means the built-in. tts_voice (optional)
names the voice a tts Catalog implementation speaks in (hardpoint.tts.v1).
[adapters] stt and tts are deprecated aliases for [hardpoints] stt and tts. A loadout that sets both forms for
one slot is refused binding_conflict. [hardpoints] user (on by default) switches every user implementation.
The Gateway window’s Hardpoints page can also switch an open slot for every session: it runs the slot’s probe, then
writes hardpoints.stt, hardpoints.tts or hardpoints.tts_voice to the gateway’s config overlay ([admin] config_writes must be on). That choice wins over each loadout’s from the next session on.
Qualification and states
| state | meaning |
|---|---|
declared |
the loadout names it |
admitted |
the manifest parses, its slot is open, the contract range overlaps, the capabilities are declared and allowed, and the transport and endpoint are allowed |
qualified |
the slot’s probe passed within 5 s: tts renders a fixed sentence to bytes (never played: nothing audible), stt opens its worker wire; its ms are measured |
bound |
the owner installed it for the scope |
live / degraded / unavailable |
the readiness the owner reports while bound |
retired |
unbound at the scope’s end, or replaced at the next bind |
The owner never claims ready on a binding that is not qualified. A failed qualification binds the fallback and
reports the bind degraded {reason: qualification_failed} in the Admin and the trace. With fallback = "none", the
bind is refused. An implementation whose measured p50 or p90 is over its leg’s budget is still bound. The Admin marks
it over budget, and the built-in stays its fallback.
A crash or hang is supervised like any adapter (crates/voice_gateway/src/adapter_supervision.rs): restart with
backoff, then unavailable and the fallback. A slot’s failure never ends a session that its fallback can carry.
Built for tts (crates/voice_gateway/src/hardpoint/supervised_tts.rs):
- A render that fails before its first audio counts one failure against
[adapters.supervision](max_restartsinsidewindow_ms). The fallback built-in speaks that request again, and every later one the implementation still held. The session hears the built-in and sees no error. - A render that fails after its audio started passes its error through.
- While the backoff runs, the fallback carries new requests. After the backoff, the next request tries the implementation again.
- Past the budget the implementation is
unavailable {reason: implementation_unavailable}for the rest of the session. The Admin row names the fallback as what carries the slot. Onehardpoint_unavailabletrace row is written: slot, ids, failures, the server’s words, no endpoint. The next bind qualifies it again. - The fallback is built on the first failure, never at bind. An entry with
fallback = "none"is not supervised: its errors reach the session. - The budget is kept on the gateway’s shared supervisor. The Health panel shows the implementation as
adapter.hardpoint.tts:<id>: up after the bind, reconnecting with its attempts, degraded once the budget is spent. Each bind resets the row. With[adapters.supervision] enabled = falsethe session keeps its own budget. - Once built, the fallback stays warm for the rest of the session, also when the implementation comes back. The
session’s TTS restart (
prewarm) restarts it too. Onehardpoint_fallback_first_audiotrace row times the first moved reply, from the failure to the fallback’s first audio, the fallback’s start included.
Built for stt (crates/voice_gateway/src/hardpoint/supervised_stt.rs), the same way:
- A user recognizer that fails before the utterance’s transcript counts one failure against the same budget: a refused send, a terminal transport error, or a recognition error. The session sees none of them.
- The utterance in flight is spoken again into the built-in recognizer from the audio kept since the last transcript
(at most about 15 s at 24 kHz). That utterance and the next are the built-in’s. A cohort the implementation left
open is closed with
speech_stoppedfirst, so the turn takes the built-in’s cohort. - After those two, once the backoff has passed and no utterance is open, the next audio tries the implementation again on a fresh connection.
- Past the budget it is
unavailable {reason: implementation_unavailable}for the session, with the same Admin row,hardpoint_unavailabletrace row andadapter.hardpoint.stt:<id>Health row astts. A rebuild inside the session (a transition) keeps the wrap and starts on the built-in once the budget is spent. - A fallback that cannot be built passes the implementation’s terminal error through, and an entry with
fallback = "none"is not supervised. Either way[stt] on_faultapplies.
Readback
- Wire: not built.
readinessis to gain oneReadinessOwnerper opened slot, additive within protocol 5; today its owners are the wake detector and speech output. - Admin: a Hardpoints card, one row per slot:
- desired, effective and live;
- the provenance;
- the contract version spoken;
- the last qualification receipt (outcome, measured ms, when);
- for a
ttsimplementation, its voice check once it ran (its own voice, fell back, or unchecked); - whether the probe was over the leg’s budget (live p50 and p90 are not built);
- the fallback in use.
- Trace: one
hardpoint_boundrow per bind: slot, implementation id, provenance, state, ms. No path, no endpoint secret.
Errors
A bind refusal names one reason: unknown_slot, slot_not_open, unknown_implementation, manifest_invalid,
contract_unsupported, digest_mismatch, capability_undeclared, transport_not_allowed, binding_conflict,
qualification_failed (only with no fallback), switched_off (a user implementation with [hardpoints] user = false and no fallback). It is refused as loadout_resolution_failed, with the reason in the trace and the Admin.
A degraded bind carries qualification_failed or switched_off as its reason. implementation_unavailable is never
a refusal: it is the reason an unavailable row carries once a bound implementation spent its restart budget.
Compatibility
hardpoint.v1 and each hardpoint.<slot>.v<N> carry their own major.minor (ADR 0059 §5). A minor may open a slot,
add a transport, add an optional manifest field or a reason value, and widen a bound. It never removes a slot or a
field, changes a state’s meaning, or requires a new manifest field. The tts conformance sample is a stub whose PCM
goes to bytes (below). Each slot adds its own sample when it opens.
Check your own
just catalog::hardpoint-check <slot> <id> (the gateway binary’s hardpoint-check) runs this bind path on a Catalog
entry under the runtime root (--root for another): admission, then the slot’s probe within the bind’s 5 s. It
prints one line. With --json it prints the receipt (vulpine.hardpoint_check.v1: admission, qualification, ms
against the leg’s budget, the reason; never an endpoint). It exits 0 when the entry would bind as itself.
just catalog::hardpoint-check --sample tts serves and checks the tts sample
(crates/voice_gateway/src/hardpoint/conformance.rs): a stub Wyoming server whose PCM is fixed silence, 50 ms per
character at 24 kHz, 16-bit mono. It is the smallest server that passes hardpoint.tts 1.0.