@absolutejs/voice 0.0.22-beta.230 → 0.0.22-beta.232

package/README.md

@@ -2758,14 +2758,21 @@ Every export manifest and artifact index includes a stable schema contract:
 ```ts
 import {
 	assertVoiceObservabilityExportSchema,
+	validateVoiceObservabilityExportRecord,
 	voiceObservabilityExportSchemaId,
 	voiceObservabilityExportSchemaVersion
 } from '@absolutejs/voice';
 
 assertVoiceObservabilityExportSchema(exportReport);
+const validation = validateVoiceObservabilityExportRecord(exportReport);
+if (!validation.ok) {
+	throw new Error(validation.issues.map((issue) => issue.message).join('\n'));
+}
 console.log(voiceObservabilityExportSchemaId, voiceObservabilityExportSchemaVersion);
 ```
 
+Use `validateVoiceObservabilityExportRecord(...)` or `assertVoiceObservabilityExportRecord(...)` when reading customer-owned records back from SQLite, Postgres, S3, a webhook collector, a warehouse, or a SIEM. The validator accepts manifests, artifact indexes, delivery reports, delivery receipts, delivery histories, and database payload records, then checks the stable schema id/version plus the minimum shape required for safe ingestion.
+
 ```ts
 import {
 	buildVoiceObservabilityExport,

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, assertVoiceObservabilityExportSchema, createVoiceObservabilityExportSchema, createVoiceFileObservabilityExportDeliveryReceiptStore, createVoiceMemoryObservabilityExportDeliveryReceiptStore, createVoiceObservabilityExportRoutes, deliverVoiceObservabilityExport, renderVoiceObservabilityExportMarkdown, voiceObservabilityExportSchemaId, voiceObservabilityExportSchemaVersion } from './observabilityExport';
+export { assertVoiceObservabilityExportRecord, buildVoiceObservabilityArtifactIndex, buildVoiceObservabilityExportDeliveryHistory, buildVoiceObservabilityExport, assertVoiceObservabilityExportSchema, createVoiceObservabilityExportSchema, createVoiceFileObservabilityExportDeliveryReceiptStore, createVoiceMemoryObservabilityExportDeliveryReceiptStore, createVoiceObservabilityExportRoutes, deliverVoiceObservabilityExport, renderVoiceObservabilityExportMarkdown, validateVoiceObservabilityExportRecord, 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, VoiceObservabilityExportSchema, VoiceObservabilityExportStatus } from './observabilityExport';
+export type { VoiceObservabilityExportArtifact, VoiceObservabilityExportArtifactChecksum, VoiceObservabilityExportArtifactFreshness, VoiceObservabilityExportArtifactIndex, VoiceObservabilityExportArtifactIndexItem, VoiceObservabilityExportArtifactKind, VoiceObservabilityExportDeliverySummary, VoiceObservabilityExportDeliveryDestination, VoiceObservabilityExportDeliveryDestinationResult, VoiceObservabilityExportDeliveryHistory, VoiceObservabilityExportDeliveryOptions, VoiceObservabilityExportDeliveryReceipt, VoiceObservabilityExportDeliveryReceiptStore, VoiceObservabilityExportDeliveryReport, VoiceObservabilityExportEnvelope, VoiceObservabilityExportIssue, VoiceObservabilityExportIssueCode, VoiceObservabilityExportOptions, VoiceObservabilityExportIngestedRecordKind, VoiceObservabilityExportRedactionSummary, VoiceObservabilityExportRecordValidationOptions, VoiceObservabilityExportReport, VoiceObservabilityExportRoutesOptions, VoiceObservabilityExportSchema, VoiceObservabilityExportStatus, VoiceObservabilityExportValidationIssue, VoiceObservabilityExportValidationResult } 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

@@ -22998,6 +22998,265 @@ var assertVoiceObservabilityExportSchema = (input) => {
     throw new Error(`Unsupported voice observability export schema: ${input.schema?.id ?? "missing"}@${input.schema?.version ?? "missing"}`);
   }
 };
+var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var isStatus2 = (value) => value === "fail" || value === "pass" || value === "warn";
+var getRecord = (value, key) => isRecord2(value) && isRecord2(value[key]) ? value[key] : undefined;
+var getRecordArray = (value, key) => isRecord2(value) && Array.isArray(value[key]) ? value[key] : undefined;
+var inferVoiceObservabilityExportRecordKind = (record) => {
+  if (isRecord2(record.manifest) && isRecord2(record.artifactIndex)) {
+    return "database-record";
+  }
+  if (Array.isArray(record.receipts)) {
+    return "delivery-history";
+  }
+  if (typeof record.runId === "string" && Array.isArray(record.destinations)) {
+    return "delivery-receipt";
+  }
+  if (Array.isArray(record.destinations) && isRecord2(record.summary) && typeof record.exportStatus === "string") {
+    return "delivery-report";
+  }
+  if (Array.isArray(record.artifacts) && isRecord2(record.summary)) {
+    return Array.isArray(record.envelopes) ? "manifest" : "artifact-index";
+  }
+  return;
+};
+var pushValidationIssue = (issues, issue) => {
+  issues.push(issue);
+};
+var requireRecordSchema = (issues, record, path) => {
+  const schema = getRecord(record, "schema");
+  if (schema?.id !== voiceObservabilityExportSchemaId || schema?.version !== voiceObservabilityExportSchemaVersion) {
+    pushValidationIssue(issues, {
+      code: "voice.observability.export.unsupported_schema",
+      message: `Unsupported voice observability export schema: ${schema?.id ?? "missing"}@${schema?.version ?? "missing"}`,
+      path: `${path}.schema`
+    });
+  }
+  return schema;
+};
+var requireArrayField = (issues, record, key, path) => {
+  if (!Array.isArray(record[key])) {
+    pushValidationIssue(issues, {
+      code: "voice.observability.export.missing_field",
+      message: `${path}.${key} must be an array.`,
+      path: `${path}.${key}`
+    });
+  }
+};
+var requireNumberField = (issues, record, key, path) => {
+  if (typeof record[key] !== "number") {
+    pushValidationIssue(issues, {
+      code: "voice.observability.export.missing_field",
+      message: `${path}.${key} must be a number.`,
+      path: `${path}.${key}`
+    });
+  }
+};
+var requireStatusField = (issues, record, key, path) => {
+  if (!isStatus2(record[key])) {
+    pushValidationIssue(issues, {
+      code: "voice.observability.export.missing_field",
+      message: `${path}.${key} must be pass, warn, or fail.`,
+      path: `${path}.${key}`
+    });
+  }
+};
+var requireDeliveryDestinationStatusField = (issues, record, key, path) => {
+  if (record[key] !== "delivered" && record[key] !== "failed") {
+    pushValidationIssue(issues, {
+      code: "voice.observability.export.missing_field",
+      message: `${path}.${key} must be delivered or failed.`,
+      path: `${path}.${key}`
+    });
+  }
+};
+var validateDeliveryDestinations = (issues, destinations, path) => {
+  if (!destinations) {
+    pushValidationIssue(issues, {
+      code: "voice.observability.export.missing_field",
+      message: `${path} must be an array.`,
+      path
+    });
+    return;
+  }
+  destinations.forEach((destination, index) => {
+    const destinationPath = `${path}.${index}`;
+    if (!isRecord2(destination)) {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.invalid_shape",
+        message: `${destinationPath} must be an object.`,
+        path: destinationPath
+      });
+      return;
+    }
+    requireRecordSchema(issues, destination, destinationPath);
+    requireDeliveryDestinationStatusField(issues, destination, "status", destinationPath);
+    if (typeof destination.destinationKind !== "string") {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.missing_field",
+        message: `${destinationPath}.destinationKind must be a string.`,
+        path: `${destinationPath}.destinationKind`
+      });
+    }
+  });
+};
+var validateVoiceObservabilityExportRecord = (input, options = {}) => {
+  const issues = [];
+  if (!isRecord2(input)) {
+    return {
+      issues: [
+        {
+          code: "voice.observability.export.invalid_shape",
+          message: "Voice observability export record must be an object.",
+          path: "$"
+        }
+      ],
+      ok: false
+    };
+  }
+  const kind = options.kind ?? inferVoiceObservabilityExportRecordKind(input);
+  if (!kind) {
+    return {
+      issues: [
+        {
+          code: "voice.observability.export.invalid_shape",
+          message: "Voice observability export record kind could not be inferred.",
+          path: "$"
+        }
+      ],
+      ok: false
+    };
+  }
+  let schema;
+  if (kind === "manifest") {
+    schema = requireRecordSchema(issues, input, "$");
+    requireArrayField(issues, input, "artifacts", "$");
+    requireArrayField(issues, input, "envelopes", "$");
+    requireArrayField(issues, input, "issues", "$");
+    requireArrayField(issues, input, "operationsRecords", "$");
+    requireArrayField(issues, input, "sessionIds", "$");
+    requireNumberField(issues, input, "checkedAt", "$");
+    requireStatusField(issues, input, "status", "$");
+    if (!isRecord2(input.deliveries)) {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.missing_field",
+        message: "$.deliveries must be an object.",
+        path: "$.deliveries"
+      });
+    }
+    if (!isRecord2(input.redaction)) {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.missing_field",
+        message: "$.redaction must be an object.",
+        path: "$.redaction"
+      });
+    }
+    if (!isRecord2(input.summary)) {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.missing_field",
+        message: "$.summary must be an object.",
+        path: "$.summary"
+      });
+    }
+  } else if (kind === "artifact-index") {
+    schema = requireRecordSchema(issues, input, "$");
+    requireArrayField(issues, input, "artifacts", "$");
+    requireNumberField(issues, input, "checkedAt", "$");
+    requireStatusField(issues, input, "status", "$");
+    if (!isRecord2(input.summary)) {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.missing_field",
+        message: "$.summary must be an object.",
+        path: "$.summary"
+      });
+    }
+  } else if (kind === "database-record") {
+    schema = requireRecordSchema(issues, input, "$");
+    requireNumberField(issues, input, "checkedAt", "$");
+    requireStatusField(issues, input, "status", "$");
+    requireStatusField(issues, input, "exportStatus", "$");
+    if (!isRecord2(input.manifest)) {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.missing_field",
+        message: "$.manifest must be an object.",
+        path: "$.manifest"
+      });
+    } else {
+      issues.push(...validateVoiceObservabilityExportRecord(input.manifest, {
+        kind: "manifest"
+      }).issues.map((issue) => ({
+        ...issue,
+        path: `$.manifest${issue.path.slice(1)}`
+      })));
+    }
+    if (!isRecord2(input.artifactIndex)) {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.missing_field",
+        message: "$.artifactIndex must be an object.",
+        path: "$.artifactIndex"
+      });
+    } else {
+      issues.push(...validateVoiceObservabilityExportRecord(input.artifactIndex, {
+        kind: "artifact-index"
+      }).issues.map((issue) => ({
+        ...issue,
+        path: `$.artifactIndex${issue.path.slice(1)}`
+      })));
+    }
+  } else if (kind === "delivery-report") {
+    requireNumberField(issues, input, "checkedAt", "$");
+    requireStatusField(issues, input, "status", "$");
+    requireStatusField(issues, input, "exportStatus", "$");
+    validateDeliveryDestinations(issues, getRecordArray(input, "destinations"), "$.destinations");
+  } else if (kind === "delivery-receipt") {
+    requireNumberField(issues, input, "checkedAt", "$");
+    requireStatusField(issues, input, "status", "$");
+    requireStatusField(issues, input, "exportStatus", "$");
+    if (typeof input.runId !== "string") {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.missing_field",
+        message: "$.runId must be a string.",
+        path: "$.runId"
+      });
+    }
+    validateDeliveryDestinations(issues, getRecordArray(input, "destinations"), "$.destinations");
+  } else if (kind === "delivery-history") {
+    requireNumberField(issues, input, "checkedAt", "$");
+    requireStatusField(issues, input, "status", "$");
+    const receipts = getRecordArray(input, "receipts");
+    if (!receipts) {
+      pushValidationIssue(issues, {
+        code: "voice.observability.export.missing_field",
+        message: "$.receipts must be an array.",
+        path: "$.receipts"
+      });
+    } else {
+      receipts.forEach((receipt, index) => {
+        const result = validateVoiceObservabilityExportRecord(receipt, {
+          kind: "delivery-receipt"
+        });
+        issues.push(...result.issues.map((issue) => ({
+          ...issue,
+          path: `$.receipts.${index}${issue.path.slice(1)}`
+        })));
+      });
+    }
+  }
+  return {
+    issues,
+    kind,
+    ok: issues.length === 0,
+    schema
+  };
+};
+var assertVoiceObservabilityExportRecord = (input, options) => {
+  const result = validateVoiceObservabilityExportRecord(input, options);
+  if (!result.ok) {
+    const firstIssue = result.issues[0];
+    throw new Error(`Invalid voice observability export record: ${firstIssue?.path ?? "$"} ${firstIssue?.message ?? "unknown validation failure"}`);
+  }
+  return result;
+};
 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);
@@ -28463,6 +28722,7 @@ export {
   verifyVoicePlivoWebhookSignature,
   verifyVoiceOpsWebhookSignature,
   validateVoiceWorkflowRouteResult,
+  validateVoiceObservabilityExportRecord,
   transcodeTwilioInboundPayloadToPCM16,
   transcodePCMToTwilioOutboundPayload,
   summarizeVoiceTurnQuality,
@@ -28922,6 +29182,7 @@ export {
   assignVoiceOpsTask,
   assertVoiceProviderRoutingContract,
   assertVoiceObservabilityExportSchema,
+  assertVoiceObservabilityExportRecord,
   assertVoiceLatencySLOGate,
   assertVoiceAgentSquadContract,
   applyVoiceTelephonyOutcome,

package/dist/observabilityExport.d.ts

@@ -21,6 +21,26 @@ export declare const assertVoiceObservabilityExportSchema: (input: {
         version?: string;
     };
 }) => void;
+export type VoiceObservabilityExportIngestedRecordKind = 'artifact-index' | 'database-record' | 'delivery-history' | 'delivery-receipt' | 'delivery-report' | 'manifest';
+export type VoiceObservabilityExportValidationIssue = {
+    code: 'voice.observability.export.invalid_shape' | 'voice.observability.export.missing_field' | 'voice.observability.export.unsupported_schema';
+    message: string;
+    path: string;
+};
+export type VoiceObservabilityExportValidationResult = {
+    issues: VoiceObservabilityExportValidationIssue[];
+    kind?: VoiceObservabilityExportIngestedRecordKind;
+    ok: boolean;
+    schema?: {
+        id?: string;
+        version?: string;
+    };
+};
+export type VoiceObservabilityExportRecordValidationOptions = {
+    kind?: VoiceObservabilityExportIngestedRecordKind;
+};
+export declare const validateVoiceObservabilityExportRecord: (input: unknown, options?: VoiceObservabilityExportRecordValidationOptions) => VoiceObservabilityExportValidationResult;
+export declare const assertVoiceObservabilityExportRecord: (input: unknown, options?: VoiceObservabilityExportRecordValidationOptions) => VoiceObservabilityExportValidationResult;
 export type VoiceObservabilityExportArtifactKind = 'incident' | 'markdown' | 'operations-record' | 'proof-pack' | 'readiness' | 'screenshot' | 'slo' | 'trace' | 'audit' | 'custom';
 export type VoiceObservabilityExportArtifactChecksum = {
     algorithm: 'sha256';

package/package.json

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