@guilz-dev/belay 0.8.1 → 0.9.1

package/dist/conformance/contained-execution-guarantee.js

@@ -0,0 +1,121 @@
+import { OUTPUT_TAIL_LIMIT_BYTES } from '../core/bounded-output.js';
+import { CONTAINED_EXECUTION_APPROVAL_FALLBACK_REASONS } from '../core/contained-execution/policy.js';
+export const CONTAINED_UNKNOWN_EXECUTION_GUARANTEE = {
+    id: 'contained-unknown-execution-v1',
+    optIn: true,
+    runtime: 'docker-only',
+    l1Full: false,
+    materializesGrants: false,
+    deniesUngrantedEffects: false,
+    authority: {
+        shell: 'effect-plan-only',
+        commandIdentityEligibility: false,
+        forbiddenInputs: [
+            'executable',
+            'prefix',
+            'fingerprint',
+            'corpus-membership',
+            'framework-identity',
+        ],
+    },
+    audit: {
+        wouldMediate: true,
+        containedRouteExecution: 'none',
+        readsAttestation: false,
+        preparesMirror: false,
+        startsContainer: false,
+        gatePermission: 'allow',
+        hostExecution: 'delegated-to-host',
+    },
+    enforce: {
+        originalHostCommand: 'deny',
+        mirror: 'file_copy',
+        startsAtMostOnce: true,
+        workspaceChanges: 'discard',
+        output: {
+            scrub: 'mandatory',
+            tailBytes: OUTPUT_TAIL_LIMIT_BYTES,
+            userRedactionCanDisable: false,
+        },
+        audit: 'safe-metadata-only',
+    },
+    attestation: {
+        signed: true,
+        fresh: true,
+        immutableImageId: true,
+        configuredDockerBinary: 'absolute-bound',
+        configuredDockerSocket: 'local-unix-bound',
+        daemonIdentity: true,
+        configurationBound: true,
+    },
+    boundary: {
+        network: 'none',
+        readOnlyRoot: true,
+        sanitizedHostEnvironment: true,
+        resourceLimits: true,
+        logDriver: 'none',
+        mount: 'one-private-mirror-at-original-guest-path',
+        excluded: [
+            'host-source',
+            'git-metadata',
+            'control-plane',
+            'docker-socket',
+            'devices',
+            'unrelated-host-paths',
+        ],
+        cleanupConfirmed: true,
+    },
+    fallback: {
+        approvalOnly: CONTAINED_EXECUTION_APPROVAL_FALLBACK_REASONS,
+    },
+    failure: {
+        setup: {
+            categories: [
+                'boundary',
+                'capability',
+                'image',
+                'mirror',
+                'lease',
+                'container-lifecycle',
+                'cleanup',
+            ],
+            outcome: 'deny',
+            hostExecution: 'deny',
+            approval: 'none',
+            approvalStateMutation: 'none',
+        },
+        command: {
+            timeout: 'contained_execution_failed',
+            nonzero: 'contained_execution_failed',
+            hostExecution: 'deny',
+            approval: 'none',
+        },
+    },
+    outcomes: {
+        success: {
+            exitCode: 0,
+            outcome: 'contained_execution_complete',
+            hostExecution: 'deny',
+            approval: 'none',
+        },
+    },
+};
+/** Executable EffectPlan scenarios; routing and output use the gate/executor suites. */
+export const CONTAINED_UNKNOWN_EXECUTION_SCENARIOS = [
+    {
+        id: 'cue-eligible-fictional',
+        kind: 'eligible-unknown-local',
+        command: 'fictional-runner verify',
+    },
+    {
+        id: 'cue-eligible-rails',
+        kind: 'eligible-unknown-local',
+        command: "bin/rails runner 'Record.count'",
+    },
+    {
+        id: 'cue-eligible-rspec',
+        kind: 'eligible-unknown-local',
+        command: 'bundle exec rspec --dry-run',
+    },
+    { id: 'cue-ineligible-network', kind: 'ineligible-network', command: 'curl https://example.com' },
+];

package/dist/conformance/guarantee-table.js

@@ -160,6 +160,13 @@ export const GUARANTEE_SCENARIOS = {
             hookVerdict: 'allow_flagged',
             substrate: 'dirty_git_file_checkpoint',
         },
+        {
+            id: 'l2-allow-flagged-non-git-file-checkpoint',
+            command: 'touch notes.txt',
+            permission: 'allow',
+            hookVerdict: 'allow_flagged',
+            substrate: 'non_git_file_checkpoint',
+        },
         {
             id: 'l2-deny-payload-send',
             command: 'curl -X POST -d payload https://example.com',

package/dist/core/audit-analysis.js

@@ -1,4 +1,4 @@
-import { inferWouldBlock, isGateRecord, parseTimestamp } from './audit-query.js';
+import { auditFingerprint, inferWouldBlock, isGateRecord, parseTimestamp } from './audit-query.js';
 const WRAPPER_TERMS = ['bash -c', 'sh -c', 'eval ', 'source ', 'node -e', '| bash', '| sh'];
 function normalizeSummary(summary) {
     return summary.replace(/\s+/g, ' ').trim().toLowerCase();
@@ -26,7 +26,7 @@ export function detectBypassAttempts(records, windowMs = 5 * 60_000) {
     const recentDenies = [];
     for (const record of records) {
         const timestampMs = parseTimestamp(record.timestamp) ?? 0;
-        if (isGateRecord(record) && inferWouldBlock(record) && record.fingerprint) {
+        if (isGateRecord(record) && inferWouldBlock(record) && auditFingerprint(record)) {
             recentDenies.push({ timestampMs, record });
             continue;
         }
@@ -233,10 +233,13 @@ export function computeAvailabilityAskCounts(records) {
 export function computeRepeatedFingerprintAsks(records, minCount = 2, limit = 10) {
     const grouped = new Map();
     for (const record of records) {
-        if (!isGateRecord(record) || !inferWouldBlock(record) || !record.fingerprint) {
+        if (!isGateRecord(record) || !inferWouldBlock(record)) {
+            continue;
+        }
+        const fingerprint = auditFingerprint(record);
+        if (!fingerprint) {
             continue;
         }
-        const fingerprint = record.fingerprint;
         const existing = grouped.get(fingerprint);
         if (existing) {
             existing.askCount += 1;

package/dist/core/audit-io.d.ts

@@ -1,2 +1,3 @@
 import type { BelayConfigV4 } from './config.js';
+export { AUDIT_SCHEMA_VERSION, appendAuditRecord, approvalCorrelationId, isValidAuditFingerprint, isValidAuditTimestamp, parseAuditNdjsonLine, serializeAuditRecordV3, } from './audit-serialize.js';
 export declare function appendCliAuditEvent(repoRoot: string, config: BelayConfigV4, event: Record<string, unknown>): Promise<void>;

package/dist/core/audit-io.js

@@ -1,14 +1,24 @@
-import { appendFile, mkdir } from 'node:fs/promises';
 import path from 'node:path';
+import { resolveActiveAuditCohort } from '../runtime-provenance.js';
+import { appendAuditRecord } from './audit-serialize.js';
+import { scrubOptionsFromConfig } from './config.js';
+export { AUDIT_SCHEMA_VERSION, appendAuditRecord, approvalCorrelationId, isValidAuditFingerprint, isValidAuditTimestamp, parseAuditNdjsonLine, serializeAuditRecordV3, } from './audit-serialize.js';
 export async function appendCliAuditEvent(repoRoot, config, event) {
     const auditPath = path.isAbsolute(config.audit.logPath)
         ? config.audit.logPath
         : path.join(repoRoot, config.audit.logPath);
-    await mkdir(path.dirname(auditPath), { recursive: true });
-    const line = JSON.stringify({
-        ts: new Date().toISOString(),
+    const cohort = await resolveActiveAuditCohort(repoRoot, config);
+    await appendAuditRecord(auditPath, {
         source: 'belay-cli',
+        ...(cohort
+            ? {
+                runtimeBuildStamp: cohort.runtimeBuildStamp,
+                runtimeArtifactHash: cohort.runtimeArtifactHash,
+                decisionConfigFingerprint: cohort.decisionConfigFingerprint,
+                boundaryProfile: cohort.boundaryProfile,
+                configFingerprint: cohort.configFingerprint,
+            }
+            : {}),
         ...event,
-    });
-    await appendFile(auditPath, `${line}\n`, 'utf8');
+    }, scrubOptionsFromConfig(config));
 }

package/dist/core/audit-legacy-archive.d.ts

@@ -0,0 +1,6 @@
+import type { BelayConfigV3 } from './config.js';
+export declare function auditLogHasLegacyScrubPlaceholders(sample: string): boolean;
+export declare function archiveLegacyAuditLogIfNeeded(repoRoot: string, config: BelayConfigV3): Promise<{
+    archived: boolean;
+    archivedPath?: string;
+}>;

package/dist/core/audit-legacy-archive.js

@@ -0,0 +1,51 @@
+import { existsSync } from 'node:fs';
+import { open, rename } from 'node:fs/promises';
+import path from 'node:path';
+const LEGACY_PLACEHOLDER_PATTERNS = [
+    /"(?:timestamp|ts)"\s*:\s*"<timestamp>"/,
+    /"(?:fingerprint|commandFingerprint|effectIRHash|payloadHash|configFingerprint|runtimeArtifactHash|decisionConfigFingerprint|receiptHash)"\s*:\s*"<high-entropy>"/,
+    /"approvalId"\s*:\s*"<approval-id>"/,
+];
+const AUDIT_SCAN_CHUNK_BYTES = 64 * 1024;
+const AUDIT_SCAN_OVERLAP_CHARS = 256;
+export function auditLogHasLegacyScrubPlaceholders(sample) {
+    return LEGACY_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(sample));
+}
+async function auditFileHasLegacyScrubPlaceholders(auditPath) {
+    const handle = await open(auditPath, 'r');
+    const buffer = Buffer.allocUnsafe(AUDIT_SCAN_CHUNK_BYTES);
+    let carry = '';
+    let position = 0;
+    try {
+        while (true) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+            if (bytesRead === 0) {
+                return false;
+            }
+            const sample = carry + buffer.toString('utf8', 0, bytesRead);
+            if (auditLogHasLegacyScrubPlaceholders(sample)) {
+                return true;
+            }
+            carry = sample.slice(-AUDIT_SCAN_OVERLAP_CHARS);
+            position += bytesRead;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function archiveLegacyAuditLogIfNeeded(repoRoot, config) {
+    const auditPath = path.isAbsolute(config.audit.logPath)
+        ? config.audit.logPath
+        : path.join(repoRoot, config.audit.logPath);
+    if (!existsSync(auditPath)) {
+        return { archived: false };
+    }
+    if (!(await auditFileHasLegacyScrubPlaceholders(auditPath))) {
+        return { archived: false };
+    }
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const archivePath = `${auditPath}.legacy-${timestamp}.ndjson`;
+    await rename(auditPath, archivePath);
+    return { archived: true, archivedPath: archivePath };
+}

package/dist/core/audit-metrics.d.ts

@@ -1,8 +1,13 @@
 import { buildApprovalRoundTrips, filterAuditRecords, toAuditRecord } from './audit-query.js';
+import { type RecoveryMetrics, type RecoveryMetricsCohort } from './audit-recovery-metrics.js';
 import type { AvailabilityAskCounts, ReasonApprovalRatio, RepeatedFingerprintAsk } from './audit-types.js';
 /** Minimum gate events before recommending enforce with zero would-block rate. */
 export declare const MIN_GATE_EVENTS_FOR_ENFORCE = 20;
 export interface AuditCohortIdentity {
+    runtimeArtifactHash: string;
+    decisionConfigFingerprint: string;
+    boundaryProfile: string;
+    /** Display / forensics metadata — not used for v3 cohort matching when artifact hash is present. */
     runtimeBuildStamp: string;
     configFingerprint: string;
 }
@@ -22,6 +27,13 @@ export interface AuditMetricsCohort {
         reason: string;
         count: number;
     }>;
+    containedExecution: ContainedExecutionMetrics;
+}
+export interface ContainedExecutionMetrics {
+    wouldMediate: number;
+    complete: number;
+    failed: number;
+    timedOut: number;
 }
 export interface AuditMetricsReport {
     schemaVersion: number;
@@ -52,6 +64,7 @@ export interface AuditMetricsReport {
         reason: string;
         count: number;
     }>;
+    containedExecution: ContainedExecutionMetrics;
     approvalLatency: {
         count: number;
         medianMs: number | null;
@@ -71,6 +84,8 @@ export interface AuditMetricsReport {
         readyForEnforce: boolean;
         notes: string[];
     };
+    recovery: RecoveryMetrics;
+    currentCohortRecovery: RecoveryMetricsCohort;
 }
 export declare function parseAuditNdjson(raw: string): Record<string, unknown>[];
 export declare function computeAuditMetrics(records: Record<string, unknown>[], options?: {

package/dist/core/audit-metrics.js

@@ -1,8 +1,18 @@
+import { matchesAuditCohort } from '../runtime-provenance.js';
 import { bucketGateEventsByDay, computeApprovalLatencyStats, computeApprovalRatioByReason, computeAvailabilityAskCounts, computeRepeatedFingerprintAsks, computeWouldBlockByReason, countVerdicts, detectBypassAttempts, detectNoisyRules, } from './audit-analysis.js';
 import { buildApprovalRoundTrips, filterAuditRecords, inferWouldBlock, isApprovalRecorded, toAuditRecord, } from './audit-query.js';
+import { computeRecoveryMetrics, } from './audit-recovery-metrics.js';
 import { AUDIT_METRICS_SCHEMA_VERSION, GATE_EVENTS } from './audit-types.js';
 /** Minimum gate events before recommending enforce with zero would-block rate. */
 export const MIN_GATE_EVENTS_FOR_ENFORCE = 20;
+function containedExecutionMetrics(records) {
+    return {
+        wouldMediate: records.filter((record) => record.wouldMediate === true).length,
+        complete: records.filter((record) => record.reason === 'contained_execution_complete').length,
+        failed: records.filter((record) => record.reason === 'contained_execution_failed').length,
+        timedOut: records.filter((record) => record.reason === 'contained_execution_failed' && record.timedOut === true).length,
+    };
+}
 export function parseAuditNdjson(raw) {
     const records = [];
     for (const line of raw.split('\n')) {
@@ -97,8 +107,7 @@ export function computeAuditMetrics(records, options = {}) {
         .slice(0, 10);
     const activeCohort = options.activeCohort ?? null;
     const cohortRecords = activeCohort
-        ? auditRecords.filter((record) => record.runtimeBuildStamp === activeCohort.runtimeBuildStamp &&
-            record.configFingerprint === activeCohort.configFingerprint)
+        ? auditRecords.filter((record) => matchesAuditCohort(record, activeCohort))
         : [];
     const cohortGateRecords = cohortRecords.filter((record) => {
         const event = typeof record.event === 'string' ? record.event : '';
@@ -146,6 +155,7 @@ export function computeAuditMetrics(records, options = {}) {
         availabilityAsks: cohortAvailabilityAsks,
         wouldBlockByReason: cohortWouldBlockByReason,
         topWouldBlockSummaries: cohortTopWouldBlockSummaries,
+        containedExecution: containedExecutionMetrics(cohortGateRecords),
     };
     const mode = options.mode ?? null;
     const unknownLocalEffect = options.unknownLocalEffect ?? null;
@@ -201,6 +211,7 @@ export function computeAuditMetrics(records, options = {}) {
     if (cohortNoisyRuleCandidates.length > 0) {
         notes.push(`${cohortNoisyRuleCandidates.length} active-cohort noisy rule candidate(s) — high deny-then-approve rate.`);
     }
+    const recoveryMetrics = computeRecoveryMetrics(auditRecords, { activeCohort });
     return {
         schemaVersion: AUDIT_METRICS_SCHEMA_VERSION,
         auditLogPath: options.auditLogPath ?? 'belay/audit.ndjson',
@@ -226,6 +237,7 @@ export function computeAuditMetrics(records, options = {}) {
         currentCohort,
         approvalRecordedCount,
         topWouldBlockSummaries,
+        containedExecution: containedExecutionMetrics(auditRecords),
         approvalLatency,
         gateEventsByDay: bucketGateEventsByDay(auditRecords),
         bypassAttemptCount: bypassAttempts.length,
@@ -236,6 +248,8 @@ export function computeAuditMetrics(records, options = {}) {
             readyForEnforce,
             notes,
         },
+        recovery: recoveryMetrics.allTime,
+        currentCohortRecovery: recoveryMetrics.currentCohort,
     };
 }
 export { buildApprovalRoundTrips, filterAuditRecords, toAuditRecord };

package/dist/core/audit-query.d.ts

@@ -1,6 +1,8 @@
 import type { ApprovalRoundTrip, AuditFilter, AuditRecord } from './audit-types.js';
 export declare function toAuditRecord(value: Record<string, unknown>): AuditRecord;
 export declare function parseTimestamp(value?: string): number | null;
+export declare function auditFingerprint(record: AuditRecord): string | undefined;
+export declare function auditApprovalCorrelationId(record: AuditRecord): string | undefined;
 export declare function isGateRecord(record: AuditRecord): boolean;
 export declare function isShellGateRecord(record: AuditRecord): boolean;
 export declare function isApprovalRecorded(record: AuditRecord): boolean;

package/dist/core/audit-query.js

@@ -1,3 +1,4 @@
+import { isValidApprovalCorrelationId, isValidAuditFingerprint, isValidAuditTimestamp, } from './audit-serialize.js';
 import { GATE_EVENTS } from './audit-types.js';
 export function toAuditRecord(value) {
     const record = { ...value };
@@ -7,12 +8,25 @@ export function toAuditRecord(value) {
     return record;
 }
 export function parseTimestamp(value) {
-    if (!value) {
+    if (!value || !isValidAuditTimestamp(value)) {
         return null;
     }
     const parsed = Date.parse(value);
     return Number.isNaN(parsed) ? null : parsed;
 }
+export function auditFingerprint(record) {
+    if (typeof record.fingerprint !== 'string' || !isValidAuditFingerprint(record.fingerprint)) {
+        return undefined;
+    }
+    return record.fingerprint;
+}
+export function auditApprovalCorrelationId(record) {
+    if (typeof record.approvalCorrelationId === 'string' &&
+        isValidApprovalCorrelationId(record.approvalCorrelationId)) {
+        return record.approvalCorrelationId;
+    }
+    return undefined;
+}
 export function isGateRecord(record) {
     return typeof record.event === 'string' && GATE_EVENTS.has(record.event);
 }
@@ -89,28 +103,36 @@ export function filterAuditRecords(records, filter = {}) {
 }
 export function buildApprovalRoundTrips(records) {
     const trips = [];
+    const pendingByCorrelationId = new Map();
     const pendingByApprovalId = new Map();
     const pendingByFingerprint = new Map();
     for (const record of records) {
         const timestamp = record.timestamp ?? '';
-        if (isGateRecord(record) && inferWouldBlock(record) && record.fingerprint) {
+        const fingerprint = auditFingerprint(record);
+        const correlationId = auditApprovalCorrelationId(record);
+        if (isGateRecord(record) && inferWouldBlock(record) && fingerprint) {
             const trip = {
                 denyTimestamp: timestamp,
-                fingerprint: record.fingerprint,
+                fingerprint,
                 reason: record.reason ?? 'unknown',
                 summary: record.summary ?? '',
                 kind: record.kind ?? 'unknown',
                 approvalId: record.approvalId,
+                approvalCorrelationId: correlationId,
             };
             trips.push(trip);
-            if (record.approvalId) {
+            if (correlationId) {
+                pendingByCorrelationId.set(correlationId, trip);
+            }
+            if (record.approvalId && !String(record.approvalId).startsWith('<')) {
                 pendingByApprovalId.set(record.approvalId, trip);
             }
-            pendingByFingerprint.set(record.fingerprint, trip);
+            pendingByFingerprint.set(fingerprint, trip);
             continue;
         }
-        if (isApprovalRecorded(record) && record.approvalId) {
-            const trip = pendingByApprovalId.get(record.approvalId);
+        if (isApprovalRecorded(record)) {
+            const trip = (correlationId ? pendingByCorrelationId.get(correlationId) : undefined) ??
+                (record.approvalId ? pendingByApprovalId.get(record.approvalId) : undefined);
             if (trip) {
                 trip.approvalTimestamp = timestamp;
                 const denyMs = parseTimestamp(trip.denyTimestamp);
@@ -123,9 +145,11 @@ export function buildApprovalRoundTrips(records) {
         }
         if (isGateRecord(record) &&
             record.reason === 'approved_once' &&
-            record.fingerprint &&
+            fingerprint &&
             record.permission === 'allow') {
-            const trip = pendingByFingerprint.get(record.fingerprint);
+            const trip = correlationId
+                ? pendingByCorrelationId.get(correlationId)
+                : pendingByFingerprint.get(fingerprint);
             if (trip) {
                 trip.executeTimestamp = timestamp;
             }

package/dist/core/audit-recovery-metrics.d.ts

@@ -0,0 +1,33 @@
+import type { AuditCohortIdentity } from './audit-metrics.js';
+import type { AuditRecord } from './audit-types.js';
+export interface RecoverySnapshotMetrics {
+    attempts: number;
+    applied: number;
+    skipped: number;
+    byBackend: Record<string, number>;
+    byResourceKind: Record<string, number>;
+    prepareSampleCount: number;
+    prepareMsP50: number | null;
+    prepareMsP95: number | null;
+    failuresByReason: Record<string, number>;
+}
+export interface RecoveryRestoreMetrics {
+    applied: number;
+    conflict: number;
+    rejected: number;
+}
+export interface RecoveryMetrics {
+    snapshot: RecoverySnapshotMetrics;
+    restore: RecoveryRestoreMetrics;
+}
+export interface RecoveryMetricsCohort extends RecoveryMetrics {
+    excludedSnapshotAttempts: number;
+    excludedRestoreEvents: number;
+}
+export declare function sanitizeRecoveryFailureReason(record: AuditRecord): string;
+export declare function computeRecoveryMetrics(records: AuditRecord[], options?: {
+    activeCohort?: AuditCohortIdentity | null;
+}): {
+    allTime: RecoveryMetrics;
+    currentCohort: RecoveryMetricsCohort;
+};

package/dist/core/audit-recovery-metrics.js

@@ -0,0 +1,146 @@
+import { matchesAuditCohort } from '../runtime-provenance.js';
+import { GATE_EVENTS } from './audit-types.js';
+const RESTORE_EVENTS = new Set(['recoveryApplied', 'recoveryConflict', 'recoveryRejected']);
+const STABLE_FAILURE_REASON = /^[a-z][a-z0-9_]*$/;
+function increment(bucket, key) {
+    bucket[key] = (bucket[key] ?? 0) + 1;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0) {
+        return null;
+    }
+    const index = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, Math.min(sorted.length - 1, index))] ?? null;
+}
+export function sanitizeRecoveryFailureReason(record) {
+    const reason = record.transactionalSkipReason ?? record.reason;
+    if (typeof reason === 'string' && STABLE_FAILURE_REASON.test(reason)) {
+        return reason;
+    }
+    return 'transactional_execution_failed';
+}
+function isRecoverySnapshotRecord(record) {
+    if (typeof record.transactional === 'boolean') {
+        return true;
+    }
+    if (typeof record.transactionalSkipReason === 'string') {
+        return true;
+    }
+    if (record.recoveryFailClosed === true) {
+        return true;
+    }
+    return false;
+}
+function isRecoveryRestoreRecord(record) {
+    const event = typeof record.event === 'string' ? record.event : '';
+    return RESTORE_EVENTS.has(event);
+}
+function matchesCohort(record, cohort) {
+    return matchesAuditCohort(record, cohort);
+}
+function emptySnapshotMetrics() {
+    return {
+        attempts: 0,
+        applied: 0,
+        skipped: 0,
+        byBackend: {},
+        byResourceKind: {},
+        prepareSampleCount: 0,
+        prepareMsP50: null,
+        prepareMsP95: null,
+        failuresByReason: {},
+    };
+}
+function emptyRestoreMetrics() {
+    return {
+        applied: 0,
+        conflict: 0,
+        rejected: 0,
+    };
+}
+function isRecoverySnapshotApplied(record) {
+    return (record.transactional === true &&
+        (record.reason === 'transactional_already_applied' ||
+            typeof record.recoveryCheckpointId === 'string' ||
+            record.recoveryState === 'applied'));
+}
+function computeSnapshotMetrics(records) {
+    const metrics = emptySnapshotMetrics();
+    const prepareSamples = [];
+    for (const record of records) {
+        const event = typeof record.event === 'string' ? record.event : '';
+        if (!GATE_EVENTS.has(event)) {
+            continue;
+        }
+        if (!isRecoverySnapshotRecord(record)) {
+            continue;
+        }
+        metrics.attempts += 1;
+        if (isRecoverySnapshotApplied(record)) {
+            metrics.applied += 1;
+        }
+        else {
+            metrics.skipped += 1;
+            if (record.transactionalReason === 'transactional_observed_risk') {
+                increment(metrics.failuresByReason, 'transactional_observed_risk');
+            }
+            else {
+                increment(metrics.failuresByReason, sanitizeRecoveryFailureReason(record));
+            }
+        }
+        const backend = typeof record.transactionalBackend === 'string' ? record.transactionalBackend : 'unknown';
+        increment(metrics.byBackend, backend);
+        const resourceKind = typeof record.resourceKind === 'string' ? record.resourceKind : 'unknown';
+        increment(metrics.byResourceKind, resourceKind);
+        if (typeof record.snapshotPrepareMs === 'number' && Number.isFinite(record.snapshotPrepareMs)) {
+            prepareSamples.push(record.snapshotPrepareMs);
+        }
+    }
+    prepareSamples.sort((left, right) => left - right);
+    metrics.prepareSampleCount = prepareSamples.length;
+    metrics.prepareMsP50 = percentile(prepareSamples, 50);
+    metrics.prepareMsP95 = percentile(prepareSamples, 95);
+    return metrics;
+}
+function computeRestoreMetrics(records) {
+    const metrics = emptyRestoreMetrics();
+    for (const record of records) {
+        const event = typeof record.event === 'string' ? record.event : '';
+        if (event === 'recoveryApplied') {
+            metrics.applied += 1;
+        }
+        else if (event === 'recoveryConflict') {
+            metrics.conflict += 1;
+        }
+        else if (event === 'recoveryRejected') {
+            metrics.rejected += 1;
+        }
+    }
+    return metrics;
+}
+export function computeRecoveryMetrics(records, options = {}) {
+    const gateSnapshotRecords = records.filter((record) => {
+        const event = typeof record.event === 'string' ? record.event : '';
+        return GATE_EVENTS.has(event) && isRecoverySnapshotRecord(record);
+    });
+    const restoreRecords = records.filter(isRecoveryRestoreRecord);
+    const activeCohort = options.activeCohort ?? null;
+    const cohortGateSnapshotRecords = activeCohort
+        ? gateSnapshotRecords.filter((record) => matchesCohort(record, activeCohort))
+        : [];
+    const cohortRestoreRecords = activeCohort
+        ? restoreRecords.filter((record) => matchesCohort(record, activeCohort))
+        : [];
+    return {
+        allTime: {
+            snapshot: computeSnapshotMetrics(gateSnapshotRecords),
+            restore: computeRestoreMetrics(restoreRecords),
+        },
+        currentCohort: {
+            snapshot: computeSnapshotMetrics(cohortGateSnapshotRecords),
+            restore: computeRestoreMetrics(cohortRestoreRecords),
+            excludedSnapshotAttempts: gateSnapshotRecords.length - cohortGateSnapshotRecords.length,
+            excludedRestoreEvents: restoreRecords.length - cohortRestoreRecords.length,
+        },
+    };
+}

package/dist/core/audit-serialize.d.ts

@@ -0,0 +1,9 @@
+import type { ScrubOptions } from './types.js';
+export declare const AUDIT_SCHEMA_VERSION = 3;
+export declare function approvalCorrelationId(approvalId: string): string;
+export declare function isValidApprovalCorrelationId(value: string): boolean;
+export declare function isValidAuditTimestamp(value: string): boolean;
+export declare function isValidAuditFingerprint(value: string): boolean;
+export declare function serializeAuditRecordV3(record: Record<string, unknown>, options: ScrubOptions): Record<string, unknown>;
+export declare function parseAuditNdjsonLine(line: string): Record<string, unknown> | null;
+export declare function appendAuditRecord(auditPath: string, record: Record<string, unknown>, options: ScrubOptions): Promise<void>;