@guilz-dev/belay 0.6.0 → 0.8.0

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

@@ -0,0 +1,87 @@
+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),
+            ...(resource.operation ? { operation: resource.operation } : {}),
+        };
+    }
+    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,281 @@
+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,
+                            operation: 'spawn',
+                        },
+                        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,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 { 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

@@ -0,0 +1,9 @@
+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 { buildShellEffectPlan } from './shell-build.js';
+export { lowerShellEffectPlan } from './shell-lower.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;

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

@@ -0,0 +1,110 @@
+import { canonicalStringify, hashValue } from '../fingerprint.js';
+export function normalizeEffectTags(tags) {
+    const set = new Set(tags);
+    if (set.has('read_only') && set.size > 1) {
+        throw new Error('read_only must not co-occur with other effect tags');
+    }
+    return [...set].sort();
+}
+export function mergeRequirements(...groups) {
+    const seen = new Map();
+    for (const group of groups) {
+        for (const req of group) {
+            const key = `${req.action}:${req.resource.kind}:${resourceKey(req.resource)}`;
+            const existing = seen.get(key);
+            if (!existing) {
+                seen.set(key, {
+                    ...req,
+                    provenances: uniqueProvenances(req.provenances ?? [req.provenance]),
+                });
+                continue;
+            }
+            const strongest = evidenceRank(req.evidence.level) > evidenceRank(existing.evidence.level) ? req : existing;
+            seen.set(key, {
+                ...strongest,
+                evidence: {
+                    level: strongest.evidence.level,
+                    signals: [...new Set([...existing.evidence.signals, ...req.evidence.signals])],
+                    basis: [...new Set([...existing.evidence.basis, ...req.evidence.basis])],
+                },
+                provenances: uniqueProvenances([
+                    ...(existing.provenances ?? [existing.provenance]),
+                    ...(req.provenances ?? [req.provenance]),
+                ]),
+            });
+        }
+    }
+    return [...seen.values()];
+}
+export function mergeEffectPlans(...plans) {
+    const present = plans.filter((plan) => plan !== null && plan !== undefined);
+    if (!present.length) {
+        return undefined;
+    }
+    if (present.length === 1) {
+        return present[0];
+    }
+    const children = present.flatMap((plan) => plan.root.kind === 'merge' ? [...plan.root.children] : [plan.root]);
+    const opacity = present.some((plan) => plan.opacity === 'unparseable')
+        ? 'unparseable'
+        : present.some((plan) => plan.opacity === 'opaque')
+            ? 'opaque'
+            : present.some((plan) => plan.opacity === 'recursive')
+                ? 'recursive'
+                : 'transparent';
+    const fingerprints = present.map((plan) => plan.inputFingerprint).sort();
+    return {
+        version: 1,
+        root: { kind: 'merge', children },
+        inputFingerprint: hashValue(`effect-plan-input:v1:${canonicalStringify(fingerprints)}`),
+        opacity,
+        disposition: present.some((plan) => plan.disposition === 'effects') ? 'effects' : 'effect_free',
+        completeness: present.every((plan) => plan.completeness === 'complete')
+            ? 'complete'
+            : 'partial',
+        signals: [...new Set(present.flatMap((plan) => [...plan.signals]))].sort(),
+    };
+}
+function uniqueProvenances(provenances) {
+    const seen = new Map();
+    for (const provenance of provenances) {
+        seen.set(canonicalStringify(provenance), provenance);
+    }
+    return [...seen.values()];
+}
+function resourceKey(resource) {
+    switch (resource.kind) {
+        case 'path':
+            return resource.path;
+        case 'network':
+            return [
+                resource.host,
+                resource.port ?? '',
+                resource.protocol ?? '',
+                resource.mode ?? '',
+                resource.payload ?? '',
+            ].join(':');
+        case 'executable':
+            return `${resource.command}:${resource.operation ?? ''}`;
+        case 'package-cache':
+            return resource.manager;
+        case 'git-ref':
+            return `${resource.ref}:${resource.scope ?? ''}:${resource.repoPath ?? ''}`;
+        case 'unknown':
+            return 'unknown';
+        default:
+            return 'unknown';
+    }
+}
+function evidenceRank(level) {
+    switch (level) {
+        case 'certain':
+            return 3;
+        case 'possible':
+            return 2;
+        case 'indeterminate':
+            return 1;
+        default:
+            return 0;
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { InternalSegmentVerdict, VerdictContext } from '../verdict/types.js';
+export interface PackageExecEvalParams {
+    command: string;
+    peeled: string[];
+    context: VerdictContext;
+    evaluateInner: (innerRecipe: string) => Promise<InternalSegmentVerdict>;
+}
+export declare function evaluatePackageExecSegment(params: PackageExecEvalParams): Promise<InternalSegmentVerdict>;