@oscharko-dev/keiko-contracts 0.2.8 → 0.2.9

package/dist/voice-action-intent.d.ts

@@ -0,0 +1,86 @@
+import type { VoiceProfile } from "./gateway.js";
+import type { CommittedVoiceTranscriptProjection, VoiceTranscriptSource } from "./voice-transcript.js";
+export declare const VOICE_ACTION_INTENT_SCHEMA_VERSION: "1";
+export declare function isVoiceActionIntentSchemaVersionSupported(version: unknown): boolean;
+export type SpokenActionEffectClass = "read-only" | "mutating" | "destructive" | "external-effect" | "unknown";
+export declare const SPOKEN_ACTION_EFFECT_CLASSES: readonly SpokenActionEffectClass[];
+export declare function isSpokenActionEffectClass(value: unknown): value is SpokenActionEffectClass;
+export declare function assertNeverSpokenActionEffectClass(value: never): never;
+export declare const SPOKEN_ACTION_EFFECT_REQUIRES_CONFIRMATION: Readonly<Record<SpokenActionEffectClass, boolean>>;
+export declare function spokenActionRequiresConfirmation(effectClass: SpokenActionEffectClass): boolean;
+export interface SpokenActionEffectMarkers {
+    readonly destructive: readonly string[];
+    readonly externalEffect: readonly string[];
+    readonly mutating: readonly string[];
+    readonly readOnly: readonly string[];
+}
+export declare const SPOKEN_ACTION_EFFECT_MARKERS: SpokenActionEffectMarkers;
+export declare function classifySpokenActionEffect(committedText: string): SpokenActionEffectClass;
+export type SpokenActionState = "proposed" | "awaiting-confirmation" | "confirmed" | "routed" | "completed" | "cancelled" | "superseded" | "interrupted" | "expired";
+export declare const SPOKEN_ACTION_STATES: readonly SpokenActionState[];
+export declare const SPOKEN_ACTION_TERMINAL_STATES: readonly SpokenActionState[];
+export declare const SPOKEN_ACTION_STATE_TRANSITIONS: Readonly<Record<SpokenActionState, readonly SpokenActionState[]>>;
+export declare function isSpokenActionState(value: unknown): value is SpokenActionState;
+export declare function canTransitionSpokenAction(from: SpokenActionState, to: SpokenActionState): boolean;
+export declare function isTerminalSpokenActionState(state: SpokenActionState): boolean;
+export declare function assertNeverSpokenActionState(value: never): never;
+export declare function voiceCanProposeAction(profile: VoiceProfile): boolean;
+export type SpokenActionOutcome = "routed" | "denied" | "cancelled" | "superseded" | "not-applicable";
+export declare const SPOKEN_ACTION_OUTCOMES: readonly SpokenActionOutcome[];
+export declare function isSpokenActionOutcome(value: unknown): value is SpokenActionOutcome;
+export interface SpokenActionConfirmationInput {
+    readonly schemaVersion: typeof VOICE_ACTION_INTENT_SCHEMA_VERSION;
+    readonly committedText: string;
+    readonly turnIndex: number;
+    readonly effectClass: SpokenActionEffectClass;
+    readonly source: VoiceTranscriptSource;
+    readonly committedSegmentCount: number;
+}
+export declare function canonicalizeSpokenActionConfirmation(input: SpokenActionConfirmationInput): string;
+export interface SpokenActionProposal {
+    readonly schemaVersion: typeof VOICE_ACTION_INTENT_SCHEMA_VERSION;
+    readonly effectClass: SpokenActionEffectClass;
+    readonly requiresConfirmation: boolean;
+    readonly state: SpokenActionState;
+    readonly source: VoiceTranscriptSource;
+    readonly turnIndex: number;
+    readonly committedSegmentCount: number;
+    readonly committedChars: number;
+    readonly confirmationInput: SpokenActionConfirmationInput;
+}
+export declare function normalizeSpokenActionProposal(projection: CommittedVoiceTranscriptProjection, profile: VoiceProfile, turnIndex: number, source: VoiceTranscriptSource): SpokenActionProposal | undefined;
+export interface SpokenActionAuditRecord {
+    readonly schemaVersion: typeof VOICE_ACTION_INTENT_SCHEMA_VERSION;
+    readonly effectClass: SpokenActionEffectClass;
+    readonly state: SpokenActionState;
+    readonly confirmationRequired: boolean;
+    readonly confirmed: boolean;
+    readonly outcome: SpokenActionOutcome;
+    readonly source: VoiceTranscriptSource;
+    readonly turnIndex: number;
+    readonly committedSegmentCount: number;
+    readonly committedChars: number;
+    readonly bindingDigest: string;
+}
+export interface SpokenActionAuditInput {
+    readonly effectClass: SpokenActionEffectClass;
+    readonly state: SpokenActionState;
+    readonly confirmationRequired: boolean;
+    readonly confirmed: boolean;
+    readonly outcome: SpokenActionOutcome;
+    readonly source: VoiceTranscriptSource;
+    readonly turnIndex: number;
+    readonly committedSegmentCount: number;
+    readonly committedChars: number;
+    readonly bindingDigest: string;
+}
+export declare function buildSpokenActionAuditRecord(input: SpokenActionAuditInput): SpokenActionAuditRecord;
+export type SpokenActionValidationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reasons: readonly string[];
+};
+export declare function validateSpokenActionProposal(value: unknown): SpokenActionValidationResult;
+export declare function validateSpokenActionAuditRecord(value: unknown): SpokenActionValidationResult;
+//# sourceMappingURL=voice-action-intent.d.ts.map

package/dist/voice-action-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-action-intent.d.ts","sourceRoot":"","sources":["../src/voice-action-intent.ts"],"names":[],"mappings":"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"}

package/dist/voice-action-intent.js

@@ -0,0 +1,387 @@
+// Spoken Action Intent governance contract (Epic #491, Issue #503, ADR-0066). Voice is an UNTRUSTED
+// input source: a committed spoken transcript may PROPOSE an action but can never EXECUTE one or bypass
+// any existing gate. This leaf module DEFINES the deterministic, fail-closed normalization +
+// confirmation layer that sits IN FRONT OF the existing governance (the workflow-handoff request, its
+// user approval gate, `validateWorkflowHandoffRequest`, and `checkPatchAgainstScope`). It ADDS
+// preconditions; it removes none.
+//
+// It is pure data + pure functions only — nothing performs IO, crypto, clock reads, randomness, or audio
+// processing. The audit record (`SpokenActionAuditRecord`) has NO raw text and NO audio field: it carries
+// only closed enums, bools, ints, and a content-free one-way digest computed downstream. The proposal
+// (`SpokenActionProposal`) carries `committedText` ONLY transiently inside `confirmationInput` for the
+// downstream digest derivation (Artifact 2); that seed is never persisted into evidence.
+//
+// Classification is a GUARDRAIL, not a semantic engine. `classifySpokenActionEffect` is deterministic,
+// local (no NLU, no model call), and fail-closed: text it does not recognize as read-only-only resolves
+// to `unknown`, which requires confirmation. Its accuracy is NOT load-bearing for safety, because (a) the
+// default is fail-closed and (b) a proposal never authorizes anything — the existing approval gate and
+// handoff gates still independently apply downstream. Keeping classification on-host and content-free is
+// the strongest posture for the banking / insurer audience.
+//
+// `VOICE_ACTION_INTENT_SCHEMA_VERSION` follows the sibling evolution rule (ADR-0010 D2): a breaking
+// change introduces a NEW literal rather than mutating "1", and it is INDEPENDENT of every other schema
+// version. Leaf-package rule (ADR-0019 direction 1): no cross-package workspace import may appear here;
+// siblings are reached by relative path only.
+import { isVoiceTranscriptSource, voiceTranscriptCaptureAllowed } from "./voice-transcript.js";
+// ─── Schema version ───────────────────────────────────────────────────────────
+export const VOICE_ACTION_INTENT_SCHEMA_VERSION = "1";
+export function isVoiceActionIntentSchemaVersionSupported(version) {
+    return version === VOICE_ACTION_INTENT_SCHEMA_VERSION;
+}
+export const SPOKEN_ACTION_EFFECT_CLASSES = [
+    "read-only",
+    "mutating",
+    "destructive",
+    "external-effect",
+    "unknown",
+];
+export function isSpokenActionEffectClass(value) {
+    return (typeof value === "string" && SPOKEN_ACTION_EFFECT_CLASSES.includes(value));
+}
+export function assertNeverSpokenActionEffectClass(value) {
+    throw new TypeError(`Unhandled SpokenActionEffectClass: ${JSON.stringify(value)}`);
+}
+// Fail-closed confirmation table: every class except `read-only` requires explicit confirmation. Keyed
+// by class for totality (a new class without an entry is a compile error).
+export const SPOKEN_ACTION_EFFECT_REQUIRES_CONFIRMATION = {
+    "read-only": false,
+    mutating: true,
+    destructive: true,
+    "external-effect": true,
+    unknown: true,
+};
+export function spokenActionRequiresConfirmation(effectClass) {
+    return SPOKEN_ACTION_EFFECT_REQUIRES_CONFIRMATION[effectClass];
+}
+export const SPOKEN_ACTION_EFFECT_MARKERS = {
+    destructive: ["delete", "remove", "drop", "purge", "erase", "destroy", "wipe", "truncate"],
+    externalEffect: [
+        "send",
+        "deploy",
+        "publish",
+        "email",
+        "pay",
+        "transfer",
+        "call",
+        "post",
+        "merge",
+    ],
+    mutating: [
+        "create",
+        "add",
+        "update",
+        "edit",
+        "rename",
+        "move",
+        "write",
+        "set",
+        "change",
+        "modify",
+    ],
+    readOnly: [
+        "show",
+        "list",
+        "read",
+        "view",
+        "display",
+        "find",
+        "search",
+        "open",
+        "get",
+        "describe",
+    ],
+};
+// Strip characters that could smuggle an invisible or compatibility-form verb past the ASCII
+// lexicon: C0/C1 controls (\u0000-\u0008, \u000E-\u001F, \u007F-\u009F),
+// zero-width chars (\u200B-\u200D, \uFEFF), and bidi-override controls
+// (\u202A-\u202E, \u2066-\u2069). The standard whitespace controls (\u0009-\u000D:
+// tab/LF/VT/FF/CR) are deliberately EXCLUDED so the later \s+ collapse turns them into a single
+// space and word boundaries survive; stripping them would join adjacent words and silently lose the
+// marker. Without this strip, a destructive verb interrupted by a zero-width char would dodge the
+// marker, misclassify as read-only, and skip confirmation.
+/* eslint-disable no-control-regex -- C0/C1 control ranges are intentional here */
+const UNSAFE_FORMAT_CHARS = /[\u0000-\u0008\u000E-\u001F\u007F-\u009F\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069]/g;
+/* eslint-enable no-control-regex */
+// Inline minimal normalization — leaf cannot import keiko-security. Apply Unicode NFKC FIRST so
+// compatibility forms fold to ASCII (a fullwidth destructive verb folds to its ASCII spelling);
+// otherwise such forms evade the ASCII marker lexicon and a destructive request would misclassify
+// as read-only and skip confirmation. Then strip zero-width / bidi / control chars, lowercase, trim,
+// and collapse internal whitespace runs to single spaces so word-boundary matching is stable. On
+// plain ASCII input NFKC and the strip are the identity, so existing ASCII classification is unchanged.
+function normalizeForClassification(text) {
+    return text
+        .normalize("NFKC")
+        .replace(UNSAFE_FORMAT_CHARS, "")
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, " ");
+}
+// Whole-word membership test: wraps both sides in spaces so `set` does not match inside `settlement`.
+function containsMarker(paddedText, markers) {
+    return markers.some((marker) => paddedText.includes(` ${marker} `));
+}
+// Conservative, ordered precedence: destructive > external-effect > mutating > read-only. Empty /
+// whitespace-only text → `unknown`. Text that matches no recognized marker → `unknown` (fail-closed).
+export function classifySpokenActionEffect(committedText) {
+    const normalized = normalizeForClassification(committedText);
+    if (normalized.length === 0) {
+        return "unknown";
+    }
+    const padded = ` ${normalized} `;
+    if (containsMarker(padded, SPOKEN_ACTION_EFFECT_MARKERS.destructive)) {
+        return "destructive";
+    }
+    if (containsMarker(padded, SPOKEN_ACTION_EFFECT_MARKERS.externalEffect)) {
+        return "external-effect";
+    }
+    if (containsMarker(padded, SPOKEN_ACTION_EFFECT_MARKERS.mutating)) {
+        return "mutating";
+    }
+    if (containsMarker(padded, SPOKEN_ACTION_EFFECT_MARKERS.readOnly)) {
+        return "read-only";
+    }
+    return "unknown";
+}
+export const SPOKEN_ACTION_STATES = [
+    "proposed",
+    "awaiting-confirmation",
+    "confirmed",
+    "routed",
+    "completed",
+    "cancelled",
+    "superseded",
+    "interrupted",
+    "expired",
+];
+export const SPOKEN_ACTION_TERMINAL_STATES = [
+    "completed",
+    "cancelled",
+    "superseded",
+    "interrupted",
+    "expired",
+];
+// The non-terminal invalidation targets every non-terminal state can reach (cancel / supersede /
+// interrupt / expire). Shared so the transition table stays consistent.
+const SPOKEN_ACTION_INVALIDATION_STATES = [
+    "cancelled",
+    "superseded",
+    "interrupted",
+    "expired",
+];
+// Legal state-changing transitions, keyed by state for totality.
+//   read-only path:   proposed → routed → completed
+//   confirm path:     proposed → awaiting-confirmation → confirmed → routed → completed
+//   any non-terminal: → cancelled | superseded | interrupted | expired
+export const SPOKEN_ACTION_STATE_TRANSITIONS = {
+    proposed: ["awaiting-confirmation", "routed", ...SPOKEN_ACTION_INVALIDATION_STATES],
+    "awaiting-confirmation": ["confirmed", ...SPOKEN_ACTION_INVALIDATION_STATES],
+    confirmed: ["routed", ...SPOKEN_ACTION_INVALIDATION_STATES],
+    routed: ["completed", ...SPOKEN_ACTION_INVALIDATION_STATES],
+    completed: [],
+    cancelled: [],
+    superseded: [],
+    interrupted: [],
+    expired: [],
+};
+export function isSpokenActionState(value) {
+    return typeof value === "string" && SPOKEN_ACTION_STATES.includes(value);
+}
+export function canTransitionSpokenAction(from, to) {
+    return SPOKEN_ACTION_STATE_TRANSITIONS[from].includes(to);
+}
+export function isTerminalSpokenActionState(state) {
+    return SPOKEN_ACTION_TERMINAL_STATES.includes(state);
+}
+export function assertNeverSpokenActionState(value) {
+    throw new TypeError(`Unhandled SpokenActionState: ${JSON.stringify(value)}`);
+}
+// ─── Capability gating (AC1 / AC2) ───────────────────────────────────────────────
+// Derived from the voice transcript capability so it cannot drift: a spoken action can be proposed only
+// where committed transcript capture is allowed (`speech-to-text` / `full-realtime`). `none` and
+// `speech-output` (playback-only) make the whole layer dormant (AC1). The text path never calls this.
+export function voiceCanProposeAction(profile) {
+    return voiceTranscriptCaptureAllowed(profile);
+}
+export const SPOKEN_ACTION_OUTCOMES = [
+    "routed",
+    "denied",
+    "cancelled",
+    "superseded",
+    "not-applicable",
+];
+export function isSpokenActionOutcome(value) {
+    return typeof value === "string" && SPOKEN_ACTION_OUTCOMES.includes(value);
+}
+// Deterministic, stable field ordering with length-prefixed segments so no field's content can be
+// confused with another's (a classic canonicalization ambiguity). Pure string; no crypto here.
+export function canonicalizeSpokenActionConfirmation(input) {
+    const fields = [
+        `v=${input.schemaVersion}`,
+        `turn=${String(input.turnIndex)}`,
+        `effect=${input.effectClass}`,
+        `source=${input.source}`,
+        `segments=${String(input.committedSegmentCount)}`,
+        `textlen=${String(input.committedText.length)}`,
+        `text=${input.committedText}`,
+    ];
+    return fields.join("\n");
+}
+// AC1/AC2 entry gate: returns `undefined` when the profile cannot propose actions (AC1) or the committed
+// projection carries no text (AC2). Partial / stable / discarded / redacted / superseded segments can
+// never appear in `projection.text` by construction (`selectCommittedVoiceTranscript`), so a non-empty
+// projection text already means committed content only.
+export function normalizeSpokenActionProposal(projection, profile, turnIndex, source) {
+    if (!voiceCanProposeAction(profile)) {
+        return undefined;
+    }
+    const committedText = projection.text;
+    if (committedText.trim().length === 0) {
+        return undefined;
+    }
+    const effectClass = classifySpokenActionEffect(committedText);
+    const requiresConfirmation = spokenActionRequiresConfirmation(effectClass);
+    const confirmationInput = {
+        schemaVersion: VOICE_ACTION_INTENT_SCHEMA_VERSION,
+        committedText,
+        turnIndex,
+        effectClass,
+        source,
+        committedSegmentCount: projection.segmentCount,
+    };
+    return {
+        schemaVersion: VOICE_ACTION_INTENT_SCHEMA_VERSION,
+        effectClass,
+        requiresConfirmation,
+        state: requiresConfirmation ? "awaiting-confirmation" : "proposed",
+        source,
+        turnIndex,
+        committedSegmentCount: projection.segmentCount,
+        committedChars: committedText.length,
+        confirmationInput,
+    };
+}
+// Pure builder. Copies only the content-free fields; structurally cannot carry committed text because no
+// text field exists on either the input or the record.
+export function buildSpokenActionAuditRecord(input) {
+    return {
+        schemaVersion: VOICE_ACTION_INTENT_SCHEMA_VERSION,
+        effectClass: input.effectClass,
+        state: input.state,
+        confirmationRequired: input.confirmationRequired,
+        confirmed: input.confirmed,
+        outcome: input.outcome,
+        source: input.source,
+        turnIndex: input.turnIndex,
+        committedSegmentCount: input.committedSegmentCount,
+        committedChars: input.committedChars,
+        bindingDigest: input.bindingDigest,
+    };
+}
+function buildSpokenActionResult(reasons) {
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+// A binding digest is either the empty string (no confirmation bound) or a 64-char lowercase sha256 hex.
+const BINDING_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+function isValidBindingDigest(value) {
+    return value === "" || (typeof value === "string" && BINDING_DIGEST_PATTERN.test(value));
+}
+// Shared count-field check used by both record validators: turnIndex / committedSegmentCount /
+// committedChars must each be non-negative integers. Extracting it keeps both validators under the
+// complexity cap and keeps the reason strings identical across record shapes.
+function validateCommittedCounts(value, reasons) {
+    if (!isNonNegativeInteger(value.turnIndex)) {
+        reasons.push("turnIndex: must be a non-negative integer");
+    }
+    if (!isNonNegativeInteger(value.committedSegmentCount)) {
+        reasons.push("committedSegmentCount: must be a non-negative integer");
+    }
+    if (!isNonNegativeInteger(value.committedChars)) {
+        reasons.push("committedChars: must be a non-negative integer");
+    }
+}
+function validateConfirmationInput(value, reasons) {
+    if (!isRecord(value)) {
+        reasons.push("confirmationInput: must be an object");
+        return;
+    }
+    if (!isVoiceActionIntentSchemaVersionSupported(value.schemaVersion)) {
+        reasons.push("confirmationInput.schemaVersion: unsupported");
+    }
+    if (typeof value.committedText !== "string") {
+        reasons.push("confirmationInput.committedText: must be a string");
+    }
+    if (!isNonNegativeInteger(value.turnIndex)) {
+        reasons.push("confirmationInput.turnIndex: must be a non-negative integer");
+    }
+    if (!isSpokenActionEffectClass(value.effectClass)) {
+        reasons.push("confirmationInput.effectClass: unknown effect class");
+    }
+    if (!isVoiceTranscriptSource(value.source)) {
+        reasons.push("confirmationInput.source: unknown transcript source");
+    }
+    if (!isNonNegativeInteger(value.committedSegmentCount)) {
+        reasons.push("confirmationInput.committedSegmentCount: must be a non-negative integer");
+    }
+}
+export function validateSpokenActionProposal(value) {
+    if (!isRecord(value)) {
+        return { ok: false, reasons: ["proposal: must be an object"] };
+    }
+    const reasons = [];
+    if (!isVoiceActionIntentSchemaVersionSupported(value.schemaVersion)) {
+        reasons.push("schemaVersion: unsupported");
+    }
+    if (!isSpokenActionEffectClass(value.effectClass)) {
+        reasons.push("effectClass: unknown effect class");
+    }
+    if (typeof value.requiresConfirmation !== "boolean") {
+        reasons.push("requiresConfirmation: must be a boolean");
+    }
+    if (!isSpokenActionState(value.state)) {
+        reasons.push("state: unknown spoken action state");
+    }
+    if (!isVoiceTranscriptSource(value.source)) {
+        reasons.push("source: unknown transcript source");
+    }
+    validateCommittedCounts(value, reasons);
+    validateConfirmationInput(value.confirmationInput, reasons);
+    return buildSpokenActionResult(reasons);
+}
+export function validateSpokenActionAuditRecord(value) {
+    if (!isRecord(value)) {
+        return { ok: false, reasons: ["audit: must be an object"] };
+    }
+    const reasons = [];
+    if (!isVoiceActionIntentSchemaVersionSupported(value.schemaVersion)) {
+        reasons.push("schemaVersion: unsupported");
+    }
+    if (!isSpokenActionEffectClass(value.effectClass)) {
+        reasons.push("effectClass: unknown effect class");
+    }
+    if (!isSpokenActionState(value.state)) {
+        reasons.push("state: unknown spoken action state");
+    }
+    if (typeof value.confirmationRequired !== "boolean") {
+        reasons.push("confirmationRequired: must be a boolean");
+    }
+    if (typeof value.confirmed !== "boolean") {
+        reasons.push("confirmed: must be a boolean");
+    }
+    if (!isSpokenActionOutcome(value.outcome)) {
+        reasons.push("outcome: unknown outcome");
+    }
+    if (!isVoiceTranscriptSource(value.source)) {
+        reasons.push("source: unknown transcript source");
+    }
+    validateCommittedCounts(value, reasons);
+    if (!isValidBindingDigest(value.bindingDigest)) {
+        reasons.push("bindingDigest: must be empty or a 64-char lowercase sha256 hex");
+    }
+    return buildSpokenActionResult(reasons);
+}

package/dist/voice-playback.d.ts

@@ -0,0 +1,50 @@
+import type { VoiceProfile } from "./gateway.js";
+import type { VoicePlaybackState, VoiceReplayClass, VoiceRedactionClass } from "./voice-protocol.js";
+export declare const VOICE_PLAYBACK_SCHEMA_VERSION: "1";
+export declare function isVoicePlaybackSchemaVersionSupported(version: unknown): boolean;
+export type VoicePlaybackPhase = "unavailable" | "preparing" | "speaking" | "paused" | "interrupted" | "canceled" | "failed" | "complete";
+export declare const VOICE_PLAYBACK_PHASES: readonly VoicePlaybackPhase[];
+export declare const VOICE_PLAYBACK_ACTIVE_PHASES: readonly VoicePlaybackPhase[];
+export declare const VOICE_PLAYBACK_SETTLED_PHASES: readonly VoicePlaybackPhase[];
+export type VoicePlaybackFailureKind = "rate-limited" | "timeout" | "provider-error" | "unavailable" | "internal";
+export declare const VOICE_PLAYBACK_FAILURE_KINDS: readonly VoicePlaybackFailureKind[];
+export declare const VOICE_PLAYBACK_PHASE_REPLAY: Record<VoicePlaybackPhase, VoiceReplayClass>;
+export declare const VOICE_PLAYBACK_PHASE_REDACTION: Record<VoicePlaybackPhase, VoiceRedactionClass>;
+export declare const VOICE_PLAYBACK_AUDIO_PLANE: import("./voice-protocol.js").VoiceMediaPlaneDescriptor;
+export declare const VOICE_PLAYBACK_TRANSITIONS: Record<VoicePlaybackPhase, readonly VoicePlaybackPhase[]>;
+export declare function isVoicePlaybackPhase(value: unknown): value is VoicePlaybackPhase;
+export declare function isVoicePlaybackFailureKind(value: unknown): value is VoicePlaybackFailureKind;
+export declare function voicePlaybackPhaseReplayClass(phase: VoicePlaybackPhase): VoiceReplayClass;
+export declare function voicePlaybackPhaseRedactionClass(phase: VoicePlaybackPhase): VoiceRedactionClass;
+export declare function isActiveVoicePlaybackPhase(phase: VoicePlaybackPhase): boolean;
+export declare function isSettledVoicePlaybackPhase(phase: VoicePlaybackPhase): boolean;
+export declare function canTransitionVoicePlayback(from: VoicePlaybackPhase, to: VoicePlaybackPhase): boolean;
+export declare function assertNeverVoicePlaybackPhase(phase: never): never;
+export declare function mapVoicePlaybackPhaseToWireState(phase: VoicePlaybackPhase): VoicePlaybackState | undefined;
+export type VoicePlaybackEffect = "request-synthesis" | "start-output" | "pause-output" | "resume-output" | "stop-output" | "mute-output" | "unmute-output" | "notify-turn-speech-start" | "notify-turn-speech-completed" | "notify-turn-speech-stopped" | "notify-turn-interrupt";
+export declare const VOICE_PLAYBACK_EFFECTS: readonly VoicePlaybackEffect[];
+export declare function isVoicePlaybackEffect(value: unknown): value is VoicePlaybackEffect;
+export declare function voicePlaybackAllowedForProfile(profile: VoiceProfile): boolean;
+export declare function voicePlaybackInterruptAllowedForProfile(profile: VoiceProfile): boolean;
+export declare function initialVoicePlaybackPhase(_profile: VoiceProfile): VoicePlaybackPhase;
+export interface VoicePlaybackTurnSummary {
+    readonly schemaVersion: typeof VOICE_PLAYBACK_SCHEMA_VERSION;
+    readonly phase: VoicePlaybackPhase;
+    readonly available: boolean;
+    readonly spoke: boolean;
+    readonly completed: boolean;
+    readonly interrupted: boolean;
+    readonly failed: boolean;
+    readonly interruptions: number;
+    readonly replays: number;
+    readonly failureKind?: VoicePlaybackFailureKind | undefined;
+}
+export declare function summarizeVoicePlaybackTurn(input: {
+    readonly phase: VoicePlaybackPhase;
+    readonly available: boolean;
+    readonly spoke: boolean;
+    readonly interruptions: number;
+    readonly replays: number;
+    readonly failureKind?: VoicePlaybackFailureKind | undefined;
+}): VoicePlaybackTurnSummary;
+//# sourceMappingURL=voice-playback.d.ts.map

package/dist/voice-playback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-playback.d.ts","sourceRoot":"","sources":["../src/voice-playback.ts"],"names":[],"mappings":"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"}