@guilz-dev/belay 0.3.0 → 0.6.0

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", "git reset --hard", "git clean -fdx", "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[];

package/dist/corpus/mutators.js

@@ -0,0 +1,162 @@
+/**
+ * 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.
+ */
+/** Must-ask catastrophic cores used as mutation seeds. */
+export const CATASTROPHIC_CORES = [
+    'rm -rf .git',
+    'git push --force',
+    'git reset --hard',
+    'git clean -fdx',
+    'dropdb prod',
+    'npm publish',
+    'aws s3 rm s3://bucket/key',
+    'terraform apply',
+    'rm -rf ~',
+];
+const bashC = {
+    id: 'bash_c',
+    purpose: 'Shell indirection via bash -c',
+    preservesSemantics: 'bash -c executes the same command string in a subshell',
+    forbiddenWhen: 'Core contains unescaped single quotes that break quoting',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `bash -c '${core}'`,
+};
+const envPrefix = {
+    id: 'env_prefix',
+    purpose: 'Environment variable prefix wrapper',
+    preservesSemantics: 'env FOO=1 does not alter command semantics for unrelated vars',
+    forbiddenWhen: 'Core relies on empty or conflicting FOO value',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `env FOO=1 ${core}`,
+};
+const subshell = {
+    id: 'subshell',
+    purpose: 'Parenthesized subshell wrapper',
+    preservesSemantics: 'Subshell executes the same command sequence',
+    forbiddenWhen: 'Core depends on shell state outside subshell scope',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `(${core})`,
+};
+const absolutePath = {
+    id: 'absolute_path',
+    purpose: 'Absolute path to first token',
+    preservesSemantics: '/usr/bin/<head> resolves to the same binary when on PATH',
+    forbiddenWhen: 'Head token is not a bare command name or binary differs from PATH',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => {
+        const [head, ...rest] = core.split(' ');
+        return `/usr/bin/${head} ${rest.join(' ')}`;
+    },
+};
+/** Phase A initial set — conservative semantics-preserving mutators only. */
+export const AUTO_LABEL_MUTATORS = [
+    bashC,
+    envPrefix,
+    subshell,
+    absolutePath,
+];
+const nohup = {
+    id: 'nohup',
+    purpose: 'Background execution via nohup',
+    preservesSemantics: 'nohup runs the same command detached from terminal',
+    forbiddenWhen: 'Core depends on foreground tty or job control',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `nohup ${core}`,
+};
+const sudo = {
+    id: 'sudo',
+    purpose: 'Privilege elevation wrapper',
+    preservesSemantics: 'sudo executes the same command with elevated privileges',
+    forbiddenWhen: 'Core semantics depend on unprivileged execution context',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `sudo ${core}`,
+};
+const evalMutator = {
+    id: 'eval',
+    purpose: 'eval string execution',
+    preservesSemantics: 'eval re-parses and runs the same command string',
+    forbiddenWhen: 'Core contains shell metacharacters that eval would reinterpret',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `eval "${core}"`,
+};
+const commandSubstitution = {
+    id: 'command_substitution',
+    purpose: 'Command substitution wrapper $(core)',
+    preservesSemantics: 'Not semantics-preserving — substitution output becomes argument context',
+    forbiddenWhen: 'Always probe-only; do not auto-label',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence', 'v1 regression guards'],
+    apply: (core) => `$(${core})`,
+};
+const echoSubstitution = {
+    id: 'echo_substitution',
+    purpose: 'Echo with command substitution',
+    preservesSemantics: 'Not semantics-preserving — inner command runs in substitution context',
+    forbiddenWhen: 'Always probe-only; do not auto-label',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `echo $(${core})`,
+};
+const base64PipeSh = {
+    id: 'base64_pipe_sh',
+    purpose: 'Pipe-to-shell obfuscation probe',
+    preservesSemantics: 'Not semantics-preserving — decodes and pipes to sh',
+    forbiddenWhen: 'Always probe-only; do not auto-label',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `echo "${core}" | base64 -d | sh`,
+};
+const pythonPipe = {
+    id: 'python_pipe',
+    purpose: 'Pipe-to-python execution probe',
+    preservesSemantics: 'Not semantics-preserving — python interprets piped input',
+    forbiddenWhen: 'Always probe-only; do not auto-label',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `echo "${core}" | python3`,
+};
+const xargsProbe = {
+    id: 'xargs',
+    purpose: 'xargs invocation probe',
+    preservesSemantics: 'Not semantics-preserving — xargs changes argument delivery',
+    forbiddenWhen: 'Always probe-only; do not auto-label',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `xargs ${core} <<< ''`,
+};
+const findExecProbe = {
+    id: 'find_exec',
+    purpose: 'find -exec invocation probe',
+    preservesSemantics: 'Not semantics-preserving — find -exec changes execution context',
+    forbiddenWhen: 'Always probe-only; do not auto-label',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `find . -name '*.tmp' -exec ${core} {} \\;`,
+};
+/** Structural probes and promotion candidates — not used for auto-label in Phase A. */
+export const STRUCTURAL_PROBES = [
+    nohup,
+    sudo,
+    evalMutator,
+    commandSubstitution,
+    echoSubstitution,
+    base64PipeSh,
+    pythonPipe,
+    xargsProbe,
+    findExecProbe,
+];
+/** All wrappers for structural-suite catastrophic bypass tests. */
+export const ALL_STRUCTURAL_WRAPPERS = [
+    ...AUTO_LABEL_MUTATORS,
+    ...STRUCTURAL_PROBES,
+];
+export function generateMutatedCases(cores, mutators) {
+    const cases = [];
+    for (const core of cores) {
+        for (const mutator of mutators) {
+            cases.push({
+                core,
+                mutatorId: mutator.id,
+                command: mutator.apply(core),
+            });
+        }
+    }
+    return cases;
+}

package/dist/corpus/ratchet.d.ts

@@ -0,0 +1,42 @@
+import { type AdversarialProbeReport } from './adversarial-probe.js';
+import { type CorpusCase } from './types.js';
+export interface RatchetCandidate {
+    command: string;
+    core: string;
+    mutatorId: string;
+    sourceBatchId: string;
+    sourceCaseId: string;
+}
+export interface RatchetPlan {
+    corpusPath: string;
+    candidates: RatchetCandidate[];
+    newCases: CorpusCase[];
+    skippedDuplicates: number;
+}
+export declare function candidatesFromPassedMutations(passed: Array<{
+    command: string;
+    core: string;
+    mutatorId: string;
+}>, batchId: string): RatchetCandidate[];
+/** Build must-ask corpus entries from ratchet candidates (add-only). */
+export declare function buildRatchetCases(candidates: RatchetCandidate[]): CorpusCase[];
+export declare function planCorpusRatchet(corpusPath: string, candidates: RatchetCandidate[]): Promise<RatchetPlan>;
+export declare function applyCorpusRatchet(plan: RatchetPlan, options?: {
+    dryRun?: boolean;
+}): Promise<{
+    appended: number;
+    skippedDuplicates: number;
+}>;
+export declare function defaultCorpusPath(repoRoot: string): string;
+export declare function passedMutationsFromProbeReport(report: Pick<AdversarialProbeReport, 'seed' | 'failures' | 'batchId' | 'passedCases' | 'maxCases'>, options?: {
+    maxCases?: number;
+}): Array<{
+    command: string;
+    core: string;
+    mutatorId: string;
+}>;
+export declare function planRatchetFromProbeReport(report: AdversarialProbeReport, corpusPath: string, options?: {
+    maxCases?: number;
+}): Promise<RatchetPlan>;
+export declare function formatRatchetPlan(plan: RatchetPlan): string;
+export declare function main(argv?: string[]): Promise<number>;

package/dist/corpus/ratchet.js

@@ -0,0 +1,116 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { generateProbeCases, probeCaseKey, } from './adversarial-probe.js';
+import { parseCorpusCases } from './types.js';
+export function candidatesFromPassedMutations(passed, batchId) {
+    return passed.map((entry, index) => ({
+        command: entry.command,
+        core: entry.core,
+        mutatorId: entry.mutatorId,
+        sourceBatchId: batchId,
+        sourceCaseId: `${batchId}:${entry.mutatorId}:${entry.core}:${index}`,
+    }));
+}
+/** Build must-ask corpus entries from ratchet candidates (add-only). */
+export function buildRatchetCases(candidates) {
+    return candidates.map((candidate) => ({
+        kind: 'shell',
+        category: 'must-ask',
+        command: candidate.command,
+        verdict: 'deny_pending_approval',
+        provenance: {
+            source: 'mutation',
+            sourceBatchId: candidate.sourceBatchId,
+            sourceCaseId: candidate.sourceCaseId,
+        },
+    }));
+}
+export async function planCorpusRatchet(corpusPath, candidates) {
+    const raw = JSON.parse(await readFile(corpusPath, 'utf8'));
+    const existing = parseCorpusCases(raw);
+    const existingCommands = new Set(existing.map((entry) => entry.command));
+    const newCases = buildRatchetCases(candidates).filter((entry) => {
+        if (existingCommands.has(entry.command)) {
+            return false;
+        }
+        existingCommands.add(entry.command);
+        return true;
+    });
+    return {
+        corpusPath,
+        candidates,
+        newCases,
+        skippedDuplicates: candidates.length - newCases.length,
+    };
+}
+export async function applyCorpusRatchet(plan, options = {}) {
+    if (plan.newCases.length === 0) {
+        return { appended: 0, skippedDuplicates: plan.skippedDuplicates };
+    }
+    if (options.dryRun) {
+        return { appended: plan.newCases.length, skippedDuplicates: plan.skippedDuplicates };
+    }
+    const raw = JSON.parse(await readFile(plan.corpusPath, 'utf8'));
+    const existing = parseCorpusCases(raw);
+    const merged = [...existing, ...plan.newCases];
+    await writeFile(plan.corpusPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+    return { appended: plan.newCases.length, skippedDuplicates: plan.skippedDuplicates };
+}
+export function defaultCorpusPath(repoRoot) {
+    return path.join(repoRoot, 'corpus', 'shell-commands.json');
+}
+export function passedMutationsFromProbeReport(report, options = {}) {
+    if (Array.isArray(report.passedCases)) {
+        return report.passedCases;
+    }
+    // Legacy artifacts (pre passedCases): regenerate from seed — fragile when mutators change.
+    const maxCases = options.maxCases ?? report.maxCases;
+    const cases = generateProbeCases(report.seed, maxCases);
+    const failureKeys = new Set(report.failures.map((failure) => probeCaseKey(failure)));
+    return cases
+        .filter((entry) => !failureKeys.has(probeCaseKey(entry)))
+        .map((entry) => ({
+        command: entry.command,
+        core: entry.core,
+        mutatorId: entry.mutatorId,
+    }));
+}
+export async function planRatchetFromProbeReport(report, corpusPath, options = {}) {
+    const passed = passedMutationsFromProbeReport(report, options);
+    const candidates = candidatesFromPassedMutations(passed, report.batchId);
+    return planCorpusRatchet(corpusPath, candidates);
+}
+export function formatRatchetPlan(plan) {
+    const lines = [
+        `Corpus ratchet plan (${plan.corpusPath})`,
+        `  candidates: ${plan.candidates.length}`,
+        `  new cases: ${plan.newCases.length}`,
+        `  skipped duplicates: ${plan.skippedDuplicates}`,
+    ];
+    for (const entry of plan.newCases.slice(0, 10)) {
+        lines.push(`  - [${entry.provenance?.sourceCaseId}] ${JSON.stringify(entry.command)}`);
+    }
+    if (plan.newCases.length > 10) {
+        lines.push(`  ... ${plan.newCases.length - 10} more`);
+    }
+    return lines.join('\n');
+}
+export async function main(argv = process.argv.slice(2)) {
+    const apply = argv.includes('--apply');
+    const reportFlagIndex = argv.indexOf('--report');
+    const reportPath = reportFlagIndex >= 0 && argv[reportFlagIndex + 1] ? argv[reportFlagIndex + 1] : undefined;
+    if (!reportPath) {
+        console.error('Usage: corpus-ratchet --report <iteration.json> [--apply]');
+        return 1;
+    }
+    const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const report = JSON.parse(await readFile(reportPath, 'utf8'));
+    const plan = await planRatchetFromProbeReport(report, defaultCorpusPath(root));
+    console.log(formatRatchetPlan(plan));
+    const result = await applyCorpusRatchet(plan, { dryRun: !apply });
+    console.log(apply
+        ? `Applied ${result.appended} case(s) to corpus.`
+        : `Dry-run only — would append ${result.appended} case(s). Pass --apply to write.`);
+    return 0;
+}

package/dist/corpus/runtime-match.d.ts

@@ -0,0 +1,19 @@
+import { type CorpusCase } from './types.js';
+/** Fixed evaluation harness paths — keep in sync with `evaluateCorpus`. */
+export declare const DEFAULT_CORPUS_REPO_ROOT = "/workspace/project";
+export declare function defaultCorpusEvalPaths(repoRoot?: string): {
+    repoRoot: string;
+    cwd: string;
+};
+/**
+ * Derive the shell verdict fingerprint used for runtime matching of `provably-benign`
+ * corpus entries. Same key as audit `fingerprint` for the harness cwd/repoRoot.
+ */
+export declare function deriveShellCorpusRuntimeKey(command: string, repoRoot?: string, cwd?: string): Promise<string>;
+/**
+ * Attach derived `runtimeKey` to provably-benign shell cases that omit it.
+ * When `runtimeKey` is precomputed in the fixture, verify it matches the derived fingerprint.
+ */
+export declare function enrichProvablyBenignRuntimeKeys(cases: CorpusCase[], repoRoot?: string, cwd?: string): Promise<CorpusCase[]>;
+/** Runtime-consumable keys from enriched provably-benign shell fixtures. */
+export declare function provablyBenignShellRuntimeKeys(cases: CorpusCase[]): string[];

package/dist/corpus/runtime-match.js

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import { classifierOptionsFromConfig, DEFAULT_CONFIG_V3 } from '../core/config.js';
+import { classifyShell } from '../core/verdict/adapter.js';
+import { CorpusSchemaError } from './types.js';
+/** Fixed evaluation harness paths — keep in sync with `evaluateCorpus`. */
+export const DEFAULT_CORPUS_REPO_ROOT = '/workspace/project';
+export function defaultCorpusEvalPaths(repoRoot = DEFAULT_CORPUS_REPO_ROOT) {
+    return { repoRoot, cwd: path.join(repoRoot, 'src') };
+}
+/**
+ * Derive the shell verdict fingerprint used for runtime matching of `provably-benign`
+ * corpus entries. Same key as audit `fingerprint` for the harness cwd/repoRoot.
+ */
+export async function deriveShellCorpusRuntimeKey(command, repoRoot = DEFAULT_CORPUS_REPO_ROOT, cwd = path.join(repoRoot, 'src')) {
+    const options = classifierOptionsFromConfig(DEFAULT_CONFIG_V3);
+    const result = await classifyShell(command, cwd, repoRoot, DEFAULT_CONFIG_V3, options);
+    return result.fingerprint;
+}
+/**
+ * Attach derived `runtimeKey` to provably-benign shell cases that omit it.
+ * When `runtimeKey` is precomputed in the fixture, verify it matches the derived fingerprint.
+ */
+export async function enrichProvablyBenignRuntimeKeys(cases, repoRoot = DEFAULT_CORPUS_REPO_ROOT, cwd = path.join(repoRoot, 'src')) {
+    return Promise.all(cases.map(async (testCase) => {
+        if (testCase.kind !== 'shell' || testCase.category !== 'provably-benign') {
+            return testCase;
+        }
+        const derived = await deriveShellCorpusRuntimeKey(testCase.command, repoRoot, cwd);
+        if (testCase.runtimeKey) {
+            if (testCase.runtimeKey !== derived) {
+                throw new CorpusSchemaError(`runtimeKey mismatch for ${JSON.stringify(testCase.command)}: fixture has ${JSON.stringify(testCase.runtimeKey)}, derived ${JSON.stringify(derived)}`);
+            }
+            return testCase;
+        }
+        return { ...testCase, runtimeKey: derived };
+    }));
+}
+/** Runtime-consumable keys from enriched provably-benign shell fixtures. */
+export function provablyBenignShellRuntimeKeys(cases) {
+    return cases
+        .filter((testCase) => testCase.kind === 'shell' && testCase.category === 'provably-benign' && testCase.runtimeKey)
+        .map((testCase) => testCase.runtimeKey);
+}

package/dist/corpus/standing-allow-catalog.generated.d.ts

@@ -0,0 +1,13 @@
+export interface StandingAllowCatalogShellEntry {
+    command: string;
+    normalizedCommand: string;
+    runtimeKey: string;
+}
+export interface StandingAllowCatalog {
+    version: 1;
+    shell: {
+        provablyBenign: StandingAllowCatalogShellEntry[];
+        mustAllow: StandingAllowCatalogShellEntry[];
+    };
+}
+export declare const STANDING_ALLOW_CATALOG: StandingAllowCatalog;