@oscharko-dev/keiko-evaluations 0.2.8 → 0.2.9

package/dist/voice-twin/metrics.js

@@ -0,0 +1,142 @@
+// Voice Digital Twin AC6 metric derivations (Epic #491, Issue #505; ADR-0068).
+//
+// Each metric is a pure derivation over a frozen keiko-contracts state machine, returning a small
+// content-free record the scorer compares against the fixture oracle. The runtime reducers that drive
+// these state machines live in keiko-ui (turn manager, transcript reducer, playback controller) and are
+// OFF LIMITS here (ADR-0019 rule 3l); this suite proves the CONTRACT the reducers are bound to is
+// regression-safe, while the reducers' own keiko-ui suites prove their behaviour. The five AC6 metrics:
+// interruption, end-of-turn, transcript correction, provider-failure recovery, and the bounded-FIFO
+// buffer model. Pure — no IO, clock, randomness.
+import { VOICE_PLAYBACK_SETTLED_PHASES, VOICE_PLAYBACK_TRANSITIONS, VOICE_PROFILE_MEDIA_TRANSPORT, VOICE_TRANSCRIPT_CONSUMABLE_STATES, VOICE_TRANSCRIPT_SEGMENT_STATES, VOICE_TRANSCRIPT_SEGMENT_TRANSITIONS, canTransitionVoicePlayback, isVoiceReplayEligible, selectCommittedVoiceTranscript, voiceMessageAllowedForProfile, voicePlaybackInterruptAllowedForProfile, voiceTranscriptCaptureAllowed, } from "@oscharko-dev/keiko-contracts";
+// Mirrors the documented keiko-ui replay ring (200) and the keiko-server MAX_REPLAY_EVENTS bound. The
+// value is restated here (not imported) because those packages are off-limits to keiko-evaluations
+// (ADR-0019 rule 3l); the buffer model proves the boundedness invariant the contract's replay-eligibility
+// classification implies, independent of the runtime ring's exact size.
+export const VOICE_TWIN_REPLAY_CAPACITY = 200;
+// A fixed content-free segment builder. `text` is harness-authored filler ("x" repeated) so the committed
+// projection has a non-zero character length without embedding any fixture content; it never leaves the
+// metric as text (only its length / count is recorded).
+function segment(id, seq, state, options = {}) {
+    const textBearing = state === "committed" || state === "corrected" || state === "stable";
+    return {
+        id,
+        seq,
+        state,
+        text: textBearing ? "xx" : "",
+        source: "realtime",
+        revision: 0,
+        replayClass: "replayable",
+        redactionClass: textBearing ? "reviewable-text" : "content-free",
+        supersedesId: options.supersedesId,
+    };
+}
+// ─── Interruption (barge-in) ─────────────────────────────────────────────────────────
+export function deriveInterruptionMetric(profile) {
+    return {
+        interruptAllowed: voicePlaybackInterruptAllowedForProfile(profile),
+        interruptedPhaseReachable: canTransitionVoicePlayback("speaking", "interrupted"),
+    };
+}
+// ─── End-of-turn (committed projection excludes uncommitted) ─────────────────────────
+export function deriveEndOfTurnMetric(profile) {
+    // A fixture segment list spanning the lifecycle: one partial + one stable (uncommitted) and one segment
+    // per consumable state. The committed projection must exclude the partial / stable text.
+    const segments = [
+        segment("eot-partial", 0, "partial"),
+        segment("eot-stable", 1, "stable"),
+        ...VOICE_TRANSCRIPT_CONSUMABLE_STATES.map((state, index) => segment(`eot-consumable-${state}`, 2 + index, state)),
+    ];
+    const projection = selectCommittedVoiceTranscript(segments);
+    const projectedIds = new Set(projection.segments.map((s) => s.id));
+    return {
+        committedKindAllowed: voiceMessageAllowedForProfile("transcript.committed", profile),
+        captureAllowed: voiceTranscriptCaptureAllowed(profile),
+        committedSegmentCount: projection.segmentCount,
+        excludesUncommitted: !projectedIds.has("eot-partial") && !projectedIds.has("eot-stable"),
+    };
+}
+// ─── Transcript correction (supersede drops prior committed text) ────────────────────
+export function deriveTranscriptCorrectionMetric() {
+    // A corrected segment supersedes a prior committed one. The committed projection must drop the
+    // superseded segment so a provider correction REPLACES rather than duplicates the prior text.
+    const segments = [
+        segment("corr-committed", 0, "committed"),
+        segment("corr-corrected", 1, "corrected", { supersedesId: "corr-committed" }),
+    ];
+    const projection = selectCommittedVoiceTranscript(segments);
+    const projectedIds = new Set(projection.segments.map((s) => s.id));
+    return {
+        stableToCorrectedAllowed: VOICE_TRANSCRIPT_SEGMENT_TRANSITIONS.stable.includes("corrected"),
+        committedToCorrectedAllowed: VOICE_TRANSCRIPT_SEGMENT_TRANSITIONS.committed.includes("corrected"),
+        correctedIsConsumable: VOICE_TRANSCRIPT_CONSUMABLE_STATES.includes("corrected"),
+        supersededTextDropped: !projectedIds.has("corr-committed") && projectedIds.has("corr-corrected"),
+    };
+}
+// ─── Provider-failure recovery ───────────────────────────────────────────────────────
+export function deriveProviderFailureRecoveryMetric() {
+    // A recovery transition out of the playback failure phase, read from the actual transition table (not
+    // assumed): `failed` may re-arm `preparing`.
+    const recoveryTransitionExists = VOICE_PLAYBACK_TRANSITIONS.failed.includes("preparing");
+    return {
+        providerErrorIsState: VOICE_TRANSCRIPT_SEGMENT_STATES.includes("provider-error"),
+        // provider-error is a reviewable lifecycle fact but is NOT in the consumable set, so failed text never
+        // reaches a downstream integration.
+        providerErrorNotConsumable: !VOICE_TRANSCRIPT_CONSUMABLE_STATES.includes("provider-error"),
+        playbackFailedIsSettled: VOICE_PLAYBACK_SETTLED_PHASES.includes("failed"),
+        recoveryTransitionExists,
+    };
+}
+// ─── Bounded-FIFO buffer model ───────────────────────────────────────────────────────
+// Push the given control-message kinds through a fixed-capacity ring that ONLY admits replay-eligible
+// kinds. Asserts length never exceeds capacity, ephemeral kinds never buffer, and overflow evicts the
+// oldest. The runtime ring lives in keiko-ui / keiko-server (off-limits); this models the same invariant
+// over the contract's `isVoiceReplayEligible` classification.
+export function deriveBufferBoundednessMetric(kinds, capacity = VOICE_TWIN_REPLAY_CAPACITY) {
+    const ring = [];
+    let maxObservedLength = 0;
+    let admittedCount = 0;
+    let ephemeralBuffered = false;
+    let evictedOldestOnOverflow = false;
+    for (const kind of kinds) {
+        if (!isVoiceReplayEligible(kind)) {
+            // An ephemeral kind is never admitted; if it ever entered the ring the invariant is broken.
+            ephemeralBuffered = ephemeralBuffered || ring.includes(kind);
+            continue;
+        }
+        admittedCount += 1;
+        if (ring.length >= capacity) {
+            ring.shift();
+            evictedOldestOnOverflow = true;
+        }
+        ring.push(kind);
+        maxObservedLength = Math.max(maxObservedLength, ring.length);
+    }
+    return {
+        capacity,
+        maxObservedLength,
+        admittedCount,
+        ephemeralBuffered,
+        evictedOldestOnOverflow,
+    };
+}
+// ─── Latency posture class (Deliverable "latency") ───────────────────────────────────
+// A total, deterministic map from the contract media-transport to the latency POSTURE class the transport
+// implies. This is NOT a wall-clock measurement (which would need a clock + network reads and is out of the
+// pure-harness boundary, covered by the keiko-ui voice-timebase suite, ADR-0061); it is the deterministic
+// class the contract's transport choice fixes: `webrtc` is interactive full-duplex, `gateway-batch` is a
+// single batched request/response, and `none` has no latency surface. Keyed for totality so a new media
+// transport added to the contract is a compile error here, not a silent wrong class.
+const LATENCY_CLASS_BY_TRANSPORT = {
+    none: "none",
+    "gateway-batch": "batch",
+    webrtc: "interactive-realtime",
+};
+export function deriveLatencyClassMetric(profile) {
+    const mediaTransport = VOICE_PROFILE_MEDIA_TRANSPORT[profile];
+    const latencyClass = LATENCY_CLASS_BY_TRANSPORT[mediaTransport];
+    return {
+        mediaTransport,
+        latencyClass,
+        isInteractive: latencyClass === "interactive-realtime",
+    };
+}

package/dist/voice-twin/privacy.d.ts

@@ -0,0 +1,9 @@
+import type { EgressDestinationClass, VoiceTwinEgressAudit, VoiceTwinEgressDestination, VoiceTwinManifestFixture, VoiceTwinManifestScan } from "./types.js";
+export declare function auditVoiceEgress(destinations: readonly {
+    readonly class: EgressDestinationClass;
+}[]): VoiceTwinEgressAudit;
+export declare const DENIED_MEDIA_PACKAGES: readonly string[];
+export declare const ALLOWED_MEDIA_RUNTIME: readonly string[];
+export declare function scanManifestsForDeniedMediaPackages(manifests: readonly VoiceTwinManifestFixture[]): VoiceTwinManifestScan;
+export type { VoiceTwinEgressDestination };
+//# sourceMappingURL=privacy.d.ts.map

package/dist/voice-twin/privacy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privacy.d.ts","sourceRoot":"","sources":["../../src/voice-twin/privacy.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAGpB,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAA;CAAE,EAAE,GAClE,oBAAoB,CAGtB;AASD,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EA8CzC,CAAC;AAEX,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAoB,CAAC;AAYxE,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS,wBAAwB,EAAE,GAC7C,qBAAqB,CAmBvB;AAGD,YAAY,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/voice-twin/privacy.js

@@ -0,0 +1,100 @@
+// Voice Digital Twin privacy / supply-chain audit (Epic #491, Issue #505; ADR-0068; AC5).
+//
+// Two pure auditors give AC5 its teeth:
+//   (a) `auditVoiceEgress` — an egress ledger is approved iff NO destination is `unapproved-external`. A
+//       voice cell may egress nowhere or only to the configured model endpoint (matrix §3 /
+//       privacy-contract §1); any other destination flips approval to false.
+//   (b) `scanManifestsForDeniedMediaPackages` — a pure scan over provided package manifests for the
+//       denied runtime-media packages from `docs/voice/supply-chain-policy.md` §1. The real-repo scan
+//       (reading the actual `packages/**/package.json`) runs in the .test.ts files (test files may do
+//       fs); this function is pure over its inputs so pure negative fixtures can prove a denied package
+//       flips `clean=false`.
+//
+// Both are pure (no IO, clock, randomness) and content-free.
+// ─── Egress audit (AC5) ──────────────────────────────────────────────────────────────
+export function auditVoiceEgress(destinations) {
+    const unapprovedCount = destinations.filter((d) => d.class === "unapproved-external").length;
+    return { approved: unapprovedCount === 0, unapprovedCount };
+}
+// ─── Supply-chain denylist (docs/voice/supply-chain-policy.md §1) ────────────────────
+// Enumerates the known runtime-media package + scope variants of the policy §1 vendors (WebRTC wrapper /
+// peer / SFU / media-server / SDK packages) the policy forbids adding by default — including the real
+// client / SDK and scoped-vendor variants, not just the bare vendor id. This is a NAME-based scan
+// (exact id OR `@scope/` prefix); the policy §1 catch-all cannot be enforced by an exact-name scan alone,
+// so operators MUST keep this list current as new vendor packages appear. `ws` is the single allowed
+// runtime media-adjacent package (already vetted, scoped). Grouped alphabetically by vendor.
+export const DENIED_MEDIA_PACKAGES = [
+    // agora
+    "agora",
+    "agora-rtc-sdk-ng",
+    "@agora-js",
+    // daily
+    "@daily-co",
+    "@daily-co/daily-js",
+    // jitsi
+    "jitsi",
+    "lib-jitsi-meet",
+    "@jitsi",
+    // janus
+    "janus",
+    "janus-gateway",
+    // kurento
+    "kurento",
+    // livekit
+    "livekit",
+    "livekit-client",
+    "livekit-server-sdk",
+    "@livekit",
+    // mediasoup
+    "mediasoup",
+    "mediasoup-client",
+    // opentok
+    "opentok",
+    // peerjs
+    "peerjs",
+    "peerjs-server",
+    // simple-peer
+    "simple-peer",
+    // sip
+    "sip.js",
+    "jssip",
+    // socket.io
+    "socket.io",
+    "socket.io-client",
+    "@socket.io",
+    // twilio
+    "twilio",
+    "twilio-video",
+    "@twilio",
+    // webrtc native bindings
+    "wrtc",
+    "node-webrtc",
+];
+export const ALLOWED_MEDIA_RUNTIME = ["ws"];
+// A dependency name matches a denied package if it equals the denied id or is a scoped sub-package of a
+// denied scope (e.g. `@daily-co/daily-js` matches the `@daily-co` scope). This catches the realistic
+// monorepo shape where a forbidden vendor ships under a scope.
+function dependencyMatchesDenied(dependencyName, denied) {
+    if (dependencyName === denied) {
+        return true;
+    }
+    return denied.startsWith("@") && dependencyName.startsWith(`${denied}/`);
+}
+export function scanManifestsForDeniedMediaPackages(manifests) {
+    const found = [];
+    for (const manifest of manifests) {
+        for (const dependency of manifest.dependencyNames) {
+            const denied = DENIED_MEDIA_PACKAGES.find((d) => dependencyMatchesDenied(dependency, d));
+            if (denied !== undefined) {
+                found.push({ packageName: manifest.packageName, deniedPackage: denied });
+            }
+        }
+    }
+    // Sort to a canonical order so the found list is stable regardless of manifest ordering.
+    const sorted = found
+        .slice()
+        .sort((a, b) => a.packageName === b.packageName
+        ? a.deniedPackage.localeCompare(b.deniedPackage)
+        : a.packageName.localeCompare(b.packageName));
+    return { clean: sorted.length === 0, found: sorted };
+}

package/dist/voice-twin/profiles.d.ts

@@ -0,0 +1,15 @@
+import { type VoiceProfile } from "@oscharko-dev/keiko-contracts";
+import type { EgressDestinationClass, VoiceEnvironmentProfile } from "./types.js";
+export declare const ALL_VOICE_PROFILES: readonly VoiceProfile[];
+export declare function localProfilesMatchContract(): boolean;
+export type VoiceNetworkPosture = "cloud-provider" | "controlled-network" | "no-provider";
+export interface VoiceEnvironmentDescriptor {
+    readonly id: VoiceEnvironmentProfile;
+    readonly label: string;
+    readonly networkPosture: VoiceNetworkPosture;
+    readonly egresses: boolean;
+}
+export declare const VOICE_ENVIRONMENT_DESCRIPTORS: Record<VoiceEnvironmentProfile, VoiceEnvironmentDescriptor>;
+export declare function effectiveVoiceProfile(environment: VoiceEnvironmentProfile, advertised: VoiceProfile): VoiceProfile;
+export declare function egressDestinationClassFor(effectiveProfile: VoiceProfile): EgressDestinationClass;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/voice-twin/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/voice-twin/profiles.ts"],"names":[],"mappings":"AAUA,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,+BAA+B,CAAC;AACjG,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAKlF,eAAO,MAAM,kBAAkB,EAAE,SAAS,YAAY,EAK5C,CAAC;AAIX,wBAAgB,0BAA0B,IAAI,OAAO,CAIpD;AAMD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,oBAAoB,GAAG,aAAa,CAAC;AAE1F,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,EAAE,uBAAuB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAChD,uBAAuB,EACvB,0BAA0B,CAoBlB,CAAC;AAKX,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,uBAAuB,EACpC,UAAU,EAAE,YAAY,GACvB,YAAY,CAEd;AAKD,wBAAgB,yBAAyB,CAAC,gBAAgB,EAAE,YAAY,GAAG,sBAAsB,CAEhG"}

package/dist/voice-twin/profiles.js

@@ -0,0 +1,58 @@
+// Voice Digital Twin profile × environment model (Epic #491, Issue #505; ADR-0068).
+//
+// The two orthogonal axes the capstone evaluates: the contract `VoiceProfile` capability axis and the
+// deployment ENVIRONMENT axis (`docs/voice/deployment-profile-matrix.md` §1). `effectiveVoiceProfile`
+// applies the matrix §3 degradation rule — in a no-voice environment EVERY advertised capability degrades
+// to `none` because no provider is configured; in a provider-configured environment the advertised
+// capability is the effective profile. `egressDestinationClassFor` encodes the matrix §3 / privacy-contract
+// §1 external-call rule: an effective-none cell egresses nowhere, any active capability egresses ONLY to
+// the configured model endpoint. Pure.
+import { VOICE_PROFILE_MEDIA_TRANSPORT } from "@oscharko-dev/keiko-contracts";
+// The four capability-axis profiles, declared locally because the contract exports no `VOICE_PROFILES`
+// array. `profiles.test.ts` asserts this equals the keys of `VOICE_PROFILE_MEDIA_TRANSPORT` so it can
+// never drift from the contract.
+export const ALL_VOICE_PROFILES = [
+    "none",
+    "speech-to-text",
+    "speech-output",
+    "full-realtime",
+];
+// Whether the contract's media-transport table — keyed by `VoiceProfile` for totality — still lists
+// exactly the locally-declared profiles. A drift (a new profile added to the contract) makes this false.
+export function localProfilesMatchContract() {
+    const contractKeys = Object.keys(VOICE_PROFILE_MEDIA_TRANSPORT).slice().sort();
+    const local = ALL_VOICE_PROFILES.slice().sort();
+    return contractKeys.length === local.length && contractKeys.every((k, i) => k === local[i]);
+}
+export const VOICE_ENVIRONMENT_DESCRIPTORS = {
+    "azure-foundry": {
+        id: "azure-foundry",
+        label: "Azure AI Foundry dev/academic",
+        networkPosture: "cloud-provider",
+        egresses: true,
+    },
+    "customer-hosted": {
+        id: "customer-hosted",
+        label: "Customer-hosted controlled-network",
+        networkPosture: "controlled-network",
+        egresses: true,
+    },
+    "no-voice-env": {
+        id: "no-voice-env",
+        label: "No voice provider configured",
+        networkPosture: "no-provider",
+        egresses: false,
+    },
+};
+// ─── Effective profile (matrix §3 degradation rule) ──────────────────────────────────
+// In a no-voice environment nothing is configured, so any advertised capability degrades to `none`
+// (AC1/AC2). Otherwise the advertised capability is the effective profile.
+export function effectiveVoiceProfile(environment, advertised) {
+    return VOICE_ENVIRONMENT_DESCRIPTORS[environment].egresses ? advertised : "none";
+}
+// ─── Egress destination class (matrix §3 external-call rule) ──────────────────────────
+// An effective-none cell egresses nowhere; any active capability egresses only to the configured model
+// endpoint. This is the ONLY positive egress class the matrix permits.
+export function egressDestinationClassFor(effectiveProfile) {
+    return effectiveProfile === "none" ? "none" : "configured-model-endpoint";
+}

package/dist/voice-twin/render.d.ts

@@ -0,0 +1,3 @@
+import type { VoiceTwinScorecard } from "./types.js";
+export declare function renderVoiceTwinSummary(scorecard: VoiceTwinScorecard): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/voice-twin/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/voice-twin/render.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AA+BpB,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,kBAAkB,GAAG,MAAM,CAiC5E"}

package/dist/voice-twin/render.js

@@ -0,0 +1,53 @@
+// renderVoiceTwinSummary (Issue #505): VoiceTwinScorecard -> human-readable string. A verdict line, a
+// per-dimension table, the profile / environment matrix-coverage lines, and the privacy line. The
+// scorecard carries only harness-authored, content-free fields (counts, closed-vocabulary labels, numeric
+// scores), so this renderer performs no redaction — it only formats fields that are safe to print.
+function glyph(result) {
+    if (result.outcome === "pass") {
+        return "PASS";
+    }
+    if (result.outcome === "fail") {
+        return "FAIL";
+    }
+    return "n/a";
+}
+function fixtureLine(fixture) {
+    const dims = fixture.dimensionResults
+        .filter((d) => d.outcome !== "not-applicable")
+        .map((d) => `${d.dimension}=${glyph(d)}`)
+        .join(" ");
+    const verdict = fixture.fullyPassed ? "OK" : "FAIL";
+    return `- ${fixture.fixtureName} [${fixture.category}/${fixture.environment}/${fixture.effectiveProfile}] ${verdict} ${dims}`.trimEnd();
+}
+function dimensionLine(entry) {
+    const rate = entry.passRate === null ? "n/a" : `${(entry.passRate * 100).toFixed(0)}%`;
+    const verdict = entry.failCount > 0 ? "FAIL" : entry.passCount > 0 ? "PASS" : "n/a";
+    return `  ${entry.dimension.padEnd(32)} ${verdict.padEnd(5)} pass=${String(entry.passCount)} fail=${String(entry.failCount)} n/a=${String(entry.notApplicableCount)} rate=${rate}`;
+}
+function yesNo(value) {
+    return value ? "yes" : "no";
+}
+export function renderVoiceTwinSummary(scorecard) {
+    const summary = scorecard.summary;
+    const lines = [];
+    lines.push(`Voice Digital Twin evaluation summary (schema v${scorecard.schemaVersion})`);
+    lines.push(`Fixtures: ${String(summary.totalFixtures)} total, ${String(summary.fullyPassedFixtures)} fully passed`);
+    lines.push(`Capability coverage: no-voice=${yesNo(summary.coversNoVoice)} stt=${yesNo(summary.coversSttOnly)} full-realtime=${yesNo(summary.coversFullRealtime)}`);
+    lines.push(`Environment coverage: azure-foundry=${yesNo(summary.coversAzureFoundry)} customer-hosted=${yesNo(summary.coversCustomerHosted)}`);
+    lines.push(`Privacy: negative-egress-caught=${yesNo(summary.coversPrivacyNegative)}, matrix cells=${String(scorecard.coveredMatrixCells.length)}`);
+    lines.push("");
+    lines.push("Fixtures:");
+    for (const fixture of scorecard.fixtureResults) {
+        lines.push(fixtureLine(fixture));
+    }
+    lines.push("");
+    lines.push("Dimensions:");
+    for (const entry of scorecard.dimensions) {
+        lines.push(dimensionLine(entry));
+    }
+    lines.push("");
+    lines.push(summary.goNoGo === "GO"
+        ? "Verdict: GO - every exercised dimension passed across the profile and environment matrix."
+        : "Verdict: NO-GO - a dimension failed or a coverage gate was unmet (see table above).");
+    return lines.join("\n");
+}

package/dist/voice-twin/runner.d.ts

@@ -0,0 +1,13 @@
+import { type VoiceTwinFixture, type VoiceTwinObservation, type VoiceTwinScorecard } from "./types.js";
+/**
+ * Derive the deterministic observation for one fixture: the contract-derived capability cell, the egress
+ * and supply-chain audits, and the declared AC6 metric records. Pure data derivation over the frozen
+ * contract.
+ */
+export declare function deriveVoiceTwinObservation(fixture: VoiceTwinFixture): VoiceTwinObservation;
+/**
+ * Run the Voice Digital Twin evaluation suite and return a fully aggregated scorecard. Pure and
+ * deterministic. Pass an explicit fixture list to scope the run (the suite tests use the default set).
+ */
+export declare function runVoiceTwinEvaluation(fixtures?: readonly VoiceTwinFixture[]): VoiceTwinScorecard;
+//# sourceMappingURL=runner.d.ts.map

package/dist/voice-twin/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/voice-twin/runner.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,KAAK,gBAAgB,EAIrB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EAExB,MAAM,YAAY,CAAC;AAmDpB;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,gBAAgB,GAAG,oBAAoB,CAU1F;AAwED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,GAAE,SAAS,gBAAgB,EAA4B,GAC9D,kBAAkB,CAUpB"}

package/dist/voice-twin/runner.js

@@ -0,0 +1,141 @@
+// Voice Digital Twin evaluation runner (Epic #491, Issue #505; ADR-0068).
+//
+// Derives a deterministic observation for each fixture from the frozen keiko-contracts voice tables and
+// state machines — the capability cell, the egress / supply-chain audit, and exactly the AC6 metric
+// records the fixture's declared dimensions require — then scores the eleven dimensions, aggregates a
+// scorecard, and derives the offline Go/No-Go verdict and the matrix-coverage flags. Pure: no IO, clock,
+// randomness, or model dispatch.
+import { VOICE_CONTROL_MESSAGE_KINDS, } from "@oscharko-dev/keiko-contracts";
+import { deriveCapabilityCell } from "./capability.js";
+import { VOICE_TWIN_REPLAY_CAPACITY, deriveBufferBoundednessMetric, deriveEndOfTurnMetric, deriveInterruptionMetric, deriveLatencyClassMetric, deriveProviderFailureRecoveryMetric, deriveTranscriptCorrectionMetric, } from "./metrics.js";
+import { auditVoiceEgress, scanManifestsForDeniedMediaPackages } from "./privacy.js";
+import { aggregateVoiceTwinQuality, scoreVoiceTwinQuality } from "./scorer.js";
+import { ALL_VOICE_TWIN_FIXTURES } from "./fixtures/index.js";
+import { VOICE_TWIN_EVAL_SCHEMA_VERSION, } from "./types.js";
+// The control-message kind sequence the buffer-boundedness model pushes: every kind repeated enough times
+// that the replay-eligible subset overflows the ring, so eviction is exercised. `transcript.partial` and
+// other ephemeral kinds are interleaved to prove they never buffer.
+function bufferProbeKinds(capacity) {
+    const kinds = [];
+    // Enough repetitions of the full kind catalog to exceed capacity with the replay-eligible subset alone.
+    const rounds = capacity + 4;
+    for (let round = 0; round < rounds; round += 1) {
+        for (const kind of VOICE_CONTROL_MESSAGE_KINDS) {
+            kinds.push(kind);
+        }
+    }
+    return kinds;
+}
+// Derive exactly the metric records the fixture's declared dimensions require, against the effective
+// profile of the cell. A metric absent from the declared dimensions is omitted (exactOptionalPropertyTypes
+// forbids assigning `undefined` to an optional prop, so we build the bundle incrementally).
+function deriveMetrics(fixture, cell) {
+    const bundle = {};
+    if (fixture.dimensions.has("interruption-metric")) {
+        bundle.interruption = deriveInterruptionMetric(cell.effectiveProfile);
+    }
+    if (fixture.dimensions.has("end-of-turn-metric")) {
+        bundle.endOfTurn = deriveEndOfTurnMetric(cell.effectiveProfile);
+    }
+    if (fixture.dimensions.has("transcript-correction-metric")) {
+        bundle.transcriptCorrection = deriveTranscriptCorrectionMetric();
+    }
+    if (fixture.dimensions.has("provider-failure-recovery-metric")) {
+        bundle.providerFailureRecovery = deriveProviderFailureRecoveryMetric();
+    }
+    if (fixture.dimensions.has("buffer-boundedness-metric")) {
+        bundle.bufferBoundedness = deriveBufferBoundednessMetric(bufferProbeKinds(VOICE_TWIN_REPLAY_CAPACITY), VOICE_TWIN_REPLAY_CAPACITY);
+    }
+    if (fixture.dimensions.has("latency-class-metric")) {
+        bundle.latencyClass = deriveLatencyClassMetric(cell.effectiveProfile);
+    }
+    return bundle;
+}
+/**
+ * Derive the deterministic observation for one fixture: the contract-derived capability cell, the egress
+ * and supply-chain audits, and the declared AC6 metric records. Pure data derivation over the frozen
+ * contract.
+ */
+export function deriveVoiceTwinObservation(fixture) {
+    const cell = deriveCapabilityCell(fixture.environment, fixture.advertisedProfile);
+    return {
+        environment: fixture.environment,
+        advertisedProfile: fixture.advertisedProfile,
+        cell,
+        egressAudit: auditVoiceEgress(fixture.egressLedger),
+        manifestScan: scanManifestsForDeniedMediaPackages(fixture.manifests),
+        metrics: deriveMetrics(fixture, cell),
+    };
+}
+function runFixture(fixture) {
+    const observation = deriveVoiceTwinObservation(fixture);
+    const dimensionResults = scoreVoiceTwinQuality(fixture, observation);
+    return {
+        fixtureName: fixture.name,
+        category: fixture.category,
+        environment: fixture.environment,
+        effectiveProfile: observation.cell.effectiveProfile,
+        observation,
+        dimensionResults,
+        fullyPassed: dimensionResults.every((d) => d.outcome !== "fail"),
+    };
+}
+function collectMatrixCells(fixtureResults) {
+    const seen = new Map();
+    for (const result of fixtureResults) {
+        const key = `${result.environment}:${result.effectiveProfile}`;
+        if (!seen.has(key)) {
+            seen.set(key, {
+                environment: result.environment,
+                effectiveProfile: result.effectiveProfile,
+            });
+        }
+    }
+    return [...seen.values()].sort((a, b) => a.environment === b.environment
+        ? a.effectiveProfile.localeCompare(b.effectiveProfile)
+        : a.environment.localeCompare(b.environment));
+}
+function summarize(fixtureResults, dimensions) {
+    const allClean = dimensions.every((d) => d.failCount === 0);
+    const coversNoVoice = fixtureResults.some((f) => f.effectiveProfile === "none");
+    const coversSttOnly = fixtureResults.some((f) => f.effectiveProfile === "speech-to-text");
+    const coversSpeechOutput = fixtureResults.some((f) => f.effectiveProfile === "speech-output");
+    const coversFullRealtime = fixtureResults.some((f) => f.effectiveProfile === "full-realtime");
+    const coversAzureFoundry = fixtureResults.some((f) => f.environment === "azure-foundry");
+    const coversCustomerHosted = fixtureResults.some((f) => f.environment === "customer-hosted");
+    const coversPrivacyNegative = fixtureResults.some((f) => f.category === "privacy" && !f.observation.egressAudit.approved);
+    const coverageMet = coversNoVoice &&
+        coversSttOnly &&
+        coversSpeechOutput &&
+        coversFullRealtime &&
+        coversAzureFoundry &&
+        coversCustomerHosted &&
+        coversPrivacyNegative;
+    return {
+        totalFixtures: fixtureResults.length,
+        fullyPassedFixtures: fixtureResults.filter((f) => f.fullyPassed).length,
+        coversNoVoice,
+        coversSttOnly,
+        coversSpeechOutput,
+        coversFullRealtime,
+        coversAzureFoundry,
+        coversCustomerHosted,
+        coversPrivacyNegative,
+        goNoGo: allClean && coverageMet ? "GO" : "NO-GO",
+    };
+}
+/**
+ * Run the Voice Digital Twin evaluation suite and return a fully aggregated scorecard. Pure and
+ * deterministic. Pass an explicit fixture list to scope the run (the suite tests use the default set).
+ */
+export function runVoiceTwinEvaluation(fixtures = ALL_VOICE_TWIN_FIXTURES) {
+    const fixtureResults = fixtures.map(runFixture);
+    const dimensions = aggregateVoiceTwinQuality(fixtureResults.map((f) => f.dimensionResults));
+    return {
+        schemaVersion: VOICE_TWIN_EVAL_SCHEMA_VERSION,
+        fixtureResults,
+        dimensions,
+        summary: summarize(fixtureResults, dimensions),
+        coveredMatrixCells: collectMatrixCells(fixtureResults),
+    };
+}

package/dist/voice-twin/scorer.d.ts

@@ -0,0 +1,8 @@
+import { type VoiceTwinDimensionResult, type VoiceTwinFixture, type VoiceTwinObservation, type VoiceTwinScorecardEntry } from "./types.js";
+/**
+ * Score one fixture's observation across all eleven dimensions. A dimension the fixture does not declare is
+ * `not-applicable`. Pure.
+ */
+export declare function scoreVoiceTwinQuality(fixture: VoiceTwinFixture, obs: VoiceTwinObservation): readonly VoiceTwinDimensionResult[];
+export declare function aggregateVoiceTwinQuality(results: readonly (readonly VoiceTwinDimensionResult[])[]): readonly VoiceTwinScorecardEntry[];
+//# sourceMappingURL=scorer.d.ts.map

package/dist/voice-twin/scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../../src/voice-twin/scorer.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC7B,MAAM,YAAY,CAAC;AAuTpB;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,oBAAoB,GACxB,SAAS,wBAAwB,EAAE,CAUrC;AA8BD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,CAAC,SAAS,wBAAwB,EAAE,CAAC,EAAE,GACxD,SAAS,uBAAuB,EAAE,CAEpC"}