@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/core/capability/boundary-session.d.ts

@@ -0,0 +1,61 @@
+import type { BelayConfigV4 } from '../config.js';
+import type { BoundaryAttestation, BoundaryDriverId } from './attestation.js';
+import { type BoundaryDriver } from './boundary-driver.js';
+import { dockerNetworkArgs } from './boundary-egress.js';
+import { type BoundaryPrepareContext, type BoundaryRunOptions } from './boundary-run.js';
+export interface BoundarySessionOptions {
+    egressProxyRunning?: boolean;
+}
+export interface ResolvedBoundaryDriverContext {
+    driver: BoundaryDriver;
+    driverId: BoundaryDriverId;
+    proxyActive: boolean;
+    proxyEnv: Record<string, string>;
+    prepareContext: BoundaryPrepareContext;
+    attestationPath: string;
+    attestation: BoundaryAttestation | null;
+    attestationFresh: boolean;
+}
+export declare function boundaryAttestationPath(repoRoot: string, config: BelayConfigV4): string;
+export declare function loadBoundaryAttestation(filePath: string, expectedRepoRoot?: string, controlPlaneDir?: string): Promise<BoundaryAttestation | null>;
+export declare function saveBoundaryAttestation(filePath: string, attestation: BoundaryAttestation, repoRoot: string, controlPlaneDir: string): Promise<void>;
+export declare function hostIntegrationBoundaryContext(repoRoot: string): ResolvedBoundaryDriverContext;
+export declare function resolveBoundaryDriverContext(params: {
+    repoRoot: string;
+    config: BelayConfigV4;
+    driverId?: BoundaryDriverId;
+    egressProxyRunning?: boolean;
+}): Promise<ResolvedBoundaryDriverContext>;
+export declare function runWithBoundaryDriver(params: {
+    context: ResolvedBoundaryDriverContext;
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+    runOptions?: BoundaryRunOptions;
+}): Promise<Awaited<ReturnType<BoundaryDriver['run']>>>;
+export declare function startBoundarySession(params: {
+    repoRoot: string;
+    config: BelayConfigV4;
+    driverId?: BoundaryDriverId;
+    egressProxyRunning?: boolean;
+}): Promise<{
+    attestation: BoundaryAttestation;
+    attestationPath: string;
+}>;
+export declare function boundarySessionStatus(params: {
+    repoRoot: string;
+    config: BelayConfigV4;
+}): Promise<{
+    attestationPath: string;
+    attestation: BoundaryAttestation | null;
+    fresh: boolean;
+}>;
+export declare function runBoundaryAgentCommand(params: {
+    repoRoot: string;
+    config: BelayConfigV4;
+    command: string;
+    cwd?: string;
+    timeoutMs?: number;
+    runOptions?: BoundaryRunOptions;
+}): Promise<Awaited<ReturnType<BoundaryDriver['run']>>>;
+export { dockerNetworkArgs };

package/dist/core/capability/boundary-session.js

@@ -0,0 +1,138 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { egressStatus } from '../../services/egress-service.js';
+import { configuredControlPlaneDir } from '../config.js';
+import { isAttestationFresh } from './attestation.js';
+import { readSignedAttestationFile, signBoundaryAttestation, verifySignedBoundaryAttestation, } from './boundary-attestation-sign.js';
+import { getDefaultBoundaryDriver } from './boundary-driver.js';
+import { dockerNetworkArgs, isEgressProxyActive, resolveBoundaryEgressProxyEnv, } from './boundary-egress.js';
+import { runWithBoundaryRunnable, } from './boundary-run.js';
+export function boundaryAttestationPath(repoRoot, config) {
+    const rel = config.capability?.attestationRelPath ?? '.belay/attestation.json';
+    return path.isAbsolute(rel) ? rel : path.join(repoRoot, rel);
+}
+export async function loadBoundaryAttestation(filePath, expectedRepoRoot, controlPlaneDir) {
+    try {
+        const raw = await readSignedAttestationFile(filePath);
+        if (expectedRepoRoot && controlPlaneDir) {
+            return verifySignedBoundaryAttestation({
+                file: raw,
+                expectedRepoRoot,
+                controlPlaneDir,
+            });
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveBoundaryAttestation(filePath, attestation, repoRoot, controlPlaneDir) {
+    const signed = await signBoundaryAttestation({
+        repoRoot,
+        attestation,
+        controlPlaneDir,
+    });
+    await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    await writeFile(filePath, `${JSON.stringify(signed, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+export function hostIntegrationBoundaryContext(repoRoot) {
+    const driver = getDefaultBoundaryDriver('host-integration', { repoRoot });
+    return {
+        driver,
+        driverId: 'host-integration',
+        proxyActive: false,
+        proxyEnv: {},
+        prepareContext: {
+            repoRoot,
+            egressProxyActive: false,
+            proxyEnv: {},
+        },
+        attestationPath: '',
+        attestation: null,
+        attestationFresh: false,
+    };
+}
+export async function resolveBoundaryDriverContext(params) {
+    const driverId = params.driverId ?? params.config.capability?.boundaryDriver ?? 'host-integration';
+    let proxyActive = params.egressProxyRunning === true;
+    if (params.egressProxyRunning === undefined) {
+        const egress = await egressStatus({ targetDir: params.repoRoot });
+        proxyActive = isEgressProxyActive({
+            config: params.config,
+            running: egress.running,
+            foreignProxy: egress.foreignProxy,
+            repoRootMismatch: egress.repoRootMismatch,
+        });
+    }
+    const proxyEnv = resolveBoundaryEgressProxyEnv({
+        driverId,
+        config: params.config,
+        proxyActive,
+    });
+    const driver = getDefaultBoundaryDriver(driverId, {
+        egressProxyEnv: proxyEnv,
+        repoRoot: params.repoRoot,
+    });
+    const attestationPath = boundaryAttestationPath(params.repoRoot, params.config);
+    const attestation = await loadBoundaryAttestation(attestationPath, params.repoRoot, configuredControlPlaneDir(params.config));
+    return {
+        driver,
+        driverId,
+        proxyActive,
+        proxyEnv,
+        prepareContext: {
+            repoRoot: params.repoRoot,
+            egressProxyActive: proxyActive,
+            proxyEnv,
+        },
+        attestationPath,
+        attestation,
+        attestationFresh: attestation ? isAttestationFresh(attestation) : false,
+    };
+}
+export async function runWithBoundaryDriver(params) {
+    return runWithBoundaryRunnable(params.context.driver, {
+        prepareContext: params.context.prepareContext,
+        command: params.command,
+        cwd: params.cwd,
+        timeoutMs: params.timeoutMs,
+        runOptions: params.runOptions,
+    });
+}
+export async function startBoundarySession(params) {
+    const resolved = await resolveBoundaryDriverContext(params);
+    const attestation = await resolved.driver.probe();
+    if (resolved.driver.prepare) {
+        await resolved.driver.prepare(resolved.prepareContext);
+    }
+    const attestationPath = boundaryAttestationPath(params.repoRoot, params.config);
+    await saveBoundaryAttestation(attestationPath, attestation, params.repoRoot, configuredControlPlaneDir(params.config));
+    return { attestation, attestationPath };
+}
+export async function boundarySessionStatus(params) {
+    const attestationPath = boundaryAttestationPath(params.repoRoot, params.config);
+    const attestation = await loadBoundaryAttestation(attestationPath, params.repoRoot, configuredControlPlaneDir(params.config));
+    return {
+        attestationPath,
+        attestation,
+        fresh: attestation ? isAttestationFresh(attestation) : false,
+    };
+}
+export async function runBoundaryAgentCommand(params) {
+    const context = await resolveBoundaryDriverContext({
+        repoRoot: params.repoRoot,
+        config: params.config,
+    });
+    return runWithBoundaryDriver({
+        context,
+        command: params.command,
+        cwd: params.cwd ?? params.repoRoot,
+        timeoutMs: params.timeoutMs ?? 30 * 60_000,
+        runOptions: params.runOptions,
+    });
+}
+export { dockerNetworkArgs };

package/dist/core/capability/boundary-workspace-mount.d.ts

@@ -0,0 +1,5 @@
+import type { BoundaryWorkspaceMount } from './boundary-run.js';
+export declare function validateWorkspaceMount(mount: BoundaryWorkspaceMount): void;
+export declare function resolveGuestWorkdir(mount: BoundaryWorkspaceMount): string;
+export declare function buildWorkspaceMountSpec(mount: BoundaryWorkspaceMount): string;
+export declare function workspaceMountEnvArgs(mount: BoundaryWorkspaceMount): string[];

package/dist/core/capability/boundary-workspace-mount.js

@@ -0,0 +1,68 @@
+import path from 'node:path';
+import { canonicalPath, pathWithinRoot } from '../path-utils.js';
+const HOST_PATH_ENV_VARS = [
+    'BELAY_EGRESS_REPO_ROOT',
+    'BELAY_JUDGE_BROKER_REPO_ROOT',
+    'BELAY_JUDGE_BROKER_STATE_DIR',
+    'BELAY_REPO_ROOT',
+];
+export function validateWorkspaceMount(mount) {
+    const hostSourceRoot = canonicalPath(mount.hostSourceRoot);
+    const guestTargetRoot = canonicalPath(mount.guestTargetRoot);
+    if (!hostSourceRoot || !guestTargetRoot) {
+        throw new Error('boundary_workspace_mount_invalid_root');
+    }
+    if (hostSourceRoot.includes(',') || guestTargetRoot.includes(',')) {
+        throw new Error('boundary_workspace_mount_invalid_root');
+    }
+    if (hostSourceRoot === guestTargetRoot) {
+        throw new Error('boundary_workspace_mount_source_equals_target');
+    }
+    if (pathWithinRoot(hostSourceRoot, guestTargetRoot)) {
+        throw new Error('boundary_workspace_mount_source_contains_target');
+    }
+    if (mount.cwdRelative.includes('\0')) {
+        throw new Error('boundary_workspace_mount_invalid_cwd');
+    }
+    const normalizedRelative = path.posix.normalize(mount.cwdRelative.replace(/\\/g, '/'));
+    if (normalizedRelative === '..' || normalizedRelative.startsWith('../')) {
+        throw new Error('boundary_workspace_mount_invalid_cwd');
+    }
+    if (path.posix.isAbsolute(normalizedRelative)) {
+        throw new Error('boundary_workspace_mount_invalid_cwd');
+    }
+}
+export function resolveGuestWorkdir(mount) {
+    validateWorkspaceMount(mount);
+    const guestTargetRoot = canonicalPath(mount.guestTargetRoot);
+    const normalizedRelative = path.posix.normalize(mount.cwdRelative.replace(/\\/g, '/'));
+    if (normalizedRelative === '.' || normalizedRelative === '') {
+        return guestTargetRoot;
+    }
+    const segments = normalizedRelative.split('/').filter(Boolean);
+    return path.posix.join(guestTargetRoot, ...segments);
+}
+export function buildWorkspaceMountSpec(mount) {
+    validateWorkspaceMount(mount);
+    const hostSourceRoot = canonicalPath(mount.hostSourceRoot);
+    const guestTargetRoot = canonicalPath(mount.guestTargetRoot);
+    const readonly = mount.writable ? '' : ',readonly';
+    return `type=bind,src=${hostSourceRoot},dst=${guestTargetRoot}${readonly}`;
+}
+export function workspaceMountEnvArgs(mount) {
+    const workdir = resolveGuestWorkdir(mount);
+    if (!mount.hideHostSourcePath) {
+        return ['-e', `PWD=${workdir}`];
+    }
+    const guestTargetRoot = canonicalPath(mount.guestTargetRoot);
+    const hostSourceRoot = canonicalPath(mount.hostSourceRoot);
+    const args = [];
+    for (const key of HOST_PATH_ENV_VARS) {
+        args.push('-e', `${key}=`);
+    }
+    args.push('-e', `PWD=${workdir}`, '-e', `OLDPWD=${workdir}`, '-e', `BELAY_REPO_ROOT=${guestTargetRoot}`);
+    if (hostSourceRoot !== guestTargetRoot) {
+        args.push('-e', `BELAY_EGRESS_REPO_ROOT=${guestTargetRoot}`);
+    }
+    return args;
+}

package/dist/core/capability/capability-request-hash.d.ts

@@ -0,0 +1,2 @@
+import type { CapabilityRequestV1 } from './request.js';
+export declare function hashCapabilityRequests(requests: CapabilityRequestV1[]): string;

package/dist/core/capability/capability-request-hash.js

@@ -0,0 +1,8 @@
+import { canonicalStringify, hashValue } from '../fingerprint.js';
+export function hashCapabilityRequests(requests) {
+    if (requests.length === 0) {
+        return '';
+    }
+    const normalized = [...requests].sort((left, right) => canonicalStringify(left).localeCompare(canonicalStringify(right)));
+    return hashValue(`capability-requests:v1:${canonicalStringify(normalized)}`);
+}

package/dist/core/capability/gate-latency-ratchet.d.ts

@@ -0,0 +1,7 @@
+import { GATE_LATENCY_BUDGET } from '../../corpus/gate-latency-budget.js';
+export type GateLatencyKind = keyof typeof GATE_LATENCY_BUDGET;
+/**
+ * Advisory warnings when CI budgets still exceed PLAN acceptance targets.
+ * Surfaced via sandbox status `advisories` and doctor warnings — not `issues` or gate exit codes.
+ */
+export declare function evaluateGateLatencyRatchetAdvisories(): string[];

package/dist/core/capability/gate-latency-ratchet.js

@@ -0,0 +1,18 @@
+import { GATE_LATENCY_BUDGET, GATE_LATENCY_PLAN_TARGET } from '../../corpus/gate-latency-budget.js';
+/**
+ * Advisory warnings when CI budgets still exceed PLAN acceptance targets.
+ * Surfaced via sandbox status `advisories` and doctor warnings — not `issues` or gate exit codes.
+ */
+export function evaluateGateLatencyRatchetAdvisories() {
+    const warnings = [];
+    for (const kind of Object.keys(GATE_LATENCY_BUDGET)) {
+        const budget = GATE_LATENCY_BUDGET[kind];
+        if (budget.p95Ms > GATE_LATENCY_PLAN_TARGET.p95Ms) {
+            warnings.push(`Gate ${kind} p95 CI budget ${budget.p95Ms}ms exceeds PLAN target ${GATE_LATENCY_PLAN_TARGET.p95Ms}ms — tighten via quality-loop ratchet.`);
+        }
+        if (budget.maxMs > GATE_LATENCY_PLAN_TARGET.maxMs) {
+            warnings.push(`Gate ${kind} max CI budget ${budget.maxMs}ms exceeds PLAN target ${GATE_LATENCY_PLAN_TARGET.maxMs}ms — tighten via quality-loop ratchet.`);
+        }
+    }
+    return warnings;
+}

package/dist/core/capability/gate-policy-shadow.d.ts

@@ -0,0 +1,25 @@
+import type { BelayConfigV4 } from '../config.js';
+import type { ClassifyResult } from '../types.js';
+import type { JudgeProviderId } from '../verdict/judge-catalog.js';
+import type { Tier1Verdict } from '../verdict/types.js';
+export { recordGateApprovalAsk } from './gate-shadow-ratchet.js';
+export declare function capabilityDecisionAuditFields(result: ClassifyResult): Record<string, unknown>;
+export declare function policyWouldBlock(result: ClassifyResult): boolean;
+export declare function judgeWouldBlock(verdict: Tier1Verdict): boolean;
+export declare function policyJudgeMismatch(result: ClassifyResult, judgeVerdict: Tier1Verdict): boolean;
+export declare function scheduleGateShadowAudit(params: {
+    repoRoot: string;
+    config: BelayConfigV4;
+    providerId: string;
+    result: ClassifyResult;
+    command?: string;
+    stateDir?: string;
+}): Record<string, unknown>;
+export declare function runGatePolicyShadowComparison(params: {
+    repoRoot: string;
+    config: BelayConfigV4;
+    providerId: Exclude<JudgeProviderId, 'ollama'>;
+    command: string;
+    result: ClassifyResult;
+    stateDir?: string;
+}): Promise<void>;

package/dist/core/capability/gate-policy-shadow.js

@@ -0,0 +1,130 @@
+import path from 'node:path';
+import { belayStateDir } from '../config.js';
+import { effectPlanAuditFields } from '../effect-ir/audit.js';
+import { buildTier1Prompt } from '../verdict/judge.js';
+import { normalizeJudgeRuntimeConfig } from '../verdict/judge-runtime-config.js';
+import { judgeShadowAuditFields, recordShadowComparison, shouldRunShadowComparison, triggerJudgeSessionKillSwitch, } from '../verdict/judge-shadow.js';
+import { evaluateWithJudgeTransport } from '../verdict/judge-transport.js';
+import { recordPolicyJudgeComparison } from './gate-shadow-ratchet.js';
+export { recordGateApprovalAsk } from './gate-shadow-ratchet.js';
+export function capabilityDecisionAuditFields(result) {
+    const fields = {
+        ...effectPlanAuditFields(result.effectPlan, {
+            capabilityRequests: result.capabilityRequests,
+            decisions: result.effectPlanPolicyDecisions,
+            authorizationDecision: result.authorizationDecision,
+        }),
+        executionRoute: 'downstream_host',
+        enforcementStatus: 'prediction_only',
+        boundaryEnforcement: 'prediction_only',
+    };
+    if (result.capabilityRequests?.length) {
+        fields.capabilityRequestCount = result.capabilityRequests.length;
+        fields.capabilityActions = result.capabilityRequests.map((request) => request.action);
+    }
+    if (result.authorizationDecision) {
+        fields.policyOutcome = result.authorizationDecision.outcome;
+        fields.policyReason = result.authorizationDecision.reason;
+        if (result.authorizationDecision.matchedRule) {
+            fields.policyMatchedRule = result.authorizationDecision.matchedRule;
+        }
+    }
+    const decisions = result.effectPlanPolicyDecisions ?? [];
+    if (decisions.length > 0 &&
+        decisions.every((decision) => decision.matchedRule === 'boundary.verified')) {
+        fields.authorizationMode = 'boundary_policy';
+    }
+    else if (decisions.length > 0 &&
+        decisions.every((decision) => decision.matchedRule === 'grant.exact')) {
+        fields.authorizationMode = 'exact_grant';
+    }
+    else {
+        fields.authorizationMode = result.authorizationDecision ? 'policy_decision' : 'none';
+    }
+    if (result.boundaryProfile) {
+        fields.boundaryProfile = result.boundaryProfile;
+    }
+    if (result.authorizationDecision?.signals.includes('boundary_materialized_grant')) {
+        fields.boundaryGrantMaterialized = true;
+    }
+    return fields;
+}
+export function policyWouldBlock(result) {
+    const outcome = result.authorizationDecision?.outcome;
+    if (outcome === 'allow') {
+        return false;
+    }
+    if (outcome === 'require_approval' || outcome === 'deny') {
+        return true;
+    }
+    return result.verdict === 'deny_pending_approval';
+}
+export function judgeWouldBlock(verdict) {
+    return !verdict.local_recoverable || verdict.destroys_history_or_secrets === true;
+}
+export function policyJudgeMismatch(result, judgeVerdict) {
+    return policyWouldBlock(result) !== judgeWouldBlock(judgeVerdict);
+}
+function queueDeferredGatePolicyShadow(params) {
+    setImmediate(() => {
+        void runGatePolicyShadowComparison(params).catch(() => { });
+    });
+}
+export function scheduleGateShadowAudit(params) {
+    const trace = capabilityDecisionAuditFields(params.result);
+    const judge = params.config.judge;
+    const mode = judge?.mode ?? 'shadow';
+    if (mode !== 'shadow' || !judge.runtime?.shadow?.enabled) {
+        return trace;
+    }
+    const deferredTrace = {
+        ...trace,
+        ...judgeShadowAuditFields(params.repoRoot),
+        judgeShadowScheduled: false,
+        judgeShadowDeferred: true,
+    };
+    const command = params.command?.trim();
+    if (!command ||
+        params.providerId === 'ollama' ||
+        !shouldRunShadowComparison(params.repoRoot, params.providerId, judge.runtime.shadow)) {
+        return deferredTrace;
+    }
+    queueDeferredGatePolicyShadow({
+        repoRoot: params.repoRoot,
+        config: params.config,
+        providerId: params.providerId,
+        command,
+        result: params.result,
+        stateDir: params.stateDir,
+    });
+    return {
+        ...deferredTrace,
+        judgeShadowQueued: true,
+    };
+}
+export async function runGatePolicyShadowComparison(params) {
+    const judge = params.config.judge;
+    const runtime = normalizeJudgeRuntimeConfig(judge.runtime);
+    const stateDir = params.stateDir ?? belayStateDir(params.config, path.join(params.repoRoot, '.belay'));
+    const transport = await evaluateWithJudgeTransport({
+        prompt: buildTier1Prompt(params.command),
+        context: {
+            providerId: params.providerId,
+            model: judge.model ?? 'default',
+            repoRoot: params.repoRoot,
+            stateDir,
+            judgeMode: judge.mode ?? 'shadow',
+            runtime,
+            judgeTimeoutMs: judge.timeoutMs ?? 25_000,
+        },
+    }, { skipTransportShadow: true, spawnOnly: true });
+    if (!transport.verdict) {
+        return;
+    }
+    const mismatch = policyJudgeMismatch(params.result, transport.verdict);
+    const shadow = recordShadowComparison(params.repoRoot, runtime.shadow, mismatch);
+    await recordPolicyJudgeComparison(params.repoRoot, stateDir, mismatch);
+    if (shadow.killSwitchTriggered) {
+        await triggerJudgeSessionKillSwitch(params.repoRoot, stateDir);
+    }
+}

package/dist/core/capability/gate-shadow-audit.d.ts

@@ -0,0 +1 @@
+export { capabilityDecisionAuditFields, judgeWouldBlock, policyJudgeMismatch, policyWouldBlock, recordGateApprovalAsk, runGatePolicyShadowComparison, scheduleGateShadowAudit, } from './gate-policy-shadow.js';

package/dist/core/capability/gate-shadow-audit.js

@@ -0,0 +1 @@
+export { capabilityDecisionAuditFields, judgeWouldBlock, policyJudgeMismatch, policyWouldBlock, recordGateApprovalAsk, runGatePolicyShadowComparison, scheduleGateShadowAudit, } from './gate-policy-shadow.js';

package/dist/core/capability/gate-shadow-ratchet.d.ts

@@ -0,0 +1,14 @@
+export interface GateShadowRatchetState {
+    version: 1;
+    policyJudgeComparisons: number;
+    policyJudgeMismatches: number;
+    approvalByReason: Record<string, {
+        asks: number;
+        approved: number;
+    }>;
+    updatedAt: string;
+}
+export declare function recordPolicyJudgeComparison(repoRoot: string, stateDir: string, mismatch: boolean): Promise<void>;
+export declare function recordGateApprovalAsk(stateDir: string, reason: string, approved: boolean): Promise<void>;
+export declare function evaluateShadowRatchetWarnings(state: GateShadowRatchetState): string[];
+export declare function loadShadowRatchetWarnings(stateDir: string): Promise<string[]>;

package/dist/core/capability/gate-shadow-ratchet.js

@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const DEFAULT_STATE = {
+    version: 1,
+    policyJudgeComparisons: 0,
+    policyJudgeMismatches: 0,
+    approvalByReason: {},
+    updatedAt: new Date(0).toISOString(),
+};
+const MISMATCH_RATE_THRESHOLD = 0.25;
+const APPROVAL_RATE_THRESHOLD = 0.5;
+const MIN_SAMPLES = 10;
+function ratchetPath(stateDir) {
+    return path.join(stateDir, 'gate-shadow-ratchet.json');
+}
+async function loadState(stateDir) {
+    const filePath = ratchetPath(stateDir);
+    if (!existsSync(filePath)) {
+        return { ...DEFAULT_STATE, updatedAt: new Date().toISOString() };
+    }
+    try {
+        const raw = JSON.parse(await readFile(filePath, 'utf8'));
+        return {
+            ...DEFAULT_STATE,
+            ...raw,
+            approvalByReason: raw.approvalByReason ?? {},
+        };
+    }
+    catch {
+        return { ...DEFAULT_STATE, updatedAt: new Date().toISOString() };
+    }
+}
+async function saveState(stateDir, state) {
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
+    await writeFile(ratchetPath(stateDir), `${JSON.stringify({ ...state, updatedAt: new Date().toISOString() }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+export async function recordPolicyJudgeComparison(repoRoot, stateDir, mismatch) {
+    void repoRoot;
+    const state = await loadState(stateDir);
+    state.policyJudgeComparisons += 1;
+    if (mismatch) {
+        state.policyJudgeMismatches += 1;
+    }
+    await saveState(stateDir, state);
+}
+export async function recordGateApprovalAsk(stateDir, reason, approved) {
+    const state = await loadState(stateDir);
+    const entry = state.approvalByReason[reason] ?? { asks: 0, approved: 0 };
+    if (approved) {
+        entry.approved += 1;
+    }
+    else {
+        entry.asks += 1;
+    }
+    state.approvalByReason[reason] = entry;
+    await saveState(stateDir, state);
+}
+export function evaluateShadowRatchetWarnings(state) {
+    const warnings = [];
+    if (state.policyJudgeComparisons >= MIN_SAMPLES) {
+        const rate = state.policyJudgeMismatches / state.policyJudgeComparisons;
+        if (rate > MISMATCH_RATE_THRESHOLD) {
+            warnings.push(`Policy/judge shadow mismatch rate ${(rate * 100).toFixed(0)}% exceeds ${(MISMATCH_RATE_THRESHOLD * 100).toFixed(0)}% threshold (${state.policyJudgeMismatches}/${state.policyJudgeComparisons}).`);
+        }
+    }
+    for (const [reason, counts] of Object.entries(state.approvalByReason)) {
+        if (counts.asks < MIN_SAMPLES) {
+            continue;
+        }
+        const approvalRate = counts.approved / counts.asks;
+        if (approvalRate >= APPROVAL_RATE_THRESHOLD) {
+            warnings.push(`High approval rate for "${reason}": ${(approvalRate * 100).toFixed(0)}% (${counts.approved}/${counts.asks}). Consider tightening policy.`);
+        }
+    }
+    return warnings;
+}
+export async function loadShadowRatchetWarnings(stateDir) {
+    const state = await loadState(stateDir);
+    return evaluateShadowRatchetWarnings(state);
+}

package/dist/core/capability/grant-consumption.d.ts

@@ -0,0 +1,4 @@
+import type { ClassifyResult } from '../types.js';
+export declare function capabilityGrantLeaseRequired(result: Pick<ClassifyResult, 'reason' | 'authorizationDecision'>): boolean;
+/** Fail closed when a grant lease is required but capability requests are missing. */
+export declare function canConsumeCapabilityGrantLease(result: ClassifyResult): boolean;

package/dist/core/capability/grant-consumption.js

@@ -0,0 +1,11 @@
+export function capabilityGrantLeaseRequired(result) {
+    return (result.reason === 'capability_grant' ||
+        result.authorizationDecision?.matchedRule === 'grant.exact');
+}
+/** Fail closed when a grant lease is required but capability requests are missing. */
+export function canConsumeCapabilityGrantLease(result) {
+    if (!capabilityGrantLeaseRequired(result)) {
+        return true;
+    }
+    return (result.capabilityRequests?.length ?? 0) > 0;
+}

package/dist/core/capability/grant-lease.d.ts

@@ -0,0 +1,44 @@
+import type { ApprovalRecord, ApprovalStateFile } from '../types.js';
+import type { CapabilityGrantV1 } from './grant.js';
+import type { CapabilityRequestV1 } from './request.js';
+export type GrantBundleValidationFailureReason = 'legacy_record' | 'empty_requests' | 'cardinality_mismatch' | 'grant_scope_too_broad' | 'grant_inactive' | 'grant_mismatch';
+export type GrantBundleValidationResult = {
+    ok: true;
+    approval: ApprovalRecord;
+} | {
+    ok: false;
+    reason: GrantBundleValidationFailureReason;
+};
+export declare function grantsFromApproval(approval: {
+    grant?: CapabilityGrantV1;
+    grants?: CapabilityGrantV1[];
+}): CapabilityGrantV1[];
+export declare function approvalGrantBundleExhausted(approval: {
+    grant?: CapabilityGrantV1;
+    grants?: CapabilityGrantV1[];
+}): boolean;
+export declare function consumeApprovalGrantBundle(approval: ApprovalRecord, requests: readonly CapabilityRequestV1[]): {
+    approval: ApprovalRecord;
+    consumed: boolean;
+};
+/** Validate and consume a marked exact bundle without mutating on any failure. */
+export declare function validateAndConsumeGrantBundle(approval: ApprovalRecord, requests: readonly CapabilityRequestV1[], now?: number): GrantBundleValidationResult;
+/** Revalidate a marked bundle during an active replay lease without consuming it twice. */
+export declare function validateGrantBundleForLeaseReuse(approval: ApprovalRecord, requests: readonly CapabilityRequestV1[], now?: number): GrantBundleValidationResult;
+/** Consume every grant in an approved record after fingerprint/hash replay validation. */
+export declare function consumeApprovedRecordGrantBundle(approval: ApprovalRecord): {
+    approval: ApprovalRecord;
+    consumed: boolean;
+};
+export declare function decrementApprovalLegacyGrant(approval: ApprovalRecord): ApprovalRecord;
+export declare function grantsFromApprovedState(state: ApprovalStateFile, repoRoot: string): CapabilityGrantV1[];
+export declare function consumeGrantLease(state: ApprovalStateFile, grantId: string): {
+    state: ApprovalStateFile;
+    consumed: boolean;
+};
+/** Consume one lease for each request; all must succeed (atomic bundle consumption). */
+export declare function consumeGrantLeasesForRequests(state: ApprovalStateFile, requests: CapabilityRequestV1[]): {
+    state: ApprovalStateFile;
+    consumed: boolean;
+};
+export declare function findMatchingGrant(grants: CapabilityGrantV1[] | undefined, request: CapabilityRequestV1): CapabilityGrantV1 | undefined;