@codapult/guard 0.3.0 → 0.5.0

package/dist/core/guard.js

@@ -1,5 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { dirname, extname, relative, resolve, sep } from 'node:path';
 import { Project, SyntaxKind } from 'ts-morph';
@@ -29,10 +30,20 @@ export const GUARD_CONVENTIONS_FILE = `${GUARD_DIR}/conventions.json`;
 export const GUARD_AGENT_FILE = `${GUARD_DIR}/agent.json`;
 export const GUARD_CONTRACTS_FILE = `${GUARD_DIR}/contracts.json`;
 export const GUARD_PROPOSALS_FILE = `${GUARD_DIR}/proposals.json`;
+export const GUARD_STATE_DIR = `${GUARD_DIR}/state`;
+export const GUARD_STATE_GENERATIONS_DIR = `${GUARD_STATE_DIR}/generations`;
+export const GUARD_STATE_CURRENT_FILE = `${GUARD_STATE_DIR}/current.json`;
+const GUARD_POLICY_TRANSACTION_FILE = `${GUARD_STATE_DIR}/policy-transaction.json`;
+const GUARD_STATE_LOCK_FILE = `${GUARD_DIR}/.state.lock`;
 export const defaultGuardConfig = {
     version: 1,
     rules: [],
     contracts: [],
+    approval: {
+        mode: 'local',
+        allowMcpApproval: true,
+        requireDistinctActor: false,
+    },
 };
 export const defaultGuardAgentConfig = {
     version: 1,
@@ -63,6 +74,142 @@ export class GuardStateBusyError extends Error {
         this.name = 'GuardStateBusyError';
     }
 }
+export class GuardStateStaleError extends Error {
+    constructor() {
+        super('Guard state changed while this operation was running.');
+        this.name = 'GuardStateStaleError';
+    }
+}
+export class GuardBaselineReasonError extends Error {
+    constructor() {
+        super('A reason is required when changing the Guard baseline.');
+        this.name = 'GuardBaselineReasonError';
+    }
+}
+const activeStateLocks = new Map();
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function sleepSync(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+function removeLockFile(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Lock cleanup is best effort. A later invocation can recover an orphaned lock by PID.
+    }
+}
+function readStateLock(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        const hasValidDate = (candidate) => typeof candidate === 'string' && Number.isFinite(Date.parse(candidate));
+        return Number.isInteger(value.pid) &&
+            value.pid > 0 &&
+            typeof value.hostname === 'string' &&
+            value.hostname.length > 0 &&
+            typeof value.command === 'string' &&
+            typeof value.token === 'string' &&
+            value.token.length > 0 &&
+            hasValidDate(value.createdAt) &&
+            hasValidDate(value.expiresAt)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getActiveStateRoot(path) {
+    const normalizedPath = resolve(path);
+    return [...activeStateLocks.keys()]
+        .filter((root) => normalizedPath === root || normalizedPath.startsWith(`${root}${sep}`))
+        .sort((left, right) => right.length - left.length)[0];
+}
+function safeGeneration(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9._-]+$/.test(value);
+}
+export function withGuardStateLock(root, callback, options = {}) {
+    const normalizedRoot = resolve(root);
+    const activeDepth = activeStateLocks.get(normalizedRoot);
+    if (activeDepth !== undefined) {
+        activeStateLocks.set(normalizedRoot, activeDepth + 1);
+        try {
+            return callback();
+        }
+        finally {
+            activeStateLocks.set(normalizedRoot, activeDepth);
+        }
+    }
+    const lockPath = resolve(normalizedRoot, GUARD_STATE_LOCK_FILE);
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const startedAt = Date.now();
+    const waitMs = options.noWait ? 0 : (options.waitMs ?? 30_000);
+    let lock;
+    let delay = 25;
+    while (!lock) {
+        const now = new Date();
+        const candidate = {
+            pid: process.pid,
+            hostname: hostname(),
+            command: process.argv.join(' '),
+            token: randomUUID(),
+            createdAt: now.toISOString(),
+            expiresAt: new Date(now.getTime() + 300_000).toISOString(),
+        };
+        try {
+            writeFileSync(lockPath, `${JSON.stringify(candidate)}\n`, { encoding: 'utf8', flag: 'wx' });
+            lock = candidate;
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const owner = readStateLock(lockPath);
+            const ownerDead = owner?.hostname === hostname() && !processIsAlive(owner.pid);
+            let malformedStale = false;
+            if (owner === undefined) {
+                try {
+                    malformedStale = Date.now() - statSync(lockPath).mtimeMs > 60_000;
+                }
+                catch {
+                    // The lock disappeared between the failed create and stat.
+                }
+            }
+            if (ownerDead || malformedStale) {
+                try {
+                    unlinkSync(lockPath);
+                    continue;
+                }
+                catch {
+                    // The owner or another waiter changed the lock; retry normally.
+                }
+            }
+            if (Date.now() - startedAt >= waitMs)
+                throw new GuardStateBusyError(lockPath);
+            sleepSync(Math.min(delay, Math.max(1, waitMs - (Date.now() - startedAt))));
+            delay = Math.min(delay * 2, 500);
+        }
+    }
+    activeStateLocks.set(normalizedRoot, 1);
+    try {
+        return callback();
+    }
+    finally {
+        activeStateLocks.delete(normalizedRoot);
+        const current = readStateLock(lockPath);
+        if (current?.token === lock.token) {
+            removeLockFile(lockPath);
+        }
+    }
+}
 function isGuardConfig(value) {
     return guardConfigSchema.safeParse(value).success;
 }
@@ -75,6 +222,12 @@ function readJson(filePath) {
     }
 }
 function atomicWriteFile(path, content) {
+    if (getActiveStateRoot(path) !== undefined) {
+        const temporaryPath = `${path}.tmp-${process.pid}-${randomUUID()}`;
+        writeFileSync(temporaryPath, content, 'utf8');
+        renameSync(temporaryPath, path);
+        return;
+    }
     const lockPath = `${path}.lock`;
     let lockAcquired = false;
     try {
@@ -103,14 +256,18 @@ function atomicWriteFile(path, content) {
         renameSync(temporaryPath, path);
     }
     finally {
-        if (lockAcquired)
-            unlinkSync(lockPath);
+        if (lockAcquired) {
+            removeLockFile(lockPath);
+        }
     }
 }
-function writeGuardArtifact(root, relativePath, value) {
+function writeGuardArtifactUnlocked(root, relativePath, value) {
     mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
     atomicWriteFile(resolve(root, relativePath), `${JSON.stringify(value, null, 2)}\n`);
 }
+function writeGuardArtifact(root, relativePath, value) {
+    withGuardStateLock(root, () => writeGuardArtifactUnlocked(root, relativePath, value));
+}
 function hasProjectTool(model, name) {
     return (Object.keys({ ...model.project.dependencies, ...model.project.devDependencies }).some((dependency) => dependency === name || dependency.endsWith(`/${name}`)) || Object.values(model.project.scripts).some((script) => script.includes(name)));
 }
@@ -143,12 +300,22 @@ export function isGuardProposalFile(value) {
 export function fingerprintProjectModel(model) {
     return createHash('sha256').update(JSON.stringify(model)).digest('hex');
 }
+export function fingerprintGuardConfig(guardConfig) {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        rules: guardConfig.rules,
+        contracts: guardConfig.contracts ?? [],
+        budgets: guardConfig.budgets ?? [],
+        approval: guardConfig.approval ?? defaultGuardConfig.approval,
+    }))
+        .digest('hex');
+}
 export function getGuardProposalFreshness(model, proposals) {
     if (!proposals?.projectFingerprint)
         return 'unknown';
     return proposals.projectFingerprint === fingerprintProjectModel(model) ? 'current' : 'stale';
 }
-export function loadGuardConfig(root) {
+function readGuardConfigFilesUnlocked(root) {
     const rulesPath = resolve(root, GUARD_RULES_FILE);
     if (!existsSync(rulesPath))
         return undefined;
@@ -160,89 +327,218 @@ export function loadGuardConfig(root) {
         const contractFile = readJson(contractsPath);
         if (!isGuardContractsFile(contractFile))
             throw new GuardConfigError(GUARD_CONTRACTS_FILE);
-        return { ...value, contracts: contractFile.contracts };
+        return {
+            ...value,
+            contracts: contractFile.contracts,
+            budgets: value.budgets ?? [],
+            approval: value.approval ?? defaultGuardConfig.approval,
+        };
     }
     return {
         ...value,
         contracts: value.contracts ?? [],
+        budgets: value.budgets ?? [],
+        approval: value.approval ?? defaultGuardConfig.approval,
     };
 }
+function isGuardPolicyTransaction(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const transaction = value;
+    return (transaction.version === 1 &&
+        typeof transaction.createdAt === 'string' &&
+        isGuardConfig(transaction.config) &&
+        (transaction.proposals === undefined || isGuardProposalFile(transaction.proposals)));
+}
+function writeGuardConfigUnlocked(root, guardConfig, options = {}) {
+    mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
+    const current = readGuardConfigFilesUnlocked(root);
+    const currentRevision = current?.revision ?? 0;
+    const expectedRevision = options.expectedRevision ?? guardConfig.revision;
+    if (expectedRevision !== undefined && expectedRevision !== currentRevision) {
+        throw new GuardStateStaleError();
+    }
+    const nextRevision = currentRevision + 1;
+    const contentFingerprint = fingerprintGuardConfig(guardConfig);
+    const { contracts = [], ...rulesConfig } = guardConfig;
+    atomicWriteFile(resolve(root, GUARD_RULES_FILE), `${JSON.stringify({ ...rulesConfig, revision: nextRevision, contentFingerprint }, null, 2)}\n`);
+    atomicWriteFile(resolve(root, GUARD_CONTRACTS_FILE), `${JSON.stringify({ version: 1, contracts }, null, 2)}\n`);
+}
+function recoverGuardPolicyTransaction(root) {
+    const path = resolve(root, GUARD_POLICY_TRANSACTION_FILE);
+    if (!existsSync(path))
+        return;
+    const value = readJson(path);
+    if (!isGuardPolicyTransaction(value)) {
+        throw new GuardConfigError(GUARD_POLICY_TRANSACTION_FILE);
+    }
+    writeGuardConfigUnlocked(root, value.config);
+    if (value.proposals) {
+        writeGuardArtifactUnlocked(root, GUARD_PROPOSALS_FILE, value.proposals);
+    }
+    unlinkSync(path);
+}
+function loadGuardConfigUnlocked(root) {
+    recoverGuardPolicyTransaction(root);
+    return readGuardConfigFilesUnlocked(root);
+}
+export function loadGuardConfig(root) {
+    if (!existsSync(resolve(root, GUARD_DIR)))
+        return loadGuardConfigUnlocked(root);
+    return withGuardStateLock(root, () => loadGuardConfigUnlocked(root));
+}
+function loadGuardProposalsUnlocked(root) {
+    const path = resolve(root, GUARD_PROPOSALS_FILE);
+    if (!existsSync(path))
+        return undefined;
+    const value = readJson(path);
+    if (value === undefined || !isGuardProposalFile(value)) {
+        throw new GuardConfigError(GUARD_PROPOSALS_FILE);
+    }
+    return value;
+}
 export function loadGuardProposals(root) {
-    const value = readJson(resolve(root, GUARD_PROPOSALS_FILE));
-    return isGuardProposalFile(value) ? value : undefined;
+    if (!existsSync(resolve(root, GUARD_DIR)))
+        return loadGuardProposalsUnlocked(root);
+    return withGuardStateLock(root, () => {
+        recoverGuardPolicyTransaction(root);
+        return loadGuardProposalsUnlocked(root);
+    });
 }
 export function isGuardAgentConfig(value) {
     return guardAgentConfigSchema.safeParse(value).success;
 }
 export function loadGuardAgentConfig(root) {
-    const value = readJson(resolve(root, GUARD_AGENT_FILE));
-    return isGuardAgentConfig(value) ? value : defaultGuardAgentConfig;
+    const path = resolve(root, GUARD_AGENT_FILE);
+    if (!existsSync(path))
+        return defaultGuardAgentConfig;
+    const value = readJson(path);
+    if (!isGuardAgentConfig(value))
+        throw new GuardConfigError(GUARD_AGENT_FILE);
+    return value;
 }
 export function writeGuardAgentConfig(root, agentConfig = defaultGuardAgentConfig) {
     writeGuardArtifact(root, GUARD_AGENT_FILE, agentConfig);
 }
 export function loadBaseline(root) {
-    const value = readJson(resolve(root, GUARD_BASELINE_FILE));
-    if (!Array.isArray(value))
+    const path = resolve(root, GUARD_BASELINE_FILE);
+    if (!existsSync(path))
         return new Set();
+    const value = readJson(path);
+    if (!Array.isArray(value))
+        throw new GuardConfigError(GUARD_BASELINE_FILE);
     return new Set(value.filter((item) => typeof item === 'string'));
 }
 export function updateBaseline(root, options = {}) {
-    const next = loadBaseline(root);
-    for (const fingerprint of options.add ?? [])
-        next.add(fingerprint);
-    for (const fingerprint of options.remove ?? [])
-        next.delete(fingerprint);
-    const fingerprints = [...next].sort();
-    const metadataPath = resolve(root, GUARD_BASELINE_META_FILE);
-    const previous = readJson(metadataPath);
-    const history = previous !== null &&
-        typeof previous === 'object' &&
-        Array.isArray(previous.decisions)
-        ? previous.decisions
-        : [];
-    const decision = {
-        at: new Date().toISOString(),
-        action: (options.add?.length ?? 0) > 0 ? 'accept' : 'remove',
-        fingerprints: [...(options.add ?? []), ...(options.remove ?? [])],
-        ...(options.reason?.trim() ? { reason: options.reason.trim() } : {}),
-    };
-    atomicWriteFile(resolve(root, GUARD_BASELINE_FILE), `${JSON.stringify(fingerprints, null, 2)}\n`);
-    atomicWriteFile(metadataPath, `${JSON.stringify({
-        ...(previous !== null && typeof previous === 'object' ? previous : {}),
-        version: 1,
-        generatedAt: new Date().toISOString(),
-        findings: fingerprints.length,
-        decisions: [...history, decision],
-    }, null, 2)}\n`);
-    return next;
+    if ((options.add?.length ?? 0) > 0 || (options.remove?.length ?? 0) > 0) {
+        if (!options.reason?.trim())
+            throw new GuardBaselineReasonError();
+    }
+    return withGuardStateLock(root, () => {
+        const next = loadBaseline(root);
+        for (const fingerprint of options.add ?? [])
+            next.add(fingerprint);
+        for (const fingerprint of options.remove ?? [])
+            next.delete(fingerprint);
+        const fingerprints = [...next].sort();
+        const metadataPath = resolve(root, GUARD_BASELINE_META_FILE);
+        const previous = readJson(metadataPath);
+        const history = previous !== null &&
+            typeof previous === 'object' &&
+            Array.isArray(previous.decisions)
+            ? previous.decisions
+            : [];
+        const decision = {
+            at: new Date().toISOString(),
+            action: (options.add?.length ?? 0) > 0 ? 'accept' : 'remove',
+            fingerprints: [...(options.add ?? []), ...(options.remove ?? [])],
+            ...(options.reason?.trim() ? { reason: options.reason.trim() } : {}),
+        };
+        atomicWriteFile(resolve(root, GUARD_BASELINE_FILE), `${JSON.stringify(fingerprints, null, 2)}\n`);
+        atomicWriteFile(metadataPath, `${JSON.stringify({
+            ...(previous !== null && typeof previous === 'object' ? previous : {}),
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            findings: fingerprints.length,
+            decisions: [...history, decision],
+        }, null, 2)}\n`);
+        return next;
+    });
 }
-export function writeGuardConfig(root, guardConfig) {
-    mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
-    const { contracts = [], ...rulesConfig } = guardConfig;
-    atomicWriteFile(resolve(root, GUARD_RULES_FILE), `${JSON.stringify(rulesConfig, null, 2)}\n`);
-    atomicWriteFile(resolve(root, GUARD_CONTRACTS_FILE), `${JSON.stringify({ version: 1, contracts }, null, 2)}\n`);
+export function writeGuardConfig(root, guardConfig, options = {}) {
+    withGuardStateLock(root, () => writeGuardConfigUnlocked(root, guardConfig, options), options);
 }
 export function writeGuardProposals(root, proposals) {
     writeGuardArtifact(root, GUARD_PROPOSALS_FILE, proposals);
 }
-export function recordGuardProposalDecision(root, decisions) {
-    const proposals = loadGuardProposals(root);
+function buildGuardProposalWithDecisionsUnlocked(root, decisions, options) {
+    const proposals = loadGuardProposalsUnlocked(root);
     if (!proposals || decisions.length === 0)
         return;
     const decidedAt = new Date().toISOString();
+    const commit = (() => {
+        try {
+            return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, stdio: 'pipe' })
+                .toString()
+                .trim();
+        }
+        catch {
+            return undefined;
+        }
+    })();
     const nextDecisions = decisions.map((decision) => ({
         ...decision,
         decidedAt,
+        source: options.source,
+        ...(process.env.GUARD_APPROVER?.trim() ? { actor: process.env.GUARD_APPROVER.trim() } : {}),
+        ...(commit ? { commit } : {}),
         ...(proposals.proposalId ? { proposalId: proposals.proposalId } : {}),
         ...(proposals.contentFingerprint ? { proposalFingerprint: proposals.contentFingerprint } : {}),
         ...(typeof proposals.revision === 'number' ? { revision: proposals.revision } : {}),
     }));
-    writeGuardProposals(root, {
+    return {
         ...proposals,
         decisions: [...(proposals.decisions ?? []), ...nextDecisions],
+    };
+}
+function appendGuardProposalDecisionsUnlocked(root, decisions, options) {
+    const proposals = buildGuardProposalWithDecisionsUnlocked(root, decisions, options);
+    if (!proposals)
+        return;
+    writeGuardArtifactUnlocked(root, GUARD_PROPOSALS_FILE, proposals);
+}
+export function recordGuardProposalDecision(root, decisions, options = { source: 'external' }) {
+    withGuardStateLock(root, () => {
+        appendGuardProposalDecisionsUnlocked(root, decisions, options);
+    });
+}
+export function applyGuardProposalDecision(root, guardConfig, decisions, options) {
+    withGuardStateLock(root, () => {
+        const proposals = buildGuardProposalWithDecisionsUnlocked(root, decisions, options);
+        writeGuardArtifactUnlocked(root, GUARD_POLICY_TRANSACTION_FILE, {
+            version: 1,
+            createdAt: new Date().toISOString(),
+            config: guardConfig,
+            ...(proposals ? { proposals } : {}),
+        });
+        writeGuardConfigUnlocked(root, guardConfig);
+        if (proposals)
+            writeGuardArtifactUnlocked(root, GUARD_PROPOSALS_FILE, proposals);
+        unlinkSync(resolve(root, GUARD_POLICY_TRANSACTION_FILE));
     });
 }
+export function validateGuardProposalApproval(policy, proposals) {
+    if (policy?.mode !== 'protected' || !policy.requireDistinctActor)
+        return undefined;
+    const actor = process.env.GUARD_APPROVER?.trim();
+    if (!actor) {
+        return 'Protected Guard policy requires GUARD_APPROVER for a distinct approval actor.';
+    }
+    if (proposals?.generatedBy && proposals.generatedBy === actor) {
+        return 'The proposal author and approval actor must be different.';
+    }
+    return undefined;
+}
 export function getPendingGuardProposals(proposals) {
     if (!proposals)
         return [];
@@ -315,6 +611,9 @@ export function buildGuardProposals(model, guardConfig) {
     const proposal = {
         version: 1,
         generatedAt: new Date().toISOString(),
+        ...(process.env.GUARD_PROPOSER?.trim()
+            ? { generatedBy: process.env.GUARD_PROPOSER.trim() }
+            : {}),
         rules: guardConfig.rules.filter((rule) => rule.status === 'proposed'),
         contracts: [
             ...(guardConfig.contracts ?? []).filter((contract) => contract.status === 'proposed'),
@@ -443,23 +742,37 @@ export function buildGeneratedGuardConfig(model) {
     return { ...defaultGuardConfig, rules: proposedRules };
 }
 export function writeGuardMemory(root, model) {
-    writeGuardArtifact(root, GUARD_ARCHITECTURE_FILE, buildArchitectureMemory(model));
-    writeGuardArtifact(root, GUARD_CONVENTIONS_FILE, buildConventionsMemory(model));
+    withGuardStateLock(root, () => {
+        writeGuardArtifact(root, GUARD_ARCHITECTURE_FILE, buildArchitectureMemory(model));
+        writeGuardArtifact(root, GUARD_CONVENTIONS_FILE, buildConventionsMemory(model));
+    });
 }
 export function writeBaseline(root, findings, model) {
-    mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
-    const fingerprints = [...new Set(findings.map((finding) => finding.fingerprint))].sort();
-    atomicWriteFile(resolve(root, GUARD_BASELINE_FILE), `${JSON.stringify(fingerprints, null, 2)}\n`);
-    atomicWriteFile(resolve(root, GUARD_BASELINE_META_FILE), `${JSON.stringify({
-        version: 1,
-        generatedAt: new Date().toISOString(),
-        findings: fingerprints.length,
-        ...(model ? { projectFingerprint: fingerprintProjectModel(model) } : {}),
-        guardSchemaVersion: 1,
-        purpose: 'Initial Guard state; findings are suppressed unless they change fingerprint.',
-    }, null, 2)}\n`);
+    withGuardStateLock(root, () => {
+        mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
+        const fingerprints = [...new Set(findings.map((finding) => finding.fingerprint))].sort();
+        atomicWriteFile(resolve(root, GUARD_BASELINE_FILE), `${JSON.stringify(fingerprints, null, 2)}\n`);
+        atomicWriteFile(resolve(root, GUARD_BASELINE_META_FILE), `${JSON.stringify({
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            findings: fingerprints.length,
+            ...(model ? { projectFingerprint: fingerprintProjectModel(model) } : {}),
+            guardSchemaVersion: 1,
+            purpose: 'Initial Guard state; findings are suppressed unless they change fingerprint.',
+        }, null, 2)}\n`);
+    });
 }
 export function loadProjectModel(root) {
+    const current = readJson(resolve(root, GUARD_STATE_CURRENT_FILE));
+    if (current !== undefined &&
+        typeof current === 'object' &&
+        safeGeneration(current.generation)) {
+        const generated = readJson(resolve(root, GUARD_STATE_GENERATIONS_DIR, current.generation, 'project.json'));
+        if (generated !== undefined &&
+            typeof generated === 'object' &&
+            generated.version === 1)
+            return generated;
+    }
     const value = readJson(resolve(root, GUARD_PROJECT_FILE));
     if (value === null ||
         typeof value !== 'object' ||
@@ -469,8 +782,40 @@ export function loadProjectModel(root) {
     return value;
 }
 export function writeProjectModel(root, model) {
-    mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
-    atomicWriteFile(resolve(root, GUARD_PROJECT_FILE), `${JSON.stringify(model, null, 2)}\n`);
+    withGuardStateLock(root, () => {
+        mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
+        atomicWriteFile(resolve(root, GUARD_PROJECT_FILE), `${JSON.stringify(model, null, 2)}\n`);
+    });
+}
+/**
+ * Persist all derived project facts as one generation. Legacy root-level files remain as
+ * compatibility mirrors, while readers that understand generations always see a coherent set.
+ */
+export function writeProjectState(root, model, options = {}) {
+    return withGuardStateLock(root, () => {
+        const generationsRoot = resolve(root, GUARD_STATE_GENERATIONS_DIR);
+        mkdirSync(generationsRoot, { recursive: true });
+        const generation = `${Date.now()}-${randomUUID()}`;
+        const temporaryRoot = resolve(generationsRoot, `.tmp-${process.pid}-${randomUUID()}`);
+        mkdirSync(temporaryRoot, { recursive: true });
+        const derived = {
+            project: model,
+            architecture: buildArchitectureMemory(model),
+            conventions: buildConventionsMemory(model),
+        };
+        for (const [name, value] of Object.entries(derived)) {
+            writeFileSync(resolve(temporaryRoot, `${name}.json`), `${JSON.stringify(value, null, 2)}\n`);
+        }
+        writeFileSync(resolve(temporaryRoot, 'manifest.json'), `${JSON.stringify({ version: 1, generation, projectFingerprint: fingerprintProjectModel(model) }, null, 2)}\n`);
+        renameSync(temporaryRoot, resolve(generationsRoot, generation));
+        atomicWriteFile(resolve(root, GUARD_STATE_CURRENT_FILE), `${JSON.stringify({ version: 1, generation, projectFingerprint: fingerprintProjectModel(model) }, null, 2)}\n`);
+        atomicWriteFile(resolve(root, GUARD_PROJECT_FILE), `${JSON.stringify(model, null, 2)}\n`);
+        atomicWriteFile(resolve(root, GUARD_ARCHITECTURE_FILE), `${JSON.stringify(derived.architecture, null, 2)}\n`);
+        atomicWriteFile(resolve(root, GUARD_CONVENTIONS_FILE), `${JSON.stringify(derived.conventions, null, 2)}\n`);
+        // Snapshot persistence is defined below the generation writer to keep the public API grouped.
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        return writeProjectSnapshot(root, model);
+    }, options);
 }
 function projectRevision(root) {
     try {
@@ -484,16 +829,18 @@ function projectRevision(root) {
     }
 }
 export function writeProjectSnapshot(root, model) {
-    const baseRevision = projectRevision(root);
-    const revision = model.git.dirty && baseRevision !== 'working-tree'
-        ? `${baseRevision}-working-tree-${createHash('sha256')
-            .update(JSON.stringify(model))
-            .digest('hex')
-            .slice(0, 12)}`
-        : baseRevision;
-    mkdirSync(resolve(root, GUARD_HISTORY_DIR), { recursive: true });
-    atomicWriteFile(resolve(root, GUARD_HISTORY_DIR, `${revision}.json`), `${JSON.stringify(model, null, 2)}\n`);
-    return revision;
+    return withGuardStateLock(root, () => {
+        const baseRevision = projectRevision(root);
+        const revision = model.git.dirty && baseRevision !== 'working-tree'
+            ? `${baseRevision}-working-tree-${createHash('sha256')
+                .update(JSON.stringify(model))
+                .digest('hex')
+                .slice(0, 12)}`
+            : baseRevision;
+        mkdirSync(resolve(root, GUARD_HISTORY_DIR), { recursive: true });
+        atomicWriteFile(resolve(root, GUARD_HISTORY_DIR, `${revision}.json`), `${JSON.stringify(model, null, 2)}\n`);
+        return revision;
+    });
 }
 function isProjectPath(root, value) {
     const normalized = value.replace(/\\/g, '/');
@@ -519,6 +866,23 @@ function isProjectPath(root, value) {
 export function loadGuardArtifact(root, relativePath) {
     if (!isProjectPath(root, relativePath))
         return undefined;
+    const generatedName = relativePath === GUARD_PROJECT_FILE
+        ? 'project.json'
+        : relativePath === GUARD_ARCHITECTURE_FILE
+            ? 'architecture.json'
+            : relativePath === GUARD_CONVENTIONS_FILE
+                ? 'conventions.json'
+                : undefined;
+    if (generatedName) {
+        const current = readJson(resolve(root, GUARD_STATE_CURRENT_FILE));
+        if (current !== undefined &&
+            typeof current === 'object' &&
+            safeGeneration(current.generation)) {
+            const generated = readJson(resolve(root, GUARD_STATE_GENERATIONS_DIR, current.generation, generatedName));
+            if (generated !== undefined)
+                return generated;
+        }
+    }
     return readJson(resolve(root, relativePath));
 }
 export function validateGuardContracts(root, contracts = []) {
@@ -595,6 +959,51 @@ export function validateGuardContracts(root, contracts = []) {
     }
     return issues;
 }
+export function validateGuardBudgets(root, budgets = []) {
+    const issues = [];
+    for (const budget of budgets) {
+        if (!budget.reason.trim()) {
+            issues.push({
+                contractId: `budget:${budget.id}`,
+                field: 'definition',
+                value: budget.id,
+                message: 'Budgets require a written reason.',
+            });
+        }
+        for (const rawScope of budget.scope) {
+            const scope = rawScope.replace(/\*+$/, '') || '.';
+            if (!isProjectPath(root, scope) || !existsSync(resolve(root, scope))) {
+                issues.push({
+                    contractId: `budget:${budget.id}`,
+                    field: 'scope',
+                    value: rawScope,
+                    message: `Budget scope does not exist inside the project: ${rawScope}`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+export function validateGuardPolicy(root, guardConfig) {
+    const issues = [];
+    for (const rule of guardConfig.rules) {
+        for (const file of rule.files ?? []) {
+            if (!isProjectPath(root, file)) {
+                issues.push({
+                    contractId: `rule:${rule.id}`,
+                    field: 'files',
+                    value: file,
+                    message: `Rule file scope must stay inside the project: ${file}`,
+                });
+            }
+        }
+    }
+    return [
+        ...issues,
+        ...validateGuardContracts(root, guardConfig.contracts ?? []),
+        ...validateGuardBudgets(root, guardConfig.budgets ?? []),
+    ];
+}
 function isSourceFile(file) {
     return /\.(?:ts|tsx|js|jsx)$/.test(file) && !/\.(?:test|spec)\.(?:ts|tsx|js|jsx)$/.test(file);
 }
@@ -892,6 +1301,49 @@ function architectureInsightFindings(root, changed) {
     }
     return findings;
 }
+function budgetMatchesFile(budget, file) {
+    return budget.scope.some((scope) => scope.endsWith('*')
+        ? file.startsWith(scope.slice(0, -1))
+        : file === scope || file.startsWith(`${scope}/`));
+}
+function budgetValue(root, metric, file, module) {
+    if (metric === 'bytes')
+        return file.bytes;
+    if (metric === 'imports') {
+        return module
+            ? new Set([...module.imports, ...module.exports, ...module.dynamicImports]).size
+            : 0;
+    }
+    try {
+        return readFileSync(resolve(root, file.path), 'utf8').split(/\r?\n/).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function scanBudgets(root, model, budgets, changed) {
+    const modules = new Map(model.modules.map((module) => [module.path, module]));
+    return budgets
+        .filter((budget) => budget.status !== 'proposed')
+        .flatMap((budget) => model.files
+        .filter((file) => budgetMatchesFile(budget, file.path) && (!changed || changed.has(file.path)))
+        .flatMap((file) => {
+        const value = budgetValue(root, budget.metric, file, modules.get(file.path));
+        if (value <= budget.limit)
+            return [];
+        return [
+            {
+                ruleId: `budget:${budget.id}`,
+                severity: budget.severity,
+                file: file.path,
+                line: 1,
+                importPath: `budget:${budget.metric}`,
+                message: `${budget.description} (${value} ${budget.metric}; limit ${budget.limit}).`,
+                fingerprint: `budget|${budget.id}|${file.path}|${budget.metric}`,
+            },
+        ];
+    }));
+}
 function isSafeReviewFile(file) {
     return !(file === '.env' ||
         file.startsWith('.env.') ||
@@ -1082,6 +1534,7 @@ export function scanGuard(root, guardConfig, options = {}) {
     const allFindings = [
         ...files.flatMap((file) => scanFile(root, file, guardConfig.rules, modules.get(file), astProject)),
         ...scanContracts(root, guardConfig.contracts ?? [], scope),
+        ...scanBudgets(root, model, guardConfig.budgets ?? [], scope),
         ...(options.includeArchitectureInsights ? architectureInsightFindings(root, scope) : []),
     ];
     const baseline = options.baseline ?? new Set();
@@ -1134,22 +1587,22 @@ export function buildGuardReviewPacket(root, guardConfig, baseline = new Set(),
     };
 }
 export function initializeGuard(root, options = {}) {
-    if (existsSync(resolve(root, GUARD_BASELINE_FILE)) && !options.force) {
-        throw new GuardAlreadyInitializedError();
-    }
-    const projectModel = discoverProject(root);
-    const guardConfig = loadGuardConfig(root) ?? buildGeneratedGuardConfig(projectModel);
-    ensureGeneratedStateIgnored(root, projectModel);
-    writeGuardConfig(root, guardConfig);
-    if (options.force || !existsSync(resolve(root, GUARD_AGENT_FILE))) {
-        writeGuardAgentConfig(root);
-    }
-    writeGuardMemory(root, projectModel);
-    writeProjectModel(root, projectModel);
-    writeProjectSnapshot(root, projectModel);
-    writeGuardProposals(root, buildGuardProposals(projectModel, guardConfig));
-    const initialReport = scanGuard(root, guardConfig, { includeArchitectureInsights: true });
-    writeBaseline(root, initialReport.findings, projectModel);
-    return { config: guardConfig, report: { ...initialReport, findings: [] } };
+    return withGuardStateLock(root, () => {
+        if (existsSync(resolve(root, GUARD_BASELINE_FILE)) && !options.force) {
+            throw new GuardAlreadyInitializedError();
+        }
+        const projectModel = discoverProject(root);
+        const guardConfig = loadGuardConfig(root) ?? buildGeneratedGuardConfig(projectModel);
+        ensureGeneratedStateIgnored(root, projectModel);
+        writeGuardConfig(root, guardConfig);
+        if (options.force || !existsSync(resolve(root, GUARD_AGENT_FILE))) {
+            writeGuardAgentConfig(root);
+        }
+        writeProjectState(root, projectModel);
+        writeGuardProposals(root, buildGuardProposals(projectModel, guardConfig));
+        const initialReport = scanGuard(root, guardConfig, { includeArchitectureInsights: true });
+        writeBaseline(root, initialReport.findings, projectModel);
+        return { config: guardConfig, report: { ...initialReport, findings: [] } };
+    }, options);
 }
 export { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findGuardRoot };