feat(dart): add streaming transcription provider contract

[Pushkraj-Space]

Summary

Issue #7 needs a provider-neutral streaming transcription boundary that works with audio from any Murmur connector. It must not expose a vendor SDK, and it needs a deterministic fake provider for coordinator tests. This PR supplies the provider seam for the capture coordinator (#36).

This change:

• adds VoiceProvider, ProviderSession, ProviderSessionRequest, ProviderCapability, and a sealed ProviderEvent family to murmur_protocol
• specifies ordering, accumulation, and revision for partial, final, and rejected transcripts
• separates graceful finalize from the hard-cancel stop, with a state matrix for every operation after start, finalize, stop, or failure
• declares optional capabilities instead of requiring adapters to simulate them
• documents failures, rate limits, close, reconnect, backpressure, buffering, and the credential boundary in the public dartdoc
• adds a manually driven test-support fake that covers every fault the issue lists
• rewrites the VoiceProvider section of docs/voice-runtime.md and updates the package README and CHANGELOG

Contract

• Creation: createSession(request) is synchronous, performs no I/O, and emits nothing. The caller subscribes to events before start(). An undecodable AudioFormat throws VoiceError(code: "unsupported_format", retryable: false).
• Session metadata: ProviderSessionRequest holds only sessionId and format. It deliberately has no capture mode, VoiceSource, metadata map, or credential field.
• Transcripts: delivery order is the session's total order.
  • A ProviderPartial is the complete, replaceable hypothesis of the open segment, and '' clears it.
  • A ProviderFinal commits the segment. Finals are never revised and include their own separators, so an utterance is the exact concatenation of its finals (CJK and punctuation stay correct). Empty finals are invalid; "nothing said" is zero finals.
  • A ProviderRejected commits and discards the segment and never enters assembly.
  • Text arrives only on events. finalize() and mute() return Future<void>.
• Finalize vs. stop:
  • finalize() closes the gate synchronously, lets accepted audio finish decoding, emits the remaining finals, and then closes. It is single-flight and terminal.
  • stop() closes the gate, discards unaccepted audio, completes every pending operation with cancelled, adds no new events, and never throws. Repeated and concurrent calls share one future.
• Capabilities: immediateMute, warmUnmute (requires immediateMute), realAudioReadiness, amplitude, and rejectedFinals.
  • An uncapable mute/unmute throws UnsupportedError.
  • Adapters must not emit undeclared optional events.
  • Mute, unmute, and finalize are serialized: repeating the pending call shares its future, and a conflicting call throws StateError.
• Failures:
  • A startup failure is reported only by start().
  • A later failure emits one ProviderFailure, followed by stream done, and every pending operation completes with that error.
  • Documented codes are cancelled, unsupported_format, unauthorized, rate_limited (optional retryAfterMs), and provider_disconnected.
  • Sessions never reconnect. A retry is a new session, and finals already emitted stay valid.
• Backpressure and buffering:
  • The caller owns a bounded pre-open pre-roll.
  • At most one addFrame is outstanding, and its future is the backpressure signal.
  • Adapters bound and document their queue. An empty queue always admits a valid frame, and a frame over the documented maximum throws ArgumentError synchronously.
  • Frames offered while muted or finalizing are discarded.
• Credentials: credentials enter only through adapter constructors or factories. They never appear in requests, events, errors, or logs, and the contract performs no logging.

Fake provider

test/support/fake_voice_provider.dart uses no timers and is driven entirely by the test. By default it enforces every rule above.

Issue fault	Control
Delay startup	holdStart, completeStart, failStart
Partial and final chunks	emitPartial, emitFinal (also while mute or finalize is pending)
Finalize late or empty	leave finalize pending, or call completeFinalize() with no finals
Reject a final	rejectFinal
Fail or disconnect	fail(error), disconnect()
Ignore cancellation incorrectly	ignoreCancellation: true (off by default)
Backpressure	holdFrames, releaseFrame

The fake records the terminal state before it notifies listeners, so a synchronous listener that reenters the session sees the ended session. Driver callbacks that arrive after the session ends add nothing.

The fake lives in test support next to the future coordinator tests. No public testing library is published until a second package needs it.

Tests

test/provider_test.dart adds 59 tests in 11 groups:

• values
• request, format, and startup
• partials
• multi-final assembly
• finalization
• duplicate finalize
• cancellation
• late events
• failure and disconnect
• capabilities and the input gate
• backpressure and validity

Together they cover partials, multi-final assembly, finalization, duplicate finalize, cancellation, late events, and failure. They also cover these edge cases:

• stop cancelling a pending start or overtaking a pending finalize
• a held frame that belongs to the flushed tail
• cleanup with no listener or a paused listener
• events queued for a paused listener before a stop
• listeners that reenter the session on failure or on done
• identical terminal futures after stop and after failures

Audit

The first audit found five issues, and all five are fixed:

• failure-listener reentrancy
• reentrant stop() future identity
• terminal finalize() future identity
• missing buffering guarantees in the dartdoc
• invalid late callbacks that threw

For fixes 1–3, I checked that reverting each fix makes its new regression test fail. The re-audit passed with no findings.

Scope

• No changes to spec/proto, conformance fixtures, other language SDKs, connectors, or pubspec.yaml dependencies.
• No vendor SDK.
• Choosing a default hosted provider, transcript persistence, and summaries remain out of scope.
• [Core] Implement the reliable voice capture coordinator #36 (open PR feat(dart): add provider-neutral voice capture coordinator #51) will rebase onto this. It will replace its provisional provider.dart and fake, map start(format) to createSession plus start(), map setInputGate to mute/unmute, and handle ProviderClosed as ProviderFailure plus stream done.

Validation

• make check-dart equivalent in dart:stable (Dart 3.13.3): format clean, analyzer clean, and all 78 tests pass (59 new, 19 existing)
• python3 tool/check_conformance.py: consistent (15 sets, 44 lines)
• git diff --check
• make check-protocol did not run because protoc is not available locally. No proto file changed.

Closes #7

🤖 Generated with Claude Code

[harshsaver]

Thanks, this is a thorough contract and it covers every #7 criterion. Local: dart format/analyze clean, 78/78 tests (59 new). It reuses VoiceError and the snake_case codes from runtime.dart, adds no dependencies, and keeps the fake in test/support. Merging — and agreed with the plan in the description: #51 rebases onto this provider.dart and fake.

Non-blocking follow-ups:

1. docs/voice-runtime.md:163 still says "empty finals are valid outcomes and do not become actions", but ProviderFinal('') now throws and "nothing said" is zero finals. Please reword that bullet so the two sections agree.
2. The endpointing section mentions muted(flushing: false), but mute() (provider.dart:288) always flushes. Either note that stop covers the non-flushing case, or drop that doc line.
3. fake_voice_provider.dart:296 marks the stop-induced cancelled error as retryable: true. Worth one sentence in the contract saying whether cancelled is retryable, so adapters agree.
4. Cross-PR consistency with #56 (graceful finalization as baseline vs. a capability; one error-code registry) — I've asked for that on #56 since it's rebasing anyway.