1.0 RC compatibility freeze inventory (JOE-1896)¶
Document version: 1.0
Freeze anchor package version: 0.0.16 (this cut begins the RC inventory)
Parent epic: JOE-1655
This inventory names the public surfaces frozen for a 1.0 RC interval. Pre-1.0 0.0.x still allows additive patches; removing or renaming a frozen item during RC resets the freeze clock (see § Breaking-change policy).
See also compatibility.md for 0.0.x classes.
Frozen surfaces (RC)¶
CLI / exit categories¶
| Item | Freeze rule | Evidence |
|---|---|---|
Primary commands: transcribe, tts, doctor, cache, models, cleanup (as shipped) | No remove/rename without freeze reset | docs/reference/cli-help.md, CLI help tests |
Exit codes from ErrorCategory::exit_code mapping | Numeric categories 1–7 stable | crates/aurum-core/src/error.rs + unit tests |
| Offline doctor / cache verify | Must remain fail-closed, no surprise network | doctor / cache tests |
Config¶
| Item | Freeze rule | Evidence |
|---|---|---|
Config load path + validate / ValidatedConfig | No silent renames of keys required for local STT/TTS | config unit tests |
| Secret redaction in diagnostics | Always-on | secret + config diagnostic tests |
| OpenRouter keys only via env/config (never logs) | Stable | credential hygiene docs |
JSON DTO schemas¶
| DTO | schema_version | Freeze rule |
|---|---|---|
SttResultDto | 1 | Unsupported version → error; unknown fields ignored on read |
TtsMetaDto | 1 | Same |
ErrorDto | 1 | Category string ids stable (ErrorCategory::as_str) |
Constants: STT_RESULT_SCHEMA_VERSION, TTS_META_SCHEMA_VERSION, ERROR_SCHEMA_VERSION in aurum-core dto module.
C ABI (FFI)¶
| Item | Value | Freeze rule |
|---|---|---|
AURUM_ABI_VERSION | 2 | Breaking C changes bump version + header |
AURUM_ABI_MIN_VERSION | 1 | Keep v1 blocking surface binary-compatible when practical |
AURUM_SAMPLE_RATE | 16000 | PCM contract |
| Jobs / cleanup / doctor / capabilities | Present in ABI v2 | Additive status codes preferred |
Evidence: crates/aurum-ffi/tests/abi_layout.rs, include/aurum.h.
Cache / manifests¶
| Item | Freeze rule |
|---|---|
| STT pin identity = filename + SHA-256 + exact size | Trusted catalogue only |
| Cache layout under user cache dir | Documented; quarantine on verify failure |
| TTS pack digests / trust modes | builtin / verified / local_unverified semantics |
Model / voice IDs (defaults)¶
| Surface | Default / pin policy |
|---|---|
| Local STT catalogue | Reviewed ggml-*.bin pins in model::pinned_sha256 |
| Default TTS catalogue id | Built-in kitten catalogue (DEFAULT_TTS_MODEL) |
| Custom/BYOM ids | Must not shadow built-in catalogue when tts feature on |
Breaking-change policy (RC)¶
- Additive only during RC: new flags with defaults, new optional DTO fields, new ABI status codes.
- Breaking = remove/rename public Rust/C/CLI/DTO fields, change exit category numbers, change schema_version without dual-read, change default model ids silently.
- A breaking change resets RC: re-cut RC branch, re-run dogfood (rc-dogfood.md), update this inventory’s freeze anchor version.
- Prefer one deprecation release before removal when practical (compatibility.md).
Automated freeze checks¶
Runs ABI constant tests, DTO schema_version unit tests, model pin catalogue guard, and mutation_semantics kill list. Wired into CI as job rc-freeze-check.