Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 stt and tts. 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 a catalog/hardpoints/<id>/hardpoint.toml, qualification before ready, and what the Admin’s Hardpoints page reads (GetHardpoints).
  • Not built: the Catalog index pin (digest_mismatch), the readiness owners 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 hardpoint Catalog entry with a hardpoint.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_restarts inside window_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. One hardpoint_unavailable trace 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 = false the 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. One hardpoint_fallback_first_audio trace 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_stopped first, 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_unavailable trace row and adapter.hardpoint.stt:<id> Health row as tts. 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_fault applies.

Readback

  • Wire: not built. readiness is to gain one ReadinessOwner per 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 tts implementation, 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_bound row 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.

Was this page helpful?