standard_asr.engine

Enforce definition-time invariants: secret annotations, flat aliases.

Definition-time guards, so a credential leak or an unclassifiable construction failure can never reach runtime:

0. The input surface stays CLOSED, at every depth. The config itself must keep extra="forbid" (BaseConfig's default; allow stores undeclared caller data and emits it from public_dump, ignore silently drops a mistyped key), and every nested input container its schema reaches -- a submodel, a TypedDict, a pydantic dataclass -- must forbid undeclared keys too: pydantic's default for all three silently DROPS them, so a typo'd nested option reads as applied while the engine runs on the field's default.
1. A field marked secret=True (via secret_field) must resolve to exactly ONE masking carrier (_secret_carrier): SecretStr or SecretBytes, optionally unioned with None and nothing else. A plain annotation (str | None) or a plaintext union member (SecretStr | int) would be hidden from REST/auto-UI while leaking plaintext in repr/str/ model_dump/public_dump; two carriers make raw-string wrapping ambiguous; a container of secrets (for example, list[SecretStr]) is only half-protected. 1b. The field's DEFAULT must uphold the same contract (pydantic does not validate defaults): required, None (only when the annotation admits it), or an instance of the carrier itself. A plain-string default would live on instances as raw str -- plaintext repr/model_dump and a crash in model_dump_json/public_dump. A default_factory is rejected outright (it runs at construction, unvetted by this guard).
2. A secret marker on a field of a nested submodel (the standard encourages per-model-family submodels) is rejected outright. The secret pipeline -- the enforcement here, the whitespace-preserving validator, and public_dump's masking -- only operates on a BaseConfig's own scalar fields, so a secret nested one level down is silently unprotected and leaks plaintext through public_dump / repr / model_dump. Credentials MUST therefore be modeled as top-level scalar SecretStr fields on the config, not buried in a submodel.
3. A non-string validation alias -- AliasPath, or an AliasChoices carrying one -- is rejected. The whole config surface is built on FLAT single-token field resolution: the env convention maps one STANDARD_ASR_<ENGINE>__<FIELD> variable to one field name (spec IC.4), and the absent-vs-invalid classifier behind ConfigurationRequiredError resolves each error loc back to a single string token. A path alias populates a field from NESTED input, which neither surface can express -- pre-guard it produced an environment-dependent compliance verdict (pure absence misclassified as a plugin defect). An AliasChoices of plain strings is fine: each choice resolves like a string alias.
4. The flat input-key vocabulary is UNIQUE across fields: a field's alias (or AliasChoices choice) colliding with another field's name or alias would let one caller key silently populate two independent settings (populate_by_name fills both) and makes loc-token resolution ambiguous. Every key has exactly one owning field.
5. The config's serialization surface is CLOSED: author-defined serialization hooks -- @computed_field, @model_serializer, @field_serializer (declared here or inherited), and PlainSerializer/WrapSerializer metadata on a field -- are rejected outright. They run INSIDE model_dump, that is, inside public_dump's "masked" serialization, where they can rematerialize a sibling secret in plaintext (a computed authorization property, a field_serializer reading self.api_key) under keys the by-name mask never touches -- and they break the dump-is-the-declared-input-surface contract (G1.3/G3.1: auto-UI renders model_fields; extra="forbid" rejects a computed key on reload). Derived values belong on a plain @property or in the engine, never in the dump.
6. A field whose annotation contains a secret CARRIER (SecretStr/SecretBytes, anywhere in it) must carry the secret MARKER: an unmarked carrier is half-protected -- pydantic masks its dumps, but the whitespace-preserving validator skips it (the raw string input is silently stripped: a padded credential is rewritten with no diagnostic), and the schema never renders it as a password/write-only input.
7. The security-owned serialization methods keep their IDENTITY: public_dump / reveal_dump (owned here) and model_dump / model_dump_json / __iter__ (owned by BaseModel) MUST NOT be overridden -- directly or through a mixin / intermediate base. Guard 5 closes the serializer SCHEMA, but an ordinary Python override of these is the same customization one DISPATCH entry over: it never enters the decorator registry or the core schema, yet it runs inside public_dump and can rematerialize a sibling secret under a key the by-name mask never touches. Resolved statically over the MRO; the runtime dumps also call the base implementations unbound (defense in depth). See _reject_security_method_override.

Validate a JSON document against this config (python-mode delegation).

Overridden because pydantic's native JSON pipeline is incompatible with the whitespace-preserving secret wrap: the wrap replaces a raw secret string with its carrier INSTANCE (SecretStr), which JSON-mode field validation rejects outright (its secret schema accepts only the JSON string form) -- so model_validate_json failed for EVERY config document carrying a secret value. Skipping the wrap in JSON mode is not an option either: str_strip_whitespace applies in JSON mode too, so the padded credential would be silently trimmed -- the exact rewrite the wrap exists to prevent. The one path that preserves both contracts is to parse the document and validate the resulting mapping in python mode, where the wrap is defined.

Grammar parity holds because json.loads and pydantic's parser accept the same token set for the config value space (both accept NaN/Infinity tokens; field validation then treats the resulting float identically on both routes -- pinned by test). A document json.loads rejects is delegated to pydantic's own JSON parser so the canonical json_invalid error surfaces; that delegation is REQUIRED to raise -- if the parsers ever diverged and pydantic accepted such a document, its JSON field pipeline would run without the wrap (the silent trim again), so a delegation that returns is refused outright (fail closed) rather than handed back.

Validate string-valued data against this config (env-grammar delegation).

Overridden for the same reason as model_validate_json: pydantic's native strings pipeline is incompatible with the whitespace-preserving secret wrap -- the wrap replaces a raw secret string with its carrier INSTANCE (SecretStr), which strings-mode field validation rejects (its secret schema accepts only the string form) -- so model_validate_strings failed for EVERY config supplying a secret value, blaming the caller's own credential field for a wrong type it never passed. Skipping the wrap is not an option either: str_strip_whitespace applies in strings mode too, so the padded credential would be silently trimmed.

The string grammar is the config surface's OWN, shared with from_env / env_overrides rather than pydantic's strings mode: a scalar field takes the raw string (python-mode lax coercion handles "4" / "true"), a STRUCTURED field (list / mapping / submodel -- the fields _ENV_CODECS marks "json") takes a JSON document, and on a JSON error the raw string is kept so construction still fails loudly. One grammar for every string-valued source (env vars, CLI key=value pairs, query params), not two subtly different ones.

Return a serialization with secrets masked (the default path).

This is the masked half of the secret-serialization contract and is the serialization to use for /v1/models, persistence, and telemetry. SecretStr / SecretBytes fields are rendered as SECRET_MASK (never plaintext). As a defensive measure, any secret-marked field is masked by name, so even a value that (hypothetically) slipped through as plaintext is never emitted. The default pydantic serializers (model_dump / model_dump_json) likewise mask the secret carriers; use reveal_dump only when plaintext is genuinely required in-process.

Trusting model_dump here rests on the definition-time guards that reject the authored serializer shapes -- the three serializer decorators, Annotated serializer metadata, nested credential carriers, fields excluded from the dump (Guards 5/5c/6) -- so the dump contains the declared input fields, serialized by pydantic's own machinery. Per the trust model (AGENTS.md) this is an enumeration, not a proof: the channels only a core-schema prover could see (SerializeAsAny, a custom __get_pydantic_core_schema__) require an author actively smuggling a credential past the mask -- an adversary, out of scope.

The guards bound what the schema installs in the dump, not the CONTENTS of the values author code constructed. Config code that copies a secret out of its carrier into non-secret state -- an after-validator writing self.api_key.get_secret_value() into a declared str field, or onto display state a trusted serializer renders by builtin dispatch (a validator-returned Path SUBCLASS whose __str__ embeds the credential; pydantic's own audited ser_path calls str() on the runtime value) -- emits that plaintext here, and no serialization mechanism can prevent it: both shapes are the same author act, and the leaking value passes every type or dispatch audit (a plain str whose content nothing can classify as secret). The value-level envelope is and remains the carrier contract (IC.3): credentials live in secret-marked SecretStr/SecretBytes fields, are masked here by name, and MUST NOT be copied out of the carrier into any other field or object state. The boundary is pinned executable in test_secret_extraction_is_the_closure_boundary; moving it means updating this contract, the spec, and that test together.

Return a serialization with secrets materialized as plaintext.

This is the reveal half of the secret-serialization contract: the explicit, named counterpart to public_dump. Use it only for in-process calls into an engine SDK that needs the raw credential (for example, an Authorization header). The result contains plaintext secrets and MUST NEVER be logged, persisted, sent to /v1/models, or emitted as telemetry -- those paths use public_dump.

SecretStr / SecretBytes fields are unwrapped via get_secret_value(); all other fields keep their Python values (no JSON coercion), so a credential is returned as the engine SDK expects it.

Construct a config, filling unset fields from the environment.

Applies the normative priority explicit > env > (required-missing error): each field that is not supplied in explicit under any of its flat input keys (canonical name, string alias/ validation_alias, or an AliasChoices choice -- the _flat_input_keys vocabulary) is filled from its STANDARD_ASR_<NORMENGINE>__<NORMFIELD> environment variable (collision detected), and the merged mapping is then passed to the constructor. Alias-awareness is what makes "explicit wins" true for aliased fields: a caller passing apiKey=... suppresses the api_key env fallback instead of colliding with it under extra="forbid". Because construction does the field coercion, SecretStr credentials are wrapped (and so masked in repr/str/public_dump) instead of being handed around as raw plaintext -- avoiding the leak footgun of passing a plaintext {field: secret} dict through application code.

Note on explicit None: "absent" means the key is not present in explicit, not "present with value None". A key passed explicitly as None is a value and wins over env (priority is "explicit wins", not "explicit-non-None wins"). A wrapper that forwards optional kwargs with None defaults therefore disables the env fallback for those fields; drop None keys before calling ({k: v for k, v in kwargs if v is not None}) if env fallback should apply.

The engine discriminator is never read from the environment; it is the entrypoint-derived identity and defaults on each engine's subclass. The strict safety policy is likewise excluded so the environment can never silently downgrade fail-loud to best_effort (see _ENV_EXCLUDED_FIELDS).

Collect config overrides from environment variables.

Only fields absent from explicit config should be filled from these; the caller applies priority (explicit > env). Collisions (two fields normalizing to the same env var) are rejected.

Security note: the returned dict holds raw plaintext values, including any credential fields, because SecretStr wrapping happens only at construction. Prefer from_env, which merges and constructs in one step (so secrets are wrapped/masked); treat the dict returned here as sensitive and never log it.

Return whether the capability at dot_path is supported.

The only standard way to query capabilities. Walks the tree segment by segment; any missing segment returns False (fail-closed). Resolving a present mode-domain or container also returns True.

Return the typed capability node at dot_path, or None.

Unlike supports (which returns a bool), this returns the leaf node object itself so callers can inspect its constraints / enums (for example, a WordTimestampsCap to validate a requested granularity against WordTimestampsCap.granularities). Returns None if the path is absent or does not resolve to a capability leaf node.

Yield every dot-path in the tree whose node is supported.

Only the children of a supported typed node are descended into, so an unsupported feature's constraint sub-containers (which are always present, never None) do not appear. A raw x_* dict subtree is walked unconditionally (see _iter_paths) so nested explicit vendor capabilities stay discoverable. Used to verify the effective ⊆ declared invariant.

Yield the dot-path of every NODE in the tree -- supported or not.

The node set is pinned by the two-layer isomorphism: exactly the paths at which canonical_json renders a JSON object and at which supports resolves a model/dict -- capability leaves, containers, constraint submodels, and x_* extension subtrees (typed or raw-dict; model extras pass the same x_* gate as every other traversal, so a non-extension unknown key is not a node). Scalar field values (a supported bool, a mode token, a granularities list) are field internals, not nodes: neither yielded nor descended. None children (an absent mode domain, a constraints=None) are skipped.

Unlike iter_supported_paths (the supported-only view behind effective ⊆ declared), UNSUPPORTED nodes are yielded and descended, so a consumer can verify the fail-closed False answers too -- for example, an unsupported feature's constraints submodel MUST probe False. The compliance suite sweeps this set to assert a hand-written supports() agrees with the tree on every node.

Return whether other is a valid narrowing of this tree.

Enforces the normative effective ⊆ declared invariant: the effective set may only close declared capabilities, never widen them. This checks two things:

• Set containment -- every supported path in other is also supported here (no feature is enabled that this tree did not declare).
• Constraint narrowing -- where both trees support a bounded or enum/mode node, other's limits MUST be no looser than this tree's (for example, a smaller-or-equal max, a subset of granularities, a mode that is the same or a reduction). A widening (declared max=2 -> effective max=999) is rejected.

Serialize to canonical JSON with a derived supported at every node.

Cross-language clients read capabilities from this JSON. Flag and bounded nodes carry supported as a real field, but enum/mode nodes derive it from mode (a Python property, absent from model_dump). This method injects the uniform boolean at every capability node and present container so a client never has to special-case archetypes or know the "none"/"unsupported" sentinels (enum/mode nodes' supported is server-injected). The root object itself carries no supported key (it is the container of all modes, not a capability); an absent mode domain serializes as null (fail-closed).

Return whether a capability is supported at runtime (fail-closed).

Warm up the engine (download / load weights) without transcribing.

The optional, synchronous, idempotent pre-warm hook, invoked by standard-asr prepare and by production / CI pre-warming to move the lazy side effects (weight download / model load) off the first transcription to one billing-free, transcription-free call. The base implementation is a no-op: an engine with nothing to warm up inherits it unchanged and the toolchain reports a no-op rather than failing.

Engines that load weights MUST override this to materialize them (for example, call _ensure_model_loaded), and that path MUST honor the same download gate as transcription: check allow_downloads and raise DiscoveryError when downloads are disabled and weights are missing. An override MUST remain a zero-argument synchronous method -- never an async def (a coroutine function would be called but never awaited, silently reporting a false success); the compliance suite and the CLI reject a coroutine prepare.

Transcribe a complete audio input (template method).

Runs the standard pipeline, fail-fast first: validate the language config -> gate parameters (provider_params + capability gating, which needs no audio) -> resolve & validate the effective language axis -> coerce -> negotiate -> convert/resample -> call the engine -> synthesize missing segment speakers from word speakers (the pinned synthesis rule) -> attach diagnostics.

Parameter validation runs before the (potentially expensive) audio decode/resample so a swapped-engine provider_params bug or an unsupported parameter is rejected before any audio is touched (fail fast on provider_params first).

Asynchronously transcribe (default: run transcribe in a thread).

Enforce the audio_format / audio mutual-exclusion.

audio_format (incremental PCM feeding) and audio (whole-input streaming output) are mutually exclusive; passing both MUST raise. This shared guard lets every streaming engine enforce the rule with one call instead of reimplementing it; the base start_transcription invokes it before raising the unsupported-streaming error.

Validate a declared streaming wire format at session establishment.

Shared session-establishment guard for streaming engines: call it first (like ensure_stream_inputs_exclusive) when opening a audio_format=... session. It is fail-closed on the wire sample rate and the channel count unconditionally, and on the wire encoding when wire_encodings is declared.

Wire encoding: when the engine declares wire_encodings, an encoding not among them is rejected up front rather than misframed as PCM and silently mistranscribed. When wire_encodings is None ("unconstrained") the encoding cannot be validated and the check is skipped -- the engine is then trusted to accept any encoding (typically a self-managed-wire-format engine). The compliance suite emits a warning for a streaming_input engine that leaves wire_encodings unset, since that skip is where a forgotten declaration would let a non-PCM frame be misframed.

Wire sample rate: the standard's v1 implementation note is explicit that v1 does NOT resample streaming bare frames in the standard layer (unlike the batch transcribe path, which resamples). Therefore, until standard-layer streaming resampling lands, a wire sample_rate that the engine does not accept MUST be rejected here rather than forwarded as frames the engine never declared -- a loud error beats a silent mistranscription. When required_input_sample_rate is set, the wire rate MUST equal it -- even when accepted_sample_rates is "any" (that combination is constructible; the declaration-time reachability validator only checks concrete lists). Otherwise the rate is accepted when accepted_sample_rates is "any" or when it is in that concrete list.

Return a minimal wire AudioFormat to open a streaming session.

Single source of truth for the legal bare-frame wire format the standard layer uses when it must open a streaming_input session but has no application-chosen format -- the CLI sync-bridge runner and the streaming gating probe both rely on it. They previously derived one independently and disagreed (which sample-rate source to use, and what to do with no declared wire_encodings); this unifies them. The format is built from the engine's own Properties so ensure_stream_format_supported accepts it (the compliance suite asserts that round-trip):

• sample_rate = required_input_sample_rate when the engine hard-requires one, else native_sample_rate (the reachability invariant guarantees the native rate is accepted).
• encoding = the first declared wire_encodings entry, else the canonical pcm_s16le (used only when wire_encodings is unconstrained, where the engine accepts any encoding).
• channels = 1 (v1 streaming wire is mono-only).

The derivation is deliberately capability-blind (Properties only): whether a bare-frame session can be opened at all is decided by the streaming_input gate in start_transcription, not here -- so the recommendation stays a pure, class-level static fact and the compliance round-trip (format ⊆ ensure_stream_format_supported) holds for every engine, streaming or not.

Open a streaming transcription session (template method).

Symmetric to transcribe: the base runs the standard streaming pipeline and delegates only the engine-specific session construction to _start_transcription. The pipeline enforces input mutual-exclusion, validates the language config, validates the wire format, gates parameters against the streaming capabilities, resolves the language axis, prepares whole-input audio through the standard audio pipeline, and attaches the resulting diagnostics to the session.

Because gating now runs here, provider_params swap-safety is enforced on the streaming path too: a swapped-engine provider_params type-mismatch always raises InvalidProviderParamError (no longer undefined behavior), and an unsupported standard parameter is rejected (strict) or dropped + diagnosed (best_effort) exactly as for batch.

The streaming input/output capability axis is checked before the hook override defense, so an engine that implements the hook but does not declare the requested session mode fails on the missing capability rather than reaching parameter or audio gating. The hook override defense still runs before parameter gating, so a batch-only engine reports "does not support streaming" rather than a confusing parameter error -- while still running the input mutual-exclusion guard first, exactly as before.

Streaming param freeze: the already-gated, frozen RuntimeParams is handed to the hook as gated_params; the engine uses that for the whole session and MUST NOT re-accept raw params mid-stream.

Return whether rate falls within the inclusive range.

Transcribe a complete audio input.

Asynchronously transcribe a complete audio input.

Open a streaming transcription session.

Always present on a compliant engine, but streaming itself is optional: a batch-only engine raises UnsupportedFeatureError here. Callers that need streaming should gate on supports("streaming_input") / supports("streaming_output") (or be ready to handle the unsupported-streaming error).

Return whether the capability at dot_path is supported.

Return a wire AudioFormat this engine accepts for streaming.

Part of the protocol because it is the documented first step of the streaming journey (README / quickstart / streaming guide all start with it) and the toolchain's sync-bridge runner and gating probes rely on it -- a member every caller is taught to invoke MUST be part of the contract, or a structural engine (and every StandardASR-typed variable) breaks on the standard's own 80% path. The value is purely derivable from the engine's static Properties (see EngineBase.recommended_wire_format for the derivation EngineBase provides for free) -- deliberately capability-blind: whether a bare-frame session can be OPENED is the streaming_input capability gate's job inside start_transcription, so a batch-only or output-only engine still derives a format here (callers gate on supports("streaming_input") first, per the streaming guide).

Build a partial event.

Build a final event.

Build a closed finality event (a final with finality=closed).

Build a supersede event replacing old segments with new ones.

Lineage is set-to-set: old_ids/new_ids express the cardinality of the re-segmentation (which ids retire, which appear) but not a per-old->per-new mapping. On a merge+split (many->many) a UI cannot tell which specific old segment a given new segment descends from. This is a documented v1 limitation; the spec does not require a pairwise mapping, and the frozen-prefix-preservation invariant is enforced over the concatenated prefixes, not per pair. Per-pair edit-ops/diffs are a possible future direction (additive later).

Build a progress event (heartbeat / cursor / reconnect notice).

Build a terminal done event.

Build an error event.

Async-iterate fed audio chunks until the input ends.

Each yielded chunk is also retained in the bounded rolling audio buffer for possible replay after a reconnect.

Consuming from this iterator is the session's liveness anchor: every dequeue resets the done_timeout backstop, so an engine that legitimately emits no events during user silence stays alive for as long as it keeps reading audio here.

Surface a structured diagnostic from _produce (the streaming channel).

The streaming counterpart of the batch path's result.diagnostics: call this from your _produce to report a non-fatal note -- a best-effort degradation, an assumed parameter, a lossy fallback -- through the session's own diagnostics channel, so a WS client (mid-stream diagnostics frame) or a sync caller (diagnostics()) sees WHY. For a fatal condition, emit an error event instead -- this is for non-fatal notes that must not end the stream.

Recorded through the same bounded channel as the guard's own diagnostics: past the cap entries aggregate into the overflow summary rather than growing without bound, so a chatty producer cannot exhaust memory.

Security -- this is engine-authored, client-facing output, like the transcript text itself. Every field (message / param / provided / effective) is forwarded to clients VERBATIM -- to a (possibly unauthenticated) WebSocket client as a diagnostics frame, and, for the batch counterpart result.diagnostics, in the REST response -- and is NOT redacted. The standard layer scrubs only the detail IT auto-captures (an error event's extra, which holds a scrubbed exception summary -- never a raw str(exc)); content you pass here is your contract to keep. NEVER pass a credential, API key, a URL with embedded auth, or raw exception text -- route sensitive operator detail to logging instead. (That asymmetry is deliberate: an error event's extra is auto-captured so the server drops it; this note you chose, so you own its safety.)

Return audio for re-feeding to a freshly re-established connection.

Engines call this on reconnect to re-send audio. For a replayable (list / tuple) source the COMPLETE source is returned -- replayability promises loss-free replay, so it must not be silently truncated to the rolling ring. For a non-replayable / live source only the bounded rolling window of recent chunks is available (older audio was evicted).

Record that an internal reconnect bridged a gap (engine-driven).

The base ALWAYS emits a progress(reconnect=True, gap_start, gap_end) event in order with produced events, followed -- IMMEDIATELY -- by a trailing error(code="content_lost", recoverable=True, gap_start, gap_end) IFF the engine passes content_lost=True.

The events are flushed promptly, the moment this is called, through the drop-proof path (_CoalescingBuffer.put_forced, the same sync primitive the base uses for synthesized terminals). This matters because an engine typically calls note_reconnect and then BLOCKS while it re-establishes the connection without yielding another event; deferring the flush to the next produced event would leave the consumer staring at a timeout/silence during a slow reconnect -- the opposite of "transparent but honest". note_reconnect runs in the producer-task coroutine on the session loop, so a synchronous flush is correct and ordered (the events land after already-emitted events and before any subsequent one). The _run_producer / finally drains remain as a harmless safety net -- they simply find nothing pending.

Content loss is an explicit engine determination, not something the base infers from rolling-buffer eviction: a live ring is always evicting, so eviction is the wrong signal (it would falsely claim permanent loss on every long live session). The engine -- which alone knows whether its reconnect + replay_buffer replay actually covered the gap -- sets content_lost=True only when audio the engine had not yet processed could not be replayed and is therefore truly lost. This mirrors the existing contract where segment_id / timestamps / detected language / speaker-label mapping continuity across the reconnect is likewise the engine's responsibility (the base never rewrites them). For speaker labels the engine MUST NOT reuse a pre-reconnect label without identity evidence; the safe default is to mint fresh labels and emit a speaker_labels_reset diagnostic via emit_diagnostic (the fidelity-warning counterpart of the content_lost error event).

Feed audio from a managed source (mutually exclusive with manual).

A bare bytes / bytearray is treated as a single audio chunk (not an iterable of chunks -- iterating it would yield int byte values). A non-async, re-iterable collection (list / tuple, or a wrapped bytes-like) is classified as replayable for reconnect purposes; an async source or a one-shot generator/iterator is non-replayable. Any AsyncIterable (the Pythonic __aiter__ protocol, not only the stricter AsyncIterator) is accepted and normalized via aiter.

Manually send one audio chunk (mutually exclusive with feed).

Manual sources are always treated as non-replayable (live input).

Mark the end of manual audio input (idempotent in manual mode).

Claims manual ownership if this is the first input call, so a later feed is correctly rejected as mixing.

Open resources and start the producer.

Anchors the max_session_seconds wall-clock origin here, at session establishment, so the absolute cap measures from when the session opened -- not from the first __anext__ -- and a re-entered iterator cannot reset it.

Tear down the producer, feed task, and engine resources.

Cancels the producer and feed tasks and AWAITS them (so no coroutine is still touching engine state when _close runs), then closes.

Return the event async iterator (single-consumer).

A session has exactly ONE event stream and exactly ONE consumer: the events live in a shared bounded buffer, and a second concurrent iterator would race the first for _CoalescingBuffer.get, silently splitting the stream between them (each iterator would see an arbitrary subset, so neither's result would match the stream -- breaking the stream == result invariant). Re-iterating would also reset the per-iteration deadline anchors. Both are programming errors, so the second call fails loudly instead of returning a competing iterator.

Return the diagnostics accumulated for this session so far.

The lifecycle-suppression channel is bounded: a misbehaving engine that trips a clamp on (nearly) every event cannot grow this list without limit over a long session. Once DEFAULT_MAX_GUARD_DIAGNOSTICS entries accumulate, further suppressions are aggregated into a single trailing diagnostics_truncated summary (per-code counts) instead of being retained individually -- so the overflow is reported honestly, never silently dropped.

Reduce the session so far into a transcription result.