@oscharko-dev/keiko-contracts 0.2.8 → 0.2.9

package/dist/voice-protocol.js

@@ -0,0 +1,312 @@
+// Public type contracts for the optional Voice Digital Twin control / media protocol (Epic #491,
+// Issue #496, ADR-0059). This module DEFINES the wire protocol; it implements no transport. It is
+// pure data + pure validators only — nothing performs IO, crypto, clock reads, randomness, or audio
+// processing, and no provider base URL, credential, or raw audio buffer is ever a field on these
+// types. The `VOICE_PROTOCOL_VERSION` discriminant follows the same evolution rule as
+// `WORKFLOW_HANDOFF_SCHEMA_VERSION` / `CONNECTED_CONTEXT_SCHEMA_VERSION`: a breaking change introduces
+// a NEW literal member rather than mutating "1". It is INDEPENDENT of
+// `CONVERSATION_CAPABILITY_CONTRACT_VERSION` (the capability registry contract, gateway.ts) and never
+// bumps it. Leaf-package rule (ADR-0019 direction 1): no `@oscharko-dev/keiko-*` imports may appear
+// here; sibling types are reached by relative path.
+//
+// The protocol separates two planes (AC1): the WebSocket control / signaling plane (every message
+// kind in this module) and the WebRTC media plane (raw audio frames). Raw audio is never a control
+// message and is never replayed or persisted by default (AC5). Today the control-plane role is
+// realized on the existing loopback HTTP + Server-Sent Events seam; a bidirectional WebSocket upgrade
+// is an explicit, ADR-gated transport decision owned by Issue #497 (ADR-0058 D3 / ADR-0059).
+// ─── Protocol version ─────────────────────────────────────────────────────────
+export const VOICE_PROTOCOL_VERSION = "1";
+// Compatibility / negotiation rule: a peer accepts a message only when its declared protocol version
+// is one this build understands. v1 understands exactly "1"; a future v2 build widens this set.
+export function isVoiceProtocolVersionSupported(version) {
+    return version === VOICE_PROTOCOL_VERSION;
+}
+export const VOICE_PLANES = ["control", "media"];
+export const VOICE_CONTROL_TRANSPORTS = [
+    "loopback-http-sse",
+    "loopback-websocket",
+];
+// The realization in effect for v1. Recorded as a constant so the spec and the implementing transport
+// issue (#497) share one source of truth and any change is an explicit edit, not a silent drift.
+export const VOICE_CONTROL_TRANSPORT_V1 = "loopback-http-sse";
+export const VOICE_MEDIA_TRANSPORTS = [
+    "none",
+    "gateway-batch",
+    "webrtc",
+];
+export const VOICE_NEGOTIATION_MODES = [
+    "proxied-sdp",
+    "direct-ephemeral",
+    "disabled",
+];
+export const PREFERRED_VOICE_NEGOTIATION_MODE = "proxied-sdp";
+export const VOICE_REPLAY_CLASSES = [
+    "replayable",
+    "ephemeral",
+    "never-persisted",
+];
+export const VOICE_REDACTION_CLASSES = [
+    "content-free",
+    "reviewable-text",
+    "secret-bearing",
+    "raw-media",
+];
+export const VOICE_MESSAGE_DIRECTIONS = [
+    "client-to-host",
+    "host-to-client",
+];
+export const VOICE_MEDIA_TRACK_KINDS = [
+    "audio-in",
+    "audio-out",
+];
+export const VOICE_MEDIA_PLANE = {
+    plane: "media",
+    transport: "webrtc",
+    trackKinds: VOICE_MEDIA_TRACK_KINDS,
+    replay: "never-persisted",
+    redaction: "raw-media",
+};
+export const VOICE_CONTROL_MESSAGE_KINDS = [
+    "session.create",
+    "session.created",
+    "session.close",
+    "session.closed",
+    "capability.offer",
+    "capability.select",
+    "signal.sdp.offer",
+    "signal.sdp.answer",
+    "signal.ice.candidate",
+    "media.track.state",
+    "control.cancel",
+    "control.interrupt",
+    "transcript.partial",
+    "transcript.committed",
+    "transcript.discarded",
+    "playback.state",
+    "policy.decision",
+    "error",
+];
+export const VOICE_DATA_CHANNEL_EVENT_KINDS = [
+    "control.interrupt",
+    "transcript.partial",
+    "playback.state",
+];
+export const VOICE_SESSION_CLOSE_REASONS = [
+    "client-request",
+    "host-request",
+    "policy-disabled",
+    "provider-unreachable",
+    "timeout",
+    "protocol-error",
+];
+export const VOICE_MEDIA_TRACK_STATES = [
+    "negotiating",
+    "live",
+    "muted",
+    "ended",
+];
+export const VOICE_PLAYBACK_STATES = [
+    "idle",
+    "playing",
+    "paused",
+    "stopped",
+    "interrupted",
+];
+export const VOICE_POLICY_DECISIONS = [
+    "allow",
+    "deny",
+    "degrade",
+];
+export const VOICE_PROTOCOL_ERROR_CODES = [
+    "unsupported-version",
+    "invalid-message",
+    "capability-unavailable",
+    "not-allowed-for-profile",
+    "negotiation-failed",
+    "rate-limited",
+    "internal",
+];
+// ─── Per-kind classification tables ─────────────────────────────────────────────
+// Keyed by `VoiceControlMessageKind` so adding a kind without classifying it is a compile error
+// (totality). No control kind is ever `raw-media` — that classification is media-plane only (AC1).
+export const VOICE_CONTROL_MESSAGE_REPLAY = {
+    "session.create": "replayable",
+    "session.created": "replayable",
+    "session.close": "replayable",
+    "session.closed": "replayable",
+    "capability.offer": "replayable",
+    "capability.select": "replayable",
+    "signal.sdp.offer": "ephemeral",
+    "signal.sdp.answer": "ephemeral",
+    "signal.ice.candidate": "ephemeral",
+    "media.track.state": "replayable",
+    "control.cancel": "replayable",
+    "control.interrupt": "replayable",
+    "transcript.partial": "ephemeral",
+    "transcript.committed": "replayable",
+    "transcript.discarded": "replayable",
+    "playback.state": "replayable",
+    "policy.decision": "replayable",
+    error: "replayable",
+};
+export const VOICE_CONTROL_MESSAGE_REDACTION = {
+    "session.create": "content-free",
+    "session.created": "content-free",
+    "session.close": "content-free",
+    "session.closed": "content-free",
+    "capability.offer": "content-free",
+    "capability.select": "content-free",
+    "signal.sdp.offer": "secret-bearing",
+    "signal.sdp.answer": "secret-bearing",
+    "signal.ice.candidate": "secret-bearing",
+    "media.track.state": "content-free",
+    "control.cancel": "content-free",
+    "control.interrupt": "content-free",
+    "transcript.partial": "reviewable-text",
+    "transcript.committed": "reviewable-text",
+    "transcript.discarded": "content-free",
+    "playback.state": "content-free",
+    "policy.decision": "content-free",
+    error: "content-free",
+};
+// ─── Capability-gating & fallback state table (Deliverable; AC2, AC3) ───────────
+// The control-message kinds permitted for each effective voice profile. `none` permits NOTHING — the
+// deterministic disabled behavior of AC2. `speech-to-text` permits the controlled-dictation control
+// subset WITHOUT any WebRTC signaling, media-track, interruption, or playback message — STT-only
+// dictation never requires the full-realtime media path (AC3). `full-realtime` permits every kind.
+export const VOICE_PROFILE_ALLOWED_MESSAGE_KINDS = {
+    none: [],
+    "speech-to-text": [
+        "session.create",
+        "session.created",
+        "session.close",
+        "session.closed",
+        "capability.offer",
+        "capability.select",
+        "control.cancel",
+        "transcript.partial",
+        "transcript.committed",
+        "transcript.discarded",
+        "policy.decision",
+        "error",
+    ],
+    "speech-output": [
+        "session.create",
+        "session.created",
+        "session.close",
+        "session.closed",
+        "capability.offer",
+        "capability.select",
+        "control.cancel",
+        "control.interrupt",
+        "playback.state",
+        "policy.decision",
+        "error",
+    ],
+    "full-realtime": [...VOICE_CONTROL_MESSAGE_KINDS],
+};
+// The media-plane transport and browser↔provider negotiation mode that each profile resolves to.
+export const VOICE_PROFILE_MEDIA_TRANSPORT = {
+    none: "none",
+    "speech-to-text": "gateway-batch",
+    "speech-output": "gateway-batch",
+    "full-realtime": "webrtc",
+};
+export const VOICE_PROFILE_NEGOTIATION_MODE = {
+    none: "disabled",
+    "speech-to-text": "disabled",
+    "speech-output": "disabled",
+    "full-realtime": "proxied-sdp",
+};
+// Defaults are conservative, controlled-network-friendly bounds. The implementing transport issue
+// (#497) polices them against its own clock; the contracts package is a leaf and reads no clock.
+export const DEFAULT_VOICE_PROTOCOL_TIMEOUTS = {
+    sessionCreateMs: 10_000,
+    signalingMs: 15_000,
+    heartbeatIntervalMs: 15_000,
+    reconnectBackoffInitialMs: 500,
+    reconnectBackoffMaxMs: 10_000,
+    maxReconnectAttempts: 5,
+};
+// ─── Type guards & lookups ───────────────────────────────────────────────────────
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyTrimmed(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isFiniteNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+export function isVoiceControlMessageKind(value) {
+    return (typeof value === "string" && VOICE_CONTROL_MESSAGE_KINDS.includes(value));
+}
+export function isVoiceMessageDirection(value) {
+    return (typeof value === "string" && VOICE_MESSAGE_DIRECTIONS.includes(value));
+}
+export function isVoiceNegotiationMode(value) {
+    return (typeof value === "string" && VOICE_NEGOTIATION_MODES.includes(value));
+}
+// The replay class for a control-message kind. `replayable` events are the ones a reconnect
+// re-delivers (AC5); `ephemeral` and the media plane's `never-persisted` are excluded.
+export function voiceControlMessageReplayClass(kind) {
+    return VOICE_CONTROL_MESSAGE_REPLAY[kind];
+}
+export function voiceControlMessageRedactionClass(kind) {
+    return VOICE_CONTROL_MESSAGE_REDACTION[kind];
+}
+// AC5: a control-message kind is replay-eligible only when classified `replayable`. Raw audio is
+// media-plane (`never-persisted`) and has no control kind, so it can never be replay-eligible.
+export function isVoiceReplayEligible(kind) {
+    return VOICE_CONTROL_MESSAGE_REPLAY[kind] === "replayable";
+}
+// AC2 / AC3: whether a kind is permitted for an effective profile. `none` permits nothing.
+export function voiceMessageAllowedForProfile(kind, profile) {
+    return VOICE_PROFILE_ALLOWED_MESSAGE_KINDS[profile].includes(kind);
+}
+// Exhaustiveness guard: a `default`/fall-through that reaches this fails to type-check if a new
+// `VoiceControlMessageKind` is added without handling, mirroring `assertNeverMemoryType`.
+export function assertNeverVoiceControlMessageKind(kind) {
+    throw new Error(`unhandled voice control message kind: ${JSON.stringify(kind)}`);
+}
+// ─── Envelope validation ─────────────────────────────────────────────────────────
+function validateEnvelope(value, reasons) {
+    if (!isVoiceProtocolVersionSupported(value.protocolVersion)) {
+        reasons.push("protocolVersion unsupported");
+    }
+    if (!isNonEmptyTrimmed(value.sessionId)) {
+        reasons.push("sessionId must be a non-empty string");
+    }
+    if (!isFiniteNonNegativeInteger(value.seq)) {
+        reasons.push("seq must be a non-negative integer");
+    }
+    if (!isVoiceMessageDirection(value.direction)) {
+        reasons.push("direction invalid");
+    }
+    if (!isVoiceControlMessageKind(value.kind)) {
+        reasons.push("kind invalid");
+    }
+}
+// Structural guard for the shared envelope (version + sessionId + seq + direction + kind). Per-kind
+// payload typing is recovered by narrowing on `kind` once the envelope is known to be well-formed.
+export function isVoiceControlMessage(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (isVoiceProtocolVersionSupported(value.protocolVersion) &&
+        isNonEmptyTrimmed(value.sessionId) &&
+        isFiniteNonNegativeInteger(value.seq) &&
+        isVoiceMessageDirection(value.direction) &&
+        isVoiceControlMessageKind(value.kind));
+}
+// Deep validation of the shared envelope, returning every reason it is malformed. Per-kind payload
+// fields are owned and validated by the implementing transport issue (#497); the contract pins the
+// envelope, the kind catalog, and the version-compatibility rule.
+export function validateVoiceControlMessage(value) {
+    if (!isRecord(value)) {
+        return { ok: false, reasons: ["message must be an object"] };
+    }
+    const reasons = [];
+    validateEnvelope(value, reasons);
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}

package/dist/voice-transcript.d.ts

@@ -0,0 +1,57 @@
+import type { VoiceProfile } from "./gateway.js";
+import type { VoiceControlMessageKind, VoiceRedactionClass, VoiceReplayClass } from "./voice-protocol.js";
+export declare const VOICE_TRANSCRIPT_SCHEMA_VERSION: "1";
+export declare function isVoiceTranscriptSchemaVersionSupported(version: unknown): boolean;
+export type VoiceTranscriptSegmentState = "partial" | "stable" | "committed" | "corrected" | "discarded" | "redacted" | "provider-error";
+export declare const VOICE_TRANSCRIPT_SEGMENT_STATES: readonly VoiceTranscriptSegmentState[];
+export declare const VOICE_TRANSCRIPT_CONSUMABLE_STATES: readonly VoiceTranscriptSegmentState[];
+export type VoiceTranscriptProviderErrorKind = "rate-limited" | "timeout" | "provider-error" | "unavailable" | "internal";
+export declare const VOICE_TRANSCRIPT_PROVIDER_ERROR_KINDS: readonly VoiceTranscriptProviderErrorKind[];
+export type VoiceTranscriptSource = "dictation" | "realtime";
+export declare const VOICE_TRANSCRIPT_SOURCES: readonly VoiceTranscriptSource[];
+export interface VoiceTranscriptSegment {
+    readonly id: string;
+    readonly seq: number;
+    readonly state: VoiceTranscriptSegmentState;
+    readonly text: string;
+    readonly source: VoiceTranscriptSource;
+    readonly revision: number;
+    readonly replayClass: VoiceReplayClass;
+    readonly redactionClass: VoiceRedactionClass;
+    readonly supersedesId?: string | undefined;
+    readonly providerErrorKind?: VoiceTranscriptProviderErrorKind | undefined;
+}
+export declare const VOICE_TRANSCRIPT_SEGMENT_REPLAY: Record<VoiceTranscriptSegmentState, VoiceReplayClass>;
+export declare const VOICE_TRANSCRIPT_SEGMENT_REDACTION: Record<VoiceTranscriptSegmentState, VoiceRedactionClass>;
+export declare const VOICE_TRANSCRIPT_SEGMENT_TRANSITIONS: Record<VoiceTranscriptSegmentState, readonly VoiceTranscriptSegmentState[]>;
+export declare function isVoiceTranscriptSegmentState(value: unknown): value is VoiceTranscriptSegmentState;
+export declare function isVoiceTranscriptProviderErrorKind(value: unknown): value is VoiceTranscriptProviderErrorKind;
+export declare function isVoiceTranscriptSource(value: unknown): value is VoiceTranscriptSource;
+export declare function voiceTranscriptSegmentReplayClass(state: VoiceTranscriptSegmentState): VoiceReplayClass;
+export declare function voiceTranscriptSegmentRedactionClass(state: VoiceTranscriptSegmentState): VoiceRedactionClass;
+export declare function canTransitionVoiceTranscriptSegment(from: VoiceTranscriptSegmentState, to: VoiceTranscriptSegmentState): boolean;
+export declare function isCommittedVoiceTranscriptState(state: VoiceTranscriptSegmentState): boolean;
+export declare function assertNeverVoiceTranscriptSegmentState(state: never): never;
+export declare function mapWireKindToVoiceTranscriptSegmentState(kind: VoiceControlMessageKind): VoiceTranscriptSegmentState | undefined;
+export declare function voiceTranscriptCaptureAllowed(profile: VoiceProfile): boolean;
+export declare function voiceTranscriptPreviewAllowed(profile: VoiceProfile): boolean;
+export interface CommittedVoiceTranscriptProjection {
+    readonly schemaVersion: typeof VOICE_TRANSCRIPT_SCHEMA_VERSION;
+    readonly segments: readonly VoiceTranscriptSegment[];
+    readonly text: string;
+    readonly segmentCount: number;
+}
+export declare function selectCommittedVoiceTranscript(segments: readonly VoiceTranscriptSegment[]): CommittedVoiceTranscriptProjection;
+export interface VoiceTranscriptEvidenceSummary {
+    readonly schemaVersion: typeof VOICE_TRANSCRIPT_SCHEMA_VERSION;
+    readonly segmentCount: number;
+    readonly committedCount: number;
+    readonly correctedCount: number;
+    readonly discardedCount: number;
+    readonly redactedCount: number;
+    readonly providerErrorCount: number;
+    readonly committedChars: number;
+    readonly highestSeq: number;
+}
+export declare function summarizeVoiceTranscript(segments: readonly VoiceTranscriptSegment[]): VoiceTranscriptEvidenceSummary;
+//# sourceMappingURL=voice-transcript.d.ts.map

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

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

package/dist/voice-transcript.js

@@ -0,0 +1,221 @@
+// Public type contract for the optional Voice Digital Twin transcript segment lifecycle (Epic #491,
+// Issue #500, ADR-0063). This module DEFINES the provider-neutral semantics that let Keiko distinguish
+// uncertain partial text, provider-stabilised text, user/turn-committed text, provider corrections, and
+// discarded / redacted / failed text. It is pure data + pure functions only — nothing performs IO,
+// crypto, clock reads, randomness, or audio processing, and no provider base URL, credential, or raw
+// audio buffer is ever a field on these types.
+//
+// It is layered ABOVE the #496 wire protocol (voice-protocol.ts): the wire carries only three transcript
+// message kinds (`transcript.partial`, `transcript.committed`, `transcript.discarded`), whereas the
+// lifecycle here has seven segment STATES. Only the three states that have a wire kind round-trip on the
+// wire (`mapWireKindToVoiceTranscriptSegmentState`); `stable`, `corrected`, `redacted`, and
+// `provider-error` are derived/internal states with no wire kind, exactly as the #499 turn manager maps
+// a richer semantic signal set onto the same wire catalog (ADR-0062). The stateful reducer that drives
+// these states lives in keiko-ui (`voice-transcript-segments.ts`) as a synchronous deterministic engine;
+// this leaf contract holds the state catalog, the classification tables, the legal-transition table, the
+// validators, and the AC5 committed-only integration boundary so server-side consumers (#503 governed
+// spoken actions and memory review) can enforce committed-only consumption without forking the reducer.
+//
+// `VOICE_TRANSCRIPT_SCHEMA_VERSION` follows the same evolution rule as `VOICE_PROTOCOL_VERSION`: a
+// breaking change introduces a NEW literal rather than mutating "1". It is INDEPENDENT of the wire
+// `VOICE_PROTOCOL_VERSION` and of `CONVERSATION_CAPABILITY_CONTRACT_VERSION`. Leaf-package rule
+// (ADR-0019 direction 1): no `@oscharko-dev/keiko-*` imports may appear here; sibling types are reached
+// by relative path.
+import { voiceMessageAllowedForProfile } from "./voice-protocol.js";
+// ─── Schema version ───────────────────────────────────────────────────────────
+export const VOICE_TRANSCRIPT_SCHEMA_VERSION = "1";
+export function isVoiceTranscriptSchemaVersionSupported(version) {
+    return version === VOICE_TRANSCRIPT_SCHEMA_VERSION;
+}
+export const VOICE_TRANSCRIPT_SEGMENT_STATES = [
+    "partial",
+    "stable",
+    "committed",
+    "corrected",
+    "discarded",
+    "redacted",
+    "provider-error",
+];
+// The two states whose text downstream integrations (memory, workflow, evaluation) may consume.
+// This is the load-bearing AC5 invariant expressed as data: a segment's text crosses the integration
+// boundary if and only if its state is in this set.
+export const VOICE_TRANSCRIPT_CONSUMABLE_STATES = [
+    "committed",
+    "corrected",
+];
+export const VOICE_TRANSCRIPT_PROVIDER_ERROR_KINDS = [
+    "rate-limited",
+    "timeout",
+    "provider-error",
+    "unavailable",
+    "internal",
+];
+export const VOICE_TRANSCRIPT_SOURCES = [
+    "dictation",
+    "realtime",
+];
+// ─── Per-state classification tables (aligned to voice-protocol.ts) ──────────────
+// Keyed by `VoiceTranscriptSegmentState` so adding a state without classifying it is a compile error
+// (totality). The classes are the same `VoiceReplayClass` / `VoiceRedactionClass` the wire protocol
+// uses, so a segment and the wire message it derives from agree on replay and redaction treatment.
+//
+// Replay (AC5 reconnect semantics): the durable, committed lifecycle facts (`committed`, `corrected`,
+// `discarded`, `redacted`, `provider-error`) are `replayable`; the in-flight `partial` / `stable`
+// previews are `ephemeral` and a reconnect never re-delivers them, mirroring `transcript.partial`.
+export const VOICE_TRANSCRIPT_SEGMENT_REPLAY = {
+    partial: "ephemeral",
+    stable: "ephemeral",
+    committed: "replayable",
+    corrected: "replayable",
+    discarded: "replayable",
+    redacted: "replayable",
+    "provider-error": "replayable",
+};
+// Redaction: the text-bearing states (`partial`, `stable`, `committed`, `corrected`) are
+// `reviewable-text` — they must pass through the existing `stripUnsafeFormatChars` + redact-at-persist
+// seam before any log or evidence manifest. The
+// content-free states carry no reviewable text, so they are `content-free`.
+export const VOICE_TRANSCRIPT_SEGMENT_REDACTION = {
+    partial: "reviewable-text",
+    stable: "reviewable-text",
+    committed: "reviewable-text",
+    corrected: "reviewable-text",
+    discarded: "content-free",
+    redacted: "content-free",
+    "provider-error": "content-free",
+};
+// ─── Legal transition table (Deliverable: reducer/state machine rules) ───────────
+// The set of states reachable from a given state by a state-CHANGING transition. Repeated operations
+// that keep the same state (partial-text churn, re-correction) are text updates handled by the reducer,
+// not transitions, so they are intentionally absent here. `discarded` and `redacted` are terminal.
+// Keyed by state for totality.
+// A correction targets already-finalised text, so `partial` has no direct edge to `corrected`
+// (an in-flight partial is refined by further partials, then stabilised/committed, then corrected).
+// `committed`/`corrected` never regress to `provider-error`: a provider failure can only affect text
+// that has not yet been committed.
+export const VOICE_TRANSCRIPT_SEGMENT_TRANSITIONS = {
+    partial: ["stable", "committed", "discarded", "redacted", "provider-error"],
+    stable: ["committed", "corrected", "discarded", "redacted", "provider-error"],
+    committed: ["corrected", "discarded", "redacted"],
+    corrected: ["discarded", "redacted"],
+    discarded: [],
+    redacted: [],
+    "provider-error": ["discarded", "redacted"],
+};
+// ─── Type guards & lookups ───────────────────────────────────────────────────────
+export function isVoiceTranscriptSegmentState(value) {
+    return (typeof value === "string" &&
+        VOICE_TRANSCRIPT_SEGMENT_STATES.includes(value));
+}
+export function isVoiceTranscriptProviderErrorKind(value) {
+    return (typeof value === "string" &&
+        VOICE_TRANSCRIPT_PROVIDER_ERROR_KINDS.includes(value));
+}
+export function isVoiceTranscriptSource(value) {
+    return (typeof value === "string" && VOICE_TRANSCRIPT_SOURCES.includes(value));
+}
+export function voiceTranscriptSegmentReplayClass(state) {
+    return VOICE_TRANSCRIPT_SEGMENT_REPLAY[state];
+}
+export function voiceTranscriptSegmentRedactionClass(state) {
+    return VOICE_TRANSCRIPT_SEGMENT_REDACTION[state];
+}
+// Whether `to` is reachable from `from` by a legal state-changing transition.
+export function canTransitionVoiceTranscriptSegment(from, to) {
+    return VOICE_TRANSCRIPT_SEGMENT_TRANSITIONS[from].includes(to);
+}
+// AC5: a segment's text is consumable downstream iff it is committed or corrected.
+export function isCommittedVoiceTranscriptState(state) {
+    return VOICE_TRANSCRIPT_CONSUMABLE_STATES.includes(state);
+}
+// Exhaustiveness guard: a `default`/fall-through that reaches this fails to type-check if a new
+// `VoiceTranscriptSegmentState` is added without handling, mirroring `assertNeverVoiceControlMessageKind`.
+export function assertNeverVoiceTranscriptSegmentState(state) {
+    throw new Error(`unhandled voice transcript segment state: ${JSON.stringify(state)}`);
+}
+// ─── Wire-kind ↔ state mapping ───────────────────────────────────────────────────
+// The initial segment state a wire transcript kind establishes. Only the three transcript wire kinds
+// map; every other control kind (and the derived states `stable`/`corrected`/`redacted`/
+// `provider-error`, which have no wire kind) returns `undefined`. A strict 1:1 wire↔state map is
+// impossible by design, the same lesson the #499 turn manager records (ADR-0062).
+export function mapWireKindToVoiceTranscriptSegmentState(kind) {
+    switch (kind) {
+        case "transcript.partial":
+            return "partial";
+        case "transcript.committed":
+            return "committed";
+        case "transcript.discarded":
+            return "discarded";
+        default:
+            return undefined;
+    }
+}
+// ─── Capability-gating predicates (AC1/AC2/AC3) — derived from the contract ──────
+// The single source of truth for capability gating is `voiceMessageAllowedForProfile`; these predicates
+// derive the transcript-relevant capabilities from it rather than re-encoding the profile table.
+// `none` permits neither (transcript handling is dormant); `speech-output` permits neither (it is
+// playback-only); `speech-to-text` and `full-realtime` permit both.
+export function voiceTranscriptCaptureAllowed(profile) {
+    return voiceMessageAllowedForProfile("transcript.committed", profile);
+}
+export function voiceTranscriptPreviewAllowed(profile) {
+    return voiceMessageAllowedForProfile("transcript.partial", profile);
+}
+// Segments carry unique ids, so the sort never compares an id to itself; a `seq` tie is broken by id.
+function bySeqThenId(a, b) {
+    if (a.seq !== b.seq) {
+        return a.seq - b.seq;
+    }
+    return a.id < b.id ? -1 : 1;
+}
+// Supersession is a PERMANENT fact: once a correction replaces a prior segment's text, that prior text
+// must never re-enter the consumable projection — even after the superseding correction is itself
+// discarded or redacted. We therefore collect `supersedesId` from ANY segment that carries it,
+// regardless of the carrier's current state (the reducer preserves `supersedesId` across transitions).
+function supersededSegmentIds(segments) {
+    const ids = new Set();
+    for (const segment of segments) {
+        if (segment.supersedesId !== undefined) {
+            ids.add(segment.supersedesId);
+        }
+    }
+    return ids;
+}
+export function selectCommittedVoiceTranscript(segments) {
+    const superseded = supersededSegmentIds(segments);
+    const committed = segments
+        .filter((segment) => isCommittedVoiceTranscriptState(segment.state) && !superseded.has(segment.id))
+        .slice()
+        .sort(bySeqThenId);
+    const text = committed
+        .map((segment) => segment.text.trim())
+        .filter((value) => value.length > 0)
+        .join(" ");
+    return {
+        schemaVersion: VOICE_TRANSCRIPT_SCHEMA_VERSION,
+        segments: committed,
+        text,
+        segmentCount: committed.length,
+    };
+}
+function countState(segments, state) {
+    return segments.filter((segment) => segment.state === state).length;
+}
+export function summarizeVoiceTranscript(segments) {
+    const projection = selectCommittedVoiceTranscript(segments);
+    // The committed character count is the length of the consumable projection text, so the evidence
+    // summary, the projection, and the reducer's onCommit observation all report the same number.
+    const committedChars = projection.text.length;
+    const highestSeq = segments.reduce((max, segment) => (segment.seq > max ? segment.seq : max), 0);
+    return {
+        schemaVersion: VOICE_TRANSCRIPT_SCHEMA_VERSION,
+        segmentCount: segments.length,
+        committedCount: countState(segments, "committed"),
+        correctedCount: countState(segments, "corrected"),
+        discardedCount: countState(segments, "discarded"),
+        redactedCount: countState(segments, "redacted"),
+        providerErrorCount: countState(segments, "provider-error"),
+        committedChars,
+        highestSeq,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oscharko-dev/keiko-contracts",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Internal workspace package: shared Keiko contracts. Not published independently.",
@@ -62,6 +62,10 @@
     "./memory-audit-events": {
       "types": "./dist/memory-audit-events.d.ts",
       "import": "./dist/memory-audit-events.js"
+    },
+    "./task-workspace": {
+      "types": "./dist/task-workspace.d.ts",
+      "import": "./dist/task-workspace.js"
     }
   },
   "scripts": {

package/dist/conversation-budget.d.ts

@@ -1,37 +0,0 @@
-export interface ConversationBudgetMessage {
-    readonly role: string;
-    readonly content: string;
-}
-export interface ConversationBudgetDocumentContext {
-    readonly extractedBytes: number;
-}
-export interface ConversationBudgetInputs {
-    readonly modelContextWindow: number;
-    readonly modelMaxOutputTokens: number;
-    readonly userDraftText: string;
-    readonly conversationHistory: readonly ConversationBudgetMessage[];
-    readonly documentContext?: readonly ConversationBudgetDocumentContext[] | undefined;
-    readonly repoContextPackBytes?: number | undefined;
-    readonly knowledgeCapsuleBytes?: number | undefined;
-    readonly memoryContextBytes?: number | undefined;
-}
-export type ConversationBudgetPressure = "low" | "moderate" | "high" | "exceeded";
-export interface ConversationBudgetBreakdown {
-    readonly draftBytes: number;
-    readonly historyBytes: number;
-    readonly documentBytes: number;
-    readonly repoContextBytes: number;
-    readonly knowledgeBytes: number;
-    readonly memoryBytes: number;
-}
-export interface ConversationBudgetEstimate {
-    readonly approximateBytes: number;
-    readonly approximateTokens: number;
-    readonly contextWindowTokens: number;
-    readonly reservedOutputTokens: number;
-    readonly availableInputTokens: number;
-    readonly pressure: ConversationBudgetPressure;
-    readonly breakdown: ConversationBudgetBreakdown;
-}
-export declare function estimateConversationBudget(input: ConversationBudgetInputs): ConversationBudgetEstimate;
-//# sourceMappingURL=conversation-budget.d.ts.map

package/dist/conversation-budget.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"conversation-budget.d.ts","sourceRoot":"","sources":["../src/conversation-budget.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACnE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,iCAAiC,EAAE,GAAG,SAAS,CAAC;IACpF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,MAAM,0BAA0B,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAElF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,2BAA2B,CAAC;CACjD;AA6DD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,wBAAwB,GAC9B,0BAA0B,CAmC5B"}