@absolutejs/voice 0.0.22-beta.223 → 0.0.22-beta.225

package/README.md

@@ -2748,9 +2748,15 @@ Use observability exports when a buyer wants the hosted-dashboard evidence graph
 ```ts
 import {
 	buildVoiceObservabilityExport,
+	createVoiceFileObservabilityExportDeliveryReceiptStore,
 	createVoiceObservabilityExportRoutes
 } from '@absolutejs/voice';
 
+const observabilityReceipts =
+	createVoiceFileObservabilityExportDeliveryReceiptStore({
+		directory: '.voice-runtime/observability-export-receipts'
+	});
+
 app.use(
 	createVoiceObservabilityExportRoutes({
 		artifactIntegrity: {
@@ -2761,8 +2767,15 @@ app.use(
 				directory: '.voice-runtime/observability-exports',
 				kind: 'file',
 				label: 'Local customer-owned observability archive'
+			},
+			{
+				bucket: process.env.VOICE_OBSERVABILITY_EXPORT_S3_BUCKET,
+				keyPrefix: 'voice/observability-exports',
+				kind: 's3',
+				label: 'S3 customer-owned observability archive'
 			}
 		],
+		deliveryReceipts: observabilityReceipts,
 		artifacts: [
 			{
 				id: 'latest-proof-pack',
@@ -2798,7 +2811,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`, 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. 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. 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.
 
 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, buildVoiceObservabilityExport, createVoiceObservabilityExportRoutes, deliverVoiceObservabilityExport, renderVoiceObservabilityExportMarkdown } from './observabilityExport';
+export { buildVoiceObservabilityArtifactIndex, buildVoiceObservabilityExportDeliveryHistory, buildVoiceObservabilityExport, createVoiceFileObservabilityExportDeliveryReceiptStore, createVoiceMemoryObservabilityExportDeliveryReceiptStore, createVoiceObservabilityExportRoutes, deliverVoiceObservabilityExport, renderVoiceObservabilityExportMarkdown } 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, VoiceObservabilityExportDeliveryOptions, 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, 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

@@ -24943,7 +24943,7 @@ var createVoiceOperationsRecordRoutes = (options) => {
 // src/observabilityExport.ts
 import { Elysia as Elysia42 } from "elysia";
 import { createHash } from "crypto";
-import { mkdir as mkdir4, readFile as readFile2, stat } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile2, stat, unlink } from "fs/promises";
 import { join as join3 } from "path";
 var isDeliveryStore = (value) => !Array.isArray(value) && typeof value.list === "function";
 var getString18 = (value) => typeof value === "string" ? value : undefined;
@@ -24984,10 +24984,80 @@ var checksumFile = async (path) => {
   return createHash("sha256").update(buffer).digest("hex");
 };
 var byteLength = (value) => new TextEncoder().encode(value).byteLength;
+var deliveryReceiptId = (runId) => `observability-export:${encodeURIComponent(runId)}`;
 var safeArtifactFileName = (artifact) => {
   const extension = artifact.contentType === "image/png" ? ".png" : artifact.contentType?.includes("markdown") ? ".md" : artifact.contentType?.includes("json") ? ".json" : "";
   return `${artifact.id.replace(/[^a-z0-9_.-]/gi, "-")}${extension}`;
 };
+var normalizeExportS3KeyPrefix = (prefix) => prefix?.trim().replace(/^\/+|\/+$/g, "") ?? "voice/observability-exports";
+var joinS3Key = (...parts) => parts.map((part) => part.trim().replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+var writeS3Object = async (input) => {
+  const file = input.client.file(input.key, input.options);
+  await file.write(input.value, {
+    type: input.contentType
+  });
+};
+var createVoiceMemoryObservabilityExportDeliveryReceiptStore = () => {
+  const receipts = new Map;
+  return {
+    get: (id) => receipts.get(id),
+    list: () => [...receipts.values()].sort((left, right) => right.checkedAt - left.checkedAt),
+    remove: (id) => {
+      receipts.delete(id);
+    },
+    set: (id, receipt) => {
+      receipts.set(id, receipt);
+    }
+  };
+};
+var createVoiceFileObservabilityExportDeliveryReceiptStore = (options) => {
+  const receiptPath = (id) => join3(options.directory, `${encodeURIComponent(id)}.json`);
+  return {
+    get: async (id) => {
+      const file = Bun.file(receiptPath(id));
+      if (!await file.exists()) {
+        return;
+      }
+      return JSON.parse(await file.text());
+    },
+    list: async () => {
+      await mkdir4(options.directory, { recursive: true });
+      const receipts = [];
+      for (const entry of await Array.fromAsync(new Bun.Glob("*.json").scan(options.directory))) {
+        const file = Bun.file(join3(options.directory, entry));
+        receipts.push(JSON.parse(await file.text()));
+      }
+      return receipts.sort((left, right) => right.checkedAt - left.checkedAt);
+    },
+    remove: async (id) => {
+      await unlink(receiptPath(id)).catch(() => {
+        return;
+      });
+    },
+    set: async (id, receipt) => {
+      await mkdir4(options.directory, { recursive: true });
+      await Bun.write(receiptPath(id), `${JSON.stringify(receipt, null, 2)}
+`);
+    }
+  };
+};
+var buildVoiceObservabilityExportDeliveryHistory = async (store) => {
+  const receipts = await store.list();
+  const failed = receipts.reduce((count, receipt) => count + receipt.summary.failed, 0);
+  const delivered = receipts.reduce((count, receipt) => count + receipt.summary.delivered, 0);
+  const totalDestinations = receipts.reduce((count, receipt) => count + receipt.summary.total, 0);
+  return {
+    checkedAt: Date.now(),
+    receipts,
+    status: failed > 0 || receipts.some((receipt) => receipt.status === "fail") ? "fail" : receipts.some((receipt) => receipt.status === "warn") ? "warn" : "pass",
+    summary: {
+      delivered,
+      failed,
+      receipts: receipts.length,
+      totalDestinations
+    }
+  };
+};
 var inferContentType = (artifact) => {
   if (artifact.contentType) {
     return artifact.contentType;
@@ -25352,6 +25422,50 @@ var deliverVoiceObservabilityExport = async (options) => {
           target
         };
       }
+      if (destination.kind === "s3") {
+        const keyPrefix = normalizeExportS3KeyPrefix(destination.keyPrefix);
+        const rootKey = joinS3Key(keyPrefix, runId);
+        const client = destination.client ?? new Bun.S3Client(destination);
+        const s3Options = destination;
+        await writeS3Object({
+          client,
+          contentType: "application/json",
+          key: joinS3Key(rootKey, "manifest.json"),
+          options: s3Options,
+          value: manifest
+        });
+        await writeS3Object({
+          client,
+          contentType: "application/json",
+          key: joinS3Key(rootKey, "artifact-index.json"),
+          options: s3Options,
+          value: index
+        });
+        if (destination.includeArtifacts !== false) {
+          for (const artifact of options.report.artifacts) {
+            if (!artifact.path) {
+              continue;
+            }
+            await writeS3Object({
+              client,
+              contentType: artifact.contentType ?? inferContentType(artifact),
+              key: joinS3Key(rootKey, "artifacts", safeArtifactFileName(artifact)),
+              options: s3Options,
+              value: await readFile2(stripArtifactPathAnchor(artifact.path))
+            });
+          }
+        }
+        return {
+          artifactCount: destination.includeArtifacts === false ? 0 : options.report.artifacts.filter((artifact) => artifact.path).length,
+          deliveredAt: Date.now(),
+          destinationId,
+          destinationKind: destination.kind,
+          label,
+          manifestBytes: byteLength(manifest),
+          status: "delivered",
+          target: destination.bucket ? `s3://${destination.bucket}/${rootKey}` : rootKey
+        };
+      }
       const controller = new AbortController;
       const timeout = setTimeout(() => controller.abort(), destination.timeoutMs ?? 1e4);
       try {
@@ -25396,22 +25510,32 @@ var deliverVoiceObservabilityExport = async (options) => {
         label,
         manifestBytes: byteLength(manifest),
         status: "failed",
-        target: destination.kind === "file" ? destination.directory : destination.url
+        target: destination.kind === "file" ? destination.directory : destination.kind === "s3" ? destination.bucket ? `s3://${destination.bucket}/${normalizeExportS3KeyPrefix(destination.keyPrefix)}` : normalizeExportS3KeyPrefix(destination.keyPrefix) : destination.url
       };
     }
   }));
   const failed = destinations.filter((destination) => destination.status === "failed").length;
-  return {
+  const status = failed > 0 || options.report.status === "fail" ? "fail" : options.report.status === "warn" ? "warn" : "pass";
+  const report = {
     checkedAt,
     destinations,
     exportStatus: options.report.status,
-    status: failed > 0 || options.report.status === "fail" ? "fail" : options.report.status === "warn" ? "warn" : "pass",
+    status,
     summary: {
       delivered: destinations.length - failed,
       failed,
       total: destinations.length
     }
   };
+  if (options.receipts) {
+    const receipt = {
+      ...report,
+      id: deliveryReceiptId(runId),
+      runId
+    };
+    await options.receipts.set(receipt.id, receipt);
+  }
+  return report;
 };
 var createVoiceObservabilityExportRoutes = (options = {}) => {
   const path = options.path ?? "/api/voice/observability-export";
@@ -25468,8 +25592,12 @@ var createVoiceObservabilityExportRoutes = (options = {}) => {
     });
   }
   if (deliveryPath !== false && options.deliveryDestinations) {
+    if (options.deliveryReceipts) {
+      app.get(deliveryPath, async () => Response.json(await buildVoiceObservabilityExportDeliveryHistory(options.deliveryReceipts), { headers }));
+    }
     app.post(deliveryPath, async () => Response.json(await deliverVoiceObservabilityExport({
       destinations: options.deliveryDestinations ?? [],
+      receipts: options.deliveryReceipts,
       report: await buildReport()
     }), { headers }));
   }
@@ -28366,6 +28494,7 @@ export {
   createVoiceMemoryTraceSinkDeliveryStore,
   createVoiceMemoryTraceEventStore,
   createVoiceMemoryStore,
+  createVoiceMemoryObservabilityExportDeliveryReceiptStore,
   createVoiceMemoryLiveOpsControlStore,
   createVoiceMemoryIncidentBundleStore,
   createVoiceMemoryHandoffDeliveryStore,
@@ -28401,6 +28530,7 @@ export {
   createVoiceFileScenarioFixtureStore,
   createVoiceFileRuntimeStorage,
   createVoiceFileReviewStore,
+  createVoiceFileObservabilityExportDeliveryReceiptStore,
   createVoiceFileIntegrationEventStore,
   createVoiceFileIncidentBundleStore,
   createVoiceFileExternalObjectMapStore,
@@ -28499,6 +28629,7 @@ export {
   buildVoiceOpsConsoleReport,
   buildVoiceOpsActionHistoryReport,
   buildVoiceOperationsRecord,
+  buildVoiceObservabilityExportDeliveryHistory,
   buildVoiceObservabilityExport,
   buildVoiceObservabilityArtifactIndex,
   buildVoiceLiveOpsControlState,

package/dist/observabilityExport.d.ts

@@ -1,4 +1,5 @@
 import { Elysia } from 'elysia';
+import type { S3Client, S3Options } from 'bun';
 import { type VoiceAuditSinkDeliveryQueueSummary, type VoiceAuditSinkDeliveryRecord, type VoiceAuditSinkDeliveryStore } from './auditSinks';
 import type { VoiceAuditEventStore, VoiceAuditEventType } from './audit';
 import { type VoiceOperationsRecord } from './operationsRecord';
@@ -113,7 +114,15 @@ export type VoiceObservabilityExportDeliveryDestination = {
     includeArtifacts?: boolean;
     kind: 'file';
     label?: string;
-} | {
+} | (S3Options & {
+    bucket?: string;
+    client?: Pick<S3Client, 'file'>;
+    id?: string;
+    includeArtifacts?: boolean;
+    keyPrefix?: string;
+    kind: 's3';
+    label?: string;
+}) | {
     fetch?: typeof fetch;
     headers?: Record<string, string>;
     id?: string;
@@ -145,9 +154,36 @@ export type VoiceObservabilityExportDeliveryReport = {
         total: number;
     };
 };
+export type VoiceObservabilityExportDeliveryReceipt = {
+    checkedAt: number;
+    destinations: VoiceObservabilityExportDeliveryDestinationResult[];
+    exportStatus: VoiceObservabilityExportStatus;
+    id: string;
+    runId: string;
+    status: VoiceObservabilityExportStatus;
+    summary: VoiceObservabilityExportDeliveryReport['summary'];
+};
+export type VoiceObservabilityExportDeliveryReceiptStore = {
+    get: (id: string) => Promise<VoiceObservabilityExportDeliveryReceipt | undefined> | VoiceObservabilityExportDeliveryReceipt | undefined;
+    list: () => Promise<VoiceObservabilityExportDeliveryReceipt[]> | VoiceObservabilityExportDeliveryReceipt[];
+    remove: (id: string) => Promise<void> | void;
+    set: (id: string, receipt: VoiceObservabilityExportDeliveryReceipt) => Promise<void> | void;
+};
+export type VoiceObservabilityExportDeliveryHistory = {
+    checkedAt: number;
+    receipts: VoiceObservabilityExportDeliveryReceipt[];
+    status: VoiceObservabilityExportStatus;
+    summary: {
+        delivered: number;
+        failed: number;
+        receipts: number;
+        totalDestinations: number;
+    };
+};
 export type VoiceObservabilityExportDeliveryOptions = {
     destinations: VoiceObservabilityExportDeliveryDestination[];
     report: VoiceObservabilityExportReport;
+    receipts?: VoiceObservabilityExportDeliveryReceiptStore;
     runId?: string;
 };
 export type VoiceObservabilityExportOptions = {
@@ -179,6 +215,7 @@ export type VoiceObservabilityExportRoutesOptions = VoiceObservabilityExportOpti
     artifactIndexPath?: false | string;
     deliveryDestinations?: VoiceObservabilityExportDeliveryDestination[];
     deliveryPath?: false | string;
+    deliveryReceipts?: VoiceObservabilityExportDeliveryReceiptStore;
     htmlPath?: false | string;
     markdownPath?: false | string;
     name?: string;
@@ -186,6 +223,11 @@ export type VoiceObservabilityExportRoutesOptions = VoiceObservabilityExportOpti
     render?: (report: VoiceObservabilityExportReport) => string | Promise<string>;
     title?: string;
 };
+export declare const createVoiceMemoryObservabilityExportDeliveryReceiptStore: () => VoiceObservabilityExportDeliveryReceiptStore;
+export declare const createVoiceFileObservabilityExportDeliveryReceiptStore: (options: {
+    directory: string;
+}) => VoiceObservabilityExportDeliveryReceiptStore;
+export declare const buildVoiceObservabilityExportDeliveryHistory: (store: VoiceObservabilityExportDeliveryReceiptStore) => Promise<VoiceObservabilityExportDeliveryHistory>;
 export declare const buildVoiceObservabilityExport: (options?: VoiceObservabilityExportOptions) => Promise<VoiceObservabilityExportReport>;
 export declare const renderVoiceObservabilityExportMarkdown: (report: VoiceObservabilityExportReport, options?: {
     title?: string;

package/package.json

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