P1 — define provider-neutral transcript normalization contract and raw/normalized runtime semantics #219

New issue

Closed

opened 2026-08-28 03:23:53 +00:00 by nsaspy · 1 comment

nsaspy commented

2026-08-28 03:23:53 +00:00

Owner

Parent: #215
Integrates with: #25, #82/#83, #122, #132

Goal

Create one provider-neutral post-STT normalization boundary so Zara can select transcript cleanup independently of the STT provider.

Required contract

Design and implement a small typed interface for final-transcript normalization with:

identity/off backend;
backend registry/selection without coordinator if/elif growth;
input: final accepted raw transcript + language/turn/trace metadata needed for policy;
output: normalized text + backend/model/version/status metadata;
explicit success, unavailable, unsupported-language, timeout, cancelled and invalid-output states;
bounded input/output sizes and deadlines;
deterministic fallback policy owned above the provider;
cancellation/stale-turn fencing;
no provider-specific object leakage.

Runtime semantics

Introduce explicit raw-vs-normalized provenance. The runtime must be able to distinguish:

raw_transcript
normalized_transcript
normalization_status

Partial transcript events remain raw. Normalization runs only after a final transcript is accepted.

The normalized text is the candidate utterance for later routing. If #122 is enabled, #122 runs after this stage.

Do not persist duplicate raw+normalized user messages as two conversation turns. Research/define which form is durable for ordinary conversation history while keeping raw evidence available only where privacy/test policy permits.

Invariants

normalizer cannot execute tools/actions;
output is still untrusted user text;
principal/session/conversation/turn ownership is preserved;
a cancelled/stale normalization result cannot mutate a newer turn;
ordinary metrics/security audit contain metadata/timing, not transcript bodies;
identity backend produces byte-for-byte input text except for explicitly documented transport encoding normalization.

TDD

Write failing tests first for identity backend, provider registration/selection, raw/normalized event semantics, cancellation, stale result rejection, timeout, oversized input/output, empty/malformed result and fallback policy.

Add one focused non-interactive script and compose its deterministic subset into the full repo/Nix gate.

Acceptance

Zara has one stable post-STT normalization seam with an off backend, exact raw/normalized semantics, and no S1-mini-specific branching in the voice coordinator.

Parent: #215 Integrates with: #25, #82/#83, #122, #132 ## Goal Create one provider-neutral post-STT normalization boundary so Zara can select transcript cleanup independently of the STT provider. ## Required contract Design and implement a small typed interface for final-transcript normalization with: - identity/`off` backend; - backend registry/selection without coordinator `if/elif` growth; - input: final accepted raw transcript + language/turn/trace metadata needed for policy; - output: normalized text + backend/model/version/status metadata; - explicit success, unavailable, unsupported-language, timeout, cancelled and invalid-output states; - bounded input/output sizes and deadlines; - deterministic fallback policy owned above the provider; - cancellation/stale-turn fencing; - no provider-specific object leakage. ## Runtime semantics Introduce explicit raw-vs-normalized provenance. The runtime must be able to distinguish: ```text raw_transcript normalized_transcript normalization_status ``` Partial transcript events remain raw. Normalization runs only after a final transcript is accepted. The normalized text is the candidate utterance for later routing. If #122 is enabled, #122 runs **after** this stage. Do not persist duplicate raw+normalized user messages as two conversation turns. Research/define which form is durable for ordinary conversation history while keeping raw evidence available only where privacy/test policy permits. ## Invariants - normalizer cannot execute tools/actions; - output is still untrusted user text; - principal/session/conversation/turn ownership is preserved; - a cancelled/stale normalization result cannot mutate a newer turn; - ordinary metrics/security audit contain metadata/timing, not transcript bodies; - identity backend produces byte-for-byte input text except for explicitly documented transport encoding normalization. ## TDD Write failing tests first for identity backend, provider registration/selection, raw/normalized event semantics, cancellation, stale result rejection, timeout, oversized input/output, empty/malformed result and fallback policy. Add one focused non-interactive script and compose its deterministic subset into the full repo/Nix gate. ## Acceptance Zara has one stable post-STT normalization seam with an `off` backend, exact raw/normalized semantics, and no S1-mini-specific branching in the voice coordinator.

nsaspy referenced this issue

2026-08-28 03:24:19 +00:00

[EPIC] Selectable post-STT transcript normalization backends, including local S1-mini #220

nsaspy referenced this issue

2026-09-08 02:03:28 +00:00

P0 — harden the bounded utterance rewriter on the current Prolog-RLM direct-mode path #122

nsaspy closed this issue

2026-09-08 02:03:30 +00:00

nsaspy referenced this issue

2026-09-08 02:03:39 +00:00

P1 — make voice conversation mode create durable chats and auto-finalize title/summary #358

nsaspy commented

2026-09-08 02:12:04 +00:00

Author

Owner

Core r1 is now draft PR #466 from exact canonical 2f4bd28a9428a117f986f06b025d1a35abf5124a, head 5a4e8dfa95ebc1872bfd7394330afeb3d7996296. Tests were committed first (4a18df2a...) before the implementation module. The slice adds the provider-neutral final-transcript contract, byte-preserving off backend, typed status taxonomy, input/output bounds, provider registry, stale-turn fencing before/after inference, and explicit caller-owned raw/fail-turn policy. Zero android/**; #219 remains the integration owner after accepted final STT and before routing/dictation. Exact-head CI #1652 is authoritative and running.

Core r1 is now draft PR #466 from exact canonical `2f4bd28a9428a117f986f06b025d1a35abf5124a`, head `5a4e8dfa95ebc1872bfd7394330afeb3d7996296`. Tests were committed first (`4a18df2a...`) before the implementation module. The slice adds the provider-neutral final-transcript contract, byte-preserving `off` backend, typed status taxonomy, input/output bounds, provider registry, stale-turn fencing before/after inference, and explicit caller-owned raw/fail-turn policy. Zero `android/**`; #219 remains the integration owner after accepted final STT and before routing/dictation. Exact-head CI #1652 is authoritative and running.