@guilz-dev/belay 0.1.0

package/dist/core/audit-analysis.js

@@ -0,0 +1,147 @@
+import { 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();
+}
+function tokenOverlap(left, right) {
+    const leftTokens = new Set(normalizeSummary(left).split(' ').filter(Boolean));
+    const rightTokens = new Set(normalizeSummary(right).split(' ').filter(Boolean));
+    if (leftTokens.size === 0 || rightTokens.size === 0) {
+        return 0;
+    }
+    let overlap = 0;
+    for (const token of leftTokens) {
+        if (rightTokens.has(token)) {
+            overlap += 1;
+        }
+    }
+    return overlap / Math.max(leftTokens.size, rightTokens.size);
+}
+function hasWrapperPattern(summary) {
+    const normalized = normalizeSummary(summary);
+    return WRAPPER_TERMS.some((term) => normalized.includes(term));
+}
+export function detectBypassAttempts(records, windowMs = 5 * 60_000) {
+    const attempts = [];
+    const recentDenies = [];
+    for (const record of records) {
+        const timestampMs = parseTimestamp(record.timestamp) ?? 0;
+        if (isGateRecord(record) && inferWouldBlock(record) && record.fingerprint) {
+            recentDenies.push({ timestampMs, record });
+            continue;
+        }
+        if (!isGateRecord(record) || inferWouldBlock(record)) {
+            continue;
+        }
+        const summary = record.summary ?? '';
+        const fingerprint = record.fingerprint ?? '';
+        for (const deny of recentDenies) {
+            if (timestampMs - deny.timestampMs > windowMs) {
+                continue;
+            }
+            if (deny.record.fingerprint === fingerprint) {
+                continue;
+            }
+            const denySummary = deny.record.summary ?? '';
+            const similarity = tokenOverlap(denySummary, summary);
+            if (similarity >= 0.6 || hasWrapperPattern(summary)) {
+                attempts.push({
+                    afterDenyTimestamp: deny.record.timestamp ?? '',
+                    denyFingerprint: deny.record.fingerprint ?? '',
+                    denySummary,
+                    attemptTimestamp: record.timestamp ?? '',
+                    attemptSummary: summary,
+                    attemptFingerprint: fingerprint,
+                    signal: hasWrapperPattern(summary) ? 'wrapper_pattern' : 'similar_command',
+                });
+            }
+        }
+    }
+    for (const record of records) {
+        const signals = record.assessment?.signals ?? [];
+        if (!signals.includes('agent_assessment_mismatch')) {
+            continue;
+        }
+        attempts.push({
+            afterDenyTimestamp: record.timestamp ?? '',
+            denyFingerprint: record.fingerprint ?? '',
+            denySummary: record.summary ?? '',
+            attemptTimestamp: record.timestamp ?? '',
+            attemptSummary: record.summary ?? '',
+            attemptFingerprint: record.fingerprint ?? '',
+            signal: 'agent_assessment_mismatch',
+        });
+    }
+    return attempts;
+}
+export function detectNoisyRules(records, roundTrips, minDenies = 2) {
+    const denyByReason = new Map();
+    const approvedByReason = new Map();
+    for (const record of records) {
+        if (!isGateRecord(record) || !inferWouldBlock(record)) {
+            continue;
+        }
+        const reason = record.reason ?? 'unknown';
+        denyByReason.set(reason, (denyByReason.get(reason) ?? 0) + 1);
+    }
+    for (const trip of roundTrips) {
+        if (!trip.approvalTimestamp) {
+            continue;
+        }
+        approvedByReason.set(trip.reason, (approvedByReason.get(trip.reason) ?? 0) + 1);
+    }
+    const candidates = [];
+    for (const [reason, denyCount] of denyByReason) {
+        if (denyCount < minDenies) {
+            continue;
+        }
+        const approvedCount = approvedByReason.get(reason) ?? 0;
+        const approvalRate = denyCount > 0 ? approvedCount / denyCount : 0;
+        if (approvalRate >= 0.5) {
+            candidates.push({ reason, denyCount, approvedCount, approvalRate });
+        }
+    }
+    return candidates.sort((left, right) => right.approvalRate - left.approvalRate);
+}
+export function computeApprovalLatencyStats(roundTrips) {
+    const latencies = roundTrips
+        .map((trip) => trip.approvalLatencyMs)
+        .filter((value) => typeof value === 'number' && value >= 0)
+        .sort((left, right) => left - right);
+    if (latencies.length === 0) {
+        return { count: 0, medianMs: null, p95Ms: null };
+    }
+    const medianIndex = Math.floor(latencies.length / 2);
+    const p95Index = Math.min(latencies.length - 1, Math.ceil(latencies.length * 0.95) - 1);
+    return {
+        count: latencies.length,
+        medianMs: latencies[medianIndex] ?? null,
+        p95Ms: latencies[p95Index] ?? null,
+    };
+}
+export function bucketGateEventsByDay(records) {
+    const buckets = {};
+    for (const record of records) {
+        if (!isGateRecord(record)) {
+            continue;
+        }
+        const timestampMs = parseTimestamp(record.timestamp);
+        if (timestampMs === null) {
+            continue;
+        }
+        const day = new Date(timestampMs).toISOString().slice(0, 10);
+        buckets[day] = (buckets[day] ?? 0) + 1;
+    }
+    return buckets;
+}
+export function countVerdicts(records) {
+    const counts = {};
+    for (const record of records) {
+        if (!isGateRecord(record)) {
+            continue;
+        }
+        const verdict = record.verdict ?? 'unknown';
+        counts[verdict] = (counts[verdict] ?? 0) + 1;
+    }
+    return counts;
+}

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

@@ -0,0 +1,51 @@
+import { buildApprovalRoundTrips, filterAuditRecords, toAuditRecord } from './audit-query.js';
+/** Minimum gate events before recommending enforce with zero would-block rate. */
+export declare const MIN_GATE_EVENTS_FOR_ENFORCE = 20;
+export interface AuditMetricsReport {
+    schemaVersion: number;
+    auditLogPath: string;
+    totalLines: number;
+    parsedRecords: number;
+    gateEvents: number;
+    wouldBlockCount: number;
+    wouldBlockRate: number;
+    byReason: Record<string, number>;
+    byKind: Record<string, number>;
+    byVerdict: Record<string, number>;
+    byLocation: Record<string, number>;
+    byOpacity: Record<string, number>;
+    byEffect: Record<string, number>;
+    byConfidence: Record<string, number>;
+    approvalRecordedCount: number;
+    topWouldBlockSummaries: Array<{
+        summary: string;
+        reason: string;
+        count: number;
+    }>;
+    approvalLatency: {
+        count: number;
+        medianMs: number | null;
+        p95Ms: number | null;
+    };
+    gateEventsByDay: Record<string, number>;
+    bypassAttemptCount: number;
+    noisyRuleCandidates: Array<{
+        reason: string;
+        denyCount: number;
+        approvedCount: number;
+        approvalRate: number;
+    }>;
+    dogfood: {
+        mode: string | null;
+        unknownLocalEffect: string | null;
+        readyForEnforce: boolean;
+        notes: string[];
+    };
+}
+export declare function parseAuditNdjson(raw: string): Record<string, unknown>[];
+export declare function computeAuditMetrics(records: Record<string, unknown>[], options?: {
+    auditLogPath?: string;
+    mode?: string;
+    unknownLocalEffect?: string;
+}): AuditMetricsReport;
+export { buildApprovalRoundTrips, filterAuditRecords, toAuditRecord };

package/dist/core/audit-metrics.js

@@ -0,0 +1,155 @@
+import { bucketGateEventsByDay, computeApprovalLatencyStats, countVerdicts, detectBypassAttempts, detectNoisyRules, } from './audit-analysis.js';
+import { buildApprovalRoundTrips, filterAuditRecords, inferWouldBlock, isApprovalRecorded, toAuditRecord, } from './audit-query.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;
+export function parseAuditNdjson(raw) {
+    const records = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        try {
+            records.push(JSON.parse(trimmed));
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    return records;
+}
+function increment(bucket, key) {
+    bucket[key] = (bucket[key] ?? 0) + 1;
+}
+export function computeAuditMetrics(records, options = {}) {
+    const auditRecords = records.map(toAuditRecord);
+    const byReason = {};
+    const byKind = {};
+    const byLocation = {};
+    const byOpacity = {};
+    const byEffect = {};
+    const byConfidence = {};
+    const summaryCounts = new Map();
+    let gateEvents = 0;
+    let wouldBlockCount = 0;
+    let approvalRecordedCount = 0;
+    for (const record of auditRecords) {
+        const event = typeof record.event === 'string' ? record.event : '';
+        if (isApprovalRecorded(record)) {
+            approvalRecordedCount += 1;
+            continue;
+        }
+        if (!GATE_EVENTS.has(event)) {
+            continue;
+        }
+        gateEvents += 1;
+        const reason = typeof record.reason === 'string' ? record.reason : 'unknown';
+        const kind = typeof record.kind === 'string' ? record.kind : 'unknown';
+        increment(byReason, reason);
+        increment(byKind, kind);
+        if (typeof record.location === 'string') {
+            increment(byLocation, record.location);
+        }
+        if (typeof record.opacity === 'string') {
+            increment(byOpacity, record.opacity);
+        }
+        if (typeof record.effect === 'string') {
+            increment(byEffect, record.effect);
+        }
+        if (typeof record.confidence === 'string') {
+            increment(byConfidence, record.confidence);
+        }
+        if (inferWouldBlock(record)) {
+            wouldBlockCount += 1;
+            const summary = typeof record.summary === 'string' ? record.summary : '';
+            const key = `${reason}::${summary}`;
+            const existing = summaryCounts.get(key);
+            if (existing) {
+                existing.count += 1;
+            }
+            else {
+                summaryCounts.set(key, { summary, reason, count: 1 });
+            }
+        }
+    }
+    const byVerdict = countVerdicts(auditRecords);
+    const roundTrips = buildApprovalRoundTrips(auditRecords);
+    const approvalLatency = computeApprovalLatencyStats(roundTrips);
+    const bypassAttempts = detectBypassAttempts(auditRecords);
+    const noisyRuleCandidates = detectNoisyRules(auditRecords, roundTrips);
+    const wouldBlockRate = gateEvents > 0 ? wouldBlockCount / gateEvents : 0;
+    const topWouldBlockSummaries = [...summaryCounts.values()]
+        .sort((left, right) => right.count - left.count)
+        .slice(0, 10);
+    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.');
+        }
+        else if (wouldBlockRate === 0) {
+            if (gateEvents >= 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.`);
+            }
+        }
+        else {
+            notes.push(`${wouldBlockCount} would-block event(s) (${(wouldBlockRate * 100).toFixed(1)}% of gate traffic). Review top summaries and add overrides.allow where appropriate.`);
+            if (approvalRecordedCount > 0) {
+                notes.push(`${approvalRecordedCount} approval(s) recorded — these likely indicate actions operators wanted.`);
+            }
+            else {
+                notes.push('Review top would-block summaries and add overrides.allow for legitimate commands before switching to enforce.');
+            }
+            if (wouldBlockRate < 0.05 && gateEvents >= 20) {
+                readyForEnforce = true;
+                notes.push('Would-block rate is below 5% with sufficient sample size — consider enforce mode.');
+            }
+        }
+    }
+    else if (mode !== 'audit') {
+        notes.push('Config is not in audit mode — metrics show enforce-time behavior.');
+    }
+    else {
+        notes.push('Set policy.unknownLocalEffect to "deny" to dogfood fail-closed defaults.');
+    }
+    if (noisyRuleCandidates.length > 0) {
+        notes.push(`${noisyRuleCandidates.length} noisy rule candidate(s) — high deny-then-approve rate.`);
+    }
+    return {
+        schemaVersion: AUDIT_METRICS_SCHEMA_VERSION,
+        auditLogPath: options.auditLogPath ?? 'belay/audit.ndjson',
+        totalLines: records.length,
+        parsedRecords: records.length,
+        gateEvents,
+        wouldBlockCount,
+        wouldBlockRate,
+        byReason,
+        byKind,
+        byVerdict,
+        byLocation,
+        byOpacity,
+        byEffect,
+        byConfidence,
+        approvalRecordedCount,
+        topWouldBlockSummaries,
+        approvalLatency,
+        gateEventsByDay: bucketGateEventsByDay(auditRecords),
+        bypassAttemptCount: bypassAttempts.length,
+        noisyRuleCandidates,
+        dogfood: {
+            mode,
+            unknownLocalEffect,
+            readyForEnforce,
+            notes,
+        },
+    };
+}
+export { buildApprovalRoundTrips, filterAuditRecords, toAuditRecord };

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

@@ -0,0 +1,11 @@
+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 isGateRecord(record: AuditRecord): boolean;
+export declare function isApprovalRecorded(record: AuditRecord): boolean;
+export declare function inferWouldBlock(record: AuditRecord): boolean;
+export declare function recordStringField(record: AuditRecord, field: 'effect' | 'reason' | 'permission' | 'verdict' | 'mode' | 'summary' | 'fingerprint' | 'location'): string;
+export declare function isSilentPassRecord(record: AuditRecord): boolean;
+export declare function filterAuditRecords(records: AuditRecord[], filter?: AuditFilter): AuditRecord[];
+export declare function buildApprovalRoundTrips(records: AuditRecord[]): ApprovalRoundTrip[];
+export declare function summarizeRoundTrips(trips: ApprovalRoundTrip[]): string[];

package/dist/core/audit-query.js

@@ -0,0 +1,142 @@
+import { GATE_EVENTS } from './audit-types.js';
+export function toAuditRecord(value) {
+    return value;
+}
+export function parseTimestamp(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+export function isGateRecord(record) {
+    return typeof record.event === 'string' && GATE_EVENTS.has(record.event);
+}
+export function isApprovalRecorded(record) {
+    return ((record.event === 'approval' ||
+        (record.event === 'beforeSubmitPrompt' && record.reason === 'approval_recorded')) &&
+        record.reason === 'approval_recorded');
+}
+export function inferWouldBlock(record) {
+    if (typeof record.wouldBlock === 'boolean') {
+        return record.wouldBlock;
+    }
+    return record.verdict === 'deny_pending_approval';
+}
+export function recordStringField(record, field) {
+    const value = record[field];
+    return typeof value === 'string' ? value : '';
+}
+export function isSilentPassRecord(record) {
+    const permission = recordStringField(record, 'permission');
+    const verdict = recordStringField(record, 'verdict');
+    return (permission === 'allow' ||
+        permission === 'allow_flagged' ||
+        verdict === 'allow' ||
+        verdict === 'allow_flagged');
+}
+export function filterAuditRecords(records, filter = {}) {
+    const sinceMs = parseTimestamp(filter.since);
+    const untilMs = parseTimestamp(filter.until);
+    let filtered = records.filter((record) => {
+        const timestampMs = parseTimestamp(record.timestamp);
+        if (sinceMs !== null && (timestampMs === null || timestampMs < sinceMs)) {
+            return false;
+        }
+        if (untilMs !== null && (timestampMs === null || timestampMs > untilMs)) {
+            return false;
+        }
+        if (filter.verdict && record.verdict !== filter.verdict) {
+            return false;
+        }
+        if (filter.reason && record.reason !== filter.reason) {
+            return false;
+        }
+        if (filter.kind && record.kind !== filter.kind) {
+            return false;
+        }
+        if (filter.fingerprint && record.fingerprint !== filter.fingerprint) {
+            return false;
+        }
+        if (filter.event && record.event !== filter.event) {
+            return false;
+        }
+        if (filter.location && record.location !== filter.location) {
+            return false;
+        }
+        if (filter.opacity && record.opacity !== filter.opacity) {
+            return false;
+        }
+        if (filter.effect && record.effect !== filter.effect) {
+            return false;
+        }
+        if (filter.confidence && record.confidence !== filter.confidence) {
+            return false;
+        }
+        return true;
+    });
+    if (typeof filter.limit === 'number' && filter.limit > 0) {
+        filtered = filtered.slice(-filter.limit);
+    }
+    return filtered;
+}
+export function buildApprovalRoundTrips(records) {
+    const trips = [];
+    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 trip = {
+                denyTimestamp: timestamp,
+                fingerprint: record.fingerprint,
+                reason: record.reason ?? 'unknown',
+                summary: record.summary ?? '',
+                kind: record.kind ?? 'unknown',
+                approvalId: record.approvalId,
+            };
+            trips.push(trip);
+            if (record.approvalId) {
+                pendingByApprovalId.set(record.approvalId, trip);
+            }
+            pendingByFingerprint.set(record.fingerprint, trip);
+            continue;
+        }
+        if (isApprovalRecorded(record) && record.approvalId) {
+            const trip = pendingByApprovalId.get(record.approvalId);
+            if (trip) {
+                trip.approvalTimestamp = timestamp;
+                const denyMs = parseTimestamp(trip.denyTimestamp);
+                const approvalMs = parseTimestamp(timestamp);
+                if (denyMs !== null && approvalMs !== null) {
+                    trip.approvalLatencyMs = approvalMs - denyMs;
+                }
+            }
+            continue;
+        }
+        if (isGateRecord(record) &&
+            record.reason === 'approved_once' &&
+            record.fingerprint &&
+            record.permission === 'allow') {
+            const trip = pendingByFingerprint.get(record.fingerprint);
+            if (trip) {
+                trip.executeTimestamp = timestamp;
+            }
+        }
+    }
+    return trips;
+}
+export function summarizeRoundTrips(trips) {
+    return trips.map((trip) => {
+        const parts = [
+            `[${trip.kind}] ${trip.summary}`,
+            `denied(${trip.reason})`,
+            trip.approvalTimestamp ? 'approved' : 'pending-approval',
+            trip.executeTimestamp ? 'executed' : 'not-retried',
+        ];
+        if (typeof trip.approvalLatencyMs === 'number') {
+            parts.push(`${Math.round(trip.approvalLatencyMs / 1000)}s latency`);
+        }
+        return parts.join(' → ');
+    });
+}

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

@@ -0,0 +1,33 @@
+import type { AuditFilter, AuditRecord } from './audit-types.js';
+export type AuditTier = 'Tier0' | 'Tier1' | 'deterministic';
+export interface RecentAskEntry {
+    timestamp?: string;
+    summary: string;
+    reason: string;
+    tier: AuditTier;
+}
+export interface AuditVisibilitySummary {
+    gateEvents: number;
+    askCount: number;
+    enforceAskCount: number;
+    auditAskCount: number;
+    unknownModeAskCount: number;
+    flagCount: number;
+    allowCount: number;
+    silentPassRate: number;
+    recentAsks: RecentAskEntry[];
+}
+export declare const DEFAULT_SILENT_PASS_THRESHOLD = 0.5;
+export declare const MIN_GATE_EVENTS_FOR_FENCE_DRIFT = 20;
+export interface FenceDriftOptions {
+    threshold?: number;
+}
+export declare function inferAuditTier(record: AuditRecord): AuditTier;
+export declare function formatAskBreakdown(summary: Pick<AuditVisibilitySummary, 'askCount' | 'enforceAskCount' | 'auditAskCount' | 'unknownModeAskCount'>, indent?: string): string[];
+export declare function summarizeAuditVisibility(records: AuditRecord[], filter?: AuditFilter, options?: {
+    recentAskLimit?: number;
+}): AuditVisibilitySummary;
+export declare function detectFenceDrift(summary: Pick<AuditVisibilitySummary, 'gateEvents' | 'silentPassRate'>, options?: FenceDriftOptions): {
+    warnings: string[];
+    notes: string[];
+};

package/dist/core/audit-summary.js

@@ -0,0 +1,111 @@
+import { filterAuditRecords, inferWouldBlock, isApprovalRecorded, isGateRecord, parseTimestamp, recordStringField, } from './audit-query.js';
+export const DEFAULT_SILENT_PASS_THRESHOLD = 0.5;
+export const MIN_GATE_EVENTS_FOR_FENCE_DRIFT = 20;
+function isTier0Reason(reason) {
+    return reason.startsWith('tier0_') || reason === 'external_effect';
+}
+export function inferAuditTier(record) {
+    const savedConfidence = typeof record.confidence === 'string' ? record.confidence : '';
+    const reason = typeof record.reason === 'string' ? record.reason : '';
+    if (savedConfidence === 'llm') {
+        return 'Tier1';
+    }
+    if (savedConfidence === 'deterministic') {
+        return isTier0Reason(reason) ? 'Tier0' : 'deterministic';
+    }
+    if (isTier0Reason(reason)) {
+        return 'Tier0';
+    }
+    if (reason === 'unknown_local_effect') {
+        return 'Tier1';
+    }
+    return 'deterministic';
+}
+export function formatAskBreakdown(summary, indent = '') {
+    const lines = [
+        `${indent}Ask (would-block): ${summary.askCount}`,
+        `${indent}  enforce (blocked): ${summary.enforceAskCount}`,
+        `${indent}  audit (would-block only): ${summary.auditAskCount}`,
+    ];
+    if (summary.unknownModeAskCount > 0) {
+        lines.push(`${indent}  mode unknown (legacy): ${summary.unknownModeAskCount}`);
+    }
+    return lines;
+}
+function isGateEventRecord(record) {
+    return isGateRecord(record) && !isApprovalRecorded(record);
+}
+export function summarizeAuditVisibility(records, filter = {}, options = {}) {
+    const filtered = filterAuditRecords(records, filter);
+    const gateRecords = filtered.filter(isGateEventRecord);
+    const recentAskLimit = options.recentAskLimit ?? 10;
+    let askCount = 0;
+    let enforceAskCount = 0;
+    let auditAskCount = 0;
+    let unknownModeAskCount = 0;
+    let flagCount = 0;
+    let allowCount = 0;
+    const recentAsks = [];
+    for (const record of gateRecords) {
+        if (inferWouldBlock(record)) {
+            askCount += 1;
+            const recordMode = recordStringField(record, 'mode');
+            if (recordMode === 'enforce') {
+                enforceAskCount += 1;
+            }
+            else if (recordMode === 'audit') {
+                auditAskCount += 1;
+            }
+            else {
+                unknownModeAskCount += 1;
+            }
+            recentAsks.push({
+                timestamp: record.timestamp,
+                summary: typeof record.summary === 'string' ? record.summary : '',
+                reason: typeof record.reason === 'string' ? record.reason : 'unknown',
+                tier: inferAuditTier(record),
+            });
+        }
+        if (record.verdict === 'allow_flagged') {
+            flagCount += 1;
+        }
+        if (record.verdict === 'allow') {
+            allowCount += 1;
+        }
+    }
+    recentAsks.sort((left, right) => {
+        const leftMs = parseTimestamp(left.timestamp) ?? 0;
+        const rightMs = parseTimestamp(right.timestamp) ?? 0;
+        return rightMs - leftMs;
+    });
+    const gateEvents = gateRecords.length;
+    const silentPassRate = gateEvents > 0 ? (allowCount + flagCount) / gateEvents : 0;
+    return {
+        gateEvents,
+        askCount,
+        enforceAskCount,
+        auditAskCount,
+        unknownModeAskCount,
+        flagCount,
+        allowCount,
+        silentPassRate,
+        recentAsks: recentAsks.slice(0, recentAskLimit),
+    };
+}
+export function detectFenceDrift(summary, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_SILENT_PASS_THRESHOLD;
+    const warnings = [];
+    const notes = [];
+    if (summary.gateEvents === 0) {
+        return { warnings, notes };
+    }
+    if (summary.gateEvents < MIN_GATE_EVENTS_FOR_FENCE_DRIFT) {
+        notes.push(`Fence drift check deferred: only ${summary.gateEvents} gate event(s) recorded (need at least ${MIN_GATE_EVENTS_FOR_FENCE_DRIFT} for a reliable silent-pass rate).`);
+        return { warnings, notes };
+    }
+    if (summary.silentPassRate < threshold) {
+        warnings.push(`Silent-pass rate is ${(summary.silentPassRate * 100).toFixed(1)}% (below ${(threshold * 100).toFixed(0)}% threshold). ` +
+            'This may indicate over-blocking (fence-like behavior). Use belay explain on recent asks to check for false positives.');
+    }
+    return { warnings, notes };
+}