@absolutejs/voice 0.0.22-beta.44 → 0.0.22-beta.46

package/dist/evalRoutes.d.ts

@@ -75,6 +75,7 @@ export type VoiceScenarioEvalDefinition = {
     requiredLifecycleTypes?: string[];
     requiredPayloadPaths?: string[];
     requiredTranscriptIncludes?: string[];
+    requiredWorkflowContracts?: string[];
     scenarioId?: string;
 };
 export type VoiceScenarioEvalSessionResult = {
@@ -102,6 +103,30 @@ export type VoiceScenarioEvalReport = {
     status: VoiceEvalStatus;
     total: number;
 };
+export type VoiceScenarioFixture = {
+    description?: string;
+    events: StoredVoiceTraceEvent[];
+    id: string;
+    label?: string;
+};
+export type VoiceScenarioFixtureStore = {
+    list: () => Promise<VoiceScenarioFixture[]>;
+};
+export type VoiceScenarioFixtureEvalResult = {
+    description?: string;
+    fixtureId: string;
+    label: string;
+    report: VoiceScenarioEvalReport;
+    status: VoiceEvalStatus;
+};
+export type VoiceScenarioFixtureEvalReport = {
+    checkedAt: number;
+    failed: number;
+    fixtures: VoiceScenarioFixtureEvalResult[];
+    passed: number;
+    status: VoiceEvalStatus;
+    total: number;
+};
 export type VoiceEvalLink = {
     href: string;
     label: string;
@@ -111,6 +136,8 @@ export type VoiceEvalRoutesOptions = {
     baselineComparison?: VoiceEvalBaselineComparisonOptions;
     baselineStore?: VoiceEvalBaselineStore;
     events?: StoredVoiceTraceEvent[];
+    fixtures?: VoiceScenarioFixture[];
+    fixtureStore?: VoiceScenarioFixtureStore;
     headers?: HeadersInit;
     links?: VoiceEvalLink[];
     limit?: number;
@@ -132,8 +159,14 @@ export declare const runVoiceScenarioEvals: (options?: {
     scenarios?: VoiceScenarioEvalDefinition[];
     store?: VoiceTraceEventStore;
 }) => Promise<VoiceScenarioEvalReport>;
+export declare const runVoiceScenarioFixtureEvals: (options?: {
+    fixtures?: VoiceScenarioFixture[];
+    fixtureStore?: VoiceScenarioFixtureStore;
+    scenarios?: VoiceScenarioEvalDefinition[];
+}) => Promise<VoiceScenarioFixtureEvalReport>;
 export declare const compareVoiceEvalBaseline: (currentReport: VoiceEvalReport, baselineReport: VoiceEvalReport, options?: VoiceEvalBaselineComparisonOptions) => VoiceEvalBaselineComparison;
 export declare const createVoiceFileEvalBaselineStore: (filePath: string) => VoiceEvalBaselineStore;
+export declare const createVoiceFileScenarioFixtureStore: (filePath: string) => VoiceScenarioFixtureStore;
 export declare const renderVoiceEvalHTML: (report: VoiceEvalReport, options?: {
     links?: VoiceEvalLink[];
     title?: string;
@@ -146,6 +179,10 @@ export declare const renderVoiceScenarioEvalHTML: (report: VoiceScenarioEvalRepo
     links?: VoiceEvalLink[];
     title?: string;
 }) => string;
+export declare const renderVoiceScenarioFixtureEvalHTML: (report: VoiceScenarioFixtureEvalReport, options?: {
+    links?: VoiceEvalLink[];
+    title?: string;
+}) => string;
 export declare const createVoiceEvalRoutes: (options: VoiceEvalRoutesOptions) => Elysia<"", {
     decorator: {};
     store: {};

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export { voice } from './plugin';
 export { createVoiceAssistant, createVoiceExperiment, summarizeVoiceAssistantRuns } from './assistant';
 export { createVoiceAssistantHealthHTMLHandler, createVoiceAssistantHealthJSONHandler, createVoiceAssistantHealthRoutes, renderVoiceAssistantHealthHTML, summarizeVoiceAssistantHealth } from './assistantHealth';
 export { buildVoiceDiagnosticsMarkdown, createVoiceDiagnosticsRoutes, resolveVoiceDiagnosticsTraceFilter } from './diagnosticsRoutes';
-export { compareVoiceEvalBaseline, createVoiceFileEvalBaselineStore, createVoiceEvalRoutes, renderVoiceEvalBaselineHTML, renderVoiceEvalHTML, renderVoiceScenarioEvalHTML, runVoiceScenarioEvals, runVoiceSessionEvals } from './evalRoutes';
+export { compareVoiceEvalBaseline, createVoiceFileEvalBaselineStore, createVoiceFileScenarioFixtureStore, createVoiceEvalRoutes, renderVoiceEvalBaselineHTML, renderVoiceEvalHTML, renderVoiceScenarioEvalHTML, renderVoiceScenarioFixtureEvalHTML, runVoiceScenarioEvals, runVoiceScenarioFixtureEvals, runVoiceSessionEvals } from './evalRoutes';
+export { createVoiceWorkflowContract, createVoiceWorkflowContractHandler, createVoiceWorkflowScenario, recordVoiceWorkflowContractTrace, validateVoiceWorkflowRouteResult } from './workflowContract';
 export { createVoiceSessionListRoutes, createVoiceSessionReplayHTMLHandler, createVoiceSessionReplayJSONHandler, createVoiceSessionReplayRoutes, createVoiceSessionsHTMLHandler, createVoiceSessionsJSONHandler, renderVoiceSessionsHTML, summarizeVoiceSessions, summarizeVoiceSessionReplay } from './sessionReplay';
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool } from './agent';
 export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap, createStoredVoiceIntegrationEvent, createStoredVoiceOpsTask, createVoiceFileExternalObjectMapStore, createVoiceFileAssistantMemoryStore, createVoiceFileIntegrationEventStore, createVoiceFileReviewStore, createVoiceFileRuntimeStorage, createVoiceFileSessionStore, createVoiceFileTaskStore, createVoiceFileTraceSinkDeliveryStore, createVoiceFileTraceEventStore } from './fileStore';
@@ -40,7 +41,8 @@ export type { VoiceAssistant, VoiceAssistantArtifactPlan, VoiceAssistantExperime
 export type { VoiceAssistantHealthFailure, VoiceAssistantHealthHTMLHandlerOptions, VoiceAssistantHealthRoutesOptions, VoiceAssistantHealthSummary, VoiceAssistantHealthSummaryOptions } from './assistantHealth';
 export type { VoiceAssistantMemoryBinding, VoiceAssistantMemoryHandle, VoiceAssistantMemoryOptions, VoiceAssistantMemoryRecord, VoiceAssistantMemoryStore } from './assistantMemory';
 export type { VoiceDiagnosticsRoutesOptions } from './diagnosticsRoutes';
-export type { VoiceEvalBaselineComparison, VoiceEvalBaselineComparisonOptions, VoiceEvalBaselineStore, VoiceEvalBaselineSummary, VoiceEvalLink, VoiceEvalReport, VoiceEvalRoutesOptions, VoiceEvalSessionReport, VoiceEvalStatus, VoiceEvalTrendBucket, VoiceScenarioEvalDefinition, VoiceScenarioEvalReport, VoiceScenarioEvalResult, VoiceScenarioEvalSessionResult } from './evalRoutes';
+export type { VoiceEvalBaselineComparison, VoiceEvalBaselineComparisonOptions, VoiceEvalBaselineStore, VoiceEvalBaselineSummary, VoiceEvalLink, VoiceEvalReport, VoiceEvalRoutesOptions, VoiceEvalSessionReport, VoiceEvalStatus, VoiceEvalTrendBucket, VoiceScenarioEvalDefinition, VoiceScenarioEvalReport, VoiceScenarioEvalResult, VoiceScenarioEvalSessionResult, VoiceScenarioFixture, VoiceScenarioFixtureEvalReport, VoiceScenarioFixtureEvalResult, VoiceScenarioFixtureStore } from './evalRoutes';
+export type { VoiceWorkflowContract, VoiceWorkflowContractDefinition, VoiceWorkflowContractField, VoiceWorkflowContractFieldMatch, VoiceWorkflowContractTracePayload, VoiceWorkflowContractValidation, VoiceWorkflowContractValidationIssue, VoiceWorkflowOutcome } from './workflowContract';
 export type { VoiceSessionListHTMLHandlerOptions, VoiceSessionListItem, VoiceSessionListOptions, VoiceSessionListRoutesOptions, VoiceSessionListStatus, VoiceSessionReplay, VoiceSessionReplayHTMLHandlerOptions, VoiceSessionReplayOptions, VoiceSessionReplayRoutesOptions, VoiceSessionReplayTurn } from './sessionReplay';
 export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOptions, OpenAIVoiceAssistantModelOptions, VoiceProviderRouterEvent, VoiceProviderRouterFallbackMode, VoiceProviderRouterHealthOptions, VoiceProviderRouterOptions, VoiceProviderRouterPolicy, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceJSONAssistantModelHandler, VoiceJSONAssistantModelOptions } from './modelAdapters';
 export type { VoiceProviderHealthStatus, VoiceProviderHealthSummary, VoiceProviderHealthSummaryOptions } from './providerHealth';

package/dist/index.js

@@ -8078,6 +8078,7 @@ var evaluateScenarioSession = (scenario, sessionId, events) => {
   const turnCount = events.filter((event) => event.type === "turn.committed").length;
   const sessionErrorCount = events.filter((event) => event.type === "session.error").length;
   const providerErrorCount = countProviderErrors(events);
+  const workflowContractEvents = events.filter((event) => event.type === "workflow.contract");
   for (const missing of includesAll(committedText, scenario.requiredTranscriptIncludes ?? [])) {
     issues.push(`Missing transcript text: ${missing}`);
   }
@@ -8121,6 +8122,16 @@ var evaluateScenarioSession = (scenario, sessionId, events) => {
       issues.push(`Missing payload path: ${path}`);
     }
   }
+  for (const contractId of scenario.requiredWorkflowContracts ?? []) {
+    const matching = workflowContractEvents.filter((event) => getString6(event.payload.contractId) === contractId);
+    if (matching.length === 0) {
+      issues.push(`Missing workflow contract: ${contractId}`);
+      continue;
+    }
+    if (matching.some((event) => getString6(event.payload.status) !== "pass")) {
+      issues.push(`Workflow contract failed: ${contractId}`);
+    }
+  }
   return {
     eventCount: events.length,
     issues,
@@ -8167,6 +8178,33 @@ var runVoiceScenarioEvals = async (options = {}) => {
     total: results.length
   };
 };
+var resolveScenarioFixtures = async (options) => [...options.fixtures ?? [], ...await options.fixtureStore?.list() ?? []];
+var runVoiceScenarioFixtureEvals = async (options = {}) => {
+  const fixtures = await resolveScenarioFixtures(options);
+  const results = await Promise.all(fixtures.map(async (fixture) => {
+    const report = await runVoiceScenarioEvals({
+      events: fixture.events,
+      scenarios: options.scenarios
+    });
+    return {
+      description: fixture.description,
+      fixtureId: fixture.id,
+      label: fixture.label ?? fixture.id,
+      report,
+      status: report.status
+    };
+  }));
+  const failed = results.filter((fixture) => fixture.status === "fail").length;
+  const passed = results.length - failed;
+  return {
+    checkedAt: Date.now(),
+    failed,
+    fixtures: results,
+    passed,
+    status: failed > 0 ? "fail" : "pass",
+    total: results.length
+  };
+};
 var summarizeEvalBaseline = (report) => {
   const failedSessionIds = report.sessions.filter((session) => session.status === "fail").map((session) => session.sessionId).sort();
   return {
@@ -8228,6 +8266,20 @@ var createVoiceFileEvalBaselineStore = (filePath) => ({
     await Bun.write(filePath, JSON.stringify(report, null, 2));
   }
 });
+var createVoiceFileScenarioFixtureStore = (filePath) => ({
+  list: async () => {
+    const file = Bun.file(filePath);
+    if (!await file.exists()) {
+      return [];
+    }
+    const text = await file.text();
+    if (!text.trim()) {
+      return [];
+    }
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : parsed.fixtures ?? [];
+  }
+});
 var formatTime = (value) => value === undefined ? "unknown" : new Date(value).toLocaleString();
 var formatPercent = (value) => `${(value * 100).toFixed(2)}%`;
 var renderVoiceEvalHTML = (report, options = {}) => {
@@ -8258,6 +8310,15 @@ var renderVoiceScenarioEvalHTML = (report, options = {}) => {
   }).join("") : "<section><p>No scenarios configured.</p></section>";
   return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml9(title)}</title><style>body{font-family:ui-sans-serif,system-ui,sans-serif;margin:2rem;background:#f8f7f2;color:#181713}main{max-width:1180px;margin:auto}nav{display:flex;gap:.5rem;flex-wrap:wrap;margin-bottom:1rem}nav a{background:#181713;border-radius:999px;color:white;padding:.35rem .7rem;text-decoration:none}.status{border-radius:999px;display:inline-flex;font-weight:800;padding:.35rem .75rem}.status.pass{background:#dcfce7;color:#166534}.status.fail{background:#fee2e2;color:#991b1b}.grid{display:grid;gap:1rem;grid-template-columns:repeat(auto-fit,minmax(160px,1fr));margin:1rem 0}.card,section{background:white;border:1px solid #e7e5e4;border-radius:1rem;padding:1rem}.card strong{display:block;font-size:2rem}section{margin:1rem 0}table{border-collapse:collapse;width:100%;margin-top:1rem}td,th{border-bottom:1px solid #eee;padding:.75rem;text-align:left}tr.fail td{border-left:4px solid #dc2626}tr.pass td{border-left:4px solid #16a34a}</style></head><body><main>${links}<h1>${escapeHtml9(title)}</h1><p class="status ${report.status}">${report.status}</p><div class="grid"><article class="card"><span>Total</span><strong>${report.total}</strong></article><article class="card"><span>Passed</span><strong>${report.passed}</strong></article><article class="card"><span>Failed</span><strong>${report.failed}</strong></article></div>${scenarios}</main></body></html>`;
 };
+var renderVoiceScenarioFixtureEvalHTML = (report, options = {}) => {
+  const title = options.title ?? "AbsoluteJS Voice Fixture Evals";
+  const links = options.links?.length ? `<nav>${options.links.map((link) => `<a href="${escapeHtml9(link.href)}">${escapeHtml9(link.label)}</a>`).join("")}</nav>` : "";
+  const fixtures = report.fixtures.length ? report.fixtures.map((fixture) => {
+    const scenarios = fixture.report.scenarios.map((scenario) => `<tr class="${scenario.status}"><td>${escapeHtml9(scenario.label)}</td><td>${escapeHtml9(scenario.status)}</td><td>${scenario.matchedSessions}</td><td>${escapeHtml9([...scenario.issues, ...scenario.sessions.flatMap((session) => session.issues)].join(", ") || "none")}</td></tr>`).join("");
+    return `<section class="${fixture.status}"><h2>${escapeHtml9(fixture.label)}</h2>${fixture.description ? `<p>${escapeHtml9(fixture.description)}</p>` : ""}<p class="status ${fixture.status}">${fixture.status}</p><table><thead><tr><th>Scenario</th><th>Status</th><th>Sessions</th><th>Issues</th></tr></thead><tbody>${scenarios}</tbody></table></section>`;
+  }).join("") : "<section><p>No scenario fixtures configured.</p></section>";
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml9(title)}</title><style>body{font-family:ui-sans-serif,system-ui,sans-serif;margin:2rem;background:#f8f7f2;color:#181713}main{max-width:1180px;margin:auto}nav{display:flex;gap:.5rem;flex-wrap:wrap;margin-bottom:1rem}nav a{background:#181713;border-radius:999px;color:white;padding:.35rem .7rem;text-decoration:none}.status{border-radius:999px;display:inline-flex;font-weight:800;padding:.35rem .75rem}.status.pass{background:#dcfce7;color:#166534}.status.fail{background:#fee2e2;color:#991b1b}.grid{display:grid;gap:1rem;grid-template-columns:repeat(auto-fit,minmax(160px,1fr));margin:1rem 0}.card,section{background:white;border:1px solid #e7e5e4;border-radius:1rem;padding:1rem}.card strong{display:block;font-size:2rem}section{margin:1rem 0}table{border-collapse:collapse;width:100%;margin-top:1rem}td,th{border-bottom:1px solid #eee;padding:.75rem;text-align:left}tr.fail td{border-left:4px solid #dc2626}tr.pass td{border-left:4px solid #16a34a}</style></head><body><main>${links}<h1>${escapeHtml9(title)}</h1><p class="status ${report.status}">${report.status}</p><div class="grid"><article class="card"><span>Total</span><strong>${report.total}</strong></article><article class="card"><span>Passed</span><strong>${report.passed}</strong></article><article class="card"><span>Failed</span><strong>${report.failed}</strong></article></div>${fixtures}</main></body></html>`;
+};
 var createVoiceEvalRoutes = (options) => {
   const path = options.path ?? "/evals";
   const routes = new Elysia7({
@@ -8279,6 +8340,11 @@ var createVoiceEvalRoutes = (options) => {
     scenarios: options.scenarios,
     store: options.store
   });
+  const getFixtureReport = () => runVoiceScenarioFixtureEvals({
+    fixtures: options.fixtures,
+    fixtureStore: options.fixtureStore,
+    scenarios: options.scenarios
+  });
   routes.get(path, async () => {
     const report = await getReport();
     return new Response(renderVoiceEvalHTML(report, {
@@ -8366,8 +8432,176 @@ var createVoiceEvalRoutes = (options) => {
     }
     return report;
   });
+  routes.get(`${path}/fixtures`, async () => {
+    const report = await getFixtureReport();
+    return new Response(renderVoiceScenarioFixtureEvalHTML(report, {
+      links: options.links,
+      title: `${options.title ?? "AbsoluteJS Voice Evals"} Fixtures`
+    }), {
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        ...options.headers
+      }
+    });
+  });
+  routes.get(`${path}/fixtures/json`, async () => getFixtureReport());
+  routes.get(`${path}/fixtures/status`, async ({ set }) => {
+    const report = await getFixtureReport();
+    if (report.status === "fail") {
+      set.status = 503;
+    }
+    return report;
+  });
   return routes;
 };
+// src/workflowContract.ts
+var getObject2 = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+var getPathValue2 = (value, path) => {
+  let current = value;
+  for (const part of path.split(".").filter(Boolean)) {
+    const record = getObject2(current);
+    if (!record || !(part in record)) {
+      return;
+    }
+    current = record[part];
+  }
+  return current;
+};
+var hasValue = (value, match) => {
+  switch (match) {
+    case "boolean":
+      return typeof value === "boolean";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "string":
+      return typeof value === "string";
+    case "truthy":
+      return Boolean(value);
+    case "non-empty":
+    default:
+      return Array.isArray(value) ? value.length > 0 : typeof value === "string" ? value.trim().length > 0 : value !== undefined && value !== null;
+  }
+};
+var resolveOutcome2 = (routeResult) => {
+  if (routeResult.complete)
+    return "complete";
+  if (routeResult.transfer)
+    return "transfer";
+  if (routeResult.escalate)
+    return "escalate";
+  if (routeResult.voicemail)
+    return "voicemail";
+  if (routeResult.noAnswer)
+    return "no-answer";
+  return;
+};
+var validateVoiceWorkflowRouteResult = (definition, routeResult) => {
+  const issues = [];
+  const requiredFields = (definition.fields ?? []).filter((field) => field.required !== false).map((field) => field.path);
+  const missingFields = [];
+  const outcome = resolveOutcome2(routeResult);
+  if (definition.outcome && outcome !== definition.outcome) {
+    issues.push({
+      code: "workflow.outcome_mismatch",
+      message: `Expected workflow outcome ${definition.outcome}, saw ${outcome ?? "none"}.`
+    });
+  }
+  for (const field of definition.fields ?? []) {
+    if (field.required === false)
+      continue;
+    const paths = [field.path, ...field.aliases ?? []];
+    const present = paths.some((path) => hasValue(getPathValue2(routeResult.result, path), field.match ?? "non-empty"));
+    if (!present) {
+      missingFields.push(field.path);
+      issues.push({
+        code: "workflow.missing_field",
+        field: field.path,
+        message: `Missing required workflow field: ${field.label ?? field.path}.`
+      });
+    }
+  }
+  issues.push(...definition.validate?.({
+    result: routeResult.result,
+    routeResult
+  }) ?? []);
+  return {
+    contractId: definition.id,
+    issues,
+    missingFields,
+    outcome,
+    pass: issues.length === 0,
+    requiredFields
+  };
+};
+var createVoiceWorkflowScenario = (definition, overrides = {}) => ({
+  description: definition.description,
+  forbiddenHandoffActions: definition.forbiddenHandoffActions,
+  id: definition.id,
+  label: definition.label,
+  maxProviderErrors: definition.maxProviderErrors,
+  maxSessionErrors: definition.maxSessionErrors,
+  minSessions: definition.minSessions,
+  minTurns: definition.minTurns,
+  requiredAssistantIncludes: definition.requiredAssistantIncludes,
+  requiredDisposition: definition.requiredDisposition,
+  requiredHandoffActions: definition.requiredHandoffActions,
+  requiredLifecycleTypes: definition.requiredLifecycleTypes,
+  requiredTranscriptIncludes: definition.requiredTranscriptIncludes,
+  requiredWorkflowContracts: [definition.id],
+  scenarioId: definition.scenarioId,
+  ...overrides
+});
+var createVoiceWorkflowContract = (definition) => ({
+  assertRouteResult: (routeResult) => {
+    const validation = validateVoiceWorkflowRouteResult(definition, routeResult);
+    if (!validation.pass) {
+      throw new Error(`Voice workflow contract ${definition.id} failed: ${validation.issues.map((issue) => issue.message).join(" ")}`);
+    }
+  },
+  definition,
+  toScenarioEval: (overrides) => createVoiceWorkflowScenario(definition, overrides),
+  validateRouteResult: (routeResult) => validateVoiceWorkflowRouteResult(definition, routeResult)
+});
+var recordVoiceWorkflowContractTrace = async (input) => input.store.append({
+  at: input.at ?? Date.now(),
+  payload: {
+    contractId: input.contractId ?? input.validation.contractId,
+    issues: input.validation.issues,
+    missingFields: input.validation.missingFields,
+    outcome: input.validation.outcome,
+    requiredFields: input.validation.requiredFields,
+    status: input.validation.pass ? "pass" : "fail"
+  },
+  scenarioId: input.scenarioId,
+  sessionId: input.sessionId,
+  traceId: input.traceId,
+  turnId: input.turnId,
+  type: "workflow.contract"
+});
+var createVoiceWorkflowContractHandler = (input) => {
+  return async (session, turn, api, context) => {
+    const legacyHandler = input.handler;
+    const objectHandler = input.handler;
+    const result = input.handler.length >= 4 ? await legacyHandler(session, turn, api, context) : await objectHandler({ api, context, session, turn });
+    if (!result)
+      return result;
+    const resolved = input.resolveContract?.({ context, result, session, turn }) ?? input.contract;
+    if (!resolved)
+      return result;
+    const contract = "validateRouteResult" in resolved ? resolved : createVoiceWorkflowContract(resolved);
+    const validation = contract.validateRouteResult(result);
+    if (input.store) {
+      await recordVoiceWorkflowContractTrace({
+        scenarioId: session.scenarioId,
+        sessionId: session.id,
+        store: input.store,
+        turnId: turn.id,
+        validation
+      });
+    }
+    return result;
+  };
+};
 // src/sessionReplay.ts
 import { Elysia as Elysia8 } from "elysia";
 var getString7 = (value) => typeof value === "string" ? value : undefined;
@@ -13293,6 +13527,7 @@ export {
   withVoiceIntegrationEventId,
   voice,
   verifyVoiceOpsWebhookSignature,
+  validateVoiceWorkflowRouteResult,
   transcodeTwilioInboundPayloadToPCM16,
   transcodePCMToTwilioOutboundPayload,
   summarizeVoiceTraceSinkDeliveries,
@@ -13312,6 +13547,7 @@ export {
   shapeTelephonyAssistantText,
   selectVoiceTraceEventsForPrune,
   runVoiceSessionEvals,
+  runVoiceScenarioFixtureEvals,
   runVoiceScenarioEvals,
   resolveVoiceTraceRedactionOptions,
   resolveVoiceSTTRoutingStrategy,
@@ -13330,6 +13566,7 @@ export {
   renderVoiceTraceMarkdown,
   renderVoiceTraceHTML,
   renderVoiceSessionsHTML,
+  renderVoiceScenarioFixtureEvalHTML,
   renderVoiceScenarioEvalHTML,
   renderVoiceResilienceHTML,
   renderVoiceQualityHTML,
@@ -13344,6 +13581,7 @@ export {
   redactVoiceTraceText,
   redactVoiceTraceEvents,
   redactVoiceTraceEvent,
+  recordVoiceWorkflowContractTrace,
   recordVoiceRuntimeOps,
   pruneVoiceTraceEvents,
   matchesVoiceOpsTaskAssignmentRule,
@@ -13369,6 +13607,9 @@ export {
   createVoiceZendeskTicketUpdateSink,
   createVoiceZendeskTicketSyncSinks,
   createVoiceZendeskTicketSink,
+  createVoiceWorkflowScenario,
+  createVoiceWorkflowContractHandler,
+  createVoiceWorkflowContract,
   createVoiceWebhookHandoffAdapter,
   createVoiceWebhookDeliveryWorkerLoop,
   createVoiceWebhookDeliveryWorker,
@@ -13455,6 +13696,7 @@ export {
   createVoiceFileTraceEventStore,
   createVoiceFileTaskStore,
   createVoiceFileSessionStore,
+  createVoiceFileScenarioFixtureStore,
   createVoiceFileRuntimeStorage,
   createVoiceFileReviewStore,
   createVoiceFileIntegrationEventStore,

package/dist/trace.d.ts

@@ -1,4 +1,4 @@
-export type VoiceTraceEventType = 'assistant.guardrail' | 'assistant.memory' | 'assistant.run' | 'agent.handoff' | 'agent.model' | 'agent.result' | 'agent.tool' | 'call.handoff' | 'call.lifecycle' | 'session.error' | 'turn.assistant' | 'turn.committed' | 'turn.cost' | 'turn.transcript';
+export type VoiceTraceEventType = 'assistant.guardrail' | 'assistant.memory' | 'assistant.run' | 'agent.handoff' | 'agent.model' | 'agent.result' | 'agent.tool' | 'call.handoff' | 'call.lifecycle' | 'session.error' | 'turn.assistant' | 'turn.committed' | 'turn.cost' | 'turn.transcript' | 'workflow.contract';
 export type VoiceTraceEvent<TPayload extends Record<string, unknown> = Record<string, unknown>> = {
     at: number;
     id?: string;

package/dist/workflowContract.d.ts

@@ -0,0 +1,85 @@
+import type { VoiceScenarioEvalDefinition } from './evalRoutes';
+import type { StoredVoiceTraceEvent, VoiceTraceEventStore } from './trace';
+import type { VoiceOnTurnHandler, VoiceRouteResult, VoiceSessionRecord, VoiceTurnRecord } from './types';
+export type VoiceWorkflowOutcome = 'complete' | 'transfer' | 'escalate' | 'voicemail' | 'no-answer';
+export type VoiceWorkflowContractFieldMatch = 'boolean' | 'non-empty' | 'number' | 'string' | 'truthy';
+export type VoiceWorkflowContractField = {
+    aliases?: string[];
+    label?: string;
+    match?: VoiceWorkflowContractFieldMatch;
+    path: string;
+    required?: boolean;
+};
+export type VoiceWorkflowContractDefinition<TResult = unknown> = {
+    description?: string;
+    fields?: VoiceWorkflowContractField[];
+    forbiddenHandoffActions?: string[];
+    id: string;
+    label?: string;
+    maxProviderErrors?: number;
+    maxSessionErrors?: number;
+    minSessions?: number;
+    minTurns?: number;
+    outcome?: VoiceWorkflowOutcome;
+    requiredAssistantIncludes?: string[];
+    requiredDisposition?: string;
+    requiredHandoffActions?: string[];
+    requiredLifecycleTypes?: string[];
+    requiredTranscriptIncludes?: string[];
+    scenarioId?: string;
+    validate?: (input: {
+        result: TResult | undefined;
+        routeResult: VoiceRouteResult<TResult>;
+    }) => VoiceWorkflowContractValidationIssue[];
+};
+export type VoiceWorkflowContractValidationIssue = {
+    code: string;
+    field?: string;
+    message: string;
+};
+export type VoiceWorkflowContractValidation = {
+    contractId: string;
+    issues: VoiceWorkflowContractValidationIssue[];
+    missingFields: string[];
+    outcome?: VoiceWorkflowOutcome;
+    pass: boolean;
+    requiredFields: string[];
+};
+export type VoiceWorkflowContract<TResult = unknown> = {
+    assertRouteResult: (routeResult: VoiceRouteResult<TResult>) => void;
+    definition: VoiceWorkflowContractDefinition<TResult>;
+    toScenarioEval: (overrides?: Partial<VoiceScenarioEvalDefinition>) => VoiceScenarioEvalDefinition;
+    validateRouteResult: (routeResult: VoiceRouteResult<TResult>) => VoiceWorkflowContractValidation;
+};
+export type VoiceWorkflowContractTracePayload = {
+    contractId: string;
+    issues: VoiceWorkflowContractValidationIssue[];
+    missingFields: string[];
+    outcome?: VoiceWorkflowOutcome;
+    requiredFields: string[];
+    status: 'pass' | 'fail';
+};
+export declare const validateVoiceWorkflowRouteResult: <TResult = unknown>(definition: VoiceWorkflowContractDefinition<TResult>, routeResult: VoiceRouteResult<TResult>) => VoiceWorkflowContractValidation;
+export declare const createVoiceWorkflowScenario: <TResult = unknown>(definition: VoiceWorkflowContractDefinition<TResult>, overrides?: Partial<VoiceScenarioEvalDefinition>) => VoiceScenarioEvalDefinition;
+export declare const createVoiceWorkflowContract: <TResult = unknown>(definition: VoiceWorkflowContractDefinition<TResult>) => VoiceWorkflowContract<TResult>;
+export declare const recordVoiceWorkflowContractTrace: (input: {
+    at?: number;
+    contractId?: string;
+    scenarioId?: string;
+    sessionId: string;
+    store: VoiceTraceEventStore;
+    traceId?: string;
+    turnId?: string;
+    validation: VoiceWorkflowContractValidation;
+}) => Promise<StoredVoiceTraceEvent<VoiceWorkflowContractTracePayload>>;
+export declare const createVoiceWorkflowContractHandler: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(input: {
+    contract?: VoiceWorkflowContract<TResult> | VoiceWorkflowContractDefinition<TResult>;
+    handler: VoiceOnTurnHandler<TContext, TSession, TResult>;
+    resolveContract?: (args: {
+        context: TContext;
+        result: VoiceRouteResult<TResult>;
+        session: TSession;
+        turn: VoiceTurnRecord;
+    }) => VoiceWorkflowContract<TResult> | VoiceWorkflowContractDefinition<TResult> | undefined;
+    store?: VoiceTraceEventStore;
+}) => VoiceOnTurnHandler<TContext, TSession, TResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.44",
+	"version": "0.0.22-beta.46",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",