@absolutejs/voice 0.0.22-beta.220 → 0.0.22-beta.221

package/README.md

@@ -2753,12 +2753,16 @@ import {
 
 app.use(
 	createVoiceObservabilityExportRoutes({
+		artifactIntegrity: {
+			maxAgeMs: 15 * 60 * 1000
+		},
 		artifacts: [
 			{
 				id: 'latest-proof-pack',
 				kind: 'proof-pack',
 				label: 'Latest proof pack',
-				path: '.voice-runtime/proof-pack/latest.md'
+				path: '.voice-runtime/proof-pack/latest.md',
+				required: true
 			}
 		],
 		audit: runtimeStorage.audit,
@@ -2773,6 +2777,9 @@ app.use(
 );
 
 const exportReport = await buildVoiceObservabilityExport({
+	artifactIntegrity: {
+		maxAgeMs: 15 * 60 * 1000
+	},
 	audit: runtimeStorage.audit,
 	auditDeliveries: runtimeStorage.auditDeliveries,
 	links: {
@@ -2784,7 +2791,7 @@ const exportReport = await buildVoiceObservabilityExport({
 });
 ```
 
-The route helper exposes JSON at `/api/voice/observability-export`, Markdown at `/voice/observability-export.md`, and HTML at `/voice/observability-export`. 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`, 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. 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.js

@@ -24942,6 +24942,8 @@ var createVoiceOperationsRecordRoutes = (options) => {
 };
 // src/observabilityExport.ts
 import { Elysia as Elysia42 } from "elysia";
+import { createHash } from "crypto";
+import { readFile as readFile2, stat } from "fs/promises";
 var isDeliveryStore = (value) => !Array.isArray(value) && typeof value.list === "function";
 var getString18 = (value) => typeof value === "string" ? value : undefined;
 var getProviderKind = (payload) => getString18(payload.kind) ?? getString18(payload.providerKind);
@@ -24965,6 +24967,78 @@ var createOperationArtifact = (record, href) => ({
   status: record.status === "failed" ? "fail" : record.status === "warning" ? "warn" : "pass"
 });
 var unique2 = (values) => [...new Set(values)].sort();
+var stripArtifactPathAnchor = (path) => path.split("#")[0] ?? path;
+var toEpochMs = (value) => {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return;
+};
+var checksumFile = async (path) => {
+  const buffer = await readFile2(path);
+  return createHash("sha256").update(buffer).digest("hex");
+};
+var verifyArtifact = async (artifact, options) => {
+  const now = options.now ?? Date.now();
+  const maxAgeMs = artifact.maxAgeMs ?? options.maxAgeMs;
+  if (!artifact.path) {
+    return maxAgeMs === undefined ? artifact : {
+      ...artifact,
+      freshness: {
+        checkedAt: now,
+        generatedAt: artifact.generatedAt,
+        maxAgeMs,
+        status: artifact.status ?? "pass"
+      }
+    };
+  }
+  const filePath = stripArtifactPathAnchor(artifact.path);
+  try {
+    const file = await stat(filePath);
+    const generatedAt = artifact.generatedAt ?? file.mtimeMs;
+    const generatedAtMs = toEpochMs(generatedAt);
+    const ageMs = generatedAtMs === undefined ? undefined : now - generatedAtMs;
+    const isStale = maxAgeMs !== undefined && ageMs !== undefined && ageMs > maxAgeMs;
+    const checksum = options.checksum === false ? artifact.checksum : {
+      algorithm: "sha256",
+      value: await checksumFile(filePath)
+    };
+    return {
+      ...artifact,
+      bytes: artifact.bytes ?? file.size,
+      checksum,
+      freshness: maxAgeMs === undefined && generatedAt === undefined ? artifact.freshness : {
+        ageMs,
+        checkedAt: now,
+        generatedAt,
+        maxAgeMs,
+        status: isStale ? options.staleSeverity ?? "fail" : "pass"
+      },
+      generatedAt,
+      status: isStale && (options.staleSeverity ?? "fail") === "fail" ? "fail" : artifact.status
+    };
+  } catch {
+    const severity = artifact.required ? options.missingSeverity ?? "fail" : "warn";
+    return {
+      ...artifact,
+      freshness: {
+        checkedAt: now,
+        generatedAt: artifact.generatedAt,
+        maxAgeMs,
+        status: severity
+      },
+      status: severity
+    };
+  }
+};
+var verifyArtifacts = (artifacts, options) => {
+  const integrity = options ?? {};
+  return Promise.all(artifacts.map((artifact) => verifyArtifact(artifact, integrity)));
+};
 var collectSessionIds = (input) => unique2([
   ...input.sessionIds ?? [],
   ...input.events.map((event) => event.sessionId),
@@ -24991,6 +25065,27 @@ var collectIssues = (input) => {
       value: failedOperationsRecords
     });
   }
+  for (const artifact of input.artifacts) {
+    if (artifact.path && artifact.status !== "pass" && artifact.required && artifact.bytes === undefined && artifact.freshness?.ageMs === undefined) {
+      issues.push({
+        code: "voice.observability.artifact_missing",
+        detail: `${artifact.label} was required but could not be verified at ${artifact.path}.`,
+        label: "Required artifact",
+        severity: artifact.status === "fail" ? "fail" : "warn",
+        value: artifact.id
+      });
+      continue;
+    }
+    if (artifact.freshness?.maxAgeMs !== undefined && artifact.freshness.ageMs !== undefined && artifact.freshness.ageMs > artifact.freshness.maxAgeMs) {
+      issues.push({
+        code: "voice.observability.artifact_stale",
+        detail: `${artifact.label} is older than the configured freshness window.`,
+        label: "Stale artifact",
+        severity: artifact.freshness.status === "fail" ? "fail" : "warn",
+        value: artifact.id
+      });
+    }
+  }
   if ((input.auditDeliveries?.failed ?? 0) > 0) {
     issues.push({
       code: "voice.observability.audit_delivery_failed",
@@ -25076,7 +25171,7 @@ var buildVoiceObservabilityExport = async (options = {}) => {
   const traceDeliverySummary = traceDeliveries ? await summarizeVoiceTraceSinkDeliveries(traceDeliveries) : undefined;
   const auditDeliverySummary = auditDeliveries ? await summarizeVoiceAuditSinkDeliveries(auditDeliveries) : undefined;
   const operationArtifacts = operationsRecords.map((record) => createOperationArtifact(record, options.links?.operationsRecord?.(record.sessionId)));
-  const artifacts = [...operationArtifacts, ...options.artifacts ?? []];
+  const artifacts = await verifyArtifacts([...operationArtifacts, ...options.artifacts ?? []], options.artifactIntegrity);
   const operationHrefBySessionId = new Map(sessionIds.map((sessionId) => [
     sessionId,
     options.links?.operationsRecord?.(sessionId)
@@ -25086,6 +25181,7 @@ var buildVoiceObservabilityExport = async (options = {}) => {
     ...auditEvents.map((event) => buildAuditEnvelope(event, event.sessionId ? operationHrefBySessionId.get(event.sessionId) : undefined))
   ].sort((left, right) => left.at - right.at);
   const issues = collectIssues({
+    artifacts,
     auditDeliveries: auditDeliverySummary,
     operationsRecords,
     totalEvidence: events.length + auditEvents.length + operationsRecords.length + artifacts.length,
@@ -25121,7 +25217,7 @@ var renderVoiceObservabilityExportMarkdown = (report, options = {}) => {
   const title = options.title ?? "Voice Observability Export";
   const issues = report.issues.map((issue) => `- ${issue.severity}: ${issue.label}${issue.value !== undefined ? ` (${issue.value})` : ""}${issue.detail ? ` - ${issue.detail}` : ""}`).join(`
 `) || "No observability export issues.";
-  const artifacts = report.artifacts.map((artifact) => `- ${artifact.label}: ${artifact.kind}${artifact.href ? ` (${artifact.href})` : ""}${artifact.status ? ` - ${artifact.status}` : ""}`).join(`
+  const artifacts = report.artifacts.map((artifact) => `- ${artifact.label}: ${artifact.kind}${artifact.href ? ` (${artifact.href})` : ""}${artifact.status ? ` - ${artifact.status}` : ""}${artifact.bytes !== undefined ? `, ${artifact.bytes} bytes` : ""}${artifact.checksum ? `, sha256 ${artifact.checksum.value}` : ""}${artifact.freshness?.ageMs !== undefined ? `, age ${Math.round(artifact.freshness.ageMs)}ms` : ""}`).join(`
 `) || "No artifacts attached.";
   return `# ${title}
 

package/dist/observabilityExport.d.ts

@@ -6,15 +6,30 @@ import { type VoiceTraceSinkDeliveryQueueSummary } from './queue';
 import { type StoredVoiceTraceEvent, type VoiceTraceEventStore, type VoiceTraceEventType, type VoiceTraceRedactionConfig, type VoiceTraceSinkDeliveryRecord, type VoiceTraceSinkDeliveryStore, type VoiceTraceSummary } from './trace';
 export type VoiceObservabilityExportStatus = 'fail' | 'pass' | 'warn';
 export type VoiceObservabilityExportArtifactKind = 'incident' | 'markdown' | 'operations-record' | 'proof-pack' | 'readiness' | 'screenshot' | 'slo' | 'trace' | 'audit' | 'custom';
+export type VoiceObservabilityExportArtifactChecksum = {
+    algorithm: 'sha256';
+    value: string;
+};
+export type VoiceObservabilityExportArtifactFreshness = {
+    ageMs?: number;
+    checkedAt: number;
+    generatedAt?: number | string;
+    maxAgeMs?: number;
+    status: VoiceObservabilityExportStatus;
+};
 export type VoiceObservabilityExportArtifact = {
     bytes?: number;
+    checksum?: VoiceObservabilityExportArtifactChecksum;
     contentType?: string;
+    freshness?: VoiceObservabilityExportArtifactFreshness;
     generatedAt?: number | string;
     href?: string;
     id: string;
     kind: VoiceObservabilityExportArtifactKind;
     label: string;
+    maxAgeMs?: number;
     path?: string;
+    required?: boolean;
     sessionId?: string;
     status?: VoiceObservabilityExportStatus;
 };
@@ -31,7 +46,7 @@ export type VoiceObservabilityExportEnvelope = {
     severity: VoiceObservabilityExportStatus;
     traceId?: string;
 };
-export type VoiceObservabilityExportIssueCode = 'voice.observability.no_evidence' | 'voice.observability.operation_failed' | 'voice.observability.audit_delivery_failed' | 'voice.observability.audit_delivery_pending' | 'voice.observability.trace_delivery_failed' | 'voice.observability.trace_delivery_pending';
+export type VoiceObservabilityExportIssueCode = 'voice.observability.no_evidence' | 'voice.observability.operation_failed' | 'voice.observability.artifact_missing' | 'voice.observability.artifact_stale' | 'voice.observability.audit_delivery_failed' | 'voice.observability.audit_delivery_pending' | 'voice.observability.trace_delivery_failed' | 'voice.observability.trace_delivery_pending';
 export type VoiceObservabilityExportIssue = {
     code: VoiceObservabilityExportIssueCode;
     detail?: string;
@@ -67,6 +82,13 @@ export type VoiceObservabilityExportReport = {
 };
 export type VoiceObservabilityExportOptions = {
     artifacts?: VoiceObservabilityExportArtifact[];
+    artifactIntegrity?: {
+        checksum?: false | 'sha256';
+        maxAgeMs?: number;
+        missingSeverity?: Exclude<VoiceObservabilityExportStatus, 'pass'>;
+        now?: number;
+        staleSeverity?: Exclude<VoiceObservabilityExportStatus, 'pass'>;
+    };
     audit?: VoiceAuditEventStore;
     auditDeliveries?: VoiceAuditSinkDeliveryRecord[] | VoiceAuditSinkDeliveryStore;
     events?: StoredVoiceTraceEvent[];

package/package.json

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