@plasius/ai-speech 0.1.1 → 0.1.2

package/dist/index.d.cts

@@ -5,8 +5,146 @@ interface AiPackageDescriptor {
     readonly summary: string;
 }
 declare const AI_SPEECH_PACKAGE = "@plasius/ai-speech";
-declare const AI_SPEECH_FEATURE_FLAG_ID = "ai.speech.enabled";
 declare const AI_SPEECH_ENV_PREFIX = "AI_SPEECH";
+declare const AI_SPEECH_FEATURE_FLAGS: {
+    readonly ttsCache: "ai.tts.cache.enabled";
+    readonly ttsNearReuse: "ai.tts.near-reuse.enabled";
+    readonly premiumCharacters: "ai.tts.premium-characters.enabled";
+};
+type AiSpeechFeatureFlagKey = (typeof AI_SPEECH_FEATURE_FLAGS)[keyof typeof AI_SPEECH_FEATURE_FLAGS];
+type AiSpeechFeatureFlagSnapshot = Readonly<Record<string, boolean | undefined>>;
+declare const AI_SPEECH_FEATURE_FLAG_ID: "ai.tts.cache.enabled";
+declare const AI_SPEECH_ROLLOUT_EVALUATORS: readonly ["remote-flag-service", "host-application", "break-glass-env"];
+type AiSpeechRolloutEvaluator = (typeof AI_SPEECH_ROLLOUT_EVALUATORS)[number];
+declare const AI_SPEECH_ROLLOUT_FALLBACK_MODES: readonly ["fail-closed", "fail-open"];
+type AiSpeechRolloutFallbackMode = (typeof AI_SPEECH_ROLLOUT_FALLBACK_MODES)[number];
+interface AiSpeechRolloutControl {
+    readonly featureFlag: AiSpeechFeatureFlagKey;
+    readonly evaluator: AiSpeechRolloutEvaluator;
+    readonly defaultEnabled: boolean;
+    readonly fallbackMode: AiSpeechRolloutFallbackMode;
+}
+interface AiSpeechRolloutDecision extends AiSpeechRolloutControl {
+    readonly enabled: boolean;
+    readonly source: "snapshot" | "default";
+}
+declare const AI_SPEECH_ROLLOUTS: Readonly<{
+    ttsCache: Readonly<AiSpeechRolloutControl>;
+    ttsNearReuse: Readonly<AiSpeechRolloutControl>;
+    premiumCharacters: Readonly<AiSpeechRolloutControl>;
+}>;
+declare function resolveAiSpeechRolloutDecision(control: AiSpeechRolloutControl, snapshot?: AiSpeechFeatureFlagSnapshot): AiSpeechRolloutDecision;
+declare function isAiSpeechFeatureEnabled(featureFlag: AiSpeechFeatureFlagKey, snapshot?: AiSpeechFeatureFlagSnapshot): boolean;
+declare const AI_SPEECH_VOICE_TIERS: readonly ["development", "standard", "premium-character"];
+type AiSpeechVoiceTier = (typeof AI_SPEECH_VOICE_TIERS)[number];
+declare const AI_SPEECH_ENVIRONMENTS: readonly ["development", "preview", "production"];
+type AiSpeechEnvironment = (typeof AI_SPEECH_ENVIRONMENTS)[number];
+interface AiSpeechVoiceTierDecision {
+    readonly requestedTier: AiSpeechVoiceTier;
+    readonly resolvedTier: AiSpeechVoiceTier;
+    readonly fallbackTier?: AiSpeechVoiceTier;
+    readonly reasonCodes: readonly string[];
+}
+interface ResolveAiSpeechVoiceTierInput {
+    readonly environment: AiSpeechEnvironment;
+    readonly requestedTier?: AiSpeechVoiceTier;
+    readonly featureFlags?: AiSpeechFeatureFlagSnapshot;
+}
+declare function resolveAiSpeechVoiceTier(input: ResolveAiSpeechVoiceTierInput): AiSpeechVoiceTierDecision;
+declare const AI_SPEECH_PLAYER_ADDRESS_SOURCES: readonly ["generic-player", "class-title", "faction-title", "authored-character", "user-name", "account-handle", "user-renamed-character"];
+type AiSpeechPlayerAddressSource = (typeof AI_SPEECH_PLAYER_ADDRESS_SOURCES)[number];
+declare const AI_SPEECH_DEFAULT_PLAYER_LABEL = "Player";
+interface AiSpeechPlayerAddressInput {
+    readonly source: AiSpeechPlayerAddressSource;
+    readonly rawValue?: string;
+    readonly fallbackLabel?: string;
+}
+interface AiSpeechPlayerAddressDecision {
+    readonly source: AiSpeechPlayerAddressSource;
+    readonly renderText: string;
+    readonly exactReuseAllowed: boolean;
+    readonly nearReuseAllowed: boolean;
+    readonly redacted: boolean;
+    readonly reasonCodes: readonly string[];
+}
+declare function resolveAiSpeechPlayerAddress(input: AiSpeechPlayerAddressInput): AiSpeechPlayerAddressDecision;
+interface AiSpeechRenderTextInput {
+    readonly textTemplate: string;
+    readonly playerAddress?: AiSpeechPlayerAddressInput;
+}
+interface AiSpeechRenderTextResult {
+    readonly renderText: string;
+    readonly normalizedRenderText: string;
+    readonly playerAddress?: AiSpeechPlayerAddressDecision;
+}
+declare function renderAiSpeechText(input: AiSpeechRenderTextInput): AiSpeechRenderTextResult;
+declare function normalizeAiSpeechText(value: string): string;
+declare const AI_SPEECH_PROVIDER_CACHE_PERMISSIONS: readonly ["forbidden", "exact-only", "exact-and-near"];
+type AiSpeechProviderCachePermission = (typeof AI_SPEECH_PROVIDER_CACHE_PERMISSIONS)[number];
+declare const AI_SPEECH_CACHE_MODES: readonly ["disabled", "no-cache", "exact", "near"];
+type AiSpeechCacheMode = (typeof AI_SPEECH_CACHE_MODES)[number];
+declare const AI_SPEECH_CACHE_SCOPES: readonly ["none", "actor", "global"];
+type AiSpeechCacheScope = (typeof AI_SPEECH_CACHE_SCOPES)[number];
+declare const AI_SPEECH_UTTERANCE_CLASSES: readonly ["system-generic", "game-npc-dialogue", "game-bark", "player-address", "moderation-notice", "private-response"];
+type AiSpeechUtteranceClass = (typeof AI_SPEECH_UTTERANCE_CLASSES)[number];
+declare const AI_SPEECH_NEAR_REUSE_SAFE_CLASSES: readonly ["system-generic", "game-npc-dialogue", "game-bark", "player-address"];
+interface AiSpeechCacheKeyInput {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly voiceId: string;
+    readonly locale: string;
+    readonly format: string;
+    readonly pronunciationVersion: string;
+    readonly normalizedRenderText: string;
+    readonly styleId?: string;
+    readonly scopeDiscriminator?: string;
+}
+interface AiSpeechVoiceProfileRef {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly voiceId: string;
+    readonly locale: string;
+    readonly format: string;
+    readonly pronunciationVersion: string;
+    readonly styleId?: string;
+    readonly cachePermission: AiSpeechProviderCachePermission;
+    readonly tier?: AiSpeechVoiceTier;
+    readonly profileId?: string;
+}
+interface AiSpeechCacheTelemetry {
+    readonly cacheHits: number;
+    readonly nearCacheHits: number;
+    readonly cacheMisses: number;
+    readonly charactersSaved: number;
+    readonly estimatedCostSavedUsd?: number;
+    readonly voiceProfileIds?: readonly string[];
+}
+interface PlanAiSpeechCacheInput {
+    readonly utteranceClass: AiSpeechUtteranceClass;
+    readonly textTemplate: string;
+    readonly playerAddress?: AiSpeechPlayerAddressInput;
+    readonly voice: AiSpeechVoiceProfileRef;
+    readonly featureFlags?: AiSpeechFeatureFlagSnapshot;
+    readonly actorScopeKey?: string;
+    readonly containsPersonalData?: boolean;
+    readonly containsPrivateContext?: boolean;
+    readonly containsModerationNotice?: boolean;
+}
+interface AiSpeechCachePlan {
+    readonly mode: AiSpeechCacheMode;
+    readonly sharingScope: AiSpeechCacheScope;
+    readonly renderText: string;
+    readonly normalizedRenderText: string;
+    readonly exactKey?: string;
+    readonly nearKey?: string;
+    readonly enabledFeatureFlags: readonly AiSpeechFeatureFlagKey[];
+    readonly playerAddress?: AiSpeechPlayerAddressDecision;
+    readonly reasonCodes: readonly string[];
+}
+declare function createAiSpeechCacheKey(input: AiSpeechCacheKeyInput): string;
+declare function createAiSpeechNearReuseFingerprint(value: string): string;
+declare function isAiSpeechNearReuseSafeClass(utteranceClass: AiSpeechUtteranceClass): boolean;
+declare function planAiSpeechCache(input: PlanAiSpeechCacheInput): AiSpeechCachePlan;
 declare const packageDescriptor: AiPackageDescriptor;
 
-export { AI_SPEECH_ENV_PREFIX, AI_SPEECH_FEATURE_FLAG_ID, AI_SPEECH_PACKAGE, type AiPackageDescriptor, packageDescriptor };
+export { AI_SPEECH_CACHE_MODES, AI_SPEECH_CACHE_SCOPES, AI_SPEECH_DEFAULT_PLAYER_LABEL, AI_SPEECH_ENVIRONMENTS, AI_SPEECH_ENV_PREFIX, AI_SPEECH_FEATURE_FLAGS, AI_SPEECH_FEATURE_FLAG_ID, AI_SPEECH_NEAR_REUSE_SAFE_CLASSES, AI_SPEECH_PACKAGE, AI_SPEECH_PLAYER_ADDRESS_SOURCES, AI_SPEECH_PROVIDER_CACHE_PERMISSIONS, AI_SPEECH_ROLLOUTS, AI_SPEECH_ROLLOUT_EVALUATORS, AI_SPEECH_ROLLOUT_FALLBACK_MODES, AI_SPEECH_UTTERANCE_CLASSES, AI_SPEECH_VOICE_TIERS, type AiPackageDescriptor, type AiSpeechCacheKeyInput, type AiSpeechCacheMode, type AiSpeechCachePlan, type AiSpeechCacheScope, type AiSpeechCacheTelemetry, type AiSpeechEnvironment, type AiSpeechFeatureFlagKey, type AiSpeechFeatureFlagSnapshot, type AiSpeechPlayerAddressDecision, type AiSpeechPlayerAddressInput, type AiSpeechPlayerAddressSource, type AiSpeechProviderCachePermission, type AiSpeechRenderTextInput, type AiSpeechRenderTextResult, type AiSpeechRolloutControl, type AiSpeechRolloutDecision, type AiSpeechRolloutEvaluator, type AiSpeechRolloutFallbackMode, type AiSpeechUtteranceClass, type AiSpeechVoiceProfileRef, type AiSpeechVoiceTier, type AiSpeechVoiceTierDecision, type PlanAiSpeechCacheInput, type ResolveAiSpeechVoiceTierInput, createAiSpeechCacheKey, createAiSpeechNearReuseFingerprint, isAiSpeechFeatureEnabled, isAiSpeechNearReuseSafeClass, normalizeAiSpeechText, packageDescriptor, planAiSpeechCache, renderAiSpeechText, resolveAiSpeechPlayerAddress, resolveAiSpeechRolloutDecision, resolveAiSpeechVoiceTier };

package/dist/index.d.ts

@@ -5,8 +5,146 @@ interface AiPackageDescriptor {
     readonly summary: string;
 }
 declare const AI_SPEECH_PACKAGE = "@plasius/ai-speech";
-declare const AI_SPEECH_FEATURE_FLAG_ID = "ai.speech.enabled";
 declare const AI_SPEECH_ENV_PREFIX = "AI_SPEECH";
+declare const AI_SPEECH_FEATURE_FLAGS: {
+    readonly ttsCache: "ai.tts.cache.enabled";
+    readonly ttsNearReuse: "ai.tts.near-reuse.enabled";
+    readonly premiumCharacters: "ai.tts.premium-characters.enabled";
+};
+type AiSpeechFeatureFlagKey = (typeof AI_SPEECH_FEATURE_FLAGS)[keyof typeof AI_SPEECH_FEATURE_FLAGS];
+type AiSpeechFeatureFlagSnapshot = Readonly<Record<string, boolean | undefined>>;
+declare const AI_SPEECH_FEATURE_FLAG_ID: "ai.tts.cache.enabled";
+declare const AI_SPEECH_ROLLOUT_EVALUATORS: readonly ["remote-flag-service", "host-application", "break-glass-env"];
+type AiSpeechRolloutEvaluator = (typeof AI_SPEECH_ROLLOUT_EVALUATORS)[number];
+declare const AI_SPEECH_ROLLOUT_FALLBACK_MODES: readonly ["fail-closed", "fail-open"];
+type AiSpeechRolloutFallbackMode = (typeof AI_SPEECH_ROLLOUT_FALLBACK_MODES)[number];
+interface AiSpeechRolloutControl {
+    readonly featureFlag: AiSpeechFeatureFlagKey;
+    readonly evaluator: AiSpeechRolloutEvaluator;
+    readonly defaultEnabled: boolean;
+    readonly fallbackMode: AiSpeechRolloutFallbackMode;
+}
+interface AiSpeechRolloutDecision extends AiSpeechRolloutControl {
+    readonly enabled: boolean;
+    readonly source: "snapshot" | "default";
+}
+declare const AI_SPEECH_ROLLOUTS: Readonly<{
+    ttsCache: Readonly<AiSpeechRolloutControl>;
+    ttsNearReuse: Readonly<AiSpeechRolloutControl>;
+    premiumCharacters: Readonly<AiSpeechRolloutControl>;
+}>;
+declare function resolveAiSpeechRolloutDecision(control: AiSpeechRolloutControl, snapshot?: AiSpeechFeatureFlagSnapshot): AiSpeechRolloutDecision;
+declare function isAiSpeechFeatureEnabled(featureFlag: AiSpeechFeatureFlagKey, snapshot?: AiSpeechFeatureFlagSnapshot): boolean;
+declare const AI_SPEECH_VOICE_TIERS: readonly ["development", "standard", "premium-character"];
+type AiSpeechVoiceTier = (typeof AI_SPEECH_VOICE_TIERS)[number];
+declare const AI_SPEECH_ENVIRONMENTS: readonly ["development", "preview", "production"];
+type AiSpeechEnvironment = (typeof AI_SPEECH_ENVIRONMENTS)[number];
+interface AiSpeechVoiceTierDecision {
+    readonly requestedTier: AiSpeechVoiceTier;
+    readonly resolvedTier: AiSpeechVoiceTier;
+    readonly fallbackTier?: AiSpeechVoiceTier;
+    readonly reasonCodes: readonly string[];
+}
+interface ResolveAiSpeechVoiceTierInput {
+    readonly environment: AiSpeechEnvironment;
+    readonly requestedTier?: AiSpeechVoiceTier;
+    readonly featureFlags?: AiSpeechFeatureFlagSnapshot;
+}
+declare function resolveAiSpeechVoiceTier(input: ResolveAiSpeechVoiceTierInput): AiSpeechVoiceTierDecision;
+declare const AI_SPEECH_PLAYER_ADDRESS_SOURCES: readonly ["generic-player", "class-title", "faction-title", "authored-character", "user-name", "account-handle", "user-renamed-character"];
+type AiSpeechPlayerAddressSource = (typeof AI_SPEECH_PLAYER_ADDRESS_SOURCES)[number];
+declare const AI_SPEECH_DEFAULT_PLAYER_LABEL = "Player";
+interface AiSpeechPlayerAddressInput {
+    readonly source: AiSpeechPlayerAddressSource;
+    readonly rawValue?: string;
+    readonly fallbackLabel?: string;
+}
+interface AiSpeechPlayerAddressDecision {
+    readonly source: AiSpeechPlayerAddressSource;
+    readonly renderText: string;
+    readonly exactReuseAllowed: boolean;
+    readonly nearReuseAllowed: boolean;
+    readonly redacted: boolean;
+    readonly reasonCodes: readonly string[];
+}
+declare function resolveAiSpeechPlayerAddress(input: AiSpeechPlayerAddressInput): AiSpeechPlayerAddressDecision;
+interface AiSpeechRenderTextInput {
+    readonly textTemplate: string;
+    readonly playerAddress?: AiSpeechPlayerAddressInput;
+}
+interface AiSpeechRenderTextResult {
+    readonly renderText: string;
+    readonly normalizedRenderText: string;
+    readonly playerAddress?: AiSpeechPlayerAddressDecision;
+}
+declare function renderAiSpeechText(input: AiSpeechRenderTextInput): AiSpeechRenderTextResult;
+declare function normalizeAiSpeechText(value: string): string;
+declare const AI_SPEECH_PROVIDER_CACHE_PERMISSIONS: readonly ["forbidden", "exact-only", "exact-and-near"];
+type AiSpeechProviderCachePermission = (typeof AI_SPEECH_PROVIDER_CACHE_PERMISSIONS)[number];
+declare const AI_SPEECH_CACHE_MODES: readonly ["disabled", "no-cache", "exact", "near"];
+type AiSpeechCacheMode = (typeof AI_SPEECH_CACHE_MODES)[number];
+declare const AI_SPEECH_CACHE_SCOPES: readonly ["none", "actor", "global"];
+type AiSpeechCacheScope = (typeof AI_SPEECH_CACHE_SCOPES)[number];
+declare const AI_SPEECH_UTTERANCE_CLASSES: readonly ["system-generic", "game-npc-dialogue", "game-bark", "player-address", "moderation-notice", "private-response"];
+type AiSpeechUtteranceClass = (typeof AI_SPEECH_UTTERANCE_CLASSES)[number];
+declare const AI_SPEECH_NEAR_REUSE_SAFE_CLASSES: readonly ["system-generic", "game-npc-dialogue", "game-bark", "player-address"];
+interface AiSpeechCacheKeyInput {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly voiceId: string;
+    readonly locale: string;
+    readonly format: string;
+    readonly pronunciationVersion: string;
+    readonly normalizedRenderText: string;
+    readonly styleId?: string;
+    readonly scopeDiscriminator?: string;
+}
+interface AiSpeechVoiceProfileRef {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly voiceId: string;
+    readonly locale: string;
+    readonly format: string;
+    readonly pronunciationVersion: string;
+    readonly styleId?: string;
+    readonly cachePermission: AiSpeechProviderCachePermission;
+    readonly tier?: AiSpeechVoiceTier;
+    readonly profileId?: string;
+}
+interface AiSpeechCacheTelemetry {
+    readonly cacheHits: number;
+    readonly nearCacheHits: number;
+    readonly cacheMisses: number;
+    readonly charactersSaved: number;
+    readonly estimatedCostSavedUsd?: number;
+    readonly voiceProfileIds?: readonly string[];
+}
+interface PlanAiSpeechCacheInput {
+    readonly utteranceClass: AiSpeechUtteranceClass;
+    readonly textTemplate: string;
+    readonly playerAddress?: AiSpeechPlayerAddressInput;
+    readonly voice: AiSpeechVoiceProfileRef;
+    readonly featureFlags?: AiSpeechFeatureFlagSnapshot;
+    readonly actorScopeKey?: string;
+    readonly containsPersonalData?: boolean;
+    readonly containsPrivateContext?: boolean;
+    readonly containsModerationNotice?: boolean;
+}
+interface AiSpeechCachePlan {
+    readonly mode: AiSpeechCacheMode;
+    readonly sharingScope: AiSpeechCacheScope;
+    readonly renderText: string;
+    readonly normalizedRenderText: string;
+    readonly exactKey?: string;
+    readonly nearKey?: string;
+    readonly enabledFeatureFlags: readonly AiSpeechFeatureFlagKey[];
+    readonly playerAddress?: AiSpeechPlayerAddressDecision;
+    readonly reasonCodes: readonly string[];
+}
+declare function createAiSpeechCacheKey(input: AiSpeechCacheKeyInput): string;
+declare function createAiSpeechNearReuseFingerprint(value: string): string;
+declare function isAiSpeechNearReuseSafeClass(utteranceClass: AiSpeechUtteranceClass): boolean;
+declare function planAiSpeechCache(input: PlanAiSpeechCacheInput): AiSpeechCachePlan;
 declare const packageDescriptor: AiPackageDescriptor;
 
-export { AI_SPEECH_ENV_PREFIX, AI_SPEECH_FEATURE_FLAG_ID, AI_SPEECH_PACKAGE, type AiPackageDescriptor, packageDescriptor };
+export { AI_SPEECH_CACHE_MODES, AI_SPEECH_CACHE_SCOPES, AI_SPEECH_DEFAULT_PLAYER_LABEL, AI_SPEECH_ENVIRONMENTS, AI_SPEECH_ENV_PREFIX, AI_SPEECH_FEATURE_FLAGS, AI_SPEECH_FEATURE_FLAG_ID, AI_SPEECH_NEAR_REUSE_SAFE_CLASSES, AI_SPEECH_PACKAGE, AI_SPEECH_PLAYER_ADDRESS_SOURCES, AI_SPEECH_PROVIDER_CACHE_PERMISSIONS, AI_SPEECH_ROLLOUTS, AI_SPEECH_ROLLOUT_EVALUATORS, AI_SPEECH_ROLLOUT_FALLBACK_MODES, AI_SPEECH_UTTERANCE_CLASSES, AI_SPEECH_VOICE_TIERS, type AiPackageDescriptor, type AiSpeechCacheKeyInput, type AiSpeechCacheMode, type AiSpeechCachePlan, type AiSpeechCacheScope, type AiSpeechCacheTelemetry, type AiSpeechEnvironment, type AiSpeechFeatureFlagKey, type AiSpeechFeatureFlagSnapshot, type AiSpeechPlayerAddressDecision, type AiSpeechPlayerAddressInput, type AiSpeechPlayerAddressSource, type AiSpeechProviderCachePermission, type AiSpeechRenderTextInput, type AiSpeechRenderTextResult, type AiSpeechRolloutControl, type AiSpeechRolloutDecision, type AiSpeechRolloutEvaluator, type AiSpeechRolloutFallbackMode, type AiSpeechUtteranceClass, type AiSpeechVoiceProfileRef, type AiSpeechVoiceTier, type AiSpeechVoiceTierDecision, type PlanAiSpeechCacheInput, type ResolveAiSpeechVoiceTierInput, createAiSpeechCacheKey, createAiSpeechNearReuseFingerprint, isAiSpeechFeatureEnabled, isAiSpeechNearReuseSafeClass, normalizeAiSpeechText, packageDescriptor, planAiSpeechCache, renderAiSpeechText, resolveAiSpeechPlayerAddress, resolveAiSpeechRolloutDecision, resolveAiSpeechVoiceTier };

package/dist/index.js

@@ -1,7 +1,332 @@
 // src/index.ts
+function requireNonEmptyString(value, label) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+  return trimmed;
+}
+function normalizeWhitespace(value) {
+  return value.replace(/\s+/gu, " ").trim();
+}
 var AI_SPEECH_PACKAGE = "@plasius/ai-speech";
-var AI_SPEECH_FEATURE_FLAG_ID = "ai.speech.enabled";
 var AI_SPEECH_ENV_PREFIX = "AI_SPEECH";
+var AI_SPEECH_FEATURE_FLAGS = {
+  ttsCache: "ai.tts.cache.enabled",
+  ttsNearReuse: "ai.tts.near-reuse.enabled",
+  premiumCharacters: "ai.tts.premium-characters.enabled"
+};
+var AI_SPEECH_FEATURE_FLAG_ID = AI_SPEECH_FEATURE_FLAGS.ttsCache;
+var AI_SPEECH_ROLLOUT_EVALUATORS = [
+  "remote-flag-service",
+  "host-application",
+  "break-glass-env"
+];
+var AI_SPEECH_ROLLOUT_FALLBACK_MODES = [
+  "fail-closed",
+  "fail-open"
+];
+var AI_SPEECH_ROLLOUTS = Object.freeze({
+  ttsCache: Object.freeze({
+    featureFlag: AI_SPEECH_FEATURE_FLAGS.ttsCache,
+    evaluator: "remote-flag-service",
+    defaultEnabled: false,
+    fallbackMode: "fail-closed"
+  }),
+  ttsNearReuse: Object.freeze({
+    featureFlag: AI_SPEECH_FEATURE_FLAGS.ttsNearReuse,
+    evaluator: "remote-flag-service",
+    defaultEnabled: false,
+    fallbackMode: "fail-closed"
+  }),
+  premiumCharacters: Object.freeze({
+    featureFlag: AI_SPEECH_FEATURE_FLAGS.premiumCharacters,
+    evaluator: "remote-flag-service",
+    defaultEnabled: false,
+    fallbackMode: "fail-closed"
+  })
+});
+function resolveAiSpeechRolloutDecision(control, snapshot = {}) {
+  const resolved = snapshot[control.featureFlag];
+  if (typeof resolved === "boolean") {
+    return {
+      ...control,
+      enabled: resolved,
+      source: "snapshot"
+    };
+  }
+  return {
+    ...control,
+    enabled: control.defaultEnabled,
+    source: "default"
+  };
+}
+function isAiSpeechFeatureEnabled(featureFlag, snapshot = {}) {
+  const control = Object.values(AI_SPEECH_ROLLOUTS).find(
+    (candidate) => candidate.featureFlag === featureFlag
+  );
+  if (!control) {
+    return false;
+  }
+  return resolveAiSpeechRolloutDecision(control, snapshot).enabled;
+}
+var AI_SPEECH_VOICE_TIERS = [
+  "development",
+  "standard",
+  "premium-character"
+];
+var AI_SPEECH_ENVIRONMENTS = [
+  "development",
+  "preview",
+  "production"
+];
+function resolveAiSpeechVoiceTier(input) {
+  const requestedTier = input.requestedTier ?? (input.environment === "development" ? "development" : "standard");
+  if (requestedTier === "premium-character" && !isAiSpeechFeatureEnabled(
+    AI_SPEECH_FEATURE_FLAGS.premiumCharacters,
+    input.featureFlags
+  )) {
+    return {
+      requestedTier,
+      resolvedTier: "standard",
+      fallbackTier: "standard",
+      reasonCodes: ["premium-character-rollout-disabled"]
+    };
+  }
+  if (requestedTier === "development" && input.environment !== "development") {
+    return {
+      requestedTier,
+      resolvedTier: "standard",
+      fallbackTier: "standard",
+      reasonCodes: ["development-voices-limited-to-development-environments"]
+    };
+  }
+  return {
+    requestedTier,
+    resolvedTier: requestedTier,
+    reasonCodes: []
+  };
+}
+var AI_SPEECH_PLAYER_ADDRESS_SOURCES = [
+  "generic-player",
+  "class-title",
+  "faction-title",
+  "authored-character",
+  "user-name",
+  "account-handle",
+  "user-renamed-character"
+];
+var AI_SPEECH_DEFAULT_PLAYER_LABEL = "Player";
+function resolveAiSpeechPlayerAddress(input) {
+  const fallbackLabel = normalizeWhitespace(input.fallbackLabel ?? "") || AI_SPEECH_DEFAULT_PLAYER_LABEL;
+  const rawValue = normalizeWhitespace(input.rawValue ?? "");
+  switch (input.source) {
+    case "generic-player":
+      return {
+        source: input.source,
+        renderText: fallbackLabel,
+        exactReuseAllowed: true,
+        nearReuseAllowed: true,
+        redacted: false,
+        reasonCodes: ["generic-player-address"]
+      };
+    case "class-title":
+    case "faction-title":
+      return {
+        source: input.source,
+        renderText: rawValue || fallbackLabel,
+        exactReuseAllowed: true,
+        nearReuseAllowed: true,
+        redacted: false,
+        reasonCodes: rawValue ? [] : ["player-address-fell-back-to-generic-label"]
+      };
+    case "authored-character":
+      return {
+        source: input.source,
+        renderText: rawValue || fallbackLabel,
+        exactReuseAllowed: true,
+        nearReuseAllowed: true,
+        redacted: false,
+        reasonCodes: rawValue ? [] : ["player-address-fell-back-to-generic-label"]
+      };
+    case "user-name":
+    case "account-handle":
+    case "user-renamed-character":
+      return {
+        source: input.source,
+        renderText: fallbackLabel,
+        exactReuseAllowed: true,
+        nearReuseAllowed: false,
+        redacted: true,
+        reasonCodes: ["player-identifier-redacted-from-render-text"]
+      };
+  }
+}
+function renderAiSpeechText(input) {
+  const textTemplate = requireNonEmptyString(
+    input.textTemplate,
+    "Speech text template"
+  );
+  const hasPlayerPlaceholder = textTemplate.includes("{playerAddress}");
+  if (hasPlayerPlaceholder && !input.playerAddress) {
+    throw new Error(
+      "Speech text template requires playerAddress when using the {playerAddress} placeholder."
+    );
+  }
+  const playerAddress = input.playerAddress ? resolveAiSpeechPlayerAddress(input.playerAddress) : void 0;
+  const renderText = normalizeWhitespace(
+    hasPlayerPlaceholder && playerAddress ? textTemplate.replace(/\{playerAddress\}/gu, playerAddress.renderText) : textTemplate
+  );
+  return {
+    renderText,
+    normalizedRenderText: normalizeAiSpeechText(renderText),
+    playerAddress
+  };
+}
+function normalizeAiSpeechText(value) {
+  return requireNonEmptyString(
+    normalizeWhitespace(value).toLocaleLowerCase("en-GB"),
+    "Speech text"
+  );
+}
+var AI_SPEECH_PROVIDER_CACHE_PERMISSIONS = [
+  "forbidden",
+  "exact-only",
+  "exact-and-near"
+];
+var AI_SPEECH_CACHE_MODES = [
+  "disabled",
+  "no-cache",
+  "exact",
+  "near"
+];
+var AI_SPEECH_CACHE_SCOPES = ["none", "actor", "global"];
+var AI_SPEECH_UTTERANCE_CLASSES = [
+  "system-generic",
+  "game-npc-dialogue",
+  "game-bark",
+  "player-address",
+  "moderation-notice",
+  "private-response"
+];
+var AI_SPEECH_NEAR_REUSE_SAFE_CLASSES = [
+  "system-generic",
+  "game-npc-dialogue",
+  "game-bark",
+  "player-address"
+];
+var AI_SPEECH_NEAR_REUSE_SAFE_CLASS_SET = new Set(AI_SPEECH_NEAR_REUSE_SAFE_CLASSES);
+function createAiSpeechCacheKey(input) {
+  const scopeDiscriminator = normalizeWhitespace(input.scopeDiscriminator ?? "");
+  return [
+    requireNonEmptyString(input.providerId, "Provider id"),
+    requireNonEmptyString(input.modelId, "Model id"),
+    requireNonEmptyString(input.voiceId, "Voice id"),
+    requireNonEmptyString(input.locale, "Locale"),
+    normalizeWhitespace(input.styleId ?? "") || "_",
+    requireNonEmptyString(input.format, "Format"),
+    requireNonEmptyString(
+      input.pronunciationVersion,
+      "Pronunciation version"
+    ),
+    scopeDiscriminator || "global",
+    normalizeAiSpeechText(input.normalizedRenderText)
+  ].map((segment) => encodeURIComponent(segment)).join("::");
+}
+function createAiSpeechNearReuseFingerprint(value) {
+  const normalized = normalizeAiSpeechText(value).replace(/[^a-z0-9\s]/gu, " ").replace(/\s+/gu, " ").trim();
+  return requireNonEmptyString(normalized, "Near-reuse fingerprint");
+}
+function isAiSpeechNearReuseSafeClass(utteranceClass) {
+  return AI_SPEECH_NEAR_REUSE_SAFE_CLASS_SET.has(utteranceClass);
+}
+function planAiSpeechCache(input) {
+  const rendered = renderAiSpeechText({
+    textTemplate: input.textTemplate,
+    playerAddress: input.playerAddress
+  });
+  const enabledFeatureFlags = [];
+  const cacheEnabled = isAiSpeechFeatureEnabled(
+    AI_SPEECH_FEATURE_FLAGS.ttsCache,
+    input.featureFlags
+  );
+  if (!cacheEnabled) {
+    return {
+      mode: "disabled",
+      sharingScope: "none",
+      renderText: rendered.renderText,
+      normalizedRenderText: rendered.normalizedRenderText,
+      enabledFeatureFlags,
+      playerAddress: rendered.playerAddress,
+      reasonCodes: ["tts-cache-rollout-disabled"]
+    };
+  }
+  enabledFeatureFlags.push(AI_SPEECH_FEATURE_FLAGS.ttsCache);
+  if (input.voice.cachePermission === "forbidden") {
+    return {
+      mode: "no-cache",
+      sharingScope: "none",
+      renderText: rendered.renderText,
+      normalizedRenderText: rendered.normalizedRenderText,
+      enabledFeatureFlags,
+      playerAddress: rendered.playerAddress,
+      reasonCodes: ["provider-forbids-tts-caching"]
+    };
+  }
+  const containsSensitiveContent = Boolean(input.containsPersonalData) || Boolean(input.containsPrivateContext) || Boolean(input.containsModerationNotice) || Boolean(rendered.playerAddress?.redacted);
+  const actorScopeKey = normalizeWhitespace(input.actorScopeKey ?? "");
+  const actorScopeRequired = containsSensitiveContent || input.utteranceClass === "private-response";
+  if (actorScopeRequired && !actorScopeKey) {
+    return {
+      mode: "no-cache",
+      sharingScope: "none",
+      renderText: rendered.renderText,
+      normalizedRenderText: rendered.normalizedRenderText,
+      enabledFeatureFlags,
+      playerAddress: rendered.playerAddress,
+      reasonCodes: ["actor-scope-key-required-for-sensitive-cache-entry"]
+    };
+  }
+  const exactKey = createAiSpeechCacheKey({
+    ...input.voice,
+    normalizedRenderText: rendered.normalizedRenderText,
+    scopeDiscriminator: actorScopeRequired ? actorScopeKey : void 0
+  });
+  const nearReuseEnabled = input.voice.cachePermission === "exact-and-near" && isAiSpeechFeatureEnabled(
+    AI_SPEECH_FEATURE_FLAGS.ttsNearReuse,
+    input.featureFlags
+  ) && isAiSpeechNearReuseSafeClass(input.utteranceClass) && !containsSensitiveContent && (rendered.playerAddress?.nearReuseAllowed ?? true);
+  if (!nearReuseEnabled) {
+    return {
+      mode: "exact",
+      sharingScope: actorScopeRequired ? "actor" : "global",
+      renderText: rendered.renderText,
+      normalizedRenderText: rendered.normalizedRenderText,
+      exactKey,
+      enabledFeatureFlags,
+      playerAddress: rendered.playerAddress,
+      reasonCodes: containsSensitiveContent ? ["exact-cache-only-for-sensitive-or-redacted-content"] : ["near-reuse-disabled-or-ineligible"]
+    };
+  }
+  enabledFeatureFlags.push(AI_SPEECH_FEATURE_FLAGS.ttsNearReuse);
+  const nearKey = createAiSpeechCacheKey({
+    ...input.voice,
+    normalizedRenderText: createAiSpeechNearReuseFingerprint(
+      rendered.normalizedRenderText
+    )
+  });
+  return {
+    mode: "near",
+    sharingScope: "global",
+    renderText: rendered.renderText,
+    normalizedRenderText: rendered.normalizedRenderText,
+    exactKey,
+    nearKey,
+    enabledFeatureFlags,
+    playerAddress: rendered.playerAddress,
+    reasonCodes: ["near-reuse-eligible"]
+  };
+}
 var packageDescriptor = Object.freeze({
   packageName: AI_SPEECH_PACKAGE,
   featureFlagId: AI_SPEECH_FEATURE_FLAG_ID,
@@ -9,9 +334,32 @@ var packageDescriptor = Object.freeze({
   summary: "Speech orchestration, TTS cache contracts, STT/TTS routing, and voice tier policy for Plasius AI."
 });
 export {
+  AI_SPEECH_CACHE_MODES,
+  AI_SPEECH_CACHE_SCOPES,
+  AI_SPEECH_DEFAULT_PLAYER_LABEL,
+  AI_SPEECH_ENVIRONMENTS,
   AI_SPEECH_ENV_PREFIX,
+  AI_SPEECH_FEATURE_FLAGS,
   AI_SPEECH_FEATURE_FLAG_ID,
+  AI_SPEECH_NEAR_REUSE_SAFE_CLASSES,
   AI_SPEECH_PACKAGE,
-  packageDescriptor
+  AI_SPEECH_PLAYER_ADDRESS_SOURCES,
+  AI_SPEECH_PROVIDER_CACHE_PERMISSIONS,
+  AI_SPEECH_ROLLOUTS,
+  AI_SPEECH_ROLLOUT_EVALUATORS,
+  AI_SPEECH_ROLLOUT_FALLBACK_MODES,
+  AI_SPEECH_UTTERANCE_CLASSES,
+  AI_SPEECH_VOICE_TIERS,
+  createAiSpeechCacheKey,
+  createAiSpeechNearReuseFingerprint,
+  isAiSpeechFeatureEnabled,
+  isAiSpeechNearReuseSafeClass,
+  normalizeAiSpeechText,
+  packageDescriptor,
+  planAiSpeechCache,
+  renderAiSpeechText,
+  resolveAiSpeechPlayerAddress,
+  resolveAiSpeechRolloutDecision,
+  resolveAiSpeechVoiceTier
 };
 //# sourceMappingURL=index.js.map