---
title: "Hardpoints"
description: "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."
type: "living"
source: "docs/contracts/hardpoint.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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](/docs/contracts/hardpoint.stt.v1) and [hardpoint.tts.v1](/docs/contracts/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](/docs/contracts/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](/docs/contracts/voice-profile-manifest.v1) | the persona's profiles | session bind | none |
| `avatar` | each frontend | [avatar-action.v1](/docs/contracts/avatar-action.v1), [avatar-puppet.v1](/docs/contracts/avatar-puppet.v1) | the 2D fox, VRM, Live2D | live | `visual_paint` |
| `render` | each frontend | [panel-card.v1](/docs/contracts/panel-card.v1), [visual.v1](/docs/contracts/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`)

```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](/docs/contracts/hardpoint.tts.v1#voice-check)) |

The entry is not yet pinned by digest through the Catalog index; `digest_mismatch` is reserved for that check.

## Binding

```toml
[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](/docs/contracts/hardpoint.tts.v1#naming-the-voice)).
`[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.
