@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.3

package/src/services/voice/fused-eot-scorer.ts

@@ -0,0 +1,139 @@
+/**
+ * Fused FFI end-of-turn scorer (ABI v11).
+ *
+ * The fused replacement for the retired node-llama-cpp `controlledEvaluate()`
+ * path the EOT classifiers depended on. Computes P(`<end_of_turn>` next | partial
+ * transcript) through the single `libelizainference` handle: tokenize the
+ * Gemma-formatted partial transcript, then one causal forward pass
+ * (`eliza_inference_llm_eot_score`) reads the next-token probability of the
+ * end-of-turn marker. No separate model weights, no sampling loop, and no KV
+ * growth on the chat session — the dedicated native scoring context clears its
+ * KV per call so scores are independent.
+ */
+
+import { formatEotPrompt } from "./eliza1-eot-scorer";
+import type {
+	ElizaInferenceContextHandle,
+	ElizaInferenceFfi,
+} from "./ffi-bindings";
+
+const END_OF_TURN_TOKEN = "<end_of_turn>";
+
+export interface FfiEotScorerOptions {
+	/** The loaded fused inference binding (must expose the v11 EOT symbols). */
+	ffi: ElizaInferenceFfi;
+	/** Resolves the live inference context handle (the loaded text bundle). */
+	getContext: () => ElizaInferenceContextHandle;
+	/** Max prompt tokens kept (tail-truncated). LiveKit's recipe uses 128. */
+	maxHistoryTokens?: number;
+	/** Model label for telemetry. */
+	modelLabel?: string;
+}
+
+export interface FfiEotScoreResult {
+	/** Probability of `<end_of_turn>` as the next token, ∈ [0, 1]. */
+	probability: number;
+	/** Wall-clock model latency for this scoring call. */
+	latencyMs: number;
+	/** Number of prompt tokens evaluated. */
+	promptTokens: number;
+}
+
+/**
+ * Stateful EOT scorer bound to a loaded fused text model. The `<end_of_turn>`
+ * token id is resolved once and cached. Safe to keep across many voice turns.
+ */
+export class FfiEotScorer {
+	private readonly ffi: ElizaInferenceFfi;
+	private readonly getContext: () => ElizaInferenceContextHandle;
+	private readonly maxHistoryTokens: number;
+	readonly modelLabel: string;
+	private endOfTurnTokenId: number | null = null;
+
+	constructor(options: FfiEotScorerOptions) {
+		this.ffi = options.ffi;
+		this.getContext = options.getContext;
+		this.maxHistoryTokens = options.maxHistoryTokens ?? 128;
+		this.modelLabel = options.modelLabel ?? "eliza-1-fused-eot";
+	}
+
+	/**
+	 * True only when the fused build wires the v11 EOT scorer AND the tokenizer
+	 * it depends on. A v10 (or older) library returns false.
+	 */
+	static isSupported(ffi: ElizaInferenceFfi | null | undefined): boolean {
+		return (
+			!!ffi &&
+			typeof ffi.eotSupported === "function" &&
+			ffi.eotSupported() &&
+			typeof ffi.eotScore === "function" &&
+			typeof ffi.tokenize === "function"
+		);
+	}
+
+	private resolveEndOfTurn(ctx: ElizaInferenceContextHandle): number {
+		if (this.endOfTurnTokenId !== null) return this.endOfTurnTokenId;
+		const tokenize = this.ffi.tokenize;
+		if (!tokenize) {
+			throw new Error("[voice] FfiEotScorer: fused tokenizer is unavailable.");
+		}
+		const ids = tokenize({
+			ctx,
+			text: END_OF_TURN_TOKEN,
+			addSpecial: false,
+			parseSpecial: true,
+		});
+		const first = ids[0];
+		if (ids.length !== 1 || first === undefined || !Number.isInteger(first)) {
+			throw new Error(
+				`[voice] FfiEotScorer: tokenizer did not resolve <end_of_turn> to a single special token (got ${JSON.stringify([...ids])}). The text bundle must be Gemma-template compatible.`,
+			);
+		}
+		this.endOfTurnTokenId = first;
+		return first;
+	}
+
+	async score(partialTranscript: string): Promise<FfiEotScoreResult> {
+		const start = performance.now();
+		const ctx = this.getContext();
+		const tokenize = this.ffi.tokenize;
+		const eotScore = this.ffi.eotScore;
+		if (!tokenize || !eotScore) {
+			throw new Error(
+				"[voice] FfiEotScorer: fused EOT symbols are unavailable.",
+			);
+		}
+		const endOfTurnId = this.resolveEndOfTurn(ctx);
+		const formatted = formatEotPrompt(partialTranscript);
+		const all = tokenize({
+			ctx,
+			text: formatted,
+			addSpecial: false,
+			parseSpecial: true,
+		});
+		const tokens =
+			all.length > this.maxHistoryTokens
+				? all.slice(all.length - this.maxHistoryTokens)
+				: all;
+		if (tokens.length === 0) {
+			return {
+				probability: 0.5,
+				latencyMs: performance.now() - start,
+				promptTokens: 0,
+			};
+		}
+		const { targetProb } = eotScore({
+			ctx,
+			tokens,
+			targetTokenId: endOfTurnId,
+		});
+		const probability = Number.isFinite(targetProb)
+			? Math.max(0, Math.min(1, targetProb))
+			: 0.5;
+		return {
+			probability,
+			latencyMs: performance.now() - start,
+			promptTokens: tokens.length,
+		};
+	}
+}

package/src/services/voice/index.ts

@@ -0,0 +1,502 @@
+export {
+	type AttributedTurn,
+	type AttributedTurnListener,
+	type AttributionPipelineLike,
+	AUDIO_FRAME_PIPELINE_SAMPLE_RATE,
+	AudioFrameConsumer,
+	type AudioFrameConsumerConfig,
+	type AudioFrameConsumerDeps,
+	AudioFrameDecodeError,
+	type AudioFrameEvent,
+	decodeAudioFramePcm,
+	type RuntimeEventSink,
+	type VadSegmenter,
+} from "./audio-frame-consumer";
+export {
+	BargeInController,
+	type BargeInControllerConfig,
+	type BargeInListener,
+	type CancelSignal,
+} from "./barge-in";
+export {
+	type CoordinatorRuntime,
+	VoiceCancellationCoordinator,
+	type VoiceCancellationCoordinatorOptions,
+} from "./cancellation-coordinator";
+export {
+	type CheckpointHandle,
+	CheckpointHandleInvalidError,
+	CheckpointManager,
+	type CheckpointManagerLike,
+	type CheckpointManagerOptions,
+	MockCheckpointManager,
+	type MockCheckpointSnapshot,
+	type MockSnapshotSource,
+} from "./checkpoint-manager";
+export {
+	computeDiarizationErrorRate,
+	type DerOptions,
+	type DerResult,
+	type DiarizationSegment,
+	diarizationWithinBudget,
+} from "./diarization-error-rate";
+export {
+	type BuildDeterministicFn,
+	type BuildMessageDependentFn,
+	type ContextPartial,
+	EagerContextBuilder,
+	type EagerContextBuilderOptions,
+	type FullContext,
+	mergeContext,
+} from "./eager-context-builder";
+export {
+	DEFAULT_PLAYBACK_DELAY_MS,
+	type EchoDelayEstimate,
+	type EchoDelayOptions,
+	estimateEchoDelaySamples,
+	PLATFORM_PLAYBACK_DELAY_DEFAULTS,
+	platformPlaybackDelayMs,
+	platformPlaybackDelaySamples,
+} from "./echo-delay";
+export { computeErle } from "./echo-metrics";
+export {
+	EchoReferenceBuffer,
+	type EchoReferenceBufferOptions,
+} from "./echo-reference-buffer";
+export type {
+	LlamaContextLike as Eliza1EotLlamaContext,
+	LlamaContextSequenceLike as Eliza1EotLlamaSequence,
+	LlamaModelLike as Eliza1EotLlamaModel,
+} from "./eliza1-eot-scorer";
+export {
+	Eliza1EotScorer,
+	formatEotPrompt as formatEliza1EotPrompt,
+} from "./eliza1-eot-scorer";
+export {
+	buildLocalEmbeddingRoute,
+	EMBEDDING_DIR_REL_PATH,
+	EMBEDDING_FULL_DIM,
+	EMBEDDING_MATRYOSHKA_DIMS,
+	isValidEmbeddingDim,
+	type LocalEmbeddingRoute,
+	type LocalEmbeddingSource,
+	POOLED_TEXT_EMBEDDING_TIERS,
+	resolveLocalEmbeddingSource,
+	truncateMatryoshka,
+} from "./embedding";
+export {
+	attributeVoiceEmotion,
+	type VoiceEmotionAsrFeatures,
+	type VoiceEmotionAttribution,
+	type VoiceEmotionAttributionInput,
+	type VoiceEmotionAttributionMethod,
+	type VoiceEmotionAudioFeatures,
+	type VoiceEmotionEvidence,
+} from "./emotion-attribution";
+export {
+	decodeMonoPcm16Wav,
+	defaultLifecycleLoaders,
+	EngineVoiceBridge,
+	type EngineVoiceBridgeOptions,
+	encodeMonoPcm16Wav,
+	FfiOmniVoiceBackend,
+	StubOmniVoiceBackend,
+	type VoiceTurnEvents,
+} from "./engine-bridge";
+export {
+	Eliza1EotClassifier,
+	type Eliza1EotScoreResult,
+	type Eliza1EotScorerOptions,
+	EOT_COMMIT_SILENCE_MS,
+	EOT_COMMIT_THRESHOLD,
+	EOT_HANGOVER_EXTENSION_MS,
+	EOT_MID_CLAUSE_THRESHOLD,
+	EOT_TENTATIVE_SILENCE_MS,
+	EOT_TENTATIVE_THRESHOLD,
+	type EotClassifier,
+	HeuristicEotClassifier,
+	LIVEKIT_TURN_DETECTOR_EN_REVISION,
+	LIVEKIT_TURN_DETECTOR_INTL_REVISION,
+	RemoteEotClassifier,
+	type RemoteEotClassifierOptions,
+	turnDetectorRevisionForTier,
+	turnSignalFromProbability,
+	type VoiceNextSpeaker,
+	type VoiceTurnSignal,
+} from "./eot-classifier";
+export {
+	applyGemmaUserTemplate,
+	createBundledLiveKitGgmlTurnDetector,
+	DEFAULT_LIVEKIT_TURN_DETECTOR_GGML_DIR,
+	DEFAULT_LIVEKIT_TURN_DETECTOR_GGUF_EN,
+	DEFAULT_LIVEKIT_TURN_DETECTOR_GGUF_INTL,
+	EotGgmlUnavailableError,
+	LIVEKIT_END_OF_TURN_TOKEN,
+	LiveKitGgmlTurnDetector,
+	type LiveKitGgmlTurnDetectorOptions,
+	turnDetectorGgufForTier,
+} from "./eot-classifier-ggml";
+export { VoiceStartupError } from "./errors";
+export * from "./ffi-bindings";
+export {
+	_resetSharedFirstLineCacheForTesting,
+	_resetVoiceRevisionMemoForTesting,
+	computeLocalVoiceRevision,
+	FIRST_SENTENCE_MAX_WORDS,
+	FIRST_SENTENCE_SNIP_VERSION,
+	FirstLineCache,
+	type FirstLineCacheEntry,
+	type FirstLineCacheKey,
+	type FirstLineCacheOptions,
+	type FirstLineCacheStats,
+	type FirstSentenceSnipResult,
+	fingerprintVoiceSettings,
+	firstLineCacheBypassFromEnv,
+	firstSentenceSnip,
+	getSharedFirstLineCache,
+	hashCacheKey,
+	type PutInput,
+	wordCount,
+} from "./first-line-cache";
+export {
+	type ArmedResources,
+	type TextResources,
+	VoiceLifecycle,
+	VoiceLifecycleError,
+	type VoiceLifecycleEvents,
+	type VoiceLifecycleLoaders,
+	type VoiceLifecycleState,
+} from "./lifecycle";
+export {
+	DesktopMicSource,
+	type DesktopMicSourceOptions,
+	PushMicSource,
+	pipeMicToRingBuffer,
+	resolveDesktopRecorder,
+} from "./mic-source";
+export {
+	NlmsEchoCanceller,
+	type NlmsEchoCancellerOptions,
+} from "./nlms-echo-canceller";
+export {
+	DEFAULT_OPTIMISTIC_EOT_THRESHOLD,
+	OptimisticGenerationPolicy,
+	type OptimisticPolicyOptions,
+	type PowerSourceState,
+	type ResolveOptimisticPolicyArgs,
+	resolveOptimisticPolicyEnabled,
+	resolvePowerSourceState,
+} from "./optimistic-policy";
+export {
+	createDefaultPhonemeTokenizer,
+	type Phoneme,
+	type PhonemeTokenizer,
+	RuleBasedEnglishPhonemeTokenizer,
+} from "./phoneme-tokenizer";
+export {
+	type CachedPhraseAudio,
+	canonicalizePhraseText,
+	DEFAULT_PHRASE_CACHE_SEED,
+	FIRST_AUDIO_FILLERS,
+	PhraseCache,
+} from "./phrase-cache";
+export { chunkTokens, PhraseChunker } from "./phrase-chunker";
+export {
+	type DraftProposer,
+	splitTranscriptToTokens,
+	type TargetVerifier,
+	VoicePipeline,
+	type VoicePipelineConfig,
+	type VoicePipelineDeps,
+	type VoicePipelineEvents,
+} from "./pipeline";
+export {
+	MissingAsrTranscriber,
+	MtpDraftProposer,
+	MtpTargetVerifier,
+	type MtpTextRunner,
+	mtpTextRunner,
+} from "./pipeline-impls";
+export {
+	type PrefillOptimisticArgs,
+	type PrefillOptimisticOptions,
+	type PrefillOptimisticResult,
+	prefillOptimistic,
+} from "./prefill-client";
+export {
+	PrefixPreservingQueue,
+	type RollbackResult,
+	type TaggedAudioChunk,
+} from "./prefix-preserving-queue";
+export {
+	isOutlier,
+	VOICE_PROFILE_RECORD_SCHEMA_VERSION,
+	type VoiceImprintMatchHandle,
+	type VoiceProfileAudioRef,
+	type VoiceProfileConsentState,
+	type VoiceProfileObservation,
+	type VoiceProfileRecord,
+	VoiceProfileStore,
+	type VoiceProfileStoreOptions,
+	welfordUpdate,
+	welfordVariance,
+} from "./profile-store";
+export { InMemoryAudioSink, PcmRingBuffer } from "./ring-buffer";
+export { type RollbackEvent, RollbackQueue } from "./rollback-queue";
+export {
+	type SchedulerDeps,
+	type SchedulerEvents,
+	VoiceScheduler,
+} from "./scheduler";
+export {
+	createMtpDraftHandle,
+	type KernelSet,
+	type MmapRegionHandle,
+	type MtpDraftHandle,
+	type RefCountedResource,
+	type SchedulerSlot,
+	SharedResourceRegistry,
+	type SharedTokenizer,
+} from "./shared-resources";
+export {
+	type VoiceAttributionOutput,
+	VoiceAttributionPipeline,
+	type VoiceAttributionPipelineDeps,
+	type VoiceAttributionRequest,
+} from "./speaker/attribution-pipeline";
+export {
+	classifyFramesToSegments,
+	type Diarizer,
+	type DiarizerOutput,
+	DiarizerUnavailableError,
+	type LocalSpeakerSegment,
+	PYANNOTE_CLASS_COUNT,
+	PYANNOTE_CLASS_TO_SPEAKERS,
+	PYANNOTE_FRAME_STRIDE_MS,
+	PYANNOTE_FRAMES_PER_WINDOW,
+	PYANNOTE_SAMPLE_RATE,
+	PYANNOTE_SEGMENTATION_3_FP32_MODEL_ID,
+	PYANNOTE_SEGMENTATION_3_INT8_MODEL_ID,
+	PYANNOTE_WINDOW_SECONDS,
+	type PyannoteDiarizerModelId,
+} from "./speaker/diarizer";
+export {
+	FusedDiarizer,
+	type FusedDiarizerOptions,
+} from "./speaker/diarizer-fused";
+export {
+	averageEmbeddings,
+	type SpeakerEncoder,
+	SpeakerEncoderUnavailableError,
+	WESPEAKER_EMBEDDING_DIM,
+	WESPEAKER_MIN_SAMPLES,
+	WESPEAKER_RESNET34_LM_FP32_MODEL_ID,
+	WESPEAKER_RESNET34_LM_INT8_MODEL_ID,
+	WESPEAKER_SAMPLE_RATE,
+	type WespeakerModelId,
+} from "./speaker/encoder";
+export {
+	FusedSpeakerEncoder,
+	type FusedSpeakerEncoderOptions,
+} from "./speaker/encoder-fused";
+export {
+	SPEAKER_GGML_EMBEDDING_DIM,
+	SPEAKER_GGML_MIN_SAMPLES,
+	SPEAKER_GGML_SAMPLE_RATE,
+	SpeakerEncoderGgmlUnavailableError,
+	voiceSpeakerDistance,
+} from "./speaker/encoder-ggml";
+export {
+	type AttributedVoiceObservation,
+	attributeVoiceImprintObservations,
+	cosineSimilarity,
+	DEFAULT_VOICE_IMPRINT_MATCH_THRESHOLD,
+	matchVoiceImprint,
+	normalizeVoiceEmbedding,
+	type SpeakerAttributionResult,
+	updateVoiceImprintCentroid,
+	type VoiceImprintCentroidUpdate,
+	type VoiceImprintMatch,
+	type VoiceImprintObservationInput,
+	type VoiceImprintProfile,
+	voiceSpeakerFromImprintMatch,
+} from "./speaker-imprint";
+export {
+	DEFAULT_VOICE_ID,
+	DEFAULT_VOICE_PRESET_REL_PATH,
+	type LoadedPresetBundle,
+	type PresetBundlePaths,
+	SpeakerPresetCache,
+	type SpeakerPresetCacheOptions,
+	voicePresetPath,
+} from "./speaker-preset-cache";
+export {
+	SystemAudioSink,
+	type SystemAudioSinkOptions,
+	WavFileAudioSink,
+	type WavFileAudioSinkOptions,
+} from "./system-audio-sink";
+export {
+	ASR_SAMPLE_RATE,
+	AsrUnavailableError,
+	BaseStreamingTranscriber,
+	type CreateStreamingTranscriberOptions,
+	createStreamingTranscriber,
+	FfiBatchTranscriber,
+	type FfiBatchTranscriberOptions,
+	FfiStreamingTranscriber,
+	ffiSupportsStreamingAsr,
+	resampleLinear,
+} from "./transcriber";
+export {
+	type VoiceGenerateRequest,
+	VoiceTurnController,
+	type VoiceTurnControllerConfig,
+	type VoiceTurnControllerDeps,
+	type VoiceTurnControllerEvents,
+	type VoiceTurnOutcome,
+} from "./turn-controller";
+export * from "./types";
+export {
+	createSileroVadDetector,
+	createVadDetector,
+	type ExternalVadAdapter,
+	GgmlSileroVad,
+	NativeSileroVad,
+	type ResolvedVadProvider,
+	RmsEnergyGate,
+	type RmsEnergyGateConfig,
+	resolveSileroVadPath,
+	resolveVadProvider,
+	rms,
+	VadDetector,
+	type VadDetectorConfig,
+	type VadLike,
+	type VadProviderId,
+	type VadProviderPreference,
+	VadUnavailableError,
+	vadProviderOrder,
+} from "./vad";
+export {
+	type AllocationPriority,
+	assessVoiceBundleFits,
+	BudgetExhaustedError,
+	type BudgetReservation,
+	createVoiceBudget,
+	createVoiceBudgetForTest,
+	DEFAULT_VOICE_BUNDLE_RESERVE_MB,
+	pickVoiceTierSlot,
+	priorityClassForRole,
+	type ReservationSnapshot,
+	VOICE_ENSEMBLE_BUDGETS,
+	type VoiceBudget,
+	type VoiceBundleFitDecision,
+	type VoiceEnsembleBudget,
+	type VoiceTierSlot,
+	voiceEnsemblePeakMb,
+	voiceEnsembleSteadyStateMb,
+} from "./voice-budget";
+export {
+	type ArbiterPreloader,
+	VoicePreloadPredictor,
+	type VoicePreloadPredictorOptions,
+} from "./voice-preload-predictor";
+export {
+	readVoicePresetFile,
+	VOICE_PRESET_MAGIC,
+	type VoicePresetFile,
+	VoicePresetFormatError,
+	type VoicePresetSeedPhrase,
+	writeVoicePresetFile,
+} from "./voice-preset-format";
+export {
+	analyzeVoiceProfileWav,
+	canonicalVoiceProfileJson,
+	createVoiceProfileArtifact,
+	VOICE_PROFILE_ARTIFACT_SCHEMA_VERSION,
+	VOICE_PROFILE_FEATURE_EMBEDDING_MODEL,
+	type VoiceProfileArtifact,
+	type VoiceProfileArtifactSample,
+	type VoiceProfileArtifactStatus,
+	type VoiceProfileArtifactVerification,
+	type VoiceProfileAudioFeatures,
+	type VoiceProfileConsent,
+	type VoiceProfileReferenceMetadata,
+	type VoiceProfileSampleInput,
+	verifyVoiceProfileArtifact,
+} from "./voice-profile-artifact";
+export {
+	type DrafterAbortReason,
+	type DrafterHandle,
+	type StartDrafterFn,
+	type VoiceState,
+	type VoiceStateEvent,
+	VoiceStateMachine,
+	type VoiceStateMachineEvents,
+	type VoiceStateMachineOptions,
+} from "./voice-state-machine";
+export {
+	GgmlWakeWordModel,
+	isPlaceholderWakeWordHead,
+	loadBundledWakeWordModel,
+	OPENWAKEWORD_DEFAULT_HEAD,
+	OPENWAKEWORD_DIR_REL_PATH,
+	OPENWAKEWORD_GGUF_REL_PATH,
+	OPENWAKEWORD_PLACEHOLDER_HEADS,
+	OpenWakeWordDetector,
+	resolveWakeWordModel,
+	type WakeWordConfig,
+	type WakeWordModel,
+	type WakeWordModelPaths,
+	WakeWordUnavailableError,
+} from "./wake-word";
+export {
+	type TtsBytes,
+	type TtsHandler,
+	type TtsHandlerInput,
+	type TtsHandlerOutput,
+	type TtsResolvedContext,
+	type WrapOptions,
+	wrapWithFirstLineCache,
+} from "./wrap-with-first-line-cache";
+
+/**
+ * Voice on/off invariants (binding for every consumer of this module):
+ *
+ * 1. Voice is OFF by default — text + drafter only. Before
+ *    `EngineVoiceBridge.start()` there are no voice resources in RAM.
+ *    After `start()` but before `VoiceLifecycle.arm()`, only the tiny
+ *    default speaker preset, phrase seed metadata, and scheduler
+ *    scaffolding are live. TTS/ASR weight regions are NOT mapped or
+ *    re-paged until `VoiceLifecycle.arm()` calls the fused ABI's
+ *    `mmap_acquire`.
+ *
+ * 2. Shared resources between text and voice (one instance each per
+ *    engine, refcounted by `SharedResourceRegistry`):
+ *      - tokenizer (Eliza-1/OmniVoice share a vocabulary)
+ *      - mmap regions for weights (deduplicated by absolute path)
+ *      - the fused kernel set (TurboQuant/QJL/Polar live in the
+ *        same shipped llama.cpp library after the fusion build)
+ *      - the scheduler queue (one queue, prioritised across surfaces)
+ *      - the MTP drafter (always wired — see AGENTS.md §3 #4)
+ *
+ *    Text and voice keep SEPARATE KV caches (different layer counts,
+ *    different head configs, different quantizations — AGENTS.md §4
+ *    "shared KV cache scheduling, not shared KV memory").
+ *
+ * 3. `arm()` lazily loads TTS + ASR via mmap; `disarm()` issues a real
+ *    page-eviction call (`madvise(MADV_DONTNEED)` on Linux/Android,
+ *    `madvise(MADV_FREE_REUSABLE)` on Apple, `VirtualUnlock` +
+ *    `OfferVirtualMemory` on Windows). The speaker preset and phrase
+ *    cache stay in a small LRU after disarm — they're KB-scale.
+ *
+ * 4. Hardware-resource exhaustion (RAM pressure, OS page eviction
+ *    refusal, mmap fail, kernel missing) MUST surface as a
+ *    `VoiceLifecycleError` with a structured `code`. There is NO
+ *    silent fallback to text-only and NO automatic downgrade to a
+ *    smaller voice model — see AGENTS.md §3.
+ *
+ * 5. Illegal lifecycle transitions throw `VoiceLifecycleError` with
+ *    code `"illegal-transition"`. The state is a discriminated
+ *    union, never a string.
+ */