@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/core/config.js

@@ -3,6 +3,7 @@ import { warnDeprecatedJudgeModelAuto } from './judge-model-policy.js';
 import { getJudgeProviderSpec, inferProviderIdFromConfig, isRemovedProviderId, normalizeLegacyProviderId, warnRemovedProviderId, } from './verdict/judge-catalog.js';
 import { normalizeJudgeRuntimeConfig, } from './verdict/judge-runtime-config.js';
 export const DEFAULT_JUDGE_LOCAL_OLLAMA = {
+    mode: 'shadow',
     provider: 'ollama',
     providerId: 'ollama',
     model: 'gemma4:e2b',
@@ -11,6 +12,7 @@ export const DEFAULT_JUDGE_LOCAL_OLLAMA = {
     keepAlive: '30m',
 };
 export const DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE = {
+    mode: 'shadow',
     provider: 'openai-compatible',
     providerId: 'codex',
     model: 'gpt-5.3-codex-high',
@@ -20,6 +22,23 @@ export const DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE = {
 };
 /** @deprecated Use DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE */
 export const DEFAULT_JUDGE_CURSOR_COMPOSER = DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE;
+export const DEFAULT_CAPABILITY_V5 = {
+    grantsEnabled: true,
+    boundaryDriver: 'host-integration',
+    attestationRelPath: '.belay/attestation.json',
+};
+function normalizeCapabilityConfig(capability) {
+    if (!capability) {
+        return undefined;
+    }
+    return {
+        ...DEFAULT_CAPABILITY_V5,
+        ...capability,
+        grantsEnabled: capability.grantsEnabled !== false,
+        boundaryDriver: capability.boundaryDriver ?? DEFAULT_CAPABILITY_V5.boundaryDriver,
+        attestationRelPath: capability.attestationRelPath ?? DEFAULT_CAPABILITY_V5.attestationRelPath,
+    };
+}
 /** Pre-v0.4 defaults preserved when migrating existing v1/v2/v3 configs. */
 import { DEFAULT_SILENT_PASS_THRESHOLD } from './audit-summary.js';
 /** @deprecated Use DEFAULT_SILENT_PASS_THRESHOLD from audit-summary.js */
@@ -32,6 +51,46 @@ export const DEFAULT_MODEL_ASSIST = {
     enabled: false,
     timeoutMs: 3000,
 };
+export const DEFAULT_FILE_CHECKPOINT = {
+    enabled: false,
+    allowNonGit: false,
+    maxFiles: 100_000,
+    maxSourceBytes: 2_147_483_648,
+    maxWorkspaceBytes: 4_294_967_296,
+    prepareTimeoutMs: 30_000,
+    copyConcurrency: 8,
+};
+function clampCopyConcurrency(value) {
+    return Math.min(32, Math.max(1, Math.floor(value)));
+}
+export function normalizeFileCheckpointConfig(raw) {
+    return {
+        enabled: raw?.enabled === true,
+        allowNonGit: raw?.allowNonGit === true,
+        maxFiles: typeof raw?.maxFiles === 'number' && raw.maxFiles > 0
+            ? Math.floor(raw.maxFiles)
+            : DEFAULT_FILE_CHECKPOINT.maxFiles,
+        maxSourceBytes: typeof raw?.maxSourceBytes === 'number' && raw.maxSourceBytes > 0
+            ? Math.floor(raw.maxSourceBytes)
+            : DEFAULT_FILE_CHECKPOINT.maxSourceBytes,
+        maxWorkspaceBytes: typeof raw?.maxWorkspaceBytes === 'number' && raw.maxWorkspaceBytes > 0
+            ? Math.floor(raw.maxWorkspaceBytes)
+            : DEFAULT_FILE_CHECKPOINT.maxWorkspaceBytes,
+        prepareTimeoutMs: typeof raw?.prepareTimeoutMs === 'number' && raw.prepareTimeoutMs > 0
+            ? Math.floor(raw.prepareTimeoutMs)
+            : DEFAULT_FILE_CHECKPOINT.prepareTimeoutMs,
+        copyConcurrency: typeof raw?.copyConcurrency === 'number' && raw.copyConcurrency > 0
+            ? clampCopyConcurrency(raw.copyConcurrency)
+            : DEFAULT_FILE_CHECKPOINT.copyConcurrency,
+    };
+}
+export const DEFAULT_RECOVERY_CHECKPOINT = {
+    enabled: false,
+    appliedRetentionHours: 7 * 24,
+    restoredRetentionHours: 24,
+    maxCheckpoints: 20,
+    maxBytes: 1024 * 1024 * 1024,
+};
 export const DEFAULT_TRANSACTIONAL_V3 = {
     enabled: false,
     minConfidence: DEFAULT_CONFIDENCE_THRESHOLDS.flag,
@@ -41,6 +100,8 @@ export const DEFAULT_TRANSACTIONAL_V3 = {
     gates: {
         shell: true,
     },
+    fileCheckpoint: { ...DEFAULT_FILE_CHECKPOINT },
+    checkpoint: { ...DEFAULT_RECOVERY_CHECKPOINT },
 };
 export const LEGACY_POLICY_V3 = {
     unknownLocalEffect: 'allow_flagged',
@@ -222,7 +283,8 @@ export function isConfigV3(value) {
     return version === 3 || version === 4;
 }
 export function isConfigV4(value) {
-    return typeof value === 'object' && value !== null && value.version === 4;
+    const version = typeof value === 'object' && value !== null ? value.version : null;
+    return version === 4 || version === 5;
 }
 export function normalizeJudgeProvider(provider) {
     if (provider === 'anthropic') {
@@ -239,6 +301,7 @@ function defaultJudgeTemplateForProvider(provider) {
     }
     if (provider === 'anthropic') {
         return {
+            mode: 'shadow',
             provider: 'anthropic',
             providerId: 'claude',
             model: 'claude-sonnet-4-6',
@@ -283,6 +346,7 @@ export function normalizeJudgeConfig(judge) {
         const timeoutMs = typeof judge.timeoutMs === 'number' && judge.timeoutMs > 0 ? judge.timeoutMs : base.timeoutMs;
         const endpoint = typeof judge.endpoint === 'string' && judge.endpoint.trim() ? judge.endpoint.trim() : null;
         return {
+            mode: judge.mode === 'off' ? 'off' : 'shadow',
             provider,
             providerId: rawProviderId,
             model,
@@ -320,6 +384,7 @@ export function normalizeJudgeConfig(judge) {
         endpoint = catalogSpec.defaultEndpoint;
     }
     const normalized = {
+        mode: judge.mode === 'off' ? 'off' : 'shadow',
         provider,
         providerId,
         model,
@@ -490,6 +555,19 @@ function normalizeV3Raw(raw) {
         },
     });
 }
+function normalizeV5Raw(raw) {
+    const base = normalizeV3Raw({ ...raw, version: 4 });
+    return {
+        ...base,
+        version: 5,
+        capability: {
+            grantsEnabled: raw.capability?.grantsEnabled !== false,
+            boundaryDriver: raw.capability?.boundaryDriver ?? 'host-integration',
+            attestationRelPath: raw.capability?.attestationRelPath ?? '.belay/attestation.json',
+            ...(raw.capability ?? {}),
+        },
+    };
+}
 export function migrateConfig(loaded) {
     if (typeof loaded !== 'object' || loaded === null) {
         return { ...DEFAULT_CONFIG_V4 };
@@ -498,6 +576,9 @@ export function migrateConfig(loaded) {
     if (raw.version === 4) {
         return normalizeV3Raw(raw);
     }
+    if (raw.version === 5) {
+        return normalizeV5Raw(raw);
+    }
     if (raw.version === 3 || (raw.version === undefined && hasV3Sections(raw))) {
         return normalizeV3Raw(raw);
     }
@@ -576,8 +657,9 @@ export function normalizeConfig(config) {
         return normalizeConfigV2(config);
     }
     const v4 = config;
-    return {
-        version: 4,
+    const version = v4.version === 5 ? 5 : 4;
+    const normalized = {
+        version,
         ...(v4.installScope === 'global' || v4.installScope === 'project'
             ? { installScope: v4.installScope }
             : {}),
@@ -656,6 +738,26 @@ export function normalizeConfig(config) {
                     gates: {
                         shell: v4.policy?.transactional?.gates?.shell !== false,
                     },
+                    fileCheckpoint: normalizeFileCheckpointConfig(v4.policy?.transactional?.fileCheckpoint),
+                    checkpoint: {
+                        enabled: v4.policy?.transactional?.checkpoint?.enabled === true,
+                        appliedRetentionHours: typeof v4.policy?.transactional?.checkpoint?.appliedRetentionHours === 'number' &&
+                            v4.policy.transactional.checkpoint.appliedRetentionHours > 0
+                            ? v4.policy.transactional.checkpoint.appliedRetentionHours
+                            : DEFAULT_RECOVERY_CHECKPOINT.appliedRetentionHours,
+                        restoredRetentionHours: typeof v4.policy?.transactional?.checkpoint?.restoredRetentionHours === 'number' &&
+                            v4.policy.transactional.checkpoint.restoredRetentionHours > 0
+                            ? v4.policy.transactional.checkpoint.restoredRetentionHours
+                            : DEFAULT_RECOVERY_CHECKPOINT.restoredRetentionHours,
+                        maxCheckpoints: typeof v4.policy?.transactional?.checkpoint?.maxCheckpoints === 'number' &&
+                            v4.policy.transactional.checkpoint.maxCheckpoints > 0
+                            ? Math.floor(v4.policy.transactional.checkpoint.maxCheckpoints)
+                            : DEFAULT_RECOVERY_CHECKPOINT.maxCheckpoints,
+                        maxBytes: typeof v4.policy?.transactional?.checkpoint?.maxBytes === 'number' &&
+                            v4.policy.transactional.checkpoint.maxBytes > 0
+                            ? Math.floor(v4.policy.transactional.checkpoint.maxBytes)
+                            : DEFAULT_RECOVERY_CHECKPOINT.maxBytes,
+                    },
                 };
             })(),
         },
@@ -743,6 +845,10 @@ export function normalizeConfig(config) {
         },
         judge: normalizeJudgeConfig(v4.judge ?? DEFAULT_JUDGE_LOCAL_OLLAMA),
     };
+    if (version === 5 || v4.capability) {
+        normalized.capability = normalizeCapabilityConfig(v4.capability ?? DEFAULT_CAPABILITY_V5);
+    }
+    return normalized;
 }
 export function isFreshConfigInput(loaded) {
     if (loaded === null || loaded === undefined) {
@@ -814,6 +920,15 @@ export function mergeConfig(existing, defaults = DEFAULT_CONFIG_V4) {
             ...migrated.audit,
         },
         ...(migrated.installScope ? { installScope: migrated.installScope } : {}),
+        ...(migrated.version === 5 || migrated.capability
+            ? {
+                version: migrated.version === 5 ? 5 : 4,
+                capability: normalizeCapabilityConfig({
+                    ...DEFAULT_CAPABILITY_V5,
+                    ...migrated.capability,
+                }),
+            }
+            : {}),
     });
 }
 export function scrubOptionsFromConfig(config) {

package/dist/core/effect-ir/audit.d.ts

@@ -0,0 +1,9 @@
+import type { PolicyDecision } from '../capability/policy-types.js';
+import type { CapabilityRequestV1 } from '../capability/request.js';
+import type { EffectPlan } from './types.js';
+export declare function hashEffectPlan(plan: EffectPlan): string;
+export declare function effectPlanAuditFields(plan: EffectPlan | undefined, policy?: {
+    capabilityRequests?: readonly CapabilityRequestV1[];
+    decisions?: readonly PolicyDecision[];
+    authorizationDecision?: PolicyDecision;
+}): Record<string, unknown>;

package/dist/core/effect-ir/audit.js

@@ -0,0 +1,86 @@
+import { canonicalStringify, hashValue } from '../fingerprint.js';
+import { collectRequirements } from './build.js';
+function auditableProvenance(provenance) {
+    return {
+        ...(provenance.segment ? { segment: provenance.segment } : {}),
+        ...(provenance.launcher ? { launcher: provenance.launcher } : {}),
+        ...(provenance.phase ? { phase: provenance.phase } : {}),
+    };
+}
+function auditableResource(resource) {
+    if (resource.kind === 'executable') {
+        return {
+            kind: 'executable',
+            commandHash: hashValue(resource.command),
+        };
+    }
+    return resource;
+}
+export function hashEffectPlan(plan) {
+    const requirements = collectRequirements(plan.root)
+        .map((requirement) => ({
+        tag: requirement.tag,
+        action: requirement.action,
+        resource: auditableResource(requirement.resource),
+        evidence: {
+            level: requirement.evidence.level,
+            signals: [...requirement.evidence.signals].sort(),
+            basis: [...requirement.evidence.basis].sort(),
+        },
+        provenance: requirement.provenance,
+        provenances: [...(requirement.provenances ?? [requirement.provenance])].sort((left, right) => canonicalStringify(left).localeCompare(canonicalStringify(right))),
+    }))
+        .sort((left, right) => canonicalStringify(left).localeCompare(canonicalStringify(right)));
+    return hashValue(`effect-plan:v1:${canonicalStringify({
+        version: plan.version,
+        inputFingerprint: plan.inputFingerprint,
+        opacity: plan.opacity,
+        disposition: plan.disposition,
+        completeness: plan.completeness,
+        signals: [...plan.signals].sort(),
+        requirements,
+    })}`);
+}
+export function effectPlanAuditFields(plan, policy) {
+    if (!plan) {
+        return {};
+    }
+    const fields = {
+        effectPlanVersion: plan.version,
+        effectIRHash: hashEffectPlan(plan),
+        effectPlanSignals: [...plan.signals],
+        effectPlanOpacity: plan.opacity,
+        effectPlanDisposition: plan.disposition,
+        effectPlanCompleteness: plan.completeness,
+        effectPlanRequirements: collectRequirements(plan.root).map((requirement) => ({
+            tag: requirement.tag,
+            action: requirement.action,
+            resource: auditableResource(requirement.resource),
+            evidence: requirement.evidence,
+            provenance: auditableProvenance(requirement.provenance),
+            provenances: (requirement.provenances ?? [requirement.provenance]).map((provenance) => auditableProvenance(provenance)),
+        })),
+    };
+    if (policy?.authorizationDecision) {
+        fields.effectPlanPolicyOutcome = policy.authorizationDecision.outcome;
+        fields.effectPlanPolicyReason = policy.authorizationDecision.reason;
+        if (policy.authorizationDecision.matchedRule) {
+            fields.effectPlanPolicyMatchedRule = policy.authorizationDecision.matchedRule;
+        }
+    }
+    if (policy?.capabilityRequests?.length) {
+        fields.effectPlanRequestActions = policy.capabilityRequests.map((request) => request.action);
+        fields.effectPlanRequestCount = policy.capabilityRequests.length;
+        if (policy.capabilityRequests.some((request) => request.evidence.signals.includes('package_cache_write'))) {
+            fields.effectPlanCacheWriteProjected = true;
+        }
+    }
+    if (policy?.decisions?.length) {
+        fields.effectPlanRequestDecisions = policy.decisions.map((decision) => ({
+            outcome: decision.outcome,
+            reason: decision.reason,
+            matchedRule: decision.matchedRule,
+        }));
+    }
+    return fields;
+}

package/dist/core/effect-ir/build.d.ts

@@ -0,0 +1,31 @@
+import type { CapabilityPrincipal, CapabilityRequestV1 } from '../capability/request.js';
+import type { LauncherResolution } from '../verdict/launcher-resolve.js';
+import type { EffectNode, EffectPlan, EffectRequirement, PackageExecLauncher } from './types.js';
+export interface BuildEffectPlanParams {
+    tokens: string[];
+    cwd: string;
+    repoRoot: string;
+    inputFingerprint: string;
+    launcherResolution?: LauncherResolution | null;
+    innerRequirements?: readonly EffectRequirement[];
+}
+export interface BuildCapabilityEffectPlanParams {
+    actionKind: 'shell' | 'tool' | 'subagent';
+    summary: string;
+    inputFingerprint: string;
+    requests: readonly CapabilityRequestV1[];
+    effectFree: boolean;
+}
+export declare function buildPackageExecEffectNode(params: BuildEffectPlanParams): EffectNode | null;
+export declare function collectRequirements(node: EffectNode): EffectRequirement[];
+export declare function buildEffectPlan(params: BuildEffectPlanParams): EffectPlan | null;
+/** Build the canonical plan envelope for non-package-exec gated actions. */
+export declare function buildCapabilityEffectPlan(params: BuildCapabilityEffectPlanParams): EffectPlan;
+export declare function flattenRequirementsToCapabilityRequests(requirements: readonly EffectRequirement[], opts: {
+    principal: CapabilityPrincipal;
+    cwd: string;
+    repoRoot: string;
+    hookKind: 'shell';
+    inputFingerprint: string;
+}): CapabilityRequestV1[];
+export type { PackageExecLauncher };

package/dist/core/effect-ir/build.js

@@ -0,0 +1,277 @@
+import { mergeRequirements } from './normalize.js';
+import { classifyPackageAcquisitionSpec, innerRecipeFromPeel, peelPackageExecArgv, resolveLocalBin, } from './package-exec.js';
+export function buildPackageExecEffectNode(params) {
+    const peel = peelPackageExecArgv(params.tokens);
+    if (!peel) {
+        return null;
+    }
+    const children = [];
+    const invokeNode = {
+        kind: 'launcher',
+        launcher: peel.launcher,
+        phase: 'invoke',
+        opaque: peel.opaque,
+        reason: peel.reason,
+        children: [],
+    };
+    children.push(invokeNode);
+    if (peel.opaque) {
+        children.push(acquireRequirement(peel, 'indeterminate'));
+        return { kind: 'merge', children };
+    }
+    if (peel.reason === 'npx_wrapper_readonly') {
+        return { kind: 'merge', children };
+    }
+    const innerRecipe = innerRecipeFromPeel(peel);
+    const binHead = peel.innerTokens[0] ?? '';
+    const local = !peel.forceAcquire ? resolveLocalBin(binHead, params.cwd, params.repoRoot) : null;
+    if (local) {
+        children.push({
+            kind: 'launcher',
+            launcher: peel.launcher,
+            phase: 'resolve',
+            opaque: false,
+            reason: 'npx_local_bin_resolved',
+            children: [],
+        });
+        if (innerRecipe) {
+            children.push(delegateExecNode(peel, innerRecipe, binHead, local.path));
+        }
+        if (innerRecipe && params.innerRequirements !== undefined) {
+            if (params.innerRequirements.length > 0) {
+                children.push({
+                    kind: 'exec',
+                    commandRedacted: innerRecipe,
+                    segmentHead: binHead,
+                    requirements: [...params.innerRequirements],
+                });
+            }
+        }
+    }
+    else {
+        children.push(acquireRequirement(peel, 'possible'));
+        if (innerRecipe) {
+            children.push(delegateExecNode(peel, innerRecipe, binHead));
+        }
+    }
+    return { kind: 'merge', children };
+}
+function delegateExecNode(peel, innerRecipe, segmentHead, resolvedLocalPath) {
+    return {
+        kind: 'launcher',
+        launcher: peel.launcher,
+        phase: 'delegate',
+        opaque: false,
+        reason: 'package_exec_delegate',
+        children: [
+            {
+                kind: 'exec',
+                commandRedacted: innerRecipe,
+                segmentHead,
+                requirements: [
+                    {
+                        tag: 'process.exec',
+                        action: 'process.exec',
+                        resource: { kind: 'executable', command: resolvedLocalPath ?? segmentHead },
+                        evidence: {
+                            level: resolvedLocalPath ? 'certain' : peel.forceAcquire ? 'possible' : 'certain',
+                            signals: [
+                                'package_exec.delegate',
+                                ...(resolvedLocalPath ? ['package_exec.local_bin_resolved'] : []),
+                            ],
+                            basis: [`launcher:${peel.launcher}`],
+                        },
+                        provenance: {
+                            launcher: peel.launcher,
+                            phase: 'delegate',
+                            innerCommand: innerRecipe,
+                            innerArgv: [...peel.innerTokens],
+                        },
+                    },
+                ],
+            },
+        ],
+    };
+}
+function cacheWriteRequirement(peel) {
+    return {
+        tag: 'fs.write',
+        action: 'fs.write',
+        resource: { kind: 'package-cache', manager: peel.launcher === 'pnpm' ? 'pnpm' : 'npm' },
+        evidence: {
+            level: 'possible',
+            signals: [...peel.signals, 'package_cache_write'],
+            basis: [`launcher:${peel.launcher}:cache_write`],
+        },
+        provenance: { launcher: peel.launcher, phase: 'cache_write' },
+    };
+}
+function acquireRequirement(peel, level) {
+    const knownResources = packageAcquisitionResources(peel.acquisitionSpecs);
+    const networkRequirements = knownResources.map((resource) => acquireNetworkRequirement(peel, resource, 'possible'));
+    if (level === 'indeterminate') {
+        networkRequirements.push(acquireNetworkRequirement(peel, { kind: 'unknown' }, level));
+    }
+    else if (networkRequirements.length === 0 && peel.acquisitionSpecs.length === 0) {
+        networkRequirements.push(acquireNetworkRequirement(peel, { kind: 'network', host: 'registry.npmjs.org', protocol: 'registry' }, level));
+    }
+    return {
+        kind: 'launcher',
+        launcher: peel.launcher,
+        phase: 'acquire',
+        opaque: level === 'indeterminate',
+        reason: peel.reason,
+        children: [
+            {
+                kind: 'exec',
+                commandRedacted: peel.innerTokens.join(' ') || peel.launcher,
+                segmentHead: peel.launcher,
+                requirements: [
+                    ...networkRequirements,
+                    ...(level === 'possible' || peel.acquisitionSpecs.length > 0
+                        ? [cacheWriteRequirement(peel)]
+                        : []),
+                ],
+            },
+        ],
+    };
+}
+function acquireNetworkRequirement(peel, resource, level) {
+    return {
+        tag: level === 'indeterminate' ? 'indeterminate' : 'network.acquire',
+        action: level === 'indeterminate' ? 'indeterminate' : 'network.connect',
+        resource,
+        evidence: {
+            level,
+            signals: [...peel.signals, 'package_acquire_possible'],
+            basis: [`launcher:${peel.launcher}:acquire`],
+        },
+        provenance: {
+            launcher: peel.launcher,
+            phase: 'acquire',
+            innerArgv: [...peel.acquisitionSpecs],
+        },
+    };
+}
+function packageAcquisitionResources(specs) {
+    const resources = new Map();
+    for (const spec of specs) {
+        const source = classifyPackageAcquisitionSpec(spec);
+        if (source.kind === 'local') {
+            continue;
+        }
+        const resource = source.kind === 'registry'
+            ? { kind: 'network', host: 'registry.npmjs.org', protocol: 'registry' }
+            : {
+                kind: 'network',
+                host: source.host,
+                ...(source.port ? { port: source.port } : {}),
+                protocol: source.protocol,
+            };
+        resources.set(`${resource.host}:${resource.port ?? ''}:${resource.protocol ?? ''}`, resource);
+    }
+    return [...resources.values()];
+}
+export function collectRequirements(node) {
+    switch (node.kind) {
+        case 'exec':
+            return [...node.requirements];
+        case 'launcher':
+            return node.children.flatMap((child) => collectRequirements(child));
+        case 'merge':
+            return mergeRequirements(...node.children.map((child) => collectRequirements(child)));
+        default:
+            return [];
+    }
+}
+export function buildEffectPlan(params) {
+    const root = buildPackageExecEffectNode(params);
+    if (!root) {
+        return null;
+    }
+    const requirements = collectRequirements(root);
+    const signals = [
+        ...new Set([
+            ...(params.launcherResolution?.reason ? [params.launcherResolution.reason] : []),
+            ...requirements.flatMap((r) => r.evidence.signals),
+        ]),
+    ];
+    const opacity = peelPackageExecArgv(params.tokens)?.opaque || params.launcherResolution?.opaque
+        ? 'opaque'
+        : 'recursive';
+    return {
+        version: 1,
+        root,
+        inputFingerprint: params.inputFingerprint,
+        opacity,
+        disposition: requirements.length > 0 ? 'effects' : 'effect_free',
+        completeness: opacity === 'recursive' ? 'complete' : 'partial',
+        signals,
+    };
+}
+function effectTagForAction(action) {
+    return action === 'indeterminate' ? 'indeterminate' : action;
+}
+/** Build the canonical plan envelope for non-package-exec gated actions. */
+export function buildCapabilityEffectPlan(params) {
+    const provenance = { segment: params.actionKind };
+    const requirements = params.requests.map((request) => ({
+        tag: effectTagForAction(request.action),
+        action: request.action,
+        resource: request.resource,
+        evidence: {
+            level: request.evidence.level,
+            signals: [...request.evidence.signals],
+            basis: [...request.context.analysisBasis],
+        },
+        provenance,
+        provenances: [provenance],
+    }));
+    if (!params.effectFree && requirements.length === 0) {
+        requirements.push({
+            tag: 'indeterminate',
+            action: 'indeterminate',
+            resource: { kind: 'unknown' },
+            evidence: {
+                level: 'indeterminate',
+                signals: ['effect_plan.incomplete'],
+                basis: [`gated_action:${params.actionKind}`],
+            },
+            provenance,
+            provenances: [provenance],
+        });
+    }
+    const partial = requirements.some((requirement) => requirement.evidence.level === 'indeterminate');
+    return {
+        version: 1,
+        root: {
+            kind: 'exec',
+            commandRedacted: params.summary,
+            segmentHead: params.actionKind,
+            requirements,
+        },
+        inputFingerprint: params.inputFingerprint,
+        opacity: partial ? 'opaque' : 'transparent',
+        disposition: params.effectFree ? 'effect_free' : 'effects',
+        completeness: partial ? 'partial' : 'complete',
+        signals: [...new Set(requirements.flatMap((requirement) => requirement.evidence.signals))],
+    };
+}
+export function flattenRequirementsToCapabilityRequests(requirements, opts) {
+    return requirements.map((req) => ({
+        version: 1,
+        principal: opts.principal,
+        action: req.action,
+        resource: req.resource,
+        context: {
+            hookKind: opts.hookKind,
+            cwd: opts.cwd,
+            inputFingerprint: opts.inputFingerprint,
+            analysisBasis: [...req.evidence.basis],
+        },
+        evidence: {
+            level: req.evidence.level,
+            signals: [...req.evidence.signals],
+        },
+    }));
+}

package/dist/core/effect-ir/index.d.ts

@@ -0,0 +1,8 @@
+export { effectPlanAuditFields, hashEffectPlan } from './audit.js';
+export { buildCapabilityEffectPlan, buildEffectPlan, buildPackageExecEffectNode, collectRequirements, flattenRequirementsToCapabilityRequests, } from './build.js';
+export { mergeEffectPlans, mergeRequirements, normalizeEffectTags } from './normalize.js';
+export { innerRecipeFromPeel, isPackageExecLauncher, peelPackageExecArgv, resolveLocalBin, } from './package-exec.js';
+export { evaluatePackageExecSegment } from './package-exec-eval.js';
+export { capabilityRequestsFromEffectPlan, capabilityRequestsToEffectRequirements, effectPlanPolicyLegacyReason, effectPlanPolicyRequiresAsk, evaluateEffectPlanPolicy, } from './policy.js';
+export type { EffectEvidence, EffectNode, EffectPlan, EffectProvenance, EffectRequirement, EffectTag, ExecEffectNode, LauncherEffectNode, LauncherPhase, MergeEffectNode, PackageExecLauncher, } from './types.js';
+export { EFFECT_PLAN_VERSION } from './types.js';

package/dist/core/effect-ir/index.js

@@ -0,0 +1,7 @@
+export { effectPlanAuditFields, hashEffectPlan } from './audit.js';
+export { buildCapabilityEffectPlan, buildEffectPlan, buildPackageExecEffectNode, collectRequirements, flattenRequirementsToCapabilityRequests, } from './build.js';
+export { mergeEffectPlans, mergeRequirements, normalizeEffectTags } from './normalize.js';
+export { innerRecipeFromPeel, isPackageExecLauncher, peelPackageExecArgv, resolveLocalBin, } from './package-exec.js';
+export { evaluatePackageExecSegment } from './package-exec-eval.js';
+export { capabilityRequestsFromEffectPlan, capabilityRequestsToEffectRequirements, effectPlanPolicyLegacyReason, effectPlanPolicyRequiresAsk, evaluateEffectPlanPolicy, } from './policy.js';
+export { EFFECT_PLAN_VERSION } from './types.js';

package/dist/core/effect-ir/normalize.d.ts

@@ -0,0 +1,4 @@
+import type { EffectPlan, EffectRequirement, EffectTag } from './types.js';
+export declare function normalizeEffectTags(tags: Iterable<EffectTag>): readonly EffectTag[];
+export declare function mergeRequirements(...groups: readonly (readonly EffectRequirement[])[]): EffectRequirement[];
+export declare function mergeEffectPlans(...plans: readonly (EffectPlan | null | undefined)[]): EffectPlan | undefined;