@guilz-dev/belay 0.8.1 → 0.9.0

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,4 +1,5 @@
 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;
@@ -22,6 +23,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 +60,7 @@ export interface AuditMetricsReport {
         reason: string;
         count: number;
     }>;
+    containedExecution: ContainedExecutionMetrics;
     approvalLatency: {
         count: number;
         medianMs: number | null;
@@ -71,6 +80,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,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')) {
@@ -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-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 { 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 (record.runtimeBuildStamp === cohort.runtimeBuildStamp &&
+        record.configFingerprint === cohort.configFingerprint);
+}
+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-types.d.ts

@@ -1,7 +1,7 @@
 import type { AuditActionSnapshot, AuditReplayContext } from './audit-replay-context.js';
 import type { Assessment } from './types.js';
 export type { AuditActionSnapshot, AuditReplayContext } from './audit-replay-context.js';
-export declare const AUDIT_METRICS_SCHEMA_VERSION = 3;
+export declare const AUDIT_METRICS_SCHEMA_VERSION = 4;
 export declare const GATE_EVENTS: Set<string>;
 export interface AuditRecord {
     timestamp?: string;
@@ -42,6 +42,12 @@ export interface AuditRecord {
     recoveryState?: string;
     replayContext?: AuditReplayContext;
     actionSnapshot?: AuditActionSnapshot;
+    wouldMediate?: boolean;
+    receiptHash?: string;
+    imageId?: string;
+    mirrorBackend?: 'file_copy';
+    exitCode?: number | null;
+    timedOut?: boolean;
     [key: string]: unknown;
 }
 export interface AuditFilter {

package/dist/core/audit-types.js

@@ -1,2 +1,2 @@
-export const AUDIT_METRICS_SCHEMA_VERSION = 3;
+export const AUDIT_METRICS_SCHEMA_VERSION = 4;
 export const GATE_EVENTS = new Set(['beforeShellExecution', 'preToolUse', 'subagentGate']);

package/dist/core/bounded-output.d.ts

@@ -0,0 +1,11 @@
+export declare const OUTPUT_TAIL_LIMIT_BYTES = 16384;
+export interface BoundedOutputTail {
+    tail: Buffer;
+    truncated: boolean;
+}
+export declare function appendBoundedOutputTail(current: Buffer, chunk: Buffer | string, limitBytes?: number): BoundedOutputTail;
+export declare function decodeBoundedOutputTail(tail: Buffer): string;
+export declare function boundedUtf8Tail(value: string, limitBytes?: number): {
+    value: string;
+    truncated: boolean;
+};

package/dist/core/bounded-output.js

@@ -0,0 +1,26 @@
+export const OUTPUT_TAIL_LIMIT_BYTES = 16_384;
+export function appendBoundedOutputTail(current, chunk, limitBytes = OUTPUT_TAIL_LIMIT_BYTES) {
+    const next = Buffer.concat([current, Buffer.from(chunk)]);
+    return {
+        tail: next.length > limitBytes ? next.subarray(-limitBytes) : next,
+        truncated: next.length > limitBytes,
+    };
+}
+export function decodeBoundedOutputTail(tail) {
+    for (let offset = 0; offset <= Math.min(3, tail.length); offset += 1) {
+        try {
+            return new TextDecoder('utf-8', { fatal: true }).decode(tail.subarray(offset));
+        }
+        catch {
+            // A byte cap may have cut a leading multi-byte character; try its next boundary.
+        }
+    }
+    return tail.toString('utf8');
+}
+export function boundedUtf8Tail(value, limitBytes = OUTPUT_TAIL_LIMIT_BYTES) {
+    const encoded = Buffer.from(value);
+    if (encoded.length <= limitBytes)
+        return { value, truncated: false };
+    const tail = encoded.subarray(-limitBytes);
+    return { value: decodeBoundedOutputTail(tail), truncated: true };
+}

package/dist/core/capability/attestation.d.ts

@@ -1,5 +1,56 @@
 export declare const BOUNDARY_ATTESTATION_VERSION: 1;
+export declare const CONTAINED_EXECUTION_ATTESTATION_VERSION: 1;
 export type BoundaryDriverId = 'container' | 'cursor-sandbox' | 'seatbelt' | 'landlock' | 'host-integration';
+export interface ContainedExecutionResourceLimits {
+    timeoutMs: number;
+    memoryMiB: number;
+    cpus: number;
+    pids: number;
+}
+export interface DockerSubstrateIdentity {
+    binaryPath: string;
+    binarySha256: string;
+    endpoint: string;
+    daemonId: string;
+}
+/** A separate execution-only capability; it does not attest L1 grant enforcement. */
+export interface ContainedExecutionAttestation {
+    version: typeof CONTAINED_EXECUTION_ATTESTATION_VERSION;
+    imageId: string;
+    imageReference: string;
+    networkNone: true;
+    isolatesWorkspaceMirror: true;
+    readOnlyRoot: true;
+    sanitizedEnvironment: true;
+    dockerSubstrate: DockerSubstrateIdentity;
+    dockerConfiguration: {
+        executable: string;
+        host: string;
+    };
+    user: string;
+    entrypoint: '/bin/sh';
+    capDropAll: true;
+    noNewPrivileges: true;
+    logDriver: 'none';
+    proxyEnvironment: 'neutralized-empty';
+    tmpfs: {
+        path: '/tmp';
+        sizeBytes: number;
+        mode: 0o1777;
+        exec: false;
+        nosuid: true;
+        nodev: true;
+    };
+    memorySwapMiB: number;
+    shmSizeMiB: number;
+    healthcheckDisabled: true;
+    privateNamespaces: true;
+    privileged: false;
+    devicesNone: true;
+    resourceLimits: ContainedExecutionResourceLimits;
+    probedAt: string;
+    expiresAt: string;
+}
 export interface BoundaryAttestation {
     version: typeof BOUNDARY_ATTESTATION_VERSION;
     driver: BoundaryDriverId;
@@ -10,7 +61,12 @@ export interface BoundaryAttestation {
     probeSignals: string[];
     /** When true, the driver can mount an execution mirror at the original workspace path. */
     isolatesWorkspaceMounts?: boolean;
+    /** Optional, execution-only proof. This must never be treated as an L1-full attestation. */
+    containedExecution?: ContainedExecutionAttestation;
 }
 export declare function validateBoundaryAttestation(value: unknown): value is BoundaryAttestation;
+export declare function validateContainedExecutionAttestation(value: unknown): value is ContainedExecutionAttestation;
+export declare function isContainedExecutionAttestationFresh(attestation: ContainedExecutionAttestation | null | undefined, now?: number): boolean;
+export declare function isAttestationCurrent(attestation: BoundaryAttestation, now?: number): boolean;
 export declare function isAttestationFresh(attestation: BoundaryAttestation, now?: number): boolean;
 export declare function attestsWorkspaceMountIsolation(attestation: BoundaryAttestation | null | undefined): boolean;