@guilz-dev/belay 0.6.0 → 0.8.0

package/dist/core/effect-ir/package-exec-eval.js

@@ -0,0 +1,152 @@
+import { policyDecisionToLegacyReason } from '../capability/policy-bridge.js';
+import { policyDecisionRequiresAsk } from '../capability/policy-engine.js';
+import { cwdRelative } from '../verdict/containment.js';
+import { verdictFingerprint } from '../verdict/fingerprint.js';
+import { redactCommand } from '../verdict/parser.js';
+import { buildEffectPlan } from './build.js';
+import { innerRecipeFromPeel, peelPackageExecArgv } from './package-exec.js';
+import { capabilityRequestsToEffectRequirements, evaluateEffectPlanPolicy } from './policy.js';
+function askFromEffectPlan(params) {
+    const { capabilityRequests, authorizationDecision, decisions } = evaluateEffectPlanPolicy(params.plan, params.context);
+    const legacyReason = policyDecisionRequiresAsk(authorizationDecision)
+        ? policyDecisionToLegacyReason(authorizationDecision)
+        : params.reason;
+    return {
+        permission: 'ask',
+        location: params.inner?.location ?? 'unknown',
+        opacity: params.plan.opacity,
+        effect: params.inner?.effect ?? 'unknown',
+        confidence: 'deterministic',
+        reason: legacyReason,
+        signals: [...new Set([...params.signals, ...params.plan.signals])],
+        capabilityRequests,
+        authorizationDecision,
+        effectPlan: params.plan,
+        effectPlanPolicyDecisions: decisions,
+    };
+}
+function allowFromEffectPlan(params) {
+    const { capabilityRequests, authorizationDecision, decisions } = evaluateEffectPlanPolicy(params.plan, params.context);
+    return {
+        ...params.inner,
+        opacity: params.plan.opacity,
+        signals: [...new Set([...params.inner.signals, ...params.signals, ...params.plan.signals])],
+        capabilityRequests,
+        authorizationDecision,
+        effectPlan: params.plan,
+        effectPlanPolicyDecisions: decisions,
+    };
+}
+export async function evaluatePackageExecSegment(params) {
+    const peel = peelPackageExecArgv(params.peeled);
+    if (!peel) {
+        return {
+            permission: 'ask',
+            location: 'unknown',
+            opacity: 'opaque',
+            effect: 'unknown',
+            confidence: 'deterministic',
+            reason: 'launcher_unresolved',
+            signals: ['launcher_unresolved'],
+        };
+    }
+    const relative = cwdRelative(params.context.repoRoot, params.context.cwd);
+    const inputFingerprint = verdictFingerprint(relative, redactCommand(params.command));
+    if (peel.opaque) {
+        const plan = buildEffectPlan({
+            tokens: params.peeled,
+            cwd: params.context.cwd,
+            repoRoot: params.context.repoRoot,
+            inputFingerprint,
+        }) ??
+            {
+                version: 1,
+                root: { kind: 'merge', children: [] },
+                inputFingerprint,
+                opacity: 'opaque',
+                disposition: 'effects',
+                completeness: 'partial',
+                signals: [peel.reason],
+            };
+        return askFromEffectPlan({
+            plan,
+            context: params.context,
+            reason: peel.reason,
+            signals: [peel.reason, ...peel.signals],
+        });
+    }
+    const innerRecipe = innerRecipeFromPeel(peel);
+    let innerVerdict = null;
+    let innerRequirements;
+    if (innerRecipe) {
+        innerVerdict = await params.evaluateInner(innerRecipe);
+        if (innerVerdict.capabilityRequests?.length) {
+            innerRequirements = capabilityRequestsToEffectRequirements(innerVerdict.capabilityRequests);
+        }
+        else if (innerVerdict.permission === 'allow' && innerVerdict.effect === 'read_only') {
+            innerRequirements = [];
+        }
+    }
+    const plan = buildEffectPlan({
+        tokens: params.peeled,
+        cwd: params.context.cwd,
+        repoRoot: params.context.repoRoot,
+        inputFingerprint,
+        innerRequirements,
+    });
+    if (!plan) {
+        return {
+            permission: 'ask',
+            location: innerVerdict?.location ?? 'unknown',
+            opacity: 'opaque',
+            effect: innerVerdict?.effect ?? 'unknown',
+            confidence: 'deterministic',
+            reason: peel.reason,
+            signals: [peel.reason, ...peel.signals],
+            capabilityRequests: innerVerdict?.capabilityRequests,
+            authorizationDecision: innerVerdict?.authorizationDecision,
+        };
+    }
+    const { capabilityRequests, authorizationDecision, decisions } = evaluateEffectPlanPolicy(plan, params.context);
+    if (policyDecisionRequiresAsk(authorizationDecision)) {
+        return askFromEffectPlan({
+            plan,
+            context: params.context,
+            reason: policyDecisionToLegacyReason(authorizationDecision),
+            signals: [peel.reason, ...peel.signals],
+            inner: innerVerdict ?? undefined,
+        });
+    }
+    if (innerVerdict?.permission === 'ask') {
+        return {
+            ...innerVerdict,
+            opacity: plan.opacity,
+            signals: [...new Set([...innerVerdict.signals, peel.reason, ...plan.signals])],
+            capabilityRequests,
+            authorizationDecision,
+            effectPlan: plan,
+            effectPlanPolicyDecisions: decisions,
+        };
+    }
+    if (!innerVerdict) {
+        return {
+            permission: 'allow',
+            location: 'repo_local',
+            opacity: plan.opacity,
+            effect: 'read_only',
+            confidence: 'deterministic',
+            reason: peel.reason,
+            signals: [peel.reason, ...plan.signals],
+            capabilityRequests,
+            authorizationDecision,
+            effectPlan: plan,
+            effectPlanPolicyDecisions: decisions,
+        };
+    }
+    return allowFromEffectPlan({
+        plan,
+        context: params.context,
+        inner: innerVerdict,
+        signals: [peel.reason, ...peel.signals],
+    });
+}

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

@@ -0,0 +1,29 @@
+import type { PackageExecLauncher } from './types.js';
+export interface PackageExecPeelResult {
+    launcher: PackageExecLauncher;
+    innerTokens: string[];
+    acquisitionSpecs: string[];
+    opaque: boolean;
+    reason: string;
+    forceAcquire: boolean;
+    signals: string[];
+}
+export type PackageAcquisitionSource = {
+    kind: 'local';
+} | {
+    kind: 'registry';
+} | {
+    kind: 'network';
+    host: string;
+    port?: number;
+    protocol: string;
+};
+export declare function isPackageExecLauncher(tokens: string[]): boolean;
+export declare function peelPackageExecArgv(tokens: string[]): PackageExecPeelResult | null;
+export declare function classifyPackageAcquisitionSpec(spec: string): PackageAcquisitionSource;
+export declare function resolveLocalBin(binName: string, cwd: string, repoRoot: string): {
+    path: string;
+    proven: true;
+} | null;
+export declare function innerRecipeFromPeel(peel: PackageExecPeelResult): string | null;
+export declare function isPackageExecHeadToken(head: string): boolean;

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

@@ -0,0 +1,292 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { parseNetworkEndpoint } from '../network-endpoint.js';
+import { pathWithinRoot } from '../path-utils.js';
+const READ_ONLY_SUFFIXES = new Set(['--version', '-v', '--help', '-h']);
+function isPackageExecHead(head) {
+    return head === 'npx' || head === 'npm' || head === 'pnpm';
+}
+export function isPackageExecLauncher(tokens) {
+    const head = tokens[0] ?? '';
+    if (head === 'npx') {
+        return true;
+    }
+    if (head === 'npm' && tokens[1] === 'exec') {
+        return true;
+    }
+    if (head === 'pnpm' && tokens[1] === 'dlx') {
+        return true;
+    }
+    return false;
+}
+export function peelPackageExecArgv(tokens) {
+    const head = tokens[0] ?? '';
+    if (head === 'npx') {
+        return peelNpx(tokens);
+    }
+    if (head === 'npm' && tokens[1] === 'exec') {
+        return peelNpmExec(tokens);
+    }
+    if (head === 'pnpm' && tokens[1] === 'dlx') {
+        return peelPnpmDlx(tokens);
+    }
+    return null;
+}
+function peelNpx(tokens) {
+    const signals = ['package_exec:npx'];
+    const acquisitionSpecs = [];
+    let index = 1;
+    let forceAcquire = false;
+    while (index < tokens.length) {
+        const token = tokens[index] ?? '';
+        if (index === 1 && tokens.length === 2 && READ_ONLY_SUFFIXES.has(token)) {
+            return {
+                launcher: 'npx',
+                innerTokens: [token],
+                acquisitionSpecs,
+                opaque: false,
+                reason: 'npx_wrapper_readonly',
+                forceAcquire: false,
+                signals: [...signals, 'npx_wrapper_readonly'],
+            };
+        }
+        if (token === '--') {
+            index += 1;
+            break;
+        }
+        if (token === '-y' || token === '--yes') {
+            forceAcquire = true;
+            signals.push('npx.force_yes');
+            index += 1;
+            continue;
+        }
+        if (token === '-p' || token === '--package') {
+            const packageSpec = tokens[index + 1];
+            if (!packageSpec) {
+                return opaquePackageExec('npx', 'npx_package_missing', signals, acquisitionSpecs);
+            }
+            acquisitionSpecs.push(packageSpec);
+            forceAcquire = true;
+            signals.push('npx.package_flag');
+            index += 2;
+            continue;
+        }
+        if (token.startsWith('--package=')) {
+            acquisitionSpecs.push(token.slice('--package='.length));
+            forceAcquire = true;
+            signals.push('npx.package_flag');
+            index += 1;
+            continue;
+        }
+        if (token === '-c' || token === '--call') {
+            return {
+                launcher: 'npx',
+                innerTokens: [],
+                acquisitionSpecs,
+                opaque: true,
+                reason: 'npx_call_script',
+                forceAcquire: true,
+                signals: [...signals, 'npx_call_script'],
+            };
+        }
+        if (token.startsWith('-')) {
+            return opaquePackageExec('npx', 'npx_unknown_option', [...signals, 'npx_unknown_option'], acquisitionSpecs);
+        }
+        break;
+    }
+    const innerTokens = tokens.slice(index);
+    if (innerTokens.length === 0) {
+        return {
+            launcher: 'npx',
+            innerTokens: [],
+            acquisitionSpecs,
+            opaque: true,
+            reason: 'npx_target_missing',
+            forceAcquire,
+            signals: [...signals, 'npx_target_missing'],
+        };
+    }
+    if (/^@[^/]+\/[^/]+/.test(innerTokens[0] ?? '')) {
+        if (acquisitionSpecs.length === 0 && innerTokens[0]) {
+            acquisitionSpecs.push(innerTokens[0]);
+        }
+        return opaquePackageExec('npx', 'npx_scoped_package_bin_indeterminate', [...signals, 'npx_scoped_package_bin_indeterminate'], acquisitionSpecs);
+    }
+    if (requiresExplicitPackageAcquisition(innerTokens[0] ?? '')) {
+        forceAcquire = true;
+        signals.push('npx.remote_spec');
+    }
+    if (acquisitionSpecs.length === 0 && innerTokens[0]) {
+        acquisitionSpecs.push(innerTokens[0]);
+    }
+    return {
+        launcher: 'npx',
+        innerTokens,
+        acquisitionSpecs,
+        opaque: false,
+        reason: 'npx_exec',
+        forceAcquire,
+        signals,
+    };
+}
+function peelNpmExec(tokens) {
+    return peelForcedPackageExec(tokens, 2, 'npm', 'npm_exec');
+}
+function peelPnpmDlx(tokens) {
+    return peelForcedPackageExec(tokens, 2, 'pnpm', 'pnpm_dlx');
+}
+function peelForcedPackageExec(tokens, startIndex, launcher, reason) {
+    const signals = [`package_exec:${reason}`, `${reason}_acquire`];
+    const acquisitionSpecs = [];
+    let index = startIndex;
+    while (index < tokens.length) {
+        const token = tokens[index] ?? '';
+        if (token === '--') {
+            index += 1;
+            break;
+        }
+        if (launcher === 'npm' && (token === '-y' || token === '--yes')) {
+            index += 1;
+            continue;
+        }
+        if (launcher === 'npm' && (token === '-p' || token === '--package')) {
+            const packageSpec = tokens[index + 1];
+            if (!packageSpec) {
+                return opaquePackageExec(launcher, `${reason}_package_missing`, signals, acquisitionSpecs);
+            }
+            acquisitionSpecs.push(packageSpec);
+            index += 2;
+            continue;
+        }
+        if (launcher === 'npm' && token.startsWith('--package=')) {
+            acquisitionSpecs.push(token.slice('--package='.length));
+            index += 1;
+            continue;
+        }
+        if (launcher === 'npm' && (token === '-c' || token === '--call')) {
+            return opaquePackageExec(launcher, `${reason}_call_script`, signals, acquisitionSpecs);
+        }
+        if (token.startsWith('-')) {
+            return opaquePackageExec(launcher, `${reason}_unknown_option`, [...signals, `${reason}_unknown_option`], acquisitionSpecs);
+        }
+        break;
+    }
+    const innerTokens = tokens.slice(index);
+    if (acquisitionSpecs.length === 0 && innerTokens[0]) {
+        acquisitionSpecs.push(innerTokens[0]);
+    }
+    return {
+        launcher,
+        innerTokens,
+        acquisitionSpecs,
+        opaque: innerTokens.length === 0,
+        reason: innerTokens.length === 0 ? `${reason}_missing` : reason,
+        forceAcquire: true,
+        signals,
+    };
+}
+function opaquePackageExec(launcher, reason, signals, acquisitionSpecs = []) {
+    return {
+        launcher,
+        innerTokens: [],
+        acquisitionSpecs,
+        opaque: true,
+        reason,
+        forceAcquire: true,
+        signals,
+    };
+}
+function requiresExplicitPackageAcquisition(token) {
+    if (!token || token.startsWith('-')) {
+        return false;
+    }
+    if (classifyPackageAcquisitionSpec(token).kind !== 'registry') {
+        return true;
+    }
+    if (token.includes('@') && !token.startsWith('@')) {
+        return true;
+    }
+    if (/^@[^/]+\/[^/]+@/.test(token)) {
+        return true;
+    }
+    if (token.startsWith('npm:')) {
+        return true;
+    }
+    return false;
+}
+export function classifyPackageAcquisitionSpec(spec) {
+    const normalized = spec.trim();
+    if (normalized.startsWith('file:') ||
+        normalized.startsWith('git+file:') ||
+        normalized.startsWith('link:') ||
+        normalized.startsWith('workspace:') ||
+        normalized.startsWith('./') ||
+        normalized.startsWith('../') ||
+        normalized.startsWith('/') ||
+        normalized.startsWith('~/') ||
+        /^[A-Za-z]:[\\/]/.test(normalized)) {
+        return { kind: 'local' };
+    }
+    const transportSpec = normalized.startsWith('git+') ? normalized.slice(4) : normalized;
+    const endpoint = parseNetworkEndpoint(transportSpec, {
+        allowHostedGitShorthand: true,
+        allowScpStyle: true,
+    });
+    if (endpoint) {
+        return { kind: 'network', ...endpoint };
+    }
+    if (/^[A-Za-z0-9][A-Za-z0-9._-]*\/[^/]+(?:#.*)?$/.test(normalized)) {
+        return { kind: 'network', host: 'github.com', protocol: 'git' };
+    }
+    if (/(?:\.tgz|\.tar|\.tar\.gz)$/i.test(normalized)) {
+        return { kind: 'local' };
+    }
+    if ((normalized.match(/\//g)?.length ?? 0) > 1) {
+        return { kind: 'local' };
+    }
+    return { kind: 'registry' };
+}
+export function resolveLocalBin(binName, cwd, repoRoot) {
+    const base = path.basename(binName);
+    if (!base || base === '.' || base === '..') {
+        return null;
+    }
+    let current = path.resolve(cwd);
+    const stop = path.resolve(repoRoot);
+    if (!pathWithinRoot(stop, current)) {
+        return null;
+    }
+    while (true) {
+        const candidate = path.join(current, 'node_modules', '.bin', base);
+        if (existsSync(candidate)) {
+            try {
+                const resolvedCandidate = realpathSync.native(candidate);
+                if (!pathWithinRoot(stop, resolvedCandidate) || !statSync(resolvedCandidate).isFile()) {
+                    return null;
+                }
+                return { path: resolvedCandidate, proven: true };
+            }
+            catch {
+                return null;
+            }
+        }
+        if (current === stop) {
+            break;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return null;
+}
+export function innerRecipeFromPeel(peel) {
+    if (peel.opaque || peel.reason === 'npx_wrapper_readonly' || peel.innerTokens.length === 0) {
+        return null;
+    }
+    return peel.innerTokens.join(' ');
+}
+export function isPackageExecHeadToken(head) {
+    return isPackageExecHead(head);
+}

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

@@ -0,0 +1,14 @@
+import type { PolicyDecision } from '../capability/policy-types.js';
+import type { CapabilityRequestV1 } from '../capability/request.js';
+import type { VerdictContext } from '../verdict/types.js';
+import type { EffectPlan, EffectPlanPolicyProjection, EffectRequirement } from './types.js';
+export declare function capabilityRequestsToEffectRequirements(requests: readonly CapabilityRequestV1[]): EffectRequirement[];
+export declare function capabilityRequestsFromEffectPlan(plan: EffectPlan, context: VerdictContext): CapabilityRequestV1[];
+export declare function evaluateEffectPlanPolicy(plan: EffectPlan, context: VerdictContext): {
+    capabilityRequests: CapabilityRequestV1[];
+    decisions: PolicyDecision[];
+    authorizationDecision: PolicyDecision;
+    projection: EffectPlanPolicyProjection;
+};
+export declare function effectPlanPolicyRequiresAsk(decision: PolicyDecision): boolean;
+export declare function effectPlanPolicyLegacyReason(decision: PolicyDecision): string;

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

@@ -0,0 +1,164 @@
+import { createHash } from 'node:crypto';
+import { policyDecisionToLegacyReason } from '../capability/policy-bridge.js';
+import { evaluateEffectRequirementPolicy, policyDecisionRequiresAsk, } from '../capability/policy-engine.js';
+import { collectRequirements, flattenRequirementsToCapabilityRequests } from './build.js';
+function shellPrincipal(repoRoot, cwd) {
+    return {
+        repoRoot,
+        sessionHash: createHash('sha256').update(`${repoRoot}:${cwd}`).digest('hex').slice(0, 16),
+    };
+}
+function capabilityActionToEffectTag(action) {
+    switch (action) {
+        case 'fs.read':
+            return 'fs.read';
+        case 'fs.write':
+            return 'fs.write';
+        case 'process.exec':
+            return 'process.exec';
+        case 'network.connect':
+            return 'network.connect';
+        case 'secret.read':
+            return 'secret.read';
+        case 'git.ref.write':
+            return 'git.ref.write';
+        case 'control_plane.write':
+            return 'control_plane.write';
+        case 'indeterminate':
+            return 'indeterminate';
+        default:
+            return 'indeterminate';
+    }
+}
+export function capabilityRequestsToEffectRequirements(requests) {
+    return requests.map((request) => ({
+        tag: capabilityActionToEffectTag(request.action),
+        action: request.action,
+        resource: request.resource,
+        evidence: {
+            level: request.evidence.level,
+            signals: [...request.evidence.signals],
+            basis: [...request.context.analysisBasis],
+        },
+        provenance: {
+            innerCommand: request.resource.kind === 'executable' ? request.resource.command : undefined,
+        },
+        provenances: [
+            {
+                innerCommand: request.resource.kind === 'executable' ? request.resource.command : undefined,
+            },
+        ],
+    }));
+}
+export function capabilityRequestsFromEffectPlan(plan, context) {
+    const requirements = collectRequirements(plan.root);
+    return flattenRequirementsToCapabilityRequests(requirements, {
+        principal: shellPrincipal(context.repoRoot, context.cwd),
+        cwd: context.cwd,
+        repoRoot: context.repoRoot,
+        hookKind: 'shell',
+        inputFingerprint: plan.inputFingerprint,
+    });
+}
+export function evaluateEffectPlanPolicy(plan, context) {
+    const requirements = collectRequirements(plan.root);
+    const capabilityRequests = capabilityRequestsFromEffectPlan(plan, context);
+    const decisions = requirements.map((requirement, index) => evaluateEffectRequirementPolicy({
+        tag: requirement.tag,
+        action: requirement.action,
+        resource: requirement.resource,
+        evidence: requirement.evidence,
+        provenance: requirement.provenance,
+    }, {
+        cwd: context.cwd,
+        repoRoot: context.repoRoot,
+        trustedWorkspaceRoots: context.trustedWorkspaceRoots,
+        sensitivePaths: context.sensitivePaths,
+        protectedArtifactRoots: context.protectedArtifactRoots,
+        grants: context.grants,
+        capabilityRequest: capabilityRequests[index],
+    }));
+    const indeterminateIndexes = requirements.flatMap((requirement, index) => requirement.action === 'indeterminate' ||
+        requirement.tag === 'indeterminate' ||
+        requirement.evidence.level === 'indeterminate'
+        ? [index]
+        : []);
+    const unresolvedPartial = indeterminateIndexes.length === 0 ||
+        indeterminateIndexes.some((index) => decisions[index]?.matchedRule !== 'grant.exact');
+    if (plan.completeness === 'partial' && unresolvedPartial) {
+        decisions.push({
+            effectDisposition: 'ask',
+            outcome: 'require_approval',
+            reason: 'indeterminate_effect',
+            signals: [...plan.signals, 'effect_plan_partial'],
+            matchedRule: 'effect.plan_partial',
+        });
+    }
+    const worstDecision = worstEffectDecision(decisions);
+    const authorizationDecision = (worstDecision?.effectDisposition === 'ask'
+        ? worstDecision
+        : (decisions.find((decision) => decision.matchedRule === 'grant.exact') ?? worstDecision)) ??
+        {
+            outcome: 'allow',
+            reason: 'read_only',
+            signals: [],
+            matchedRule: 'effect.effect_free',
+        };
+    const projection = projectEffectPlanPolicy(decisions, authorizationDecision);
+    return {
+        capabilityRequests,
+        decisions,
+        authorizationDecision,
+        projection,
+    };
+}
+function dispositionRank(disposition) {
+    switch (disposition) {
+        case 'ask':
+            return 2;
+        case 'allow_flagged':
+            return 1;
+        case 'allow':
+            return 0;
+        default:
+            return 2;
+    }
+}
+function projectEffectPlanPolicy(decisions, authorizationDecision) {
+    const worst = worstEffectDecision(decisions);
+    if (!worst) {
+        return {
+            permission: 'allow',
+            hookVerdict: 'allow',
+            reason: 'read_only',
+        };
+    }
+    if (worst.effectDisposition === 'ask') {
+        return {
+            permission: 'ask',
+            hookVerdict: 'deny_pending_approval',
+            reason: policyDecisionToLegacyReason(authorizationDecision),
+        };
+    }
+    return {
+        permission: 'allow',
+        hookVerdict: worst.effectDisposition === 'allow_flagged' ? 'allow_flagged' : 'allow',
+        reason: policyDecisionToLegacyReason(worst),
+    };
+}
+function worstEffectDecision(decisions) {
+    let worst;
+    for (const decision of decisions) {
+        if (!worst ||
+            dispositionRank(decision.effectDisposition) > dispositionRank(worst.effectDisposition)) {
+            worst = decision;
+        }
+    }
+    return worst;
+}
+export function effectPlanPolicyRequiresAsk(decision) {
+    return policyDecisionRequiresAsk(decision);
+}
+export function effectPlanPolicyLegacyReason(decision) {
+    return policyDecisionToLegacyReason(decision);
+}

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

@@ -0,0 +1,43 @@
+import type { CapabilityResource } from '../capability/request.js';
+import type { AnalysisCompleteness, EffectPlan, EffectRequirement } from './types.js';
+type ShellNetworkResource = Extract<CapabilityResource, {
+    kind: 'network';
+}> & Required<Pick<Extract<CapabilityResource, {
+    kind: 'network';
+}>, 'mode' | 'payload'>>;
+type ShellExecutableResource = Extract<CapabilityResource, {
+    kind: 'executable';
+}> & Required<Pick<Extract<CapabilityResource, {
+    kind: 'executable';
+}>, 'operation'>>;
+type ShellGitRefResource = Extract<CapabilityResource, {
+    kind: 'git-ref';
+}> & Required<Pick<Extract<CapabilityResource, {
+    kind: 'git-ref';
+}>, 'scope'>>;
+export type ShellEffectResource = Exclude<CapabilityResource, {
+    kind: 'network' | 'executable' | 'git-ref';
+}> | ShellNetworkResource | ShellExecutableResource | ShellGitRefResource;
+export type ShellEffectRequirement = Omit<EffectRequirement, 'resource'> & {
+    resource: ShellEffectResource;
+};
+export interface ShellEffectSegment {
+    commandRedacted: string;
+    segmentHead: string;
+    requirements: readonly ShellEffectRequirement[];
+    completeness: AnalysisCompleteness;
+    opacity: EffectPlan['opacity'];
+    signals: readonly string[];
+}
+export interface BuildShellEffectPlanParams {
+    inputFingerprint: string;
+    segments: readonly ShellEffectSegment[];
+    signals?: readonly string[];
+}
+/**
+ * Build a canonical EffectPlan from shell segments that have already been
+ * semantically analyzed. This function only assembles and normalizes effects;
+ * command-specific lowering belongs to the segment producers.
+ */
+export declare function buildShellEffectPlan(params: BuildShellEffectPlanParams): EffectPlan;
+export {};