@guilz-dev/belay 0.8.0 → 0.9.0

package/dist/conformance/contained-execution-guarantee.d.ts

@@ -0,0 +1,121 @@
+import { CONTAINED_EXECUTION_APPROVAL_FALLBACK_REASONS } from '../core/contained-execution/policy.js';
+/**
+ * Normative contained-execution capability contract.
+ *
+ * This is intentionally not a LayerProfileId: it describes one opt-in mediated execution and
+ * never upgrades the surrounding configuration to L1-full.
+ */
+export interface ContainedUnknownExecutionGuarantee {
+    id: 'contained-unknown-execution-v1';
+    optIn: true;
+    runtime: 'docker-only';
+    l1Full: false;
+    materializesGrants: false;
+    deniesUngrantedEffects: false;
+    authority: {
+        shell: 'effect-plan-only';
+        commandIdentityEligibility: false;
+        forbiddenInputs: readonly [
+            '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: 16384;
+            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: readonly [
+            'host-source',
+            'git-metadata',
+            'control-plane',
+            'docker-socket',
+            'devices',
+            'unrelated-host-paths'
+        ];
+        cleanupConfirmed: true;
+    };
+    fallback: {
+        approvalOnly: typeof CONTAINED_EXECUTION_APPROVAL_FALLBACK_REASONS;
+    };
+    failure: {
+        /** Every setup failure other than the exact approval fallback set denies before host replay. */
+        setup: {
+            categories: readonly [
+                'boundary',
+                'capability',
+                'image',
+                'mirror',
+                'lease',
+                'container-lifecycle',
+                'cleanup'
+            ];
+            outcome: 'deny';
+            hostExecution: 'deny';
+            approval: 'none';
+            approvalStateMutation: 'none';
+        };
+        /** A started container that times out or exits nonzero is terminal, never an approval. */
+        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';
+        };
+    };
+}
+export type ContainedUnknownExecutionScenario = {
+    id: string;
+    kind: 'eligible-unknown-local';
+    command: string;
+} | {
+    id: string;
+    kind: 'ineligible-network';
+    command: string;
+};
+export declare const CONTAINED_UNKNOWN_EXECUTION_GUARANTEE: ContainedUnknownExecutionGuarantee;
+/** Executable EffectPlan scenarios; routing and output use the gate/executor suites. */
+export declare const CONTAINED_UNKNOWN_EXECUTION_SCENARIOS: readonly ContainedUnknownExecutionScenario[];

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-io.js

@@ -1,13 +1,21 @@
 import { appendFile, mkdir } from 'node:fs/promises';
 import path from 'node:path';
+import { resolveActiveAuditCohort } from '../runtime-provenance.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 cohort = await resolveActiveAuditCohort(repoRoot, config);
     const line = JSON.stringify({
         ts: new Date().toISOString(),
         source: 'belay-cli',
+        ...(cohort
+            ? {
+                runtimeBuildStamp: cohort.runtimeBuildStamp,
+                configFingerprint: cohort.configFingerprint,
+            }
+            : {}),
         ...event,
     });
     await appendFile(auditPath, `${line}\n`, 'utf8');

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

@@ -1,7 +1,36 @@
 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 {
+    runtimeBuildStamp: string;
+    configFingerprint: string;
+}
+export interface AuditMetricsCohort {
+    identity: AuditCohortIdentity | null;
+    gateEvents: number;
+    excludedGateEvents: number;
+    wouldBlockCount: number;
+    wouldBlockRate: number;
+    classifierWouldBlockCount: number;
+    classifierWouldBlockRate: number;
+    approvalRecordedCount: number;
+    availabilityAsks: AvailabilityAskCounts;
+    wouldBlockByReason: Record<string, number>;
+    topWouldBlockSummaries: Array<{
+        summary: string;
+        reason: string;
+        count: number;
+    }>;
+    containedExecution: ContainedExecutionMetrics;
+}
+export interface ContainedExecutionMetrics {
+    wouldMediate: number;
+    complete: number;
+    failed: number;
+    timedOut: number;
+}
 export interface AuditMetricsReport {
     schemaVersion: number;
     auditLogPath: string;
@@ -24,12 +53,14 @@ export interface AuditMetricsReport {
     byEffect: Record<string, number>;
     byConfidence: Record<string, number>;
     gateEventsByRuntime: Record<string, number>;
+    currentCohort: AuditMetricsCohort;
     approvalRecordedCount: number;
     topWouldBlockSummaries: Array<{
         summary: string;
         reason: string;
         count: number;
     }>;
+    containedExecution: ContainedExecutionMetrics;
     approvalLatency: {
         count: number;
         medianMs: number | null;
@@ -49,11 +80,14 @@ 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?: {
     auditLogPath?: string;
     mode?: string;
     unknownLocalEffect?: string;
+    activeCohort?: AuditCohortIdentity | null;
 }): AuditMetricsReport;
 export { buildApprovalRoundTrips, filterAuditRecords, toAuditRecord };

package/dist/core/audit-metrics.js

@@ -1,8 +1,17 @@
 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')) {
@@ -95,33 +104,91 @@ export function computeAuditMetrics(records, options = {}) {
     const topWouldBlockSummaries = [...summaryCounts.values()]
         .sort((left, right) => right.count - left.count)
         .slice(0, 10);
+    const activeCohort = options.activeCohort ?? null;
+    const cohortRecords = activeCohort
+        ? auditRecords.filter((record) => record.runtimeBuildStamp === activeCohort.runtimeBuildStamp &&
+            record.configFingerprint === activeCohort.configFingerprint)
+        : [];
+    const cohortGateRecords = cohortRecords.filter((record) => {
+        const event = typeof record.event === 'string' ? record.event : '';
+        return GATE_EVENTS.has(event) && !isApprovalRecorded(record);
+    });
+    const cohortGateEvents = cohortGateRecords.length;
+    const cohortWouldBlockCount = cohortGateRecords.filter(inferWouldBlock).length;
+    const cohortWouldBlockRate = cohortGateEvents > 0 ? cohortWouldBlockCount / cohortGateEvents : 0;
+    const cohortApprovalRecordedCount = cohortRecords.filter(isApprovalRecorded).length;
+    const cohortAvailabilityAsks = computeAvailabilityAskCounts(cohortRecords);
+    const cohortClassifierWouldBlockCount = Math.max(0, cohortWouldBlockCount - cohortAvailabilityAsks.total);
+    const cohortClassifierWouldBlockRate = cohortGateEvents > 0 ? cohortClassifierWouldBlockCount / cohortGateEvents : 0;
+    const cohortRoundTrips = buildApprovalRoundTrips(cohortRecords);
+    const cohortRepeatedFingerprintAsks = computeRepeatedFingerprintAsks(cohortRecords);
+    const cohortNoisyRuleCandidates = detectNoisyRules(cohortRecords, cohortRoundTrips);
+    const cohortWouldBlockByReason = computeWouldBlockByReason(cohortRecords);
+    const cohortSummaryCounts = new Map();
+    for (const record of cohortGateRecords) {
+        if (!inferWouldBlock(record)) {
+            continue;
+        }
+        const reason = typeof record.reason === 'string' ? record.reason : 'unknown';
+        const summary = typeof record.summary === 'string' ? record.summary : '';
+        const key = `${reason}::${summary}`;
+        const existing = cohortSummaryCounts.get(key);
+        if (existing) {
+            existing.count += 1;
+        }
+        else {
+            cohortSummaryCounts.set(key, { summary, reason, count: 1 });
+        }
+    }
+    const cohortTopWouldBlockSummaries = [...cohortSummaryCounts.values()]
+        .sort((left, right) => right.count - left.count)
+        .slice(0, 10);
+    const currentCohort = {
+        identity: activeCohort,
+        gateEvents: cohortGateEvents,
+        excludedGateEvents: gateEvents - cohortGateEvents,
+        wouldBlockCount: cohortWouldBlockCount,
+        wouldBlockRate: cohortWouldBlockRate,
+        classifierWouldBlockCount: cohortClassifierWouldBlockCount,
+        classifierWouldBlockRate: cohortClassifierWouldBlockRate,
+        approvalRecordedCount: cohortApprovalRecordedCount,
+        availabilityAsks: cohortAvailabilityAsks,
+        wouldBlockByReason: cohortWouldBlockByReason,
+        topWouldBlockSummaries: cohortTopWouldBlockSummaries,
+        containedExecution: containedExecutionMetrics(cohortGateRecords),
+    };
     const mode = options.mode ?? null;
     const unknownLocalEffect = options.unknownLocalEffect ?? null;
     const notes = [];
     let readyForEnforce = false;
     if (mode === 'audit' && unknownLocalEffect === 'deny') {
         notes.push('Dogfood config detected: audit mode with fail-closed shell policy.');
-        if (gateEvents === 0) {
-            notes.push('No gate events yet — run normal agent work, then re-check metrics.');
+        if (!activeCohort) {
+            notes.push('Active runtime provenance is unavailable — readiness cannot use historical audit evidence.');
+        }
+        else if (cohortGateEvents === 0) {
+            notes.push('No gate events for the active runtime/config cohort — run normal agent work, then re-check metrics.');
         }
-        else if (wouldBlockRate === 0) {
-            if (gateEvents >= MIN_GATE_EVENTS_FOR_ENFORCE) {
+        else if (cohortWouldBlockRate === 0) {
+            if (cohortGateEvents >= MIN_GATE_EVENTS_FOR_ENFORCE) {
                 readyForEnforce = true;
                 notes.push('No would-block events recorded — safe to try mode: "enforce".');
             }
             else {
-                notes.push(`Only ${gateEvents} gate event(s) recorded — collect at least ${MIN_GATE_EVENTS_FOR_ENFORCE} before enforce.`);
+                notes.push(`Only ${cohortGateEvents} active-cohort gate event(s) recorded — collect at least ${MIN_GATE_EVENTS_FOR_ENFORCE} before enforce.`);
             }
         }
         else {
-            notes.push(`${wouldBlockCount} would-block event(s) (${(wouldBlockRate * 100).toFixed(1)}% of gate traffic; classifier-quality ${(classifierWouldBlockRate * 100).toFixed(1)}%). Review top summaries and correct EffectPlan semantics or resource scope; use exact approval only when the modeled effects are correct.`);
-            if (approvalRecordedCount > 0) {
-                notes.push(`${approvalRecordedCount} approval(s) recorded — these likely indicate actions operators wanted.`);
+            notes.push(`${cohortWouldBlockCount} active-cohort would-block event(s) (${(cohortWouldBlockRate * 100).toFixed(1)}% of gate traffic; classifier-quality ${(cohortClassifierWouldBlockRate * 100).toFixed(1)}%). Review top summaries and correct EffectPlan semantics or resource scope; use exact approval only when the modeled effects are correct.`);
+            if (cohortApprovalRecordedCount > 0) {
+                notes.push(`${cohortApprovalRecordedCount} active-cohort approval(s) recorded — these likely indicate actions operators wanted.`);
             }
             else {
                 notes.push('Review top would-block summaries and correct EffectPlan semantics or resource scope before switching to enforce.');
             }
-            if (classifierWouldBlockRate < 0.05 && gateEvents >= 20 && availabilityAsks.total === 0) {
+            if (cohortClassifierWouldBlockRate < 0.05 &&
+                cohortGateEvents >= 20 &&
+                cohortAvailabilityAsks.total === 0) {
                 readyForEnforce = true;
                 notes.push('Classifier-quality would-block rate is below 5% with sufficient sample size — consider enforce mode.');
             }
@@ -133,17 +200,18 @@ export function computeAuditMetrics(records, options = {}) {
     else {
         notes.push('Set policy.unknownLocalEffect to "deny" to dogfood fail-closed defaults.');
     }
-    if (availabilityAsks.total > 0) {
+    if (cohortAvailabilityAsks.total > 0) {
         readyForEnforce = false;
-        notes.push(`${availabilityAsks.total} availability-caused ask(s) — tune infrastructure before changing Effect semantics.`);
+        notes.push(`${cohortAvailabilityAsks.total} active-cohort availability-caused ask(s) — tune infrastructure before changing Effect semantics.`);
         notes.push('Ready for enforce withheld while availability-caused asks are present.');
     }
-    if (repeatedFingerprintAsks.length > 0) {
-        notes.push(`${repeatedFingerprintAsks.length} repeated fingerprint ask pattern(s) — review EffectPlan semantics and exact approval history.`);
+    if (cohortRepeatedFingerprintAsks.length > 0) {
+        notes.push(`${cohortRepeatedFingerprintAsks.length} active-cohort repeated fingerprint ask pattern(s) — review EffectPlan semantics and exact approval history.`);
     }
-    if (noisyRuleCandidates.length > 0) {
-        notes.push(`${noisyRuleCandidates.length} noisy rule candidate(s) — high deny-then-approve rate.`);
+    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',
@@ -166,8 +234,10 @@ export function computeAuditMetrics(records, options = {}) {
         byEffect,
         byConfidence,
         gateEventsByRuntime,
+        currentCohort,
         approvalRecordedCount,
         topWouldBlockSummaries,
+        containedExecution: containedExecutionMetrics(auditRecords),
         approvalLatency,
         gateEventsByDay: bucketGateEventsByDay(auditRecords),
         bypassAttemptCount: bypassAttempts.length,
@@ -178,6 +248,8 @@ export function computeAuditMetrics(records, options = {}) {
             readyForEnforce,
             notes,
         },
+        recovery: recoveryMetrics.allTime,
+        currentCohortRecovery: recoveryMetrics.currentCohort,
     };
 }
 export { buildApprovalRoundTrips, filterAuditRecords, toAuditRecord };

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;
+};