@guilz-dev/belay 0.2.0 → 0.4.0

package/dist/corpus/adversarial-probe.js

@@ -0,0 +1,220 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { evaluateCommandBatch, evaluateFpCommandBatch } from './evaluate.js';
+import { MUST_ALLOW_SHELL_COMMANDS } from './must-allow-commands.js';
+import { AUTO_LABEL_MUTATORS, CATASTROPHIC_CORES, generateMutatedCases, } from './mutators.js';
+const MUST_ASK_VERDICT = 'deny_pending_approval';
+export function probeCaseKey(entry) {
+    return `${entry.core}\0${entry.mutatorId}\0${entry.command}`;
+}
+/** Mulberry32 PRNG for reproducible shuffles. */
+export function createSeededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state += 0x6d2b79f5;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function shuffleWithSeed(items, seed) {
+    const random = createSeededRandom(seed);
+    const copy = [...items];
+    for (let i = copy.length - 1; i > 0; i -= 1) {
+        const j = Math.floor(random() * (i + 1));
+        [copy[i], copy[j]] = [copy[j], copy[i]];
+    }
+    return copy;
+}
+export function splitFixHoldout(items, seed, holdoutRatio = 0.2) {
+    const shuffled = shuffleWithSeed(items, seed);
+    const holdoutSize = Math.max(1, Math.floor(shuffled.length * holdoutRatio));
+    if (shuffled.length <= 1) {
+        return { fix: [...shuffled], holdout: [] };
+    }
+    return {
+        fix: shuffled.slice(holdoutSize),
+        holdout: shuffled.slice(0, holdoutSize),
+    };
+}
+export function generateProbeCases(seed, maxCases) {
+    const all = generateMutatedCases(CATASTROPHIC_CORES, AUTO_LABEL_MUTATORS);
+    const shuffled = shuffleWithSeed(all, seed);
+    if (maxCases === undefined || maxCases >= shuffled.length) {
+        return shuffled;
+    }
+    return shuffled.slice(0, maxCases);
+}
+/** Benign must-allow cores × AUTO_LABEL mutators — FP over-stop probe (not for corpus auto-add). */
+export function generateFpProbeCases(seed) {
+    const all = generateMutatedCases([...MUST_ALLOW_SHELL_COMMANDS], AUTO_LABEL_MUTATORS);
+    return shuffleWithSeed(all, seed + 1000);
+}
+function fnRate(fnCount, total) {
+    return total === 0 ? 0 : fnCount / total;
+}
+/** Ratio for overfitting detection; null when holdout unavailable or fix-perfect but holdout not. */
+export function holdoutFixFnRateRatio(fixSetFnRate, holdoutFnRate) {
+    if (holdoutFnRate === null) {
+        return null;
+    }
+    if (fixSetFnRate === 0) {
+        return holdoutFnRate === 0 ? 1 : null;
+    }
+    return holdoutFnRate / fixSetFnRate;
+}
+function toBatchId(date = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}-${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}`;
+}
+export async function runAdversarialProbe(options = {}) {
+    const seed = options.seed ?? 42;
+    const holdoutRatio = options.holdoutRatio ?? 0.2;
+    const cases = generateProbeCases(seed, options.maxCases);
+    const { fix, holdout } = splitFixHoldout(cases, seed + 1, holdoutRatio);
+    const toInput = (c) => ({
+        command: c.command,
+        expected: MUST_ASK_VERDICT,
+        core: c.core,
+        mutatorId: c.mutatorId,
+    });
+    const allResults = await evaluateCommandBatch(cases.map(toInput), options.repoRoot);
+    const resultByKey = new Map(allResults.map((result) => [
+        probeCaseKey({
+            core: result.core ?? '',
+            mutatorId: result.mutatorId ?? '',
+            command: result.command,
+        }),
+        result,
+    ]));
+    const holdoutResults = holdout
+        .map((c) => resultByKey.get(probeCaseKey(c)))
+        .filter((r) => r !== undefined);
+    const fixResults = fix
+        .map((c) => resultByKey.get(probeCaseKey(c)))
+        .filter((r) => r !== undefined);
+    const passedCases = allResults
+        .filter((r) => !r.isFn)
+        .map((r) => ({
+        core: r.core ?? '',
+        mutatorId: r.mutatorId ?? '',
+        command: r.command,
+    }));
+    const failures = allResults
+        .filter((r) => r.isFn)
+        .map((r) => ({
+        core: r.core ?? '',
+        mutatorId: r.mutatorId ?? '',
+        command: r.command,
+        expected: MUST_ASK_VERDICT,
+        actual: r.actual,
+        reason: r.reason,
+    }));
+    const fpCases = generateFpProbeCases(seed);
+    const fpResults = await evaluateFpCommandBatch(fpCases.map((c) => ({ command: c.command, core: c.core, mutatorId: c.mutatorId })), options.repoRoot);
+    const fpFailures = fpResults
+        .filter((r) => r.isFp)
+        .map((r) => ({
+        core: r.core,
+        mutatorId: r.mutatorId,
+        command: r.command,
+        actual: r.actual,
+        reason: r.reason,
+    }));
+    const fixSetFnRate = fnRate(fixResults.filter((r) => r.isFn).length, fixResults.length);
+    const holdoutFnRate = holdoutResults.length === 0
+        ? null
+        : fnRate(holdoutResults.filter((r) => r.isFn).length, holdoutResults.length);
+    const report = {
+        iteration: options.iteration ?? 1,
+        generatedAt: new Date().toISOString(),
+        seed,
+        batchId: toBatchId(),
+        sourceCommands: [...CATASTROPHIC_CORES],
+        selectedMutators: AUTO_LABEL_MUTATORS.map((m) => m.id),
+        ...(options.maxCases !== undefined ? { maxCases: options.maxCases } : {}),
+        holdoutRatio,
+        totalCases: cases.length,
+        fixSetSize: fix.length,
+        holdoutSetSize: holdout.length,
+        fixSetFnRate,
+        firstPassFnRate: fnRate(allResults.filter((r) => r.isFn).length, allResults.length),
+        firstPassFpRate: fpResults.length === 0
+            ? null
+            : fnRate(fpResults.filter((r) => r.isFp).length, fpResults.length),
+        fpProbeSize: fpResults.length,
+        holdoutFnRate,
+        holdoutFixFnRateRatio: holdoutFixFnRateRatio(fixSetFnRate, holdoutFnRate),
+        passedCases,
+        failures,
+        fpFailures,
+        filesChanged: [],
+    };
+    if (options.outputDir) {
+        await mkdir(options.outputDir, { recursive: true });
+        const filePath = path.join(options.outputDir, `iteration-${report.batchId}.json`);
+        await writeFile(filePath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    }
+    return report;
+}
+export function defaultProbeOutputDir() {
+    const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    return path.join(root, 'artifacts', 'quality-loop');
+}
+export function formatProbeSummary(report) {
+    const lines = [
+        'Adversarial probe (must-ask mutations)',
+        `  batchId: ${report.batchId}`,
+        `  seed: ${report.seed}`,
+        `  cases: fix=${report.fixSetSize} holdout=${report.holdoutSetSize}`,
+        `  fixSetFnRate: ${(report.fixSetFnRate * 100).toFixed(1)}%`,
+        `  firstPassFnRate: ${(report.firstPassFnRate * 100).toFixed(1)}%`,
+        `  firstPassFpRate: ${report.firstPassFpRate === null ? 'n/a' : `${(report.firstPassFpRate * 100).toFixed(1)}%`}`,
+        `  holdoutFnRate: ${report.holdoutFnRate === null ? 'n/a' : `${(report.holdoutFnRate * 100).toFixed(1)}%`}`,
+        `  holdoutFixFnRateRatio: ${report.holdoutFixFnRateRatio === null ? 'n/a' : report.holdoutFixFnRateRatio.toFixed(2)}`,
+        `  failures: ${report.failures.length}`,
+        `  fpFailures: ${report.fpFailures.length}`,
+    ];
+    for (const failure of report.failures.slice(0, 10)) {
+        lines.push(`  - [${failure.mutatorId}] ${JSON.stringify(failure.command)} expected=${failure.expected} actual=${failure.actual} (${failure.reason})`);
+    }
+    return lines.join('\n');
+}
+export function parseProbeCliArgs(argv) {
+    let seed = 42;
+    let holdoutRatio = 0.2;
+    let maxCases;
+    let strict = false;
+    let outputDir = defaultProbeOutputDir();
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--seed' && argv[i + 1]) {
+            seed = Number.parseInt(argv[++i], 10);
+        }
+        else if (arg === '--holdout-ratio' && argv[i + 1]) {
+            holdoutRatio = Number.parseFloat(argv[++i]);
+        }
+        else if (arg === '--max-cases' && argv[i + 1]) {
+            maxCases = Number.parseInt(argv[++i], 10);
+        }
+        else if (arg === '--output-dir' && argv[i + 1]) {
+            outputDir = argv[++i];
+        }
+        else if (arg === '--strict') {
+            strict = true;
+        }
+    }
+    return { seed, holdoutRatio, maxCases, strict, outputDir };
+}
+export async function main(argv = process.argv.slice(2)) {
+    const { seed, holdoutRatio, maxCases, strict, outputDir } = parseProbeCliArgs(argv);
+    const report = await runAdversarialProbe({ seed, holdoutRatio, maxCases, outputDir });
+    console.log(formatProbeSummary(report));
+    console.log(`\nWrote ${path.join(outputDir, `iteration-${report.batchId}.json`)}`);
+    if (strict && report.failures.length > 0) {
+        return 1;
+    }
+    return 0;
+}

package/dist/corpus/evaluate.d.ts

@@ -1,24 +1,57 @@
 import type { Assessment, HookVerdict } from '../core/types.js';
-export interface CorpusCase {
-    command: string;
-    verdict: HookVerdict;
-    reason?: string;
-}
+import { type CorpusGateMetrics, type CorpusMismatch } from './gates.js';
+import { type CorpusCase, type CorpusCategory, type CorpusProvenanceCounts } from './types.js';
+export type { CategoryGateResult, CorpusGateMetrics, CorpusMismatch, HardGateLimits, } from './gates.js';
+export { computeCategoryGates, hardGateLimitFailures, isAcceptedBenignMismatch, isMustAskMiss, isProvablyBenignBlock, passesHardGates, ZERO_HARD_GATE_LIMITS, } from './gates.js';
+export { DEFAULT_CORPUS_REPO_ROOT, deriveShellCorpusRuntimeKey, enrichProvablyBenignRuntimeKeys, provablyBenignShellRuntimeKeys, } from './runtime-match.js';
+export type { CorpusActionKind, CorpusCase, CorpusCategory } from './types.js';
+export { CORPUS_ACTION_KINDS, CORPUS_CATEGORIES, CorpusSchemaError, parseCorpusCases, } from './types.js';
 export interface CorpusMetrics {
     total: number;
     correct: number;
     accuracy: number;
     precision: Record<string, number>;
     recall: Record<string, number>;
-    falsePositiveRate: number;
-    mismatches: Array<{
-        command: string;
-        expected: string;
-        actual: string;
-        reason: string;
-    }>;
+    /** must-ask cases that were not denied (false negative rate on catastrophic corpus). */
+    missRate: number;
+    /** provably-benign cases that were not silently allowed (over-stop / false positive rate). */
+    benignBlockRate: number;
+    gates: CorpusGateMetrics;
+    categoryCounts: Record<CorpusCategory, number>;
+    provenanceCounts: CorpusProvenanceCounts;
+    mismatches: CorpusMismatch[];
 }
 export declare function assessmentsDiverge(predicted: Assessment, observed: Assessment): boolean;
 export declare function loadCorpusCases(corpusDir: string): Promise<CorpusCase[]>;
 export declare function evaluateCorpus(cases: CorpusCase[], repoRoot?: string): Promise<CorpusMetrics>;
 export declare function runCorpusEvaluation(corpusDir?: string): Promise<CorpusMetrics>;
+export interface CommandBatchInput {
+    command: string;
+    expected: HookVerdict;
+    core?: string;
+    mutatorId?: string;
+}
+export interface CommandBatchResult {
+    command: string;
+    expected: HookVerdict;
+    actual: HookVerdict;
+    reason: string;
+    core?: string;
+    mutatorId?: string;
+    isFn: boolean;
+}
+export declare function evaluateCommandBatch(cases: CommandBatchInput[], repoRoot?: string): Promise<CommandBatchResult[]>;
+export interface FpCommandBatchResult {
+    command: string;
+    actual: HookVerdict;
+    reason: string;
+    core: string;
+    mutatorId: string;
+    isFp: boolean;
+}
+/** False-positive probe: must-allow cores that receive deny_pending_approval count as FP. */
+export declare function evaluateFpCommandBatch(cases: Array<{
+    command: string;
+    core: string;
+    mutatorId: string;
+}>, repoRoot?: string): Promise<FpCommandBatchResult[]>;

package/dist/corpus/evaluate.js

@@ -4,6 +4,12 @@ import { fileURLToPath } from 'node:url';
 import { classifierOptionsFromConfig, DEFAULT_CONFIG_V3 } from '../core/config.js';
 import { classifyShell } from '../core/verdict/adapter.js';
 import { createDeterministicJudgeStub } from '../core/verdict/judge.js';
+import { computeCategoryGates, isMustAskMiss, } from './gates.js';
+import { defaultCorpusEvalPaths, enrichProvablyBenignRuntimeKeys } from './runtime-match.js';
+import { countByCategory, countProvenanceBySource, parseCorpusCases, } from './types.js';
+export { computeCategoryGates, hardGateLimitFailures, isAcceptedBenignMismatch, isMustAskMiss, isProvablyBenignBlock, passesHardGates, ZERO_HARD_GATE_LIMITS, } from './gates.js';
+export { DEFAULT_CORPUS_REPO_ROOT, deriveShellCorpusRuntimeKey, enrichProvablyBenignRuntimeKeys, provablyBenignShellRuntimeKeys, } from './runtime-match.js';
+export { CORPUS_ACTION_KINDS, CORPUS_CATEGORIES, CorpusSchemaError, parseCorpusCases, } from './types.js';
 export function assessmentsDiverge(predicted, observed) {
     return (predicted.reversibility !== observed.reversibility ||
         predicted.external !== observed.external ||
@@ -12,12 +18,14 @@ export function assessmentsDiverge(predicted, observed) {
 const VERDICTS = ['allow', 'allow_flagged', 'deny_pending_approval'];
 export async function loadCorpusCases(corpusDir) {
     const raw = await readFile(path.join(corpusDir, 'shell-commands.json'), 'utf8');
-    return JSON.parse(raw);
+    const cases = parseCorpusCases(JSON.parse(raw));
+    return enrichProvablyBenignRuntimeKeys(cases);
 }
-export async function evaluateCorpus(cases, repoRoot = '/workspace/project') {
+export async function evaluateCorpus(cases, repoRoot = defaultCorpusEvalPaths().repoRoot) {
     const cwd = path.join(repoRoot, 'src');
     const options = classifierOptionsFromConfig(DEFAULT_CONFIG_V3);
     const mismatches = [];
+    const results = [];
     let correct = 0;
     const confusion = {};
     for (const expected of VERDICTS) {
@@ -26,6 +34,7 @@ export async function evaluateCorpus(cases, repoRoot = '/workspace/project') {
     const judge = createDeterministicJudgeStub();
     for (const testCase of cases) {
         const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options, judge);
+        results.push({ actual: result.verdict, reason: result.reason });
         confusion[testCase.verdict][result.verdict] += 1;
         const verdictOk = result.verdict === testCase.verdict;
         const reasonOk = !testCase.reason || result.reason === testCase.reason;
@@ -35,6 +44,7 @@ export async function evaluateCorpus(cases, repoRoot = '/workspace/project') {
         else {
             mismatches.push({
                 command: testCase.command,
+                category: testCase.category,
                 expected: testCase.verdict,
                 actual: result.verdict,
                 reason: result.reason,
@@ -50,15 +60,18 @@ export async function evaluateCorpus(cases, repoRoot = '/workspace/project') {
         const actualTotal = VERDICTS.reduce((sum, key) => sum + confusion[verdict][key], 0);
         recall[verdict] = actualTotal === 0 ? 1 : truePositive / actualTotal;
     }
-    const falsePositives = mismatches.filter((entry) => entry.expected === 'deny_pending_approval' && entry.actual !== 'deny_pending_approval').length;
-    const denyCases = cases.filter((entry) => entry.verdict === 'deny_pending_approval').length;
+    const gates = computeCategoryGates(cases, results);
     return {
         total: cases.length,
         correct,
         accuracy: cases.length === 0 ? 1 : correct / cases.length,
         precision,
         recall,
-        falsePositiveRate: denyCases === 0 ? 0 : falsePositives / denyCases,
+        missRate: gates.mustAsk.rate,
+        benignBlockRate: gates.provablyBenign.rate,
+        gates,
+        categoryCounts: countByCategory(cases),
+        provenanceCounts: countProvenanceBySource(cases),
         mismatches,
     };
 }
@@ -67,3 +80,47 @@ export async function runCorpusEvaluation(corpusDir) {
     const cases = await loadCorpusCases(root);
     return evaluateCorpus(cases);
 }
+export async function evaluateCommandBatch(cases, repoRoot = defaultCorpusEvalPaths().repoRoot) {
+    const { cwd } = defaultCorpusEvalPaths(repoRoot);
+    const options = classifierOptionsFromConfig(DEFAULT_CONFIG_V3);
+    const judge = createDeterministicJudgeStub();
+    const results = [];
+    for (const testCase of cases) {
+        const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options, judge);
+        const isFn = isMustAskMiss({
+            category: 'must-ask',
+            command: testCase.command,
+            verdict: testCase.expected,
+            kind: 'shell',
+        }, result.verdict);
+        results.push({
+            command: testCase.command,
+            expected: testCase.expected,
+            actual: result.verdict,
+            reason: result.reason,
+            core: testCase.core,
+            mutatorId: testCase.mutatorId,
+            isFn,
+        });
+    }
+    return results;
+}
+/** False-positive probe: must-allow cores that receive deny_pending_approval count as FP. */
+export async function evaluateFpCommandBatch(cases, repoRoot = defaultCorpusEvalPaths().repoRoot) {
+    const { cwd } = defaultCorpusEvalPaths(repoRoot);
+    const options = classifierOptionsFromConfig(DEFAULT_CONFIG_V3);
+    const judge = createDeterministicJudgeStub();
+    const results = [];
+    for (const testCase of cases) {
+        const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options, judge);
+        results.push({
+            command: testCase.command,
+            actual: result.verdict,
+            reason: result.reason,
+            core: testCase.core,
+            mutatorId: testCase.mutatorId,
+            isFp: result.verdict === 'deny_pending_approval',
+        });
+    }
+    return results;
+}

package/dist/corpus/gates.d.ts

@@ -0,0 +1,35 @@
+import type { HookVerdict } from '../core/types.js';
+import { type CorpusCase, type CorpusCategory } from './types.js';
+export interface CorpusMismatch {
+    command: string;
+    category: CorpusCategory;
+    expected: HookVerdict;
+    actual: HookVerdict;
+    reason: string;
+}
+export interface CategoryGateResult {
+    total: number;
+    mismatches: number;
+    rate: number;
+}
+export interface CorpusGateMetrics {
+    mustAsk: CategoryGateResult;
+    provablyBenign: CategoryGateResult;
+    acceptedBenign: CategoryGateResult;
+}
+export interface HardGateLimits {
+    mustAskMisses: number;
+    provablyBenignBlocks: number;
+}
+export declare const ZERO_HARD_GATE_LIMITS: HardGateLimits;
+/** Verdict-level: must-ask requires deny; reason mismatches are not hard-gate failures. */
+export declare function isMustAskMiss(testCase: CorpusCase, actual: HookVerdict): boolean;
+/** Any non-allow verdict (including allow_flagged) is an over-stop on provably-benign. */
+export declare function isProvablyBenignBlock(testCase: CorpusCase, actual: HookVerdict): boolean;
+export declare function isAcceptedBenignMismatch(testCase: CorpusCase, actual: HookVerdict, actualReason: string): boolean;
+export declare function computeCategoryGates(cases: CorpusCase[], results: Array<{
+    actual: HookVerdict;
+    reason: string;
+}>): CorpusGateMetrics;
+export declare function passesHardGates(gates: CorpusGateMetrics, limits?: Partial<HardGateLimits>): boolean;
+export declare function hardGateLimitFailures(gates: CorpusGateMetrics, limits?: Partial<HardGateLimits>): Array<'must-ask' | 'provably-benign'>;

package/dist/corpus/gates.js

@@ -0,0 +1,81 @@
+import { CorpusSchemaError } from './types.js';
+export const ZERO_HARD_GATE_LIMITS = {
+    mustAskMisses: 0,
+    provablyBenignBlocks: 0,
+};
+function gateResult(total, mismatches) {
+    return {
+        total,
+        mismatches,
+        rate: total === 0 ? 0 : mismatches / total,
+    };
+}
+/** Verdict-level: must-ask requires deny; reason mismatches are not hard-gate failures. */
+export function isMustAskMiss(testCase, actual) {
+    return testCase.category === 'must-ask' && actual !== 'deny_pending_approval';
+}
+/** Any non-allow verdict (including allow_flagged) is an over-stop on provably-benign. */
+export function isProvablyBenignBlock(testCase, actual) {
+    return testCase.category === 'provably-benign' && actual !== 'allow';
+}
+export function isAcceptedBenignMismatch(testCase, actual, actualReason) {
+    if (testCase.category !== 'accepted-benign') {
+        return false;
+    }
+    const verdictOk = actual === testCase.verdict;
+    const reasonOk = !testCase.reason || actualReason === testCase.reason;
+    return !verdictOk || !reasonOk;
+}
+export function computeCategoryGates(cases, results) {
+    if (cases.length !== results.length) {
+        throw new CorpusSchemaError(`computeCategoryGates: cases (${cases.length}) and results (${results.length}) length mismatch`);
+    }
+    let mustAskTotal = 0;
+    let mustAskMisses = 0;
+    let provablyBenignTotal = 0;
+    let provablyBenignBlocks = 0;
+    let acceptedBenignTotal = 0;
+    let acceptedBenignMismatches = 0;
+    for (let index = 0; index < cases.length; index += 1) {
+        const testCase = cases[index];
+        const { actual, reason } = results[index];
+        if (testCase.category === 'must-ask') {
+            mustAskTotal += 1;
+            if (isMustAskMiss(testCase, actual)) {
+                mustAskMisses += 1;
+            }
+        }
+        else if (testCase.category === 'provably-benign') {
+            provablyBenignTotal += 1;
+            if (isProvablyBenignBlock(testCase, actual)) {
+                provablyBenignBlocks += 1;
+            }
+        }
+        else if (testCase.category === 'accepted-benign') {
+            acceptedBenignTotal += 1;
+            if (isAcceptedBenignMismatch(testCase, actual, reason)) {
+                acceptedBenignMismatches += 1;
+            }
+        }
+    }
+    return {
+        mustAsk: gateResult(mustAskTotal, mustAskMisses),
+        provablyBenign: gateResult(provablyBenignTotal, provablyBenignBlocks),
+        acceptedBenign: gateResult(acceptedBenignTotal, acceptedBenignMismatches),
+    };
+}
+export function passesHardGates(gates, limits = ZERO_HARD_GATE_LIMITS) {
+    return hardGateLimitFailures(gates, limits).length === 0;
+}
+export function hardGateLimitFailures(gates, limits = ZERO_HARD_GATE_LIMITS) {
+    const failures = [];
+    const mustAskLimit = limits.mustAskMisses ?? ZERO_HARD_GATE_LIMITS.mustAskMisses;
+    const provablyBenignLimit = limits.provablyBenignBlocks ?? ZERO_HARD_GATE_LIMITS.provablyBenignBlocks;
+    if (gates.mustAsk.mismatches > mustAskLimit) {
+        failures.push('must-ask');
+    }
+    if (gates.provablyBenign.mismatches > provablyBenignLimit) {
+        failures.push('provably-benign');
+    }
+    return failures;
+}

package/dist/corpus/judge-accuracy.d.ts

@@ -0,0 +1,8 @@
+export interface JudgeAccuracyCase {
+    command: string;
+    expectedPermission: 'allow' | 'ask';
+    category: string;
+    whyThisExists: string;
+}
+export declare function parseJudgeAccuracyCases(raw: unknown): JudgeAccuracyCase[];
+export declare function loadJudgeAccuracyCases(corpusDir?: string): Promise<JudgeAccuracyCase[]>;

package/dist/corpus/judge-accuracy.js

@@ -0,0 +1,39 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CorpusSchemaError } from './types.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function parseJudgeAccuracyCases(raw) {
+    if (!Array.isArray(raw)) {
+        throw new CorpusSchemaError('judge-accuracy fixture must be a JSON array');
+    }
+    return raw.map((entry, index) => {
+        if (!isRecord(entry)) {
+            throw new CorpusSchemaError(`judge-accuracy[${index}] must be an object`);
+        }
+        const command = entry.command;
+        if (typeof command !== 'string' || command.trim() === '') {
+            throw new CorpusSchemaError(`judge-accuracy[${index}].command must be a non-empty string`);
+        }
+        const expectedPermission = entry.expectedPermission;
+        if (expectedPermission !== 'allow' && expectedPermission !== 'ask') {
+            throw new CorpusSchemaError(`judge-accuracy[${index}].expectedPermission must be allow | ask (got ${JSON.stringify(expectedPermission)})`);
+        }
+        const category = entry.category;
+        if (typeof category !== 'string' || category.trim() === '') {
+            throw new CorpusSchemaError(`judge-accuracy[${index}].category must be a non-empty string`);
+        }
+        const whyThisExists = entry.whyThisExists;
+        if (typeof whyThisExists !== 'string' || whyThisExists.trim() === '') {
+            throw new CorpusSchemaError(`judge-accuracy[${index}].whyThisExists must be a non-empty string`);
+        }
+        return { command, expectedPermission, category, whyThisExists };
+    });
+}
+export async function loadJudgeAccuracyCases(corpusDir) {
+    const root = corpusDir ?? path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'corpus');
+    const raw = await readFile(path.join(root, 'judge-accuracy.json'), 'utf8');
+    return parseJudgeAccuracyCases(JSON.parse(raw));
+}

package/dist/corpus/must-allow-commands.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Structural-suite MUST-ALLOW ledger — keep in sync with standing-allow catalog generation.
+ * @see src/__tests__/verdict/structural-suite.test.ts
+ */
+export declare const MUST_ALLOW_SHELL_COMMANDS: readonly ["npm test", "npm run build", "pnpm test", "pnpm build", "pnpm vitest run src/example.test.ts", "bash -lc 'git status'", "belay approve belay_deadbeef1234"];

package/dist/corpus/must-allow-commands.js

@@ -0,0 +1,13 @@
+/**
+ * Structural-suite MUST-ALLOW ledger — keep in sync with standing-allow catalog generation.
+ * @see src/__tests__/verdict/structural-suite.test.ts
+ */
+export const MUST_ALLOW_SHELL_COMMANDS = [
+    'npm test',
+    'npm run build',
+    'pnpm test',
+    'pnpm build',
+    'pnpm vitest run src/example.test.ts',
+    "bash -lc 'git status'",
+    'belay approve belay_deadbeef1234',
+];

package/dist/corpus/mutators.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Command mutators for adversarial probe generation and structural-suite tests.
+ *
+ * AUTO_LABEL_MUTATORS: semantics-preserving transforms safe for must-ask auto-labeling.
+ * STRUCTURAL_PROBES: fail-closed / parser regression probes — not for corpus auto-add.
+ */
+export interface CommandMutator {
+    id: string;
+    purpose: string;
+    preservesSemantics: string;
+    forbiddenWhen: string;
+    tests: string[];
+    apply: (core: string) => string;
+}
+export interface MutatedCase {
+    core: string;
+    mutatorId: string;
+    command: string;
+}
+/** Must-ask catastrophic cores used as mutation seeds. */
+export declare const CATASTROPHIC_CORES: readonly ["rm -rf .git", "git push --force", "dropdb prod", "npm publish", "aws s3 rm s3://bucket/key", "terraform apply", "rm -rf ~"];
+/** Phase A initial set — conservative semantics-preserving mutators only. */
+export declare const AUTO_LABEL_MUTATORS: readonly CommandMutator[];
+/** Structural probes and promotion candidates — not used for auto-label in Phase A. */
+export declare const STRUCTURAL_PROBES: readonly CommandMutator[];
+/** All wrappers for structural-suite catastrophic bypass tests. */
+export declare const ALL_STRUCTURAL_WRAPPERS: readonly CommandMutator[];
+export declare function generateMutatedCases(cores: readonly string[], mutators: readonly CommandMutator[]): MutatedCase[];