@absolutejs/voice 0.0.22-beta.228 → 0.0.22-beta.229

package/README.md

@@ -2753,6 +2753,19 @@ Readiness emits the stable `voice.readiness.ops_recovery` gate code when unresol
 
 Use observability exports when a buyer wants the hosted-dashboard evidence graph, but inside their own storage, warehouse, SIEM, incident flow, or release notes. The export manifest links traces, audits, operations records, delivery queues, provider SLOs, readiness reports, screenshots, and proof-pack artifacts without making AbsoluteJS Voice the dashboard.
 
+Every export manifest and artifact index includes a stable schema contract:
+
+```ts
+import {
+	assertVoiceObservabilityExportSchema,
+	voiceObservabilityExportSchemaId,
+	voiceObservabilityExportSchemaVersion
+} from '@absolutejs/voice';
+
+assertVoiceObservabilityExportSchema(exportReport);
+console.log(voiceObservabilityExportSchemaId, voiceObservabilityExportSchemaVersion);
+```
+
 ```ts
 import {
 	buildVoiceObservabilityExport,
@@ -2832,7 +2845,7 @@ const exportReport = await buildVoiceObservabilityExport({
 });
 ```
 
-The route helper exposes JSON at `/api/voice/observability-export`, an artifact index at `/api/voice/observability-export/artifacts`, per-artifact downloads at `/api/voice/observability-export/artifacts/:artifactId`, delivery at `POST /api/voice/observability-export/deliveries`, delivery history at `GET /api/voice/observability-export/deliveries`, Markdown at `/voice/observability-export.md`, and HTML at `/voice/observability-export`. Path-backed artifacts are hashed with SHA-256 by default, include byte size and freshness metadata, and can fail the export when required evidence is missing or stale. File delivery writes `manifest.json`, `artifact-index.json`, and artifact files into a customer-owned archive directory; webhook delivery posts the manifest and artifact index to a buyer-owned collector, SIEM bridge, or warehouse endpoint; S3 delivery writes the same manifest, index, and artifact files through Bun's native S3 client; SQLite and Postgres delivery persist the manifest, artifact index, checksum metadata, status, run id, and timestamps into buyer-owned database tables. Delivery receipt stores persist run id, destinations, status, and target history so operators can prove exports have been continuously healthy. Failed trace/audit deliveries fail the export report, pending deliveries warn, and every trace/audit envelope includes the linked operations-record URL when one is configured. This is the primitive to use when customers ask how voice evidence leaves the app without going through a hosted vendor dashboard.
+The route helper exposes JSON at `/api/voice/observability-export`, an artifact index at `/api/voice/observability-export/artifacts`, per-artifact downloads at `/api/voice/observability-export/artifacts/:artifactId`, delivery at `POST /api/voice/observability-export/deliveries`, delivery history at `GET /api/voice/observability-export/deliveries`, Markdown at `/voice/observability-export.md`, and HTML at `/voice/observability-export`. Path-backed artifacts are hashed with SHA-256 by default, include byte size and freshness metadata, and can fail the export when required evidence is missing or stale. File delivery writes `manifest.json`, `artifact-index.json`, and artifact files into a customer-owned archive directory; webhook delivery posts the manifest and artifact index to a buyer-owned collector, SIEM bridge, or warehouse endpoint; S3 delivery writes the same manifest, index, and artifact files through Bun's native S3 client; SQLite and Postgres delivery persist the schema id/version, manifest, artifact index, checksum metadata, status, run id, and timestamps into buyer-owned database tables. Delivery receipt stores persist run id, destinations, status, schema, and target history so operators can prove exports have been continuously healthy. Failed trace/audit deliveries fail the export report, pending deliveries warn, and every trace/audit envelope includes the linked operations-record URL when one is configured. This is the primitive to use when customers ask how voice evidence leaves the app without going through a hosted vendor dashboard.
 
 Pass the same report into production readiness when export health should block deploys:
 

package/dist/index.d.ts

@@ -53,7 +53,7 @@ export { createVoiceReadinessProfile, recommendVoiceReadinessProfile } from './r
 export { buildVoiceProviderContractMatrix, createVoiceProviderContractMatrixHTMLHandler, createVoiceProviderContractMatrixJSONHandler, createVoiceProviderContractMatrixPreset, createVoiceProviderContractMatrixRoutes, evaluateVoiceProviderStackGaps, renderVoiceProviderContractMatrixHTML, recommendVoiceProviderStack } from './providerStackRecommendations';
 export { buildVoiceOpsConsoleReport, createVoiceOpsConsoleRoutes, renderVoiceOpsConsoleHTML } from './opsConsoleRoutes';
 export { buildVoiceOperationsRecord, createVoiceOperationsRecordRoutes, renderVoiceOperationsRecordHTML, renderVoiceOperationsRecordIncidentMarkdown } from './operationsRecord';
-export { buildVoiceObservabilityArtifactIndex, buildVoiceObservabilityExportDeliveryHistory, buildVoiceObservabilityExport, createVoiceFileObservabilityExportDeliveryReceiptStore, createVoiceMemoryObservabilityExportDeliveryReceiptStore, createVoiceObservabilityExportRoutes, deliverVoiceObservabilityExport, renderVoiceObservabilityExportMarkdown } from './observabilityExport';
+export { buildVoiceObservabilityArtifactIndex, buildVoiceObservabilityExportDeliveryHistory, buildVoiceObservabilityExport, assertVoiceObservabilityExportSchema, createVoiceObservabilityExportSchema, createVoiceFileObservabilityExportDeliveryReceiptStore, createVoiceMemoryObservabilityExportDeliveryReceiptStore, createVoiceObservabilityExportRoutes, deliverVoiceObservabilityExport, renderVoiceObservabilityExportMarkdown, voiceObservabilityExportSchemaId, voiceObservabilityExportSchemaVersion } from './observabilityExport';
 export { buildVoiceOpsRecoveryReadinessCheck, buildVoiceOpsRecoveryReport, createVoiceOpsRecoveryRoutes, renderVoiceOpsRecoveryHTML, renderVoiceOpsRecoveryMarkdown } from './opsRecovery';
 export { buildVoiceIncidentBundle, createStoredVoiceIncidentBundleArtifact, createVoiceIncidentBundleRoutes, createVoiceMemoryIncidentBundleStore, pruneVoiceIncidentBundleArtifacts, saveVoiceIncidentBundleArtifact } from './incidentBundle';
 export { summarizeVoiceOpsStatus } from './opsStatus';
@@ -118,7 +118,7 @@ export type { VoiceProductionReadinessAction, VoiceProductionReadinessAuditOptio
 export type { VoiceReadinessProfileName, VoiceReadinessProfileOptions, VoiceReadinessProfileRecommendation, VoiceReadinessProfileRecommendationScore, VoiceReadinessProfileRoutesOptions } from './readinessProfiles';
 export type { VoiceProviderStackChoice, VoiceProviderStackCapabilities, VoiceProviderStackCapabilityGap, VoiceProviderStackCapabilityGapInput, VoiceProviderStackCapabilityGapReport, VoiceProviderContractCheck, VoiceProviderContractCheckStatus, VoiceProviderContractDefinition, VoiceProviderContractMatrixHandlerOptions, VoiceProviderContractMatrixHTMLHandlerOptions, VoiceProviderContractMatrixInput, VoiceProviderContractMatrixPresetOptions, VoiceProviderContractMatrixReport, VoiceProviderContractMatrixRoutesOptions, VoiceProviderContractMatrixRow, VoiceProviderStackInput, VoiceProviderStackKind, VoiceProviderStackRecommendation } from './providerStackRecommendations';
 export type { VoiceOperationsRecord, VoiceOperationsRecordAgentHandoff, VoiceOperationsRecordAuditSummary, VoiceOperationsRecordIntegrationEventSummary, VoiceOperationsRecordOptions, VoiceOperationsRecordOutcome, VoiceOperationsRecordProviderDecision, VoiceOperationsRecordReviewSummary, VoiceOperationsRecordRoutesOptions, VoiceOperationsRecordStatus, VoiceOperationsRecordTaskSummary, VoiceOperationsRecordTranscriptTurn, VoiceOperationsRecordTool } from './operationsRecord';
-export type { VoiceObservabilityExportArtifact, VoiceObservabilityExportArtifactChecksum, VoiceObservabilityExportArtifactFreshness, VoiceObservabilityExportArtifactIndex, VoiceObservabilityExportArtifactIndexItem, VoiceObservabilityExportArtifactKind, VoiceObservabilityExportDeliverySummary, VoiceObservabilityExportDeliveryDestination, VoiceObservabilityExportDeliveryDestinationResult, VoiceObservabilityExportDeliveryHistory, VoiceObservabilityExportDeliveryOptions, VoiceObservabilityExportDeliveryReceipt, VoiceObservabilityExportDeliveryReceiptStore, VoiceObservabilityExportDeliveryReport, VoiceObservabilityExportEnvelope, VoiceObservabilityExportIssue, VoiceObservabilityExportIssueCode, VoiceObservabilityExportOptions, VoiceObservabilityExportRedactionSummary, VoiceObservabilityExportReport, VoiceObservabilityExportRoutesOptions, VoiceObservabilityExportStatus } from './observabilityExport';
+export type { VoiceObservabilityExportArtifact, VoiceObservabilityExportArtifactChecksum, VoiceObservabilityExportArtifactFreshness, VoiceObservabilityExportArtifactIndex, VoiceObservabilityExportArtifactIndexItem, VoiceObservabilityExportArtifactKind, VoiceObservabilityExportDeliverySummary, VoiceObservabilityExportDeliveryDestination, VoiceObservabilityExportDeliveryDestinationResult, VoiceObservabilityExportDeliveryHistory, VoiceObservabilityExportDeliveryOptions, VoiceObservabilityExportDeliveryReceipt, VoiceObservabilityExportDeliveryReceiptStore, VoiceObservabilityExportDeliveryReport, VoiceObservabilityExportEnvelope, VoiceObservabilityExportIssue, VoiceObservabilityExportIssueCode, VoiceObservabilityExportOptions, VoiceObservabilityExportRedactionSummary, VoiceObservabilityExportReport, VoiceObservabilityExportRoutesOptions, VoiceObservabilityExportSchema, VoiceObservabilityExportStatus } from './observabilityExport';
 export type { VoiceOpsRecoveryFailedSession, VoiceOpsRecoveryInterventionSummary, VoiceOpsRecoveryIssue, VoiceOpsRecoveryIssueCode, VoiceOpsRecoveryLinks, VoiceOpsRecoveryProviderSummary, VoiceOpsRecoveryReport, VoiceOpsRecoveryReportOptions, VoiceOpsRecoveryRoutesOptions, VoiceOpsRecoveryStatus } from './opsRecovery';
 export type { StoredVoiceIncidentBundleArtifact, VoiceIncidentBundle, VoiceIncidentBundleArtifactOptions, VoiceIncidentBundleFormat, VoiceIncidentBundleOptions, VoiceIncidentBundleRetentionOptions, VoiceIncidentBundleRetentionReport, VoiceIncidentBundleRoutesOptions, VoiceIncidentBundleStore, VoiceIncidentBundleStoreFilter, VoiceIncidentBundleSummary } from './incidentBundle';
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds } from './qualityRoutes';

package/dist/index.js

@@ -22987,6 +22987,17 @@ var createVoiceOperationsRecordRoutes = (options) => {
 };
 
 // src/observabilityExport.ts
+var voiceObservabilityExportSchemaVersion = "1.0.0";
+var voiceObservabilityExportSchemaId = "com.absolutejs.voice.observability-export";
+var createVoiceObservabilityExportSchema = () => ({
+  id: voiceObservabilityExportSchemaId,
+  version: voiceObservabilityExportSchemaVersion
+});
+var assertVoiceObservabilityExportSchema = (input) => {
+  if (input.schema?.id !== voiceObservabilityExportSchemaId || input.schema?.version !== voiceObservabilityExportSchemaVersion) {
+    throw new Error(`Unsupported voice observability export schema: ${input.schema?.id ?? "missing"}@${input.schema?.version ?? "missing"}`);
+  }
+};
 var isDeliveryStore = (value) => !Array.isArray(value) && typeof value.list === "function";
 var getString17 = (value) => typeof value === "string" ? value : undefined;
 var getProviderKind = (payload) => getString17(payload.kind) ?? getString17(payload.providerKind);
@@ -23048,6 +23059,7 @@ var buildObservabilityExportDatabaseRecord = (input) => ({
   exportStatus: input.report.status,
   manifest: input.report,
   runId: input.runId,
+  schema: input.report.schema,
   status: input.report.status
 });
 var deliverObservabilityExportToSQLite = async (input) => {
@@ -23460,6 +23472,7 @@ var buildVoiceObservabilityExport = async (options = {}) => {
       enabled: Boolean(options.redact),
       mode: options.redact ? "redacted" : "none"
     },
+    schema: createVoiceObservabilityExportSchema(),
     sessionIds,
     status,
     summary: {
@@ -23528,6 +23541,7 @@ var buildVoiceObservabilityArtifactIndex = (report) => {
   return {
     artifacts,
     checkedAt: report.checkedAt,
+    schema: report.schema,
     status: report.status,
     summary: {
       downloadable: artifacts.filter((artifact) => artifact.downloadHref).length,
@@ -23570,6 +23584,7 @@ var deliverVoiceObservabilityExport = async (options) => {
           destinationKind: destination.kind,
           label,
           manifestBytes: byteLength(manifest),
+          schema: options.report.schema,
           status: "delivered",
           target
         };
@@ -23614,6 +23629,7 @@ var deliverVoiceObservabilityExport = async (options) => {
           destinationKind: destination.kind,
           label,
           manifestBytes: byteLength(manifest),
+          schema: options.report.schema,
           status: "delivered",
           target: destination.bucket ? `s3://${destination.bucket}/${rootKey}` : rootKey
         };
@@ -23635,6 +23651,7 @@ var deliverVoiceObservabilityExport = async (options) => {
           destinationKind: destination.kind,
           label,
           manifestBytes: byteLength(manifest),
+          schema: options.report.schema,
           status: "delivered",
           target
         };
@@ -23656,6 +23673,7 @@ var deliverVoiceObservabilityExport = async (options) => {
           destinationKind: destination.kind,
           label,
           manifestBytes: byteLength(manifest),
+          schema: options.report.schema,
           status: "delivered",
           target
         };
@@ -23691,6 +23709,7 @@ var deliverVoiceObservabilityExport = async (options) => {
         destinationKind: destination.kind,
         label,
         manifestBytes: byteLength(manifest),
+        schema: options.report.schema,
         status: "delivered",
         target: destination.url
       };
@@ -23703,6 +23722,7 @@ var deliverVoiceObservabilityExport = async (options) => {
         error: error instanceof Error ? error.message : String(error),
         label,
         manifestBytes: byteLength(manifest),
+        schema: options.report.schema,
         status: "failed",
         target: observabilityExportDeliveryFailureTarget(destination)
       };
@@ -28434,6 +28454,8 @@ export {
   withVoiceOpsTaskId,
   withVoiceIntegrationEventId,
   voiceTelephonyOutcomeToRouteResult,
+  voiceObservabilityExportSchemaVersion,
+  voiceObservabilityExportSchemaId,
   voiceComplianceRedactionDefaults,
   voice,
   verifyVoiceTwilioWebhookSignature,
@@ -28741,6 +28763,7 @@ export {
   createVoiceOpsConsoleRoutes,
   createVoiceOpsActionAuditRoutes,
   createVoiceOperationsRecordRoutes,
+  createVoiceObservabilityExportSchema,
   createVoiceObservabilityExportRoutes,
   createVoiceMemoryTraceSinkDeliveryStore,
   createVoiceMemoryTraceEventStore,
@@ -28898,6 +28921,7 @@ export {
   buildVoiceAuditDeliveryReport,
   assignVoiceOpsTask,
   assertVoiceProviderRoutingContract,
+  assertVoiceObservabilityExportSchema,
   assertVoiceLatencySLOGate,
   assertVoiceAgentSquadContract,
   applyVoiceTelephonyOutcome,

package/dist/observabilityExport.d.ts

@@ -8,6 +8,16 @@ import { type VoiceTraceSinkDeliveryQueueSummary } from './queue';
 import { type StoredVoiceTraceEvent, type VoiceTraceEventStore, type VoiceTraceEventType, type VoiceTraceRedactionConfig, type VoiceTraceSinkDeliveryRecord, type VoiceTraceSinkDeliveryStore, type VoiceTraceSummary } from './trace';
 import type { VoicePostgresClient } from './postgresStore';
 export type VoiceObservabilityExportStatus = 'fail' | 'pass' | 'warn';
+export declare const voiceObservabilityExportSchemaVersion = "1.0.0";
+export declare const voiceObservabilityExportSchemaId = "com.absolutejs.voice.observability-export";
+export type VoiceObservabilityExportSchema = {
+    id: typeof voiceObservabilityExportSchemaId;
+    version: typeof voiceObservabilityExportSchemaVersion;
+};
+export declare const createVoiceObservabilityExportSchema: () => VoiceObservabilityExportSchema;
+export declare const assertVoiceObservabilityExportSchema: (input: {
+    schema?: Partial<VoiceObservabilityExportSchema>;
+}) => void;
 export type VoiceObservabilityExportArtifactKind = 'incident' | 'markdown' | 'operations-record' | 'proof-pack' | 'readiness' | 'screenshot' | 'slo' | 'trace' | 'audit' | 'custom';
 export type VoiceObservabilityExportArtifactChecksum = {
     algorithm: 'sha256';
@@ -74,6 +84,7 @@ export type VoiceObservabilityExportReport = {
     issues: VoiceObservabilityExportIssue[];
     operationsRecords: VoiceOperationsRecord[];
     redaction: VoiceObservabilityExportRedactionSummary;
+    schema: VoiceObservabilityExportSchema;
     sessionIds: string[];
     status: VoiceObservabilityExportStatus;
     summary: {
@@ -101,6 +112,7 @@ export type VoiceObservabilityExportArtifactIndexItem = {
 export type VoiceObservabilityExportArtifactIndex = {
     artifacts: VoiceObservabilityExportArtifactIndexItem[];
     checkedAt: number;
+    schema: VoiceObservabilityExportSchema;
     status: VoiceObservabilityExportStatus;
     summary: {
         downloadable: number;
@@ -157,6 +169,7 @@ export type VoiceObservabilityExportDeliveryDestinationResult = {
     error?: string;
     label: string;
     manifestBytes: number;
+    schema: VoiceObservabilityExportSchema;
     status: 'delivered' | 'failed';
     target: string;
 };

package/package.json

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