@guilz-dev/belay 0.7.0 → 0.8.0

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

@@ -2,6 +2,10 @@ export declare const CAPABILITY_REQUEST_VERSION: 1;
 export type CapabilityAction = 'fs.read' | 'fs.write' | 'process.exec' | 'network.connect' | 'secret.read' | 'git.ref.write' | 'control_plane.write' | 'indeterminate';
 export type CapabilityEvidenceLevel = 'certain' | 'possible' | 'indeterminate';
 export type CapabilityHookKind = 'shell' | 'tool' | 'subagent';
+export type NetworkMode = 'read' | 'mutate' | 'ambiguous';
+export type NetworkPayload = 'none' | 'present' | 'secret';
+export type ProcessOperation = 'inspect' | 'spawn' | 'signal';
+export type GitRefScope = 'local' | 'remote';
 export interface CapabilityPrincipal {
     adapter?: string;
     repoRoot: string;
@@ -15,15 +19,20 @@ export type CapabilityResource = {
     host: string;
     port?: number;
     protocol?: string;
+    mode?: NetworkMode;
+    payload?: NetworkPayload;
 } | {
     kind: 'executable';
     command: string;
+    operation?: ProcessOperation;
 } | {
     kind: 'package-cache';
     manager: 'npm' | 'pnpm';
 } | {
     kind: 'git-ref';
     ref: string;
+    scope?: GitRefScope;
+    repoPath?: string;
 } | {
     kind: 'unknown';
 };

package/dist/core/capability/resolver.d.ts

@@ -1,4 +1,3 @@
-export { evaluateSegmentShellPolicy, type SegmentShellPolicyInput, } from '../verdict/shell-policy.js';
 export { BOUNDARY_PROFILE_L3_POLICY, checkGatedActionLimits } from './limits.js';
 export { type CapabilityAuthorizationMetadata, policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
 export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, buildSubagentCapabilityRequest, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, type FileMutationCapabilityAnalysis, policyDecisionRequiresAsk, type ShellCapabilityAnalysis, type SubagentCapabilityAnalysis, } from './policy-engine.js';

package/dist/core/capability/resolver.js

@@ -1,4 +1,3 @@
-export { evaluateSegmentShellPolicy, } from '../verdict/shell-policy.js';
 export { BOUNDARY_PROFILE_L3_POLICY, checkGatedActionLimits } from './limits.js';
 export { policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
 export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, buildSubagentCapabilityRequest, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, policyDecisionRequiresAsk, } from './policy-engine.js';

package/dist/core/config.js

@@ -937,8 +937,6 @@ export function scrubOptionsFromConfig(config) {
 export function classifierOptionsFromConfig(config) {
     return {
         strictChains: config.classifier.strictChains,
-        customExternalCommands: config.overrides.external,
-        customAllowCommands: config.overrides.allow,
         sensitivePaths: config.classifier.sensitivePaths,
         unknownLocalEffect: config.policy.unknownLocalEffect,
         unparseableShell: config.policy.unparseableShell,

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

@@ -12,6 +12,7 @@ function auditableResource(resource) {
         return {
             kind: 'executable',
             commandHash: hashValue(resource.command),
+            ...(resource.operation ? { operation: resource.operation } : {}),
         };
     }
     return resource;

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

@@ -72,7 +72,11 @@ function delegateExecNode(peel, innerRecipe, segmentHead, resolvedLocalPath) {
                     {
                         tag: 'process.exec',
                         action: 'process.exec',
-                        resource: { kind: 'executable', command: resolvedLocalPath ?? segmentHead },
+                        resource: {
+                            kind: 'executable',
+                            command: resolvedLocalPath ?? segmentHead,
+                            operation: 'spawn',
+                        },
                         evidence: {
                             level: resolvedLocalPath ? 'certain' : peel.forceAcquire ? 'possible' : 'certain',
                             signals: [

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

@@ -1,8 +1,13 @@
+export type { GitRefScope, NetworkMode, NetworkPayload, ProcessOperation, } from '../capability/request.js';
 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 type { BuildShellEffectPlanParams, ShellEffectRequirement, ShellEffectResource, ShellEffectSegment, } from './shell-build.js';
+export { buildShellEffectPlan } from './shell-build.js';
+export type { LowerShellEffectPlanParams } from './shell-lower.js';
+export { lowerShellEffectPlan } from './shell-lower.js';
+export type { AnalysisCompleteness, EffectEvidence, EffectNode, EffectPlan, EffectPlanDisposition, EffectPlanPolicyProjection, 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

@@ -4,4 +4,6 @@ export { mergeEffectPlans, mergeRequirements, normalizeEffectTags } from './norm
 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 { buildShellEffectPlan } from './shell-build.js';
+export { lowerShellEffectPlan } from './shell-lower.js';
 export { EFFECT_PLAN_VERSION } from './types.js';

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

@@ -77,13 +77,19 @@ function resourceKey(resource) {
         case 'path':
             return resource.path;
         case 'network':
-            return `${resource.host}:${resource.port ?? ''}:${resource.protocol ?? ''}`;
+            return [
+                resource.host,
+                resource.port ?? '',
+                resource.protocol ?? '',
+                resource.mode ?? '',
+                resource.payload ?? '',
+            ].join(':');
         case 'executable':
-            return resource.command;
+            return `${resource.command}:${resource.operation ?? ''}`;
         case 'package-cache':
             return resource.manager;
         case 'git-ref':
-            return resource.ref;
+            return `${resource.ref}:${resource.scope ?? ''}:${resource.repoPath ?? ''}`;
         case 'unknown':
             return 'unknown';
         default:

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

@@ -1,13 +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, EffectRequirement } from './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

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { policyDecisionToLegacyReason } from '../capability/policy-bridge.js';
-import { evaluateCapabilityRequestsPolicy, policyDecisionRequiresAsk, } from '../capability/policy-engine.js';
+import { evaluateEffectRequirementPolicy, policyDecisionRequiresAsk, } from '../capability/policy-engine.js';
 import { collectRequirements, flattenRequirementsToCapabilityRequests } from './build.js';
 function shellPrincipal(repoRoot, cwd) {
     return {
@@ -61,13 +61,100 @@ export function capabilityRequestsFromEffectPlan(plan, context) {
     });
 }
 export function evaluateEffectPlanPolicy(plan, context) {
+    const requirements = collectRequirements(plan.root);
     const capabilityRequests = capabilityRequestsFromEffectPlan(plan, context);
-    const { decisions, decision } = evaluateCapabilityRequestsPolicy(capabilityRequests, context.config, {
+    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,
-        attestation: context.attestation,
-        egressProxyActive: context.egressProxyActive,
-    }, context.trustedWorkspaceRoots);
-    return { capabilityRequests, decisions, authorizationDecision: decision };
+        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);

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 {};

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

@@ -0,0 +1,77 @@
+import { collectRequirements } from './build.js';
+import { mergeRequirements } from './normalize.js';
+/**
+ * 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 function buildShellEffectPlan(params) {
+    const nodes = params.segments.map(buildSegmentNode);
+    const root = mergeNodes(nodes);
+    const requirements = collectRequirements(root);
+    const completeness = requirements.some(isIndeterminateRequirement)
+        ? 'partial'
+        : 'complete';
+    return {
+        version: 1,
+        root,
+        inputFingerprint: params.inputFingerprint,
+        opacity: mergeOpacity(params.segments.map((segment) => segment.opacity)),
+        disposition: requirements.length === 0 ? 'effect_free' : 'effects',
+        completeness,
+        signals: [
+            ...new Set([
+                ...(params.signals ?? []),
+                ...params.segments.flatMap((segment) => [...segment.signals]),
+                ...requirements.flatMap((requirement) => [...requirement.evidence.signals]),
+            ]),
+        ].sort(),
+    };
+}
+function buildSegmentNode(segment) {
+    const requirements = mergeRequirements(segment.requirements);
+    const partial = segment.completeness === 'partial' ||
+        requirements.some((requirement) => requirement.evidence.level === 'indeterminate');
+    if (partial && !requirements.some(isIndeterminateRequirement)) {
+        const provenance = { segment: segment.commandRedacted };
+        requirements.push({
+            tag: 'indeterminate',
+            action: 'indeterminate',
+            resource: { kind: 'unknown' },
+            evidence: {
+                level: 'indeterminate',
+                signals: [...new Set([...segment.signals, 'effect_plan.segment_partial'])],
+                basis: [`shell_segment:${segment.segmentHead}`],
+            },
+            provenance,
+            provenances: [provenance],
+        });
+    }
+    return {
+        kind: 'exec',
+        commandRedacted: segment.commandRedacted,
+        segmentHead: segment.segmentHead,
+        requirements,
+    };
+}
+function isIndeterminateRequirement(requirement) {
+    return requirement.tag === 'indeterminate' || requirement.action === 'indeterminate';
+}
+function mergeNodes(nodes) {
+    if (nodes.length === 1 && nodes[0]) {
+        return nodes[0];
+    }
+    return { kind: 'merge', children: nodes };
+}
+function mergeOpacity(opacities) {
+    if (opacities.includes('unparseable')) {
+        return 'unparseable';
+    }
+    if (opacities.includes('opaque')) {
+        return 'opaque';
+    }
+    if (opacities.includes('recursive')) {
+        return 'recursive';
+    }
+    return 'transparent';
+}

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

@@ -0,0 +1,14 @@
+import type { EffectPlan } from './types.js';
+export interface LowerShellEffectPlanParams {
+    command: string;
+    cwd: string;
+    repoRoot: string;
+    inputFingerprint: string;
+    env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Parse and lower a general shell command into the canonical Task 2 model.
+ * This function only produces effects; it does not evaluate policy or return a
+ * permission/verdict.
+ */
+export declare function lowerShellEffectPlan(params: LowerShellEffectPlanParams): EffectPlan;