@guilz-dev/belay 0.6.0 → 0.8.0

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

@@ -0,0 +1,62 @@
+import type { CapabilityAction, CapabilityEvidenceLevel, CapabilityResource } from '../capability/request.js';
+import type { VerdictOpacity } from '../verdict/types.js';
+export declare const EFFECT_PLAN_VERSION: 1;
+export type EffectTag = 'fs.read' | 'fs.write' | 'process.exec' | 'network.connect' | 'network.acquire' | 'git.ref.write' | 'secret.read' | 'control_plane.write' | 'read_only' | 'indeterminate';
+export type LauncherPhase = 'invoke' | 'resolve' | 'acquire' | 'cache_read' | 'cache_write' | 'delegate';
+export type PackageExecLauncher = 'npx' | 'npm' | 'pnpm';
+export type EffectPlanDisposition = 'effects' | 'effect_free';
+export type AnalysisCompleteness = 'complete' | 'partial';
+export interface EffectPlanPolicyProjection {
+    permission: 'allow' | 'ask';
+    hookVerdict: 'allow' | 'allow_flagged' | 'deny_pending_approval';
+    reason: string;
+}
+export interface EffectEvidence {
+    level: CapabilityEvidenceLevel;
+    signals: readonly string[];
+    basis: readonly string[];
+}
+export interface EffectProvenance {
+    segment?: string;
+    launcher?: PackageExecLauncher;
+    phase?: LauncherPhase;
+    innerCommand?: string;
+    innerArgv?: readonly string[];
+}
+export interface EffectRequirement {
+    tag: EffectTag;
+    action: CapabilityAction;
+    resource: CapabilityResource;
+    evidence: EffectEvidence;
+    provenance: EffectProvenance;
+    /** All contributing sources after requirement de-duplication. */
+    provenances?: readonly EffectProvenance[];
+}
+export interface ExecEffectNode {
+    kind: 'exec';
+    commandRedacted: string;
+    segmentHead: string;
+    requirements: readonly EffectRequirement[];
+}
+export interface LauncherEffectNode {
+    kind: 'launcher';
+    launcher: PackageExecLauncher | 'npm' | 'pnpm' | 'make';
+    phase: LauncherPhase;
+    opaque: boolean;
+    reason: string;
+    children: readonly EffectNode[];
+}
+export interface MergeEffectNode {
+    kind: 'merge';
+    children: readonly EffectNode[];
+}
+export type EffectNode = ExecEffectNode | LauncherEffectNode | MergeEffectNode;
+export interface EffectPlan {
+    version: typeof EFFECT_PLAN_VERSION;
+    root: EffectNode;
+    inputFingerprint: string;
+    opacity: VerdictOpacity;
+    disposition: EffectPlanDisposition;
+    completeness: AnalysisCompleteness;
+    signals: readonly string[];
+}

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

@@ -0,0 +1 @@
+export const EFFECT_PLAN_VERSION = 1;

package/dist/core/egress/allowlist.d.ts

@@ -3,5 +3,6 @@ import type { EgressAllowlistEntry, EgressAllowlistFile } from './types.js';
 export declare function egressAllowlistPath(config: BelayConfigV3, repoLocalStateDir: string): string;
 export declare function loadEgressAllowlist(filePath: string): Promise<EgressAllowlistFile>;
 export declare function saveEgressAllowlist(filePath: string, state: EgressAllowlistFile): Promise<void>;
+export declare function mutateEgressAllowlist(filePath: string, mutate: (state: EgressAllowlistFile) => EgressAllowlistFile): Promise<EgressAllowlistFile>;
 export declare function isHostAllowlisted(host: string, allowlist: EgressAllowlistFile): boolean;
 export declare function addDomainToAllowlist(allowlist: EgressAllowlistFile, entry: EgressAllowlistEntry): EgressAllowlistFile;

package/dist/core/egress/allowlist.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { withStateFileLock } from '../capability/approval-state-mutation.js';
 import { belayStateDir } from '../config.js';
 export function egressAllowlistPath(config, repoLocalStateDir) {
     return path.join(belayStateDir(config, repoLocalStateDir), 'egress-allowlist.json');
@@ -19,6 +20,13 @@ export async function saveEgressAllowlist(filePath, state) {
     await mkdir(path.dirname(filePath), { recursive: true });
     await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
 }
+export async function mutateEgressAllowlist(filePath, mutate) {
+    return withStateFileLock(filePath, async () => {
+        const updated = mutate(await loadEgressAllowlist(filePath));
+        await saveEgressAllowlist(filePath, updated);
+        return updated;
+    });
+}
 export function isHostAllowlisted(host, allowlist) {
     const normalized = host.toLowerCase();
     return allowlist.domains.some((entry) => entry.host.toLowerCase() === normalized);

package/dist/core/egress-approval.js

@@ -1,23 +1,15 @@
 import { randomUUID } from 'node:crypto';
 import { compactApprovals, createApprovalRecord } from './approval.js';
 import { issueApprovalToken } from './approval-token.js';
+import { mutateApprovalStateWithRetry } from './capability/approval-state-mutation.js';
 import { configuredControlPlaneDir } from './config.js';
-import { addDomainToAllowlist, loadEgressAllowlist, saveEgressAllowlist, } from './egress/allowlist.js';
+import { addDomainToAllowlist, mutateEgressAllowlist } from './egress/allowlist.js';
 import { parseHostFromSummary } from './egress/fingerprint.js';
 import { notifyDeny } from './notify.js';
 export async function ensurePendingEgressApproval(params) {
     const { config, repoRoot, policyResult, store } = params;
-    const pending = await store.loadPending();
-    pending.state = compactApprovals(pending.state);
-    const existing = pending.state.approvals.find((approval) => approval.kind === 'egress' &&
-        approval.fingerprint === policyResult.fingerprint &&
-        approval.repoRoot === repoRoot);
-    if (existing) {
-        await store.writePending(pending.filePath, pending.state);
-        return { approvalId: existing.approvalId, approval: existing, created: false };
-    }
     const approvalId = `belay_${randomUUID().replaceAll('-', '').slice(0, 12)}`;
-    const approval = createApprovalRecord({
+    const candidate = createApprovalRecord({
         kind: 'egress',
         fingerprint: policyResult.fingerprint,
         repoRoot,
@@ -26,44 +18,47 @@ export async function ensurePendingEgressApproval(params) {
         approvalTtlMinutes: config.approvalTtlMinutes,
         approvalId,
     });
-    pending.state.approvals.push(approval);
-    await store.writePending(pending.filePath, pending.state);
-    return { approvalId, approval, created: true };
-}
-const consumeLocks = new Map();
-async function withConsumeLock(key, fn) {
-    const previous = consumeLocks.get(key) ?? Promise.resolve();
-    let release;
-    const gate = new Promise((resolve) => {
-        release = resolve;
+    const outcome = await mutateApprovalStateWithRetry({
+        load: store.loadPending,
+        write: store.writePending,
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const existing = compacted.approvals.find((approval) => approval.kind === 'egress' &&
+                approval.fingerprint === policyResult.fingerprint &&
+                approval.repoRoot === repoRoot);
+            if (existing) {
+                return {
+                    state: compacted,
+                    result: { approvalId: existing.approvalId, approval: existing, created: false },
+                };
+            }
+            compacted.approvals.push(candidate);
+            return {
+                state: compacted,
+                result: { approvalId, approval: candidate, created: true },
+            };
+        },
     });
-    consumeLocks.set(key, previous.then(() => gate));
-    await previous;
-    try {
-        return await fn();
-    }
-    finally {
-        release();
-        if (consumeLocks.get(key) === gate) {
-            consumeLocks.delete(key);
-        }
+    if (!outcome) {
+        throw new Error('Failed to persist pending egress approval');
     }
+    return outcome;
 }
 export async function consumeApprovedEgress(params) {
-    const lockKey = `${params.repoRoot}:${params.fingerprint}`;
-    return withConsumeLock(lockKey, async () => {
-        const approved = await params.store.loadApproved();
-        approved.state = compactApprovals(approved.state);
-        const index = approved.state.approvals.findIndex((approval) => approval.kind === 'egress' &&
-            approval.fingerprint === params.fingerprint &&
-            approval.repoRoot === params.repoRoot);
-        if (index === -1) {
-            await params.store.writeApproved(approved.filePath, approved.state);
-            return null;
-        }
-        const [approval] = approved.state.approvals.splice(index, 1);
-        await params.store.writeApproved(approved.filePath, approved.state);
-        return approval;
+    return mutateApprovalStateWithRetry({
+        load: params.store.loadApproved,
+        write: params.store.writeApproved,
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const index = compacted.approvals.findIndex((approval) => approval.kind === 'egress' &&
+                approval.fingerprint === params.fingerprint &&
+                approval.repoRoot === params.repoRoot);
+            if (index === -1) {
+                return null;
+            }
+            const [approval] = compacted.approvals.splice(index, 1);
+            return { state: compacted, result: approval ?? null };
+        },
     });
 }
 export async function notifyEgressDeny(params) {
@@ -98,8 +93,8 @@ export async function recordEgressApproval(params) {
     const { recordApproval } = await import('./approval-service.js');
     const pending = await params.store.loadPending();
     const match = pending.state.approvals.find((approval) => approval.approvalId === params.approvalId);
-    const host = match ? parseHostFromSummary(match.summary) : null;
-    if (params.scope === 'domain' && match && !host) {
+    const pendingHost = match ? parseHostFromSummary(match.summary) : null;
+    if (params.scope === 'domain' && match && !pendingHost) {
         return {
             ok: false,
             message: `Cannot add domain to egress allowlist: could not parse host from summary "${match.summary}".`,
@@ -112,16 +107,15 @@ export async function recordEgressApproval(params) {
         requireSignedToken: params.requireSignedToken ?? false,
         store: params.store,
     });
+    const host = result.approval ? parseHostFromSummary(result.approval.summary) : pendingHost;
     if (!result.ok || params.scope !== 'domain' || !host) {
         return { ok: result.ok, message: result.message };
     }
-    const allowlist = await loadEgressAllowlist(params.store.allowlistPath);
-    const updated = addDomainToAllowlist(allowlist, {
+    await mutateEgressAllowlist(params.store.allowlistPath, (allowlist) => addDomainToAllowlist(allowlist, {
         host,
         approvedAt: new Date().toISOString(),
         approvalId: params.approvalId,
-    });
-    await saveEgressAllowlist(params.store.allowlistPath, updated);
+    }));
     return {
         ok: true,
         message: `${result.message} Domain ${host} added to egress allowlist.`,

package/dist/core/gate-contract.d.ts

@@ -31,6 +31,8 @@ export interface GateVerdict extends GatePermissionResponse {
     axes?: ClassifyResult['axes'];
     capabilityRequests?: ClassifyResult['capabilityRequests'];
     authorizationDecision?: ClassifyResult['authorizationDecision'];
+    effectPlan?: ClassifyResult['effectPlan'];
+    effectPlanPolicyDecisions?: ClassifyResult['effectPlanPolicyDecisions'];
     boundaryProfile?: string;
 }
 export declare function isGatedAction(value: unknown): value is GatedAction;

package/dist/core/gate-contract.js

@@ -28,6 +28,8 @@ export function classifyResultToGateVerdict(params) {
         axes: result.axes,
         capabilityRequests: result.capabilityRequests,
         authorizationDecision: result.authorizationDecision,
+        effectPlan: result.effectPlan,
+        effectPlanPolicyDecisions: result.effectPlanPolicyDecisions,
         boundaryProfile: result.boundaryProfile,
     };
 }

package/dist/core/gate-engine.js

@@ -4,9 +4,12 @@ import { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload, } from
 import { classifySubagent } from './classify-subagent.js';
 import { classifyToolUse } from './classify-tool.js';
 import { classifierOptionsFromConfig } from './config.js';
+import { buildCapabilityEffectPlan } from './effect-ir/build.js';
+import { evaluateEffectPlanPolicy } from './effect-ir/policy.js';
+import { buildShellEffectPlan } from './effect-ir/shell-build.js';
 import { GATE_CONTRACT_VERSION } from './gate-contract.js';
 import { mergeAgentAssessment } from './judgment.js';
-import { classifyShell } from './verdict/adapter.js';
+import { buildVerdictContext, classifyShell } from './verdict/adapter.js';
 export class GateNormalizationError extends Error {
     reason = 'normalization_failed';
     constructor(message) {
@@ -167,16 +170,6 @@ function applyFsScopePeripheralPolicy(outsideRepoPaths, result, options) {
     }
     return result;
 }
-function applySandboxOutsideBoundary(command, action, result, options) {
-    const outsideRepoPaths = collectOutsideRepoPaths(command, action.cwd, action.repoRoot, options.trustedWorkspaceRoots);
-    return applySandboxFsScopeBoundary(outsideRepoPaths, result, options, {
-        redirect: command.includes('>'),
-    });
-}
-function applyShellPeripheralPolicy(command, action, result, options) {
-    const outsideRepoPaths = collectOutsideRepoPaths(command, action.cwd, action.repoRoot, options.trustedWorkspaceRoots);
-    return applyFsScopePeripheralPolicy(outsideRepoPaths, result, options);
-}
 function outsideRepoPathsForToolAction(action, options) {
     const payload = action.payload ?? {};
     const paths = new Set(collectOutsideRepoPathsFromToolPayload(payload, action.cwd, action.repoRoot, options.trustedWorkspaceRoots));
@@ -198,50 +191,114 @@ function applyToolSandboxPolicies(action, result, options) {
     return next;
 }
 export async function classifyGatedAction(action, config, extraOptions = {}) {
+    const options = { ...classifierOptionsFromConfig(config), ...extraOptions };
     const limitResult = checkGatedActionLimits(action);
     if (limitResult) {
-        return limitResult;
+        if (action.kind === 'shell') {
+            return projectShellLimitResult(action, limitResult, config, options);
+        }
+        return attachEffectPlan(action, limitResult);
     }
-    const options = { ...classifierOptionsFromConfig(config), ...extraOptions };
     if (action.kind === 'shell') {
         const command = action.command ?? shellCommandFromPayload(action.payload ?? {});
         if (!command) {
             throw new GateNormalizationError('Shell gated action requires a command.');
         }
-        let result = await classifyShell(command, action.cwd, action.repoRoot, config, options);
-        result = applySandboxOutsideBoundary(command, action, result, options);
-        result = applyShellPeripheralPolicy(command, action, result, options);
+        const result = await classifyShell(command, action.cwd, action.repoRoot, config, options);
         if (!action.agentAssessment) {
             return result;
         }
         const merged = mergeAgentAssessment(result.assessment, action.agentAssessment);
-        if (!merged.mismatch) {
-            return { ...result, assessment: merged.assessment };
-        }
         return {
             ...result,
-            verdict: 'deny_pending_approval',
-            reason: 'agent_assessment_mismatch',
             assessment: merged.assessment,
         };
     }
     if (action.kind === 'subagent') {
-        return classifySubagent(action.payload ?? {}, action.repoRoot, options, config);
+        return attachEffectPlan(action, classifySubagent(action.payload ?? {}, action.repoRoot, options, config));
     }
     let result = await classifyToolUse(action.payload ?? {}, action.repoRoot, action.cwd, config, options);
     result = applyToolSandboxPolicies(action, result, options);
     if (!action.agentAssessment) {
-        return result;
+        return attachEffectPlan(action, result);
     }
     const merged = mergeAgentAssessment(result.assessment, action.agentAssessment);
     if (!merged.mismatch) {
-        return { ...result, assessment: merged.assessment };
+        return attachEffectPlan(action, { ...result, assessment: merged.assessment });
     }
-    return {
+    return attachEffectPlan(action, {
         ...result,
         verdict: 'deny_pending_approval',
         reason: 'agent_assessment_mismatch',
         assessment: merged.assessment,
+    });
+}
+function projectShellLimitResult(action, result, config, options) {
+    const summary = result.summary ?? 'oversized shell input';
+    const effectPlan = buildShellEffectPlan({
+        inputFingerprint: result.fingerprint,
+        segments: [
+            {
+                commandRedacted: summary,
+                segmentHead: 'input-limit',
+                requirements: [
+                    {
+                        tag: 'indeterminate',
+                        action: 'indeterminate',
+                        resource: { kind: 'unknown' },
+                        evidence: {
+                            level: 'indeterminate',
+                            signals: ['input_too_large', 'analysis_budget_exceeded'],
+                            basis: ['gate:input_limit'],
+                        },
+                        provenance: { segment: summary },
+                    },
+                ],
+                completeness: 'partial',
+                opacity: 'opaque',
+                signals: ['input_too_large', 'analysis_budget_exceeded'],
+            },
+        ],
+    });
+    const policy = evaluateEffectPlanPolicy(effectPlan, buildVerdictContext({
+        cwd: action.cwd,
+        repoRoot: action.repoRoot,
+        config,
+        options,
+    }));
+    return {
+        ...result,
+        verdict: policy.projection.hookVerdict,
+        axes: {
+            location: 'unknown',
+            opacity: effectPlan.opacity,
+            effect: 'unknown',
+            confidence: 'deterministic',
+            would: policy.projection.permission,
+            by: 'effect_plan',
+            signals: [...effectPlan.signals],
+        },
+        capabilityRequests: policy.capabilityRequests,
+        authorizationDecision: policy.authorizationDecision,
+        effectPlan,
+        effectPlanPolicyDecisions: policy.decisions,
+        effectPlanProjection: policy.projection,
+    };
+}
+function attachEffectPlan(action, result) {
+    if (result.effectPlan) {
+        return result;
+    }
+    const summary = result.normalizedCommand ?? result.summary ?? action.command ?? action.kind;
+    return {
+        ...result,
+        effectPlan: buildCapabilityEffectPlan({
+            actionKind: action.kind,
+            summary,
+            inputFingerprint: result.fingerprint,
+            requests: result.capabilityRequests ?? [],
+            effectFree: result.reason === 'read_only',
+        }),
     };
 }
 export async function classifyGatedActionAsync(action, config, extraOptions = {}) {

package/dist/core/git-resource-identity.d.ts

@@ -0,0 +1,26 @@
+export interface GitResourceIdentity {
+    repositoryRoot: string;
+    gitDir: string;
+    commonDir: string;
+    gitEntryPath: string;
+}
+export type GitResourceIdentityInspection = {
+    status: 'resolved';
+    identity: GitResourceIdentity;
+} | {
+    status: 'absent';
+} | {
+    status: 'invalid';
+    boundaryPath: string;
+    metadataRoots: string[];
+};
+/**
+ * Inspects the Git boundary containing a path without executing Git or a shell.
+ * Malformed or unreadable metadata is distinct from an absent Git boundary.
+ */
+export declare function inspectGitResourceIdentity(targetPath: string): GitResourceIdentityInspection;
+/** Resolves only structurally valid Git metadata; otherwise returns null. */
+export declare function resolveGitResourceIdentity(targetPath: string): GitResourceIdentity | null;
+export declare function sameGitResourceIdentity(leftPath: string, rightPath: string): boolean;
+/** Protects control data for any proven repository and any malformed Git boundary. */
+export declare function isGitMetadataPath(targetPath: string, _repositoryPath?: string): boolean;