---
title: "Voice profiles"
description: "Draft: the manifest a Voice Profile candidate carries before any synthesis (consent record, the four sha256-hashed inputs, a profile id derived from persona, seed and hashes, operator-owned WER and naturalness budgets) and the codes the checker tools/speech/voice_foundry.py refuses it with."
type: "living"
source: "docs/contracts/voice-profile-manifest.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

voice-profile-manifest.v1 — the consent and provenance a Voice Profile candidate must carry

- Status: draft. The checker is built. Nothing in the gateway reads the manifest. The gateway's Voice Profile is a
  name (`VoiceProfile {id, label, description}` in `crates/protocol/src/lib.rs`) with no provenance field.
- Checker: `tools/speech/voice_foundry.py` (`check`, `derive-id`).


A Voice Profile candidate is a voice made from reference material plus a model, a config, a prompt and a seed. Its
manifest must pass this check before any synthesis, evaluation or admission uses the candidate. The manifest is a
JSON file next to its artifacts.

## The manifest

```json
{
  "schema": "voice-profile-manifest.v1",
  "profile_id": "vp1-<24 lowercase hex>",
  "profile": {"persona": "fox9", "label": "free text", "uses": ["evaluation"]},
  "consent": {
    "record_id": "consent-0001",
    "subject": "a pseudonym, never a real name in git",
    "granted_on": "2026-10-01",
    "expires_on": "2027-10-01",
    "scope": ["evaluation", "audition"],
    "revoked_on": null
  },
  "inputs": {
    "seed": 7,
    "artifacts": [
      {"role": "source", "path": "source.wav", "sha256": "<64 lowercase hex>"},
      {"role": "model", "path": "model.json", "sha256": "..."},
      {"role": "config", "path": "config.json", "sha256": "..."},
      {"role": "prompt", "path": "prompt.txt", "sha256": "..."}
    ]
  },
  "budgets": {"set_by": null, "wer_regression_max": null, "naturalness_regression_max": null}
}
```

- **uses** and **scope** use a closed vocabulary: `evaluation` (offline scoring), `audition` (a blind A/B for
  the operator) and `persona_tts` (a Persona speaks with the voice). Any other word is refused.
- **artifacts**: one row per role. The roles `source`, `model`, `config` and `prompt` are required. Other lowercase
  roles are allowed, once each. A path is relative to the manifest's folder, or to `--root`.
- **budgets** belong to the operator. `null` means the operator has not set the budget. Until the WER and
  naturalness budgets are set, every real manifest is refused (`budget_unset`).

## What the check refuses

The check re-reads every artifact's bytes and refuses the manifest when one of these is true. The receipt names the
code and the field.

| code | when |
|---|---|
| `consent_missing` | no consent record |
| `consent_incomplete` | no `record_id`, `subject`, `granted_on` or scope; an `expires_on` that is not a date |
| `consent_not_yet_granted` / `consent_expired` | the check date is before `granted_on` or after `expires_on` |
| `consent_revoked` | `revoked_on` is set (any date) |
| `consent_scope` | a profile use is outside the consent scope |
| `unknown_use` | a use is outside the vocabulary |
| `artifact_unhashed` | an artifact has no sha256, or the value is not 64 lowercase hex |
| `artifact_path` | the path is absolute, contains `..`, goes through a symlink, or does not name a regular file |
| `artifact_hash_mismatch` | the bytes on disk do not hash to the declared sha256 |
| `artifact_role_missing` / `artifact_role_duplicate` | a required role is missing, or a role occurs twice |
| `seed_missing` | the seed is not an integer |
| `id_missing` / `id_mismatch` | no `profile_id`, or it is not the id derived from the inputs |
| `budget_missing` | a budget field is absent (it must be present, even as `null`) |
| `budget_unset` | a budget is `null`: the detail says the operator has not set the budget |
| `budget_owner` | a budget is set but `set_by` is not the operator (`BUDGET_OWNER` in the checker): the same detail |
| `budget_invalid` | a budget is not a non-negative number |

Also: `schema_mismatch`, `profile_incomplete`, `inputs_missing` and `artifact_invalid` for a malformed manifest.

## The identity

`profile_id` is `vp1-` plus the first 24 hex characters of the sha256 of a canonical JSON object: the schema, the
persona, the seed and the sorted `[role, sha256]` pairs (sorted keys, no spaces, ASCII). So:

- the same inputs always give the same id, whatever the order of the artifacts, their paths or the label;
- any change to the source, model, config, prompt, seed or persona gives a new id;
- consent is not part of the id. Revocation makes the candidate unavailable but keeps its id. Old receipts keep the
  id they recorded.

`derive-id` prints the id for a new manifest. The id is a machine reference: a voice never reads it.

## The receipt

```json
{"schema": "voice-profile-check.v1", "manifest_schema": "voice-profile-manifest.v1", "verdict": "refuse",
 "profile_id": "vp1-...", "as_of": "2026-10-25", "artifacts_checked": 4,
 "refusals": [{"code": "budget_unset", "field": "budgets.wer_regression_max", "detail": "budget not set by <operator>"}]}
```

The receipt has these seven keys only. Each refusal has `code`, `field` and `detail` only. The receipt never holds an
artifact path, a hash, the consent subject or any content bytes (audio, transcript or vector). `check` exits 0 for
admit, 1 for refuse and 2 for a manifest that cannot be read.

