@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/config-io.js

@@ -1,8 +1,10 @@
+import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { chmod, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, open, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { getAdapterLayout } from './adapters/layouts/index.js';
 import { compactApprovals, isExpired, mergeApprovalStates } from './core/approval.js';
+import { mutateApprovalStateWithRetry } from './core/capability/approval-state-mutation.js';
 import { approvedApprovalsFile, belayStateDir, configuredControlPlaneDir, mergeConfig, pendingApprovalsFile, } from './core/config.js';
 import { resolveLayeredConfig, teamConfigPath, } from './core/config-layers.js';
 export function resolveAdapterName(config) {
@@ -49,6 +51,42 @@ const APPROVAL_STATE_FILES = ['pending-approvals.json', 'approved-approvals.json
 function approvalFilesExist(dir) {
     return APPROVAL_STATE_FILES.some((fileName) => existsSync(path.join(dir, fileName)));
 }
+async function isCorruptApprovalStateFile(filePath) {
+    const raw = await readFile(filePath, 'utf8');
+    try {
+        JSON.parse(raw);
+        return false;
+    }
+    catch (error) {
+        return error instanceof SyntaxError;
+    }
+}
+function normalizeApprovalStateFile(parsed) {
+    const version = parsed.version === 3 ? 3 : parsed.version === 2 ? 2 : 1;
+    return {
+        version,
+        revision: typeof parsed.revision === 'number' ? parsed.revision : undefined,
+        approvals: Array.isArray(parsed.approvals) ? parsed.approvals : [],
+    };
+}
+/** Gate reads: corrupt JSON is treated as empty state (fail-closed). */
+async function readApprovalStateFileForGate(filePath) {
+    const raw = await readFile(filePath, 'utf8');
+    try {
+        return normalizeApprovalStateFile(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return { version: 1, approvals: [] };
+        }
+        throw error;
+    }
+}
+/** Migration reads: corrupt JSON must not be treated as empty. */
+async function readApprovalStateFileStrict(filePath) {
+    const raw = await readFile(filePath, 'utf8');
+    return normalizeApprovalStateFile(JSON.parse(raw));
+}
 async function repoLocalApprovalsEmpty(repoRoot, config) {
     const repoLocalDir = repoLocalStateDirFor(repoRoot, config);
     if (!approvalFilesExist(repoLocalDir)) {
@@ -59,28 +97,43 @@ async function repoLocalApprovalsEmpty(repoRoot, config) {
         if (!existsSync(filePath)) {
             continue;
         }
-        const state = await readApprovalStateFile(filePath);
+        if (await isCorruptApprovalStateFile(filePath)) {
+            return false;
+        }
+        const state = await readApprovalStateFileForGate(filePath);
         if (state.approvals.length > 0) {
             return false;
         }
     }
     return true;
 }
-async function readApprovalStateFile(filePath) {
-    const raw = await readFile(filePath, 'utf8');
-    const parsed = JSON.parse(raw);
-    return {
-        version: parsed.version === 2 ? 2 : 1,
-        approvals: Array.isArray(parsed.approvals) ? parsed.approvals : [],
-    };
-}
 async function writeApprovalStateFile(filePath, state) {
-    await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
-    await writeFile(filePath, `${JSON.stringify(compactApprovals(state), null, 2)}\n`, {
-        encoding: 'utf8',
-        mode: 0o600,
-    });
-    await chmod(filePath, 0o600);
+    const directory = path.dirname(filePath);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const tempPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+    let handle = null;
+    try {
+        handle = await open(tempPath, 'wx', 0o600);
+        await handle.writeFile(`${JSON.stringify(compactApprovals(state), null, 2)}\n`, 'utf8');
+        await handle.sync();
+        await handle.close();
+        handle = null;
+        await rename(tempPath, filePath);
+        await chmod(filePath, 0o600);
+        const directoryHandle = await open(directory, 'r');
+        try {
+            await directoryHandle.sync().catch(() => undefined);
+        }
+        finally {
+            await directoryHandle.close();
+        }
+    }
+    finally {
+        if (handle) {
+            await handle.close().catch(() => undefined);
+        }
+        await unlink(tempPath).catch(() => undefined);
+    }
 }
 async function migrateApprovalFilesBetween(sourceDir, targetDir) {
     await mkdir(targetDir, { recursive: true, mode: 0o700 });
@@ -90,14 +143,29 @@ async function migrateApprovalFilesBetween(sourceDir, targetDir) {
         if (!existsSync(from)) {
             continue;
         }
-        if (!existsSync(to)) {
-            await copyFile(from, to);
-            await chmod(to, 0o600);
+        if ((await isCorruptApprovalStateFile(from)) ||
+            (existsSync(to) && (await isCorruptApprovalStateFile(to)))) {
             continue;
         }
-        const targetState = await readApprovalStateFile(to);
-        const sourceState = await readApprovalStateFile(from);
-        await writeApprovalStateFile(to, mergeApprovalStates(targetState, sourceState));
+        const sourceState = await readApprovalStateFileStrict(from);
+        const migrated = await mutateApprovalStateWithRetry({
+            load: async () => ({
+                filePath: to,
+                state: existsSync(to)
+                    ? await readApprovalStateFileStrict(to)
+                    : { version: 1, approvals: [] },
+            }),
+            write: writeApprovalStateFile,
+            mutate: (targetState) => ({
+                state: targetState.approvals.length === 0
+                    ? sourceState
+                    : mergeApprovalStates(targetState, sourceState),
+                result: true,
+            }),
+        });
+        if (migrated !== true) {
+            throw new Error(`Failed to migrate approval state to ${to}`);
+        }
     }
 }
 export async function migrateRepoLocalApprovalsToControlPlane(repoRoot, config) {
@@ -172,7 +240,7 @@ export async function loadApprovalState(repoRoot, fileName, config) {
     if (!existsSync(filePath)) {
         return { version: 1, approvals: [] };
     }
-    return readApprovalStateFile(filePath);
+    return readApprovalStateFileForGate(filePath);
 }
 export async function saveApprovalState(repoRoot, fileName, state, config) {
     const filePath = fileName === 'pending-approvals.json'

package/dist/conformance/guarantee-posture.d.ts

@@ -0,0 +1,21 @@
+import type { BoundaryAttestation } from '../core/capability/attestation.js';
+import type { BelayConfigV4 } from '../core/config.js';
+import type { LayerProfileId } from './types.js';
+export interface GuaranteePosture {
+    configuredProfile: LayerProfileId;
+    attestedProfile: LayerProfileId;
+    attestationFresh: boolean;
+    l1FullConfigured: boolean;
+    l1FullAttested: boolean;
+    postureMismatch: boolean;
+}
+export declare function resolveConfiguredProfile(config: BelayConfigV4, egressProxyRunning: boolean): LayerProfileId;
+export declare function resolveAttestedProfile(params: {
+    attestation: BoundaryAttestation | null;
+    l1FullConfigured: boolean;
+}): LayerProfileId;
+export declare function evaluateGuaranteePosture(params: {
+    config: BelayConfigV4;
+    attestation: BoundaryAttestation | null;
+    egressProxyRunning: boolean;
+}): GuaranteePosture;

package/dist/conformance/guarantee-posture.js

@@ -0,0 +1,46 @@
+import { isAttestationFresh } from '../core/capability/attestation.js';
+import { evaluateL1FullStatus } from '../core/capability/broker.js';
+export function resolveConfiguredProfile(config, egressProxyRunning) {
+    const l1Full = evaluateL1FullStatus({ config, egressProxyRunning });
+    if (l1Full.active) {
+        return 'l1-full';
+    }
+    if (config.egress.enabled) {
+        return 'l1-partial-egress';
+    }
+    if (config.policy.transactional.enabled) {
+        return 'l1-l2-transactional';
+    }
+    return 'l3-l4-only';
+}
+export function resolveAttestedProfile(params) {
+    if (!params.attestation || !isAttestationFresh(params.attestation)) {
+        return 'l3-l4-only';
+    }
+    if (params.l1FullConfigured &&
+        params.attestation.deniesUngrantedEffects &&
+        params.attestation.materializesGrants) {
+        return 'l1-full';
+    }
+    return 'l3-l4-only';
+}
+export function evaluateGuaranteePosture(params) {
+    const l1Full = evaluateL1FullStatus({
+        config: params.config,
+        egressProxyRunning: params.egressProxyRunning,
+    });
+    const configuredProfile = resolveConfiguredProfile(params.config, params.egressProxyRunning);
+    const attestedProfile = resolveAttestedProfile({
+        attestation: params.attestation,
+        l1FullConfigured: l1Full.active,
+    });
+    return {
+        configuredProfile,
+        attestedProfile,
+        attestationFresh: params.attestation ? isAttestationFresh(params.attestation) : false,
+        l1FullConfigured: l1Full.active,
+        l1FullAttested: attestedProfile === 'l1-full' &&
+            Boolean(params.attestation?.deniesUngrantedEffects && params.attestation.materializesGrants),
+        postureMismatch: configuredProfile === 'l1-full' && attestedProfile !== 'l1-full',
+    };
+}

package/dist/conformance/guarantee-table.d.ts

@@ -1,4 +1,5 @@
 import type { LayerConformanceScenario, LayerProfileId } from './types.js';
+export { evaluateGuaranteePosture, type GuaranteePosture } from './guarantee-posture.js';
 export type { LayerConformanceScenario, LayerProfileId } from './types.js';
 export interface GuaranteeTableRow {
     profile: LayerProfileId;

package/dist/conformance/guarantee-table.js

@@ -1,3 +1,4 @@
+export { evaluateGuaranteePosture } from './guarantee-posture.js';
 /** Normative rows — keep in sync with docs/guarantee-table.md */
 export const GUARANTEE_TABLE_ROWS = [
     {
@@ -33,9 +34,10 @@ export const GUARANTEE_SCENARIOS = {
             permission: 'allow',
         },
         {
-            id: 'l3-allow-read-egress',
+            id: 'l3-deny-read-egress',
             command: 'curl https://example.com',
-            permission: 'allow',
+            permission: 'deny',
+            reason: 'external_effect',
         },
     ],
     'l1-partial-egress': [
@@ -45,9 +47,10 @@ export const GUARANTEE_SCENARIOS = {
             permission: 'allow',
         },
         {
-            id: 'l1p-allow-read-egress',
+            id: 'l1p-deny-read-egress',
             command: 'curl https://example.com',
-            permission: 'allow',
+            permission: 'deny',
+            reason: 'external_effect',
         },
         {
             id: 'l1p-deny-write-egress',
@@ -63,9 +66,16 @@ export const GUARANTEE_SCENARIOS = {
             permission: 'allow',
         },
         {
-            id: 'l2-allow-read-egress',
-            command: 'curl https://example.com',
+            id: 'l2-allow-dirty-git-file-checkpoint',
+            command: 'touch notes.txt',
             permission: 'allow',
+            substrate: 'dirty_git_file_checkpoint',
+        },
+        {
+            id: 'l2-deny-read-egress',
+            command: 'curl https://example.com',
+            permission: 'deny',
+            reason: 'external_effect',
         },
     ],
     'l1-full': [
@@ -75,9 +85,10 @@ export const GUARANTEE_SCENARIOS = {
             permission: 'allow',
         },
         {
-            id: 'l1f-allow-read-egress',
+            id: 'l1f-deny-read-egress',
             command: 'curl https://example.com',
-            permission: 'allow',
+            permission: 'deny',
+            reason: 'external_effect',
         },
         {
             id: 'l1f-deny-write-egress',
@@ -90,7 +101,7 @@ export const GUARANTEE_SCENARIOS = {
             id: 'l1f-deny-outside-repo',
             command: 'echo hi > ../../outside.txt',
             permission: 'deny',
-            reason: 'outside_repo_redirect',
+            reason: 'outside_repo_mutation',
         },
         {
             id: 'l1f-deny-outside-repo-write',

package/dist/conformance/types.d.ts

@@ -5,4 +5,5 @@ export interface LayerConformanceScenario {
     reason?: string;
     kind?: 'shell' | 'tool';
     toolPayload?: Record<string, unknown>;
+    substrate?: 'clean_git_worktree' | 'dirty_git_file_checkpoint' | 'non_git_file_checkpoint';
 }

package/dist/core/approval-replay.d.ts

@@ -40,6 +40,6 @@ export declare function buildReplayEnvelopeFields(input: ReplayEnvelopeInput): P
 export declare function hasReplayEnvelope(approval: ApprovalRecord): boolean;
 export declare function validateReplayEnvelope(approval: ApprovalRecord, action: ReplayActionContext): boolean;
 export declare function canAutoReplay(config: BelayConfigV4, kind: ApprovalRecord['kind'], adapter?: ReplayAdapterId): boolean;
-export declare function buildRetryInstructionForConfig(config: BelayConfigV4, tokenPrefix: string, approvalId: string): string;
+export declare function buildRetryInstructionForConfig(config: BelayConfigV4, tokenPrefix: string, approvalId: string, kind?: ApprovalRecord['kind'], adapter?: ReplayAdapterId): string;
 export declare function buildApprovalRecordedMessage(config: BelayConfigV4, approval: ApprovalRecord, adapter?: ReplayAdapterId): string;
 export declare function buildReplayHint(config: BelayConfigV4, approval: ApprovalRecord, adapter?: ReplayAdapterId): ApprovalReplayHint | null;

package/dist/core/approval-replay.js

@@ -103,7 +103,10 @@ export function canAutoReplay(config, kind, adapter) {
     }
     return kind === 'shell' && scopes?.shell !== false;
 }
-export function buildRetryInstructionForConfig(config, tokenPrefix, approvalId) {
+export function buildRetryInstructionForConfig(config, tokenPrefix, approvalId, kind, adapter) {
+    if (kind === 'shell' && canAutoReplay(config, kind, adapter)) {
+        return `To approve and run this exact shell action once, send ${tokenPrefix} ${approvalId}. No follow-up prompt is required.`;
+    }
     if (approvalFlow(config) === 'one_step') {
         return `To allow this action once, send ${tokenPrefix} ${approvalId}. After approval, retry the same action unchanged.`;
     }

package/dist/core/approval-service.d.ts

@@ -26,11 +26,16 @@ export declare function recordApproval(params: {
     message: string;
     approval?: ApprovalStateFile['approvals'][number];
 }>;
-/** CLI `--replay` already executed the shell command; drop the one-shot grant. */
+/** @deprecated Replay callers must claim before execution with `claimApprovedForReplay`. */
 export declare function consumeApprovedAfterCliReplay(params: {
     approvalId: string;
     store: ApprovalStore;
 }): Promise<void>;
+/** Atomically spend and return a one-shot approval before executing its replay. */
+export declare function claimApprovedForReplay(params: {
+    approvalId: string;
+    store: ApprovalStore;
+}): Promise<ApprovalStateFile['approvals'][number] | null>;
 export declare function createGateApprovalStore(repoRoot: string, config: BelayConfigV3): ApprovalStore;
 export declare function gateApprovalStoreFromDeps(deps: {
     loadApprovals: (fileName: 'pending-approvals.json' | 'approved-approvals.json') => Promise<{

package/dist/core/approval-service.js

@@ -2,17 +2,25 @@ import { approvedApprovalsPath, loadApprovalState, pendingApprovalsPath, saveApp
 import { compactApprovals } from './approval.js';
 import { buildApprovalRecordedMessage } from './approval-replay.js';
 import { verifyApprovalToken } from './approval-token.js';
+import { mutateApprovalStateWithRetry, mutatePendingAndApprovedWithRetry, } from './capability/approval-state-mutation.js';
+import { APPROVAL_STATE_VERSION_V3, mintGrantForApprovedRecord } from './capability/approval-v3.js';
 import { configuredControlPlaneDir } from './config.js';
 export async function recordApproval(params) {
     const { approvalId, config, store, token, requireSignedToken = false, adapter } = params;
-    const pending = await store.loadPending();
+    const [pending, approved] = await Promise.all([store.loadPending(), store.loadApproved()]);
     pending.state = compactApprovals(pending.state);
-    const index = pending.state.approvals.findIndex((approval) => approval.approvalId === approvalId);
-    if (index === -1) {
-        await store.writePending(pending.filePath, pending.state);
+    approved.state = compactApprovals(approved.state);
+    const pendingApproval = pending.state.approvals.find((entry) => entry.approvalId === approvalId);
+    const approvedApproval = approved.state.approvals.find((entry) => entry.approvalId === approvalId);
+    const approval = pendingApproval ?? approvedApproval;
+    if (!approval) {
+        await mutateApprovalStateWithRetry({
+            load: store.loadPending,
+            write: store.writePending,
+            mutate: (state) => ({ state: compactApprovals(state), result: true }),
+        });
         return { ok: false, message: 'Belay approval not found or expired.' };
     }
-    const [approval] = pending.state.approvals.slice(index, index + 1);
     if (requireSignedToken) {
         if (!token) {
             return { ok: false, message: 'Signed approval token required for out-of-band approval.' };
@@ -26,31 +34,86 @@ export async function recordApproval(params) {
             return { ok: false, message: 'Signed approval token does not match the pending approval.' };
         }
     }
-    pending.state.approvals.splice(index, 1);
-    await store.writePending(pending.filePath, pending.state);
-    const approved = await store.loadApproved();
-    approved.state = compactApprovals(approved.state);
-    approved.state.approvals.push({
-        ...approval,
-        approvedAt: new Date().toISOString(),
+    if (!pendingApproval && approvedApproval) {
+        return {
+            ok: true,
+            message: buildApprovalRecordedMessage(config, approvedApproval, adapter),
+            approval: approvedApproval,
+        };
+    }
+    const recorded = await mutatePendingAndApprovedWithRetry({
+        loadPending: store.loadPending,
+        loadApproved: store.loadApproved,
+        writePending: store.writePending,
+        writeApproved: store.writeApproved,
+        mutate: (pendingState, approvedState) => {
+            const compactedPending = compactApprovals(pendingState);
+            const compactedApproved = compactApprovals(approvedState);
+            const existing = compactedApproved.approvals.find((entry) => entry.approvalId === approvalId);
+            if (existing &&
+                (existing.fingerprint !== approval.fingerprint || existing.repoRoot !== approval.repoRoot)) {
+                return null;
+            }
+            const pendingIndex = compactedPending.approvals.findIndex((entry) => entry.approvalId === approvalId &&
+                entry.fingerprint === approval.fingerprint &&
+                entry.repoRoot === approval.repoRoot);
+            if (pendingIndex === -1) {
+                return existing
+                    ? {
+                        pending: compactedPending,
+                        approved: compactedApproved,
+                        result: existing,
+                    }
+                    : null;
+            }
+            const [claimed] = compactedPending.approvals.splice(pendingIndex, 1);
+            if (!claimed) {
+                return null;
+            }
+            const approvedRecord = existing ??
+                mintGrantForApprovedRecord({
+                    ...claimed,
+                    approvedAt: new Date().toISOString(),
+                });
+            if (!existing) {
+                compactedApproved.version = APPROVAL_STATE_VERSION_V3;
+                compactedApproved.approvals.push(approvedRecord);
+            }
+            return {
+                pending: compactedPending,
+                approved: compactedApproved,
+                result: approvedRecord,
+            };
+        },
     });
-    await store.writeApproved(approved.filePath, approved.state);
+    if (!recorded) {
+        return { ok: false, message: 'Belay approval not found, expired, or already claimed.' };
+    }
     return {
         ok: true,
-        message: buildApprovalRecordedMessage(config, approval, adapter),
-        approval,
+        message: buildApprovalRecordedMessage(config, recorded, adapter),
+        approval: recorded,
     };
 }
-/** CLI `--replay` already executed the shell command; drop the one-shot grant. */
+/** @deprecated Replay callers must claim before execution with `claimApprovedForReplay`. */
 export async function consumeApprovedAfterCliReplay(params) {
-    const approved = await params.store.loadApproved();
-    approved.state = compactApprovals(approved.state);
-    const remaining = approved.state.approvals.filter((approval) => approval.approvalId !== params.approvalId);
-    if (remaining.length === approved.state.approvals.length) {
-        return;
-    }
-    approved.state.approvals = remaining;
-    await params.store.writeApproved(approved.filePath, approved.state);
+    await claimApprovedForReplay(params);
+}
+/** Atomically spend and return a one-shot approval before executing its replay. */
+export async function claimApprovedForReplay(params) {
+    return mutateApprovalStateWithRetry({
+        load: params.store.loadApproved,
+        write: params.store.writeApproved,
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const index = compacted.approvals.findIndex((approval) => approval.approvalId === params.approvalId);
+            if (index === -1) {
+                return null;
+            }
+            const [claimed] = compacted.approvals.splice(index, 1);
+            return { state: compacted, result: claimed ?? null };
+        },
+    });
 }
 export function createGateApprovalStore(repoRoot, config) {
     return {

package/dist/core/approval.d.ts

@@ -24,6 +24,8 @@ export declare function createApprovalRecordWithEnvelope(params: {
         payload?: Record<string, unknown>;
     };
     scopeHint?: ApprovalRecord['scopeHint'];
+    capabilityRequests?: ApprovalRecord['capabilityRequests'];
+    effectPlanHash?: string;
 }): ApprovalRecord;
 export declare function createApprovalRecord(params: {
     kind: ApprovalRecord['kind'];
@@ -40,4 +42,6 @@ export declare function createApprovalRecord(params: {
     payloadHash?: string;
     payloadJson?: string;
     scopeHint?: ApprovalRecord['scopeHint'];
+    capabilityRequests?: ApprovalRecord['capabilityRequests'];
+    effectPlanHash?: string;
 }): ApprovalRecord;

package/dist/core/approval.js

@@ -1,4 +1,5 @@
 import { buildReplayEnvelopeFields } from './approval-replay.js';
+import { attachCapabilityEnvelope } from './capability/approval-v3.js';
 import { DEFAULT_APPROVAL_CONFIG } from './config.js';
 /** @deprecated Use `DEFAULT_APPROVAL_CONFIG.executionLeaseMs` */
 export const APPROVAL_EXECUTION_LEASE_MS = DEFAULT_APPROVAL_CONFIG.executionLeaseMs;
@@ -6,19 +7,25 @@ export function nowIso() {
     return new Date().toISOString();
 }
 export function isExpired(approval) {
-    return Date.parse(approval.expiresAt) <= Date.now();
+    const expiresAt = Date.parse(approval.expiresAt);
+    return !Number.isFinite(expiresAt) || expiresAt <= Date.now();
 }
 export function isExecutionLeaseExpired(approval) {
     if (!approval.executionLeaseExpiresAt) {
         return false;
     }
-    return Date.parse(approval.executionLeaseExpiresAt) <= Date.now();
+    const expiresAt = Date.parse(approval.executionLeaseExpiresAt);
+    return !Number.isFinite(expiresAt) || expiresAt <= Date.now();
 }
 export function compactApprovals(state) {
-    return {
+    const compacted = {
         version: state.version,
         approvals: state.approvals.filter((approval) => !isExpired(approval) && !isExecutionLeaseExpired(approval)),
     };
+    if (state.revision !== undefined) {
+        compacted.revision = state.revision;
+    }
+    return compacted;
 }
 export function mergeApprovalStates(target, source) {
     const byId = new Map();
@@ -31,7 +38,12 @@ export function mergeApprovalStates(target, source) {
         }
     }
     return compactApprovals({
-        version: target.version === 2 || source.version === 2 ? 2 : 1,
+        version: target.version === 3 || source.version === 3
+            ? 3
+            : target.version === 2 || source.version === 2
+                ? 2
+                : 1,
+        revision: Math.max(target.revision ?? 0, source.revision ?? 0),
         approvals: [...byId.values()],
     });
 }
@@ -78,6 +90,8 @@ export function createApprovalRecordWithEnvelope(params) {
         payloadHash: envelope.payloadHash,
         payloadJson: envelope.payloadJson,
         scopeHint: params.scopeHint,
+        capabilityRequests: params.capabilityRequests,
+        effectPlanHash: params.effectPlanHash,
     });
 }
 export function createApprovalRecord(params) {
@@ -112,5 +126,5 @@ export function createApprovalRecord(params) {
     if (params.scopeHint) {
         record.scopeHint = params.scopeHint;
     }
-    return record;
+    return attachCapabilityEnvelope(record, params.capabilityRequests, params.effectPlanHash);
 }

package/dist/core/audit-types.d.ts

@@ -20,10 +20,23 @@ export interface AuditRecord {
     predictedAssessment?: Assessment;
     observedAssessment?: Assessment;
     transactional?: boolean;
+    transactionalBackend?: 'git_worktree' | 'file_checkpoint';
+    resourceKind?: 'git_repository' | 'directory';
+    baselineTreeHash?: string;
+    snapshotFileCount?: number;
+    snapshotSourceBytes?: number;
+    snapshotWorkspaceBytes?: number;
+    snapshotCopyStrategy?: 'clonefile' | 'reflink' | 'copy';
+    snapshotPrepareMs?: number;
     transactionalReason?: string;
     transactionalCategories?: string[];
     transactionalChangeCount?: number;
     transactionalSkipReason?: string;
+    transactionalSkipDetail?: string;
+    recoveryCheckpointId?: string;
+    recoveryBackend?: string;
+    recoveryProofHash?: string;
+    recoveryState?: string;
     replayContext?: AuditReplayContext;
     actionSnapshot?: AuditActionSnapshot;
     [key: string]: unknown;

package/dist/core/capability/approval-state-mutation.d.ts

@@ -0,0 +1,32 @@
+import type { ApprovalStateFile } from '../types.js';
+export declare function withStateFileLock<T>(filePath: string, operation: () => Promise<T>, maxRetries?: number): Promise<T>;
+export declare function mutateApprovalStateWithRetry<T>(params: {
+    load: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    write: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    mutate: (state: ApprovalStateFile) => {
+        state: ApprovalStateFile;
+        result: T;
+    } | null;
+    maxRetries?: number;
+}): Promise<T | null>;
+export declare function mutatePendingAndApprovedWithRetry<T>(params: {
+    loadPending: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    loadApproved: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    writePending: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    writeApproved: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    mutate: (pending: ApprovalStateFile, approved: ApprovalStateFile) => {
+        pending: ApprovalStateFile;
+        approved: ApprovalStateFile;
+        result: T;
+    } | null;
+    maxRetries?: number;
+}): Promise<T | null>;