@apexops/cli 0.10.0-next.0

package/dist/service.js

@@ -0,0 +1,3817 @@
+import { ApprovalEvidenceV1Schema, ArchitectureAvailabilityV1Schema, ArchitectureV1Schema, CONTRACT_VERSION, CostEstimateV1Schema, DeploymentPreviewV1Schema, DiagnosisV1Schema, EnvironmentInputsV1Schema, EvidenceManifestV1Schema, ExecutionPlanAttestationV1Schema, GovernanceConstraintsV1Schema, IacBindingV1Schema, IacHandoffV1Schema, InputRequestV1Schema, InputValueV1Schema, InputSubmissionV1Schema, ImplementationIntentV1Schema, LogicalResourceManifestV1Schema, OperationRecordV1Schema, PolicyPropertyMapV1Schema, QualityMeasurementsV1Schema, QualityReportV1Schema, RequirementsV1Schema, ResourceInventoryV1Schema, ReviewFindingsV1Schema, RuntimeBundleLockV1Schema, WorkloadDecisionManifestV1Schema, hasOnlyTypedSecretReferences, hasValidInputRequestQuestions, hasValidCostArithmetic, hasValidLogicalResourceReferences, } from "@apexops/contracts";
+import { Value } from "@sinclair/typebox/value";
+import { CapabilityPackManager, FakeIaCProvider, ProcessRunner, generateBicepTree, generateTerraformTree, } from "@apexops/capabilities";
+import { ContentCache, EvidencePolicy, EvidenceStore, EventJournal, ImprovementStore, ObjectStore, ProjectStore, RunRepository, ValidatorRegistry, WriterTransferStore, WorkflowEngine, assertTaskCurrent, atomicWriteBytes, atomicWriteJson, createTaskEnvelope, decideGate, inheritGate, openGate, sha256Bytes, sha256Json, validateInputAnswers, workflowValidatorOwnership, } from "@apexops/kernel";
+import { DOCUMENT_REGISTRY, renderApprovalEvidence, renderDeploymentPreview, renderRequirementsDocument, renderResourceInventory, renderRunStatus, } from "@apexops/renderers";
+import { constants } from "node:fs";
+import { access, cp, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, delimiter, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { resolveBundledAssets } from "./assets.js";
+import { dependencyRevision as calculateDependencyRevision } from "./dependency-revision.js";
+import { ApexError, EXIT_CODES } from "./errors.js";
+import { APEX_VERSION } from "./version.js";
+import { registerWorkflowValidators, taskWorkflowValidatorInput, } from "./workflow-validators.js";
+const ZERO_HASH = "0".repeat(64);
+const TASK_TTL_MS = 24 * 60 * 60 * 1000;
+const PREVIEW_TTL_MS = 24 * 60 * 60 * 1000;
+const APEX_GITIGNORE = "/cache/\n/local/\n/work/\n/runtime/capability-packs/\n";
+const PROFILE_BOOTSTRAP_FILENAME = "apex-bootstrap.agent.md";
+const PROFILE_BOOTSTRAP_RECEIPT = ".apex-bootstrap.lock.json";
+function profileBootstrapAgent() {
+    return Buffer.from(`---
+name: APEX Bootstrap
+description: Create an APEX workspace through the supported bootstrap workflow.
+target: vscode
+user-invocable: true
+disable-model-invocation: true
+tools:
+  - vscode/askQuestions
+  - run_in_terminal
+---
+
+## Role
+
+Guide a user through creating an APEX workspace. Ask for the project ID, display
+name, environment, target scope, IaC track, and whether Git may be initialized.
+
+## Workflow
+
+1. Confirm the open folder is the intended workspace and is trusted.
+2. Collect the onboarding values with \`vscode/askQuestions\`.
+3. Run \`npx --yes @apexops/cli@${APEX_VERSION} bootstrap --project PROJECT_ID --name "DISPLAY_NAME" --environment ENVIRONMENT --target TARGET_SCOPE --iac IAC_TOOL --client github-copilot-vscode --yes\`.
+  Include \`--create-repo\` only after the user explicitly approves Git initialization.
+4. Run \`apex setup --json\` and \`apex doctor --json\` from the workspace.
+5. Ask the user to reload the VS Code window, then select the workspace APEX agent.
+
+## Boundaries
+
+Do not write workspace files, .apex state, MCP configuration, or managed agents.
+Do not approve gates, deploy resources, or infer workflow state. The CLI owns
+workspace initialization and the kernel owns all workflow authority.
+`, "utf8");
+}
+const ARTIFACTS = {
+    requirements: ["requirements", RequirementsV1Schema],
+    "workload-decision-manifest": ["workload-decision-manifest", WorkloadDecisionManifestV1Schema],
+    architecture: ["architecture", ArchitectureV1Schema],
+    "cost-estimate": ["cost-estimate", CostEstimateV1Schema],
+    "review-findings": ["review-findings", ReviewFindingsV1Schema],
+    "governance-constraints": ["governance-constraints", GovernanceConstraintsV1Schema],
+    "policy-property-map": ["policy-property-map", PolicyPropertyMapV1Schema],
+    "implementation-intent": ["implementation-intent", ImplementationIntentV1Schema],
+    "iac-binding": ["iac-binding", IacBindingV1Schema],
+    "environment-inputs": ["environment-inputs", EnvironmentInputsV1Schema],
+    "logical-resource-manifest": ["logical-resource-manifest", LogicalResourceManifestV1Schema],
+    "iac-handoff": ["iac-handoff", IacHandoffV1Schema],
+    "validation-evidence": ["validation-evidence", EvidenceManifestV1Schema],
+    "deployment-preview": ["preview", DeploymentPreviewV1Schema],
+    "execution-plan-attestation": ["execution-plan-attestation", ExecutionPlanAttestationV1Schema],
+    "operation-record": ["operation", OperationRecordV1Schema],
+    "resource-inventory": ["inventory", ResourceInventoryV1Schema],
+    diagnosis: ["diagnosis", DiagnosisV1Schema],
+    "quality-report": ["quality-report", QualityReportV1Schema],
+};
+export const SUPPORTED_ARTIFACT_KINDS = Object.keys(ARTIFACTS);
+const TASKS = [
+    { id: "requirements", role: "requirements", outputs: ["requirements"] },
+    { id: "requirements-review", role: "reviewer", outputs: ["review-findings"], reviewSubject: "requirements", gate: 1 },
+    { id: "architecture", role: "architect", outputs: ["architecture", "cost-estimate", "workload-decision-manifest"] },
+    { id: "architecture-review", role: "reviewer", outputs: ["review-findings"], reviewSubject: "architecture" },
+    {
+        id: "governance-discovery",
+        role: "governance-operator",
+        outputs: ["governance-constraints"],
+        capabilities: ["governance-discovery"],
+    },
+    { id: "governance-reconciliation", role: "governance-operator", outputs: ["policy-property-map"] },
+    {
+        id: "governance-review",
+        role: "reviewer",
+        outputs: ["review-findings"],
+        reviewSubject: "governance-reconciliation",
+        gate: 2,
+    },
+    { id: "plan", role: "planner", outputs: ["implementation-intent", "iac-binding", "environment-inputs"] },
+    { id: "plan-review", role: "reviewer", outputs: ["review-findings"], reviewSubject: "plan", gate: 3 },
+    { id: "codegen-bicep", role: "bicep-codegen", outputs: ["logical-resource-manifest", "iac-handoff"], track: "bicep" },
+    {
+        id: "codegen-terraform",
+        role: "terraform-codegen",
+        outputs: ["logical-resource-manifest", "iac-handoff"],
+        track: "terraform",
+    },
+    { id: "validation-bicep", role: "validator", outputs: ["validation-evidence"], track: "bicep" },
+    { id: "validation-terraform", role: "validator", outputs: ["validation-evidence"], track: "terraform" },
+    { id: "diagnosis", role: "diagnostic-operator", outputs: ["diagnosis"] },
+    { id: "quality", role: "quality-evaluator", outputs: ["quality-report"] },
+];
+const REQUIREMENTS_INTAKE = [
+    {
+        round: "business-discovery",
+        questions: [
+            { id: "workload", prompt: "Briefly describe the workload and its users." },
+            { id: "industry", prompt: "Which industry or domain does this workload serve?" },
+            {
+                id: "delivery-scenario",
+                prompt: "Is this a greenfield build, migration, modernization, or extension?",
+                options: ["greenfield", "migration", "modernization", "extension"],
+            },
+            {
+                id: "target-environments",
+                prompt: "Which environments are in scope?",
+                options: ["dev", "test", "staging", "prod"],
+                multiSelect: true,
+                valueType: "environment-set",
+            },
+        ],
+    },
+    {
+        round: "workload-pattern",
+        questions: [
+            {
+                id: "workload-pattern",
+                prompt: "Which workload pattern best fits the solution?",
+                options: ["web-api", "event-driven", "data-analytics", "iot", "batch"],
+            },
+            { id: "scale", prompt: "Describe expected users, concurrency, throughput, or data volume." },
+            { id: "budget", prompt: "State the monthly budget or explicitly defer it.", valueType: "budget" },
+            {
+                id: "data-sensitivity",
+                prompt: "Choose the data classification or explicitly defer it.",
+                valueType: "data-classification",
+            },
+            { id: "iac-preference", prompt: "Choose the preferred infrastructure tool.", options: ["bicep", "terraform"] },
+        ],
+    },
+    {
+        round: "service-preferences",
+        questions: [
+            { id: "retained-services", prompt: "List Azure services or integrations that must be retained, or 'none'." },
+            { id: "prohibited-services", prompt: "List prohibited services or use 'none'." },
+            {
+                id: "service-preferences",
+                prompt: "State preferred compute, database, integration, and observability services.",
+            },
+            { id: "sku-preferences", prompt: "State required SKUs, tier floors, reservations, or use 'no preference'." },
+            { id: "environment-overrides", prompt: "State environment-specific service or sizing overrides, or 'none'." },
+        ],
+    },
+    {
+        round: "security-compliance",
+        questions: [
+            {
+                id: "compliance",
+                prompt: "List compliance and regulatory scopes or explicitly defer them.",
+                valueType: "compliance",
+            },
+            {
+                id: "security-controls",
+                prompt: "List required identity, network, encryption, and secret-management controls.",
+            },
+            { id: "authentication", prompt: "Describe authentication and authorization requirements." },
+            { id: "region", prompt: "State the required Azure region or use 'deferred: <owner>'." },
+            { id: "availability-recovery", prompt: "State availability, RTO, RPO, backup, and recovery requirements." },
+            {
+                id: "recovery",
+                prompt: "Provide RTO and RPO in whole minutes or explicitly defer them.",
+                valueType: "recovery",
+            },
+            { id: "operations", prompt: "State monitoring, alerting, support, and operational requirements." },
+        ],
+    },
+];
+const ARCHITECTURE_DECISIONS = [
+    {
+        id: "network-exposure",
+        questions: [
+            {
+                id: "network-exposure",
+                prompt: "Choose the architecture network exposure posture.",
+                options: ["private-only", "public-approved", "deferred"],
+            },
+        ],
+    },
+];
+export class ApexService {
+    root;
+    clock;
+    idSource;
+    projects;
+    objects;
+    cache;
+    validators = new ValidatorRegistry();
+    providers;
+    architectureAvailabilityAdapter;
+    executableChecker;
+    azureAuthStatus;
+    customizationFailureInjector;
+    processRunner;
+    profileRoot;
+    improvementPolicy;
+    improvementRuntime;
+    requirementsDocumentTemplate;
+    constructor(root, options = {}) {
+        this.root = resolve(root);
+        this.clock = options.clock ?? (() => new Date());
+        this.idSource = options.idSource ?? (() => crypto.randomUUID());
+        this.projects = new ProjectStore(this.root, this.clock, this.idSource);
+        this.objects = new ObjectStore(this.root);
+        this.cache = new ContentCache(this.root);
+        for (const [, [validator, schema]] of Object.entries(ARTIFACTS))
+            this.validators.register(validator, schema);
+        this.validators.register("approval", ApprovalEvidenceV1Schema);
+        this.validators.register("runtime-lock", RuntimeBundleLockV1Schema);
+        this.validators.register("quality-measurements", QualityMeasurementsV1Schema);
+        this.validators.register("architecture-availability", ArchitectureAvailabilityV1Schema);
+        registerWorkflowValidators(this.validators);
+        this.providers = {
+            fake: new FakeIaCProvider({ track: "bicep", now: this.clock, nextId: this.idSource }),
+            ...options.providers,
+        };
+        this.architectureAvailabilityAdapter = options.architectureAvailabilityAdapter;
+        this.executableChecker = options.executableChecker ?? (async (executable) => this.pathExecutableExists(executable));
+        this.azureAuthStatus =
+            options.azureAuthStatus ?? (async () => ({ authenticated: false, detail: "not-checked; run setup --live" }));
+        this.customizationFailureInjector = options.customizationFailureInjector;
+        this.processRunner = options.processRunner ?? new ProcessRunner();
+        this.profileRoot = resolve(options.profileRoot ?? join(homedir(), ".copilot", "agents"));
+        this.improvementPolicy = options.improvementPolicy;
+    }
+    async improvementObserve(input) {
+        const run = await this.currentRun();
+        return (await this.improvements(run)).observe({ projectId: run.projectId, runId: run.runId, ...input });
+    }
+    async improvementObservations() {
+        const run = await this.currentRun();
+        const observations = await (await this.improvements(run)).listObservations();
+        return observations.filter(({ projectId }) => projectId === run.projectId);
+    }
+    async improvementScan() {
+        const run = await this.currentRun();
+        return (await this.improvements(run)).scan(run.projectId);
+    }
+    async improvementProposals() {
+        const run = await this.currentRun();
+        return (await this.improvements(run)).listProposals(run.projectId);
+    }
+    async improvementDecide(input) {
+        const run = await this.currentRun();
+        return (await this.improvements(run)).decide({ projectId: run.projectId, ...input });
+    }
+    async improvementDeleteObservation(observationId) {
+        const run = await this.currentRun();
+        const store = await this.improvements(run);
+        const observation = (await store.listObservations()).find((item) => item.observationId === observationId);
+        if (observation === undefined || observation.projectId !== run.projectId) {
+            throw new ApexError("APEX_NOT_FOUND", "Improvement observation not found", EXIT_CODES.notFound);
+        }
+        await store.deleteObservation(observationId);
+        return { deleted: observationId };
+    }
+    async improvementPrune() {
+        const run = await this.currentRun();
+        return (await this.improvements(run)).prune();
+    }
+    async capabilityList(manifestPath) {
+        return this.capabilityPacks(manifestPath).list();
+    }
+    async capabilityStatus(id, manifestPath) {
+        return this.capabilityPacks(manifestPath).status(id);
+    }
+    async capabilityInstall(id, manifestPath, options = {}) {
+        return this.capabilityPacks(manifestPath).install(id, options);
+    }
+    async capabilityUpdate(id, manifestPath, options = {}) {
+        return this.capabilityPacks(manifestPath).update(id, options);
+    }
+    async capabilityRollback(id, manifestPath) {
+        return this.capabilityPacks(manifestPath).rollback(id);
+    }
+    async capabilityVerify(id, manifestPath) {
+        return this.capabilityPacks(manifestPath).verify(id);
+    }
+    async capabilityUninstall(id, manifestPath) {
+        return this.capabilityPacks(manifestPath).uninstall(id);
+    }
+    async init(input) {
+        await this.assertCleanInitialization();
+        await mkdir(join(this.root, ".apex"), { recursive: true });
+        try {
+            await this.ensureLocalGitBoundary();
+            const assets = await resolveBundledAssets();
+            const clientId = input.clientId ?? "github-copilot-vscode";
+            const selection = {
+                version: 1,
+                clientId,
+                sourceMode: input.customizationsSource === undefined ? "bundled-projection" : "custom-source",
+                ...(input.customizationsSource === undefined ? {} : { customSource: resolve(input.customizationsSource) }),
+            };
+            await atomicWriteJson(join(this.root, ".apex", "customizations.selection.json"), selection);
+            await this.installCustomizations(input.customizationsSource ?? assets.clientProjections[clientId], false, assets.config, false, clientId);
+            await this.installCapabilityAssets(assets);
+            const runtimeLock = await this.createRuntimeLock(assets);
+            await atomicWriteJson(join(this.root, ".apex", "apex.lock.json"), runtimeLock);
+            return this.createProject(input);
+        }
+        catch (error) {
+            if (await this.pathExistsLstat(join(this.root, ".apex", "customizations.lock.json"))) {
+                await this.uninstallCustomizations();
+            }
+            await rm(join(this.root, ".apex"), { recursive: true, force: true });
+            throw error;
+        }
+    }
+    async bootstrap(input) {
+        await this.assertCleanInitialization();
+        await this.ensureWorkspaceGitRepository(input.createRepository === true);
+        const runtimeInstalled = await this.ensureWorkspaceRuntime();
+        const initialized = await this.init(input);
+        return { ...initialized, runtimeInstalled };
+    }
+    async profileStatus() {
+        const paths = this.profilePaths();
+        const receipt = await this.readProfileReceipt(paths.receipt);
+        const agent = await this.readProfileOptional(paths.agent);
+        if (receipt === undefined || agent === undefined)
+            return { installed: false, modified: receipt !== undefined || agent !== undefined };
+        return {
+            installed: sha256Bytes(agent) === receipt.contentHash,
+            modified: sha256Bytes(agent) !== receipt.contentHash,
+            version: receipt.packageVersion,
+        };
+    }
+    async profileInstall() {
+        await this.ensureProfileRoot();
+        const paths = this.profilePaths();
+        const content = profileBootstrapAgent();
+        const current = await this.readProfileOptional(paths.agent);
+        if (current !== undefined && !current.equals(content)) {
+            throw new ApexError("APEX_CONFLICT", "Profile APEX bootstrap agent was modified or is owned by another tool", EXIT_CODES.conflict);
+        }
+        await atomicWriteBytes(paths.agent, content);
+        await atomicWriteJson(paths.receipt, {
+            version: 1,
+            packageVersion: APEX_VERSION,
+            contentHash: sha256Bytes(content),
+        });
+        return { installed: current === undefined, version: APEX_VERSION };
+    }
+    async profileUpdate() {
+        await this.ensureProfileRoot();
+        const paths = this.profilePaths();
+        const receipt = await this.readProfileReceipt(paths.receipt);
+        const current = await this.readProfileOptional(paths.agent);
+        if (receipt === undefined || current === undefined) {
+            throw new ApexError("APEX_NOT_FOUND", "Profile APEX bootstrap agent is not installed", EXIT_CODES.notFound);
+        }
+        if (sha256Bytes(current) !== receipt.contentHash) {
+            throw new ApexError("APEX_CONFLICT", "Profile APEX bootstrap agent was modified", EXIT_CODES.conflict);
+        }
+        const content = profileBootstrapAgent();
+        await atomicWriteBytes(paths.agent, content);
+        await atomicWriteJson(paths.receipt, {
+            version: 1,
+            packageVersion: APEX_VERSION,
+            contentHash: sha256Bytes(content),
+        });
+        return { updated: !current.equals(content), version: APEX_VERSION };
+    }
+    async profileUninstall() {
+        await this.ensureProfileRoot();
+        const paths = this.profilePaths();
+        const receipt = await this.readProfileReceipt(paths.receipt);
+        const current = await this.readProfileOptional(paths.agent);
+        if (receipt !== undefined && current !== undefined && sha256Bytes(current) !== receipt.contentHash) {
+            throw new ApexError("APEX_CONFLICT", "Profile APEX bootstrap agent was modified", EXIT_CODES.conflict);
+        }
+        await rm(paths.agent, { force: true });
+        await rm(paths.receipt, { force: true });
+        return { removed: receipt !== undefined || current !== undefined };
+    }
+    async createProject(input) {
+        let runtimeLock;
+        try {
+            runtimeLock = JSON.parse(await readFile(join(this.root, ".apex", "apex.lock.json"), "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new ApexError("APEX_NOT_FOUND", "Initialize the workspace with apex init before creating a project", EXIT_CODES.notFound);
+            }
+            throw error;
+        }
+        const runtimeLockHash = sha256Json(runtimeLock);
+        await this.projects.initializeProject({
+            projectId: input.projectId,
+            displayName: input.displayName ?? input.projectId,
+            defaultIacTool: input.iacTool ?? "bicep",
+        });
+        const run = await this.projects.createRun(input.projectId, {
+            environment: input.environment ?? "dev",
+            targetScope: input.targetScope ?? "local",
+            runtimeLockHash,
+        });
+        await this.writeSelection({ projectId: input.projectId, runId: run.runId });
+        await this.append(run, "project.created", { runtimeLockHash });
+        return { projectId: input.projectId, runId: run.runId };
+    }
+    async update(customizationsSource) {
+        const selection = await this.selection();
+        await this.ensureLocalGitBoundary();
+        const assets = await resolveBundledAssets();
+        const lock = JSON.parse(await readFile(join(this.root, ".apex", "customizations.lock.json"), "utf8"));
+        const persisted = await this.customizationSelection(lock.clientId);
+        const clientId = persisted.clientId;
+        if (persisted.sourceMode === "custom-source" && customizationsSource === undefined) {
+            throw new ApexError("APEX_USAGE", "Custom-source updates require --customizations-source", EXIT_CODES.usage);
+        }
+        const source = customizationsSource ?? assets.clientProjections[clientId];
+        const updated = await this.installCustomizations(source, true, assets.config, false, clientId);
+        await this.append(await this.run(selection), "customizations.updated", { source: resolve(source), updated });
+        return { updated };
+    }
+    async rollbackCustomizations() {
+        await this.recoverCustomizationTransaction();
+        const lockPath = join(this.root, ".apex", "customizations.lock.json");
+        const current = JSON.parse(await readFile(lockPath, "utf8"));
+        if (current.previousLockRef === undefined)
+            throw new ApexError("APEX_NOT_FOUND", "No prior customization bundle is available", EXIT_CODES.notFound);
+        if (!this.safeManagedRelativePath(current.previousLockRef)) {
+            throw new ApexError("APEX_VALIDATION", "Previous customization lock path is unsafe", EXIT_CODES.validation);
+        }
+        const previousPath = resolve(this.root, current.previousLockRef);
+        await this.assertSafeExistingPath(this.root, previousPath);
+        const previous = JSON.parse(await readFile(previousPath, "utf8"));
+        const restored = [];
+        const conflicts = [];
+        for (const [root, desired, installed] of [
+            [this.root, previous.files, current.files],
+            [join(this.root, ".apex", "runtime"), previous.runtime, current.runtime],
+        ]) {
+            for (const file of desired) {
+                if (!this.safeManagedRelativePath(file.path)) {
+                    throw new ApexError("APEX_VALIDATION", "Managed customization path is unsafe", EXIT_CODES.validation);
+                }
+                const destination = resolve(root, file.path);
+                await this.assertSafeDestination(root, destination);
+                const installedFile = installed.find(({ path }) => path === file.path);
+                const incoming = await this.readManagedBase(file.baseRef);
+                if (incoming === undefined) {
+                    conflicts.push(file.path);
+                    continue;
+                }
+                if (await this.pathExistsLstat(destination)) {
+                    const local = await readFile(destination);
+                    const localHash = sha256Bytes(local);
+                    if (installedFile !== undefined &&
+                        localHash !== installedFile.currentHash &&
+                        localHash !== installedFile.baseHash) {
+                        const base = await this.readManagedBase(installedFile.baseRef);
+                        const merged = base === undefined ? undefined : this.mergeText(base, local, incoming);
+                        if (merged === undefined) {
+                            conflicts.push(file.path);
+                            continue;
+                        }
+                        await atomicWriteBytes(destination, merged);
+                    }
+                    else
+                        await atomicWriteBytes(destination, incoming);
+                }
+                else
+                    await atomicWriteBytes(destination, incoming);
+                restored.push(file.path);
+            }
+        }
+        if (conflicts.length === 0)
+            await atomicWriteJson(lockPath, previous);
+        return { restored, conflicts };
+    }
+    async uninstallCustomizations() {
+        await this.recoverCustomizationTransaction();
+        const lockPath = join(this.root, ".apex", "customizations.lock.json");
+        const lock = JSON.parse(await readFile(lockPath, "utf8"));
+        const removed = [];
+        const conflicts = [];
+        for (const file of lock.files) {
+            const destination = join(this.root, file.path);
+            if (!(await this.pathExistsLstat(destination)))
+                continue;
+            await this.assertSafeDestination(this.root, destination);
+            if (sha256Bytes(await readFile(destination)) !== file.currentHash) {
+                conflicts.push(file.path);
+                continue;
+            }
+            await rm(destination);
+            removed.push(file.path);
+        }
+        await rm(lockPath, { force: true });
+        return { removed, conflicts };
+    }
+    async reinstallCustomizations(customizationsSource) {
+        await this.recoverCustomizationTransaction();
+        const lockPath = join(this.root, ".apex", "customizations.lock.json");
+        if (await this.exists(lockPath)) {
+            throw new ApexError("APEX_CONFLICT", "Managed customizations are already installed", EXIT_CODES.conflict);
+        }
+        const selection = await this.customizationSelection();
+        if (selection.sourceMode === "custom-source" && customizationsSource === undefined) {
+            throw new ApexError("APEX_USAGE", "Custom-source reinstall requires --customizations-source", EXIT_CODES.usage);
+        }
+        const assets = await resolveBundledAssets();
+        const source = customizationsSource ?? assets.clientProjections[selection.clientId];
+        const installed = await this.installCustomizations(source, false, assets.config, false, selection.clientId);
+        return { installed, clientId: selection.clientId };
+    }
+    async listProjects() {
+        const directory = join(this.root, ".apex", "projects");
+        let names;
+        try {
+            names = await readdir(directory);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        const projects = await Promise.all(names.sort().map(async (projectId) => this.projects.getProject(projectId)));
+        return projects.map(({ projectId, displayName }) => ({ projectId, displayName }));
+    }
+    async use(projectId, runId) {
+        await this.projects.getProject(projectId);
+        const selectedRun = runId ?? (await this.latestRun(projectId));
+        await this.projects.getRun(projectId, selectedRun);
+        const selection = { projectId, runId: selectedRun };
+        await this.writeSelection(selection);
+        await this.append(await this.run(selection), "selection.changed", selection);
+        return selection;
+    }
+    async show(projectId) {
+        if (projectId !== undefined)
+            return this.projects.getProject(projectId);
+        const selection = await this.selection();
+        return { project: await this.projects.getProject(selection.projectId), run: await this.run(selection) };
+    }
+    async search(term, limit = 50) {
+        const needle = term.toLowerCase();
+        const results = [];
+        for (const project of await this.listProjects()) {
+            const matches = [];
+            const runNames = await readdir(join(this.projects.projectDirectory(project.projectId), "runs"));
+            for (const runName of runNames.sort()) {
+                const run = await this.projects.getRun(project.projectId, runName);
+                for (const event of await this.journal(run).replay()) {
+                    if (`${event.type}\n${JSON.stringify(event.payload)}`.toLowerCase().includes(needle)) {
+                        matches.push({ runId: run.runId, type: event.type, sequence: event.sequence });
+                        if (matches.length >= limit)
+                            break;
+                    }
+                }
+                if (matches.length >= limit)
+                    break;
+            }
+            if (project.projectId.toLowerCase().includes(needle) ||
+                project.displayName.toLowerCase().includes(needle) ||
+                matches.length > 0) {
+                results.push({ ...project, ...(matches.length === 0 ? {} : { matches }) });
+            }
+            if (results.length >= limit)
+                break;
+        }
+        return results;
+    }
+    async history(limit = 100) {
+        const events = await this.journal(await this.currentRun()).replay();
+        return events
+            .slice(-Math.max(1, Math.min(limit, 500)))
+            .reverse()
+            .map((event) => ({
+            sequence: event.sequence,
+            type: event.type,
+            timestamp: event.timestamp,
+            artifactKinds: Object.keys(event.payload.artifactHashes ?? {}).sort(),
+            payload: event.payload,
+        }));
+    }
+    async status() {
+        const selection = await this.selection();
+        const run = await this.run(selection);
+        let events = await this.journal(run).replay();
+        let route = await this.route(run, events);
+        if (route.task === undefined && route.blockers.length === 0) {
+            const completedEvents = await this.ensureTerminalCompletion(run, events);
+            if (completedEvents !== events) {
+                events = completedEvents;
+                route = await this.route(run, events);
+            }
+        }
+        return {
+            run,
+            head: events.at(-1)?.hash ?? null,
+            events: events.length,
+            task: route.task?.id ?? null,
+            blockers: route.blockers,
+        };
+    }
+    async nextTask() {
+        const selection = await this.selection();
+        const run = await this.run(selection);
+        const events = await this.journal(run).replay();
+        const requirements = this.artifactHash(events, "requirements");
+        if (requirements === undefined) {
+            const pending = this.nextRequirementsIntakeRound(events);
+            if (pending !== undefined)
+                return { status: "needs_input", request: await this.issueRequirementsInput(run, pending) };
+            return { status: "task", task: await this.issueTask(run, TASKS[0], []) };
+        }
+        const route = await this.route(run, events);
+        if (route.blockers.length > 0)
+            throw new ApexError("APEX_AUTHORIZATION", route.blockers.join("; "), EXIT_CODES.authorization, route.blockers);
+        if (route.task === undefined)
+            throw new ApexError("APEX_NOT_FOUND", "No task is currently available", EXIT_CODES.notFound);
+        if (route.task.id === "architecture") {
+            const decision = this.architectureDecisionState(events, run.ownerEpoch);
+            if (decision.pending !== undefined)
+                return { status: "needs_input", request: decision.pending };
+            if (decision.staleTaskId !== undefined) {
+                return {
+                    status: "needs_input",
+                    request: await this.issueArchitectureDecision(run, await this.readTask(run, decision.staleTaskId)),
+                };
+            }
+            if (decision.taskId !== undefined) {
+                const task = await this.readTask(run, decision.taskId);
+                if (task.expectedHead === events.at(-1)?.hash && task.ownerEpoch === run.ownerEpoch) {
+                    return { status: "task", task };
+                }
+                return { status: "task", task: await this.issueTask(run, route.task, this.inputRefs(events, route.task)) };
+            }
+            const task = await this.issueTask(run, route.task, this.inputRefs(events, route.task));
+            return { status: "needs_input", request: await this.issueArchitectureDecision(run, task) };
+        }
+        return { status: "task", task: await this.issueTask(run, route.task, this.inputRefs(events, route.task)) };
+    }
+    async recordInput(input) {
+        let run;
+        try {
+            const selection = await this.selection();
+            run = await this.run(selection);
+        }
+        catch (error) {
+            if (error instanceof Error && /mutation is already in progress/i.test(error.message)) {
+                throw new ApexError("APEX_STALE", "Input request is being recorded by another writer", EXIT_CODES.stale);
+            }
+            throw error;
+        }
+        if (!Value.Check(InputSubmissionV1Schema, input)) {
+            throw new ApexError("APEX_VALIDATION", "Input submission is malformed", EXIT_CODES.validation);
+        }
+        const events = await this.journal(run).replay();
+        const requested = [...events]
+            .reverse()
+            .find((event) => event.type === "requirements.input-requested" || event.type === "architecture.decision-requested");
+        if (requested === undefined) {
+            throw new ApexError("APEX_CONFLICT", "No input request is pending", EXIT_CODES.conflict);
+        }
+        const request = requested.type === "requirements.input-requested"
+            ? this.inputRequest(requested, run.ownerEpoch)
+            : this.architectureDecisionRequest(requested, run.ownerEpoch);
+        const recordedType = requested.type === "requirements.input-requested"
+            ? "requirements.input-recorded"
+            : "architecture.decision-recorded";
+        if (events.some((event) => event.type === recordedType && event.payload.requestId === request.requestId)) {
+            throw new ApexError("APEX_CONFLICT", "Input request was already recorded", EXIT_CODES.conflict);
+        }
+        if (input.requestId !== request.requestId) {
+            throw new ApexError("APEX_CONFLICT", "Input request ID does not match the pending request", EXIT_CODES.conflict);
+        }
+        if (input.expectedHead !== request.expectedHead || events.at(-1)?.hash !== request.expectedHead) {
+            throw new ApexError("APEX_STALE", "Input request journal head is stale", EXIT_CODES.stale);
+        }
+        if (input.ownerEpoch !== request.ownerEpoch || run.ownerEpoch !== request.ownerEpoch) {
+            throw new ApexError("APEX_STALE", "Input request owner epoch is stale", EXIT_CODES.stale);
+        }
+        let normalizedAnswers;
+        try {
+            normalizedAnswers = validateInputAnswers(request.questions, input.answers);
+        }
+        catch (error) {
+            throw new ApexError("APEX_VALIDATION", error instanceof Error ? error.message : "Input answers are invalid", EXIT_CODES.validation);
+        }
+        try {
+            await this.append(run, recordedType, {
+                requestId: request.requestId,
+                ...("intake" in request ? { intake: request.intake } : { decision: request.decision }),
+                answers: normalizedAnswers,
+            }, request.expectedHead);
+            if (request.decision !== undefined)
+                await this.refreshTaskHead(run, await this.readTask(run, request.decision.taskId));
+        }
+        catch (error) {
+            if (error instanceof Error && /stale journal head|mutation is already in progress/i.test(error.message)) {
+                throw new ApexError("APEX_STALE", "Input request journal head is stale", EXIT_CODES.stale, undefined, error);
+            }
+            throw error;
+        }
+        return { recorded: true, requestId: request.requestId };
+    }
+    async recordRequirementsInput(value) {
+        const pending = await this.nextTask();
+        if (pending.status !== "needs_input") {
+            throw new ApexError("APEX_CONFLICT", "No requirements input request is pending", EXIT_CODES.conflict);
+        }
+        const source = value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+        const missing = pending.request.questions.filter(({ id }) => typeof source[id] !== "string" || source[id].length === 0);
+        if (missing.length > 0) {
+            throw new ApexError("APEX_VALIDATION", `Missing requirements input: ${missing.map(({ id }) => id).join(", ")}`, EXIT_CODES.validation);
+        }
+        await this.recordInput({
+            schemaVersion: CONTRACT_VERSION,
+            requestId: pending.request.requestId,
+            expectedHead: pending.request.expectedHead,
+            ownerEpoch: pending.request.ownerEpoch,
+            answers: pending.request.questions.map(({ id }) => ({
+                questionId: id,
+                value: source[id],
+            })),
+        });
+    }
+    async taskContext(taskId) {
+        const run = await this.currentRun();
+        const task = await this.readTask(run, taskId);
+        const events = await this.journal(run).replay();
+        const route = await this.route(run, events);
+        const outputTemplates = {};
+        if (task.taskType === "requirements" || task.taskType === "plan") {
+            for (const kind of task.allowedOutputKinds) {
+                if (!SUPPORTED_ARTIFACT_KINDS.includes(kind)) {
+                    throw new ApexError("APEX_INTERNAL", `Unsupported task output kind: ${kind}`, EXIT_CODES.internal);
+                }
+                outputTemplates[kind] = this.outputTemplate(kind, run, events);
+            }
+        }
+        const artifactHashes = this.acceptedArtifactHashes(events);
+        return {
+            task,
+            inputs: await Promise.all(task.inputRefs.map((hash) => this.objects.getJson(hash))),
+            artifactHashes,
+            recordedInput: task.taskType === "requirements" ? this.recordedRequirementsInput(events) : null,
+            decisions: task.taskType === "architecture" ? this.architectureDecisionValues(events, task.taskId) : {},
+            outputTemplates,
+            outputRoot: join(this.root, ".apex", "work", run.runId, taskId),
+            status: this.completedNodeIds(events).has(task.taskType) ? "completed" : "active",
+            blockers: route.blockers,
+        };
+    }
+    async stageArtifact(taskId, output) {
+        const run = await this.currentRun();
+        const task = await this.readTask(run, taskId);
+        const head = await this.journal(run).head();
+        if (head === null)
+            throw new ApexError("APEX_STALE", "Task journal is empty", EXIT_CODES.stale);
+        assertTaskCurrent(task, head, run.ownerEpoch, this.clock);
+        if (!task.allowedOutputKinds.includes(output.kind)) {
+            throw new ApexError("APEX_VALIDATION", `Task does not allow ${output.kind}`, EXIT_CODES.validation);
+        }
+        this.validateOutput(run, output);
+        const bytes = Buffer.from(JSON.stringify(output.value), "utf8");
+        if (bytes.byteLength > task.maxOutputBytes) {
+            throw new ApexError("APEX_VALIDATION", "Task output exceeds its size limit", EXIT_CODES.validation);
+        }
+        const directory = join(this.root, ".apex", "work", run.runId, taskId);
+        const path = join(directory, `${output.kind}.json`);
+        await mkdir(directory, { recursive: true });
+        await atomicWriteJson(path, output.value);
+        const hash = sha256Bytes(await readFile(path));
+        await this.append(run, "artifact.staged", { taskId, kind: output.kind, hash, bytes: bytes.byteLength });
+        const expectedHead = await this.journal(run).head();
+        if (expectedHead === null)
+            throw new ApexError("APEX_STALE", "Staging event was not recorded", EXIT_CODES.stale);
+        await atomicWriteJson(join(this.projects.runDirectory(run.projectId, run.runId), "tasks", `${taskId}.json`), {
+            ...task,
+            expectedHead,
+        });
+        return { taskId, kind: output.kind, path, bytes: bytes.byteLength, hash };
+    }
+    async stageFile(taskId, relativePath, content, expectedSha) {
+        const run = await this.currentRun();
+        const task = await this.readTask(run, taskId);
+        const head = await this.journal(run).head();
+        if (head === null)
+            throw new ApexError("APEX_STALE", "Task journal is empty", EXIT_CODES.stale);
+        assertTaskCurrent(task, head, run.ownerEpoch, this.clock);
+        if (!task.taskType.startsWith("codegen-"))
+            throw new ApexError("APEX_AUTHORIZATION", "Only code generation tasks may stage files", EXIT_CODES.authorization);
+        const normalized = relativePath.replaceAll("\\", "/");
+        const suffixes = [".terraform.lock.hcl", ".tfvars.example", ".bicep", ".json", ".tf", ".md"];
+        if (isAbsolute(relativePath) ||
+            normalized.length === 0 ||
+            normalized.split("/").some((part) => part === "" || part === "." || part === "..") ||
+            !suffixes.some((suffix) => normalized.endsWith(suffix))) {
+            throw new ApexError("APEX_VALIDATION", `Unsafe or unsupported staged path: ${relativePath}`, EXIT_CODES.validation);
+        }
+        const codeRoot = resolve(this.root, ".apex", "work", run.runId, taskId, "code");
+        const path = resolve(codeRoot, normalized);
+        if (path !== codeRoot && !path.startsWith(`${codeRoot}${sep}`))
+            throw new ApexError("APEX_VALIDATION", "Staged path escapes the code root", EXIT_CODES.validation);
+        await this.assertNoSymlinkPath(codeRoot, path);
+        const bytes = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
+        const hash = sha256Bytes(bytes);
+        if (expectedSha !== undefined && expectedSha !== hash)
+            throw new ApexError("APEX_STALE", "Staged content hash does not match expected SHA", EXIT_CODES.stale);
+        let idempotent = false;
+        if (await this.exists(path)) {
+            const entry = await lstat(path);
+            if (!entry.isFile() || entry.isSymbolicLink())
+                throw new ApexError("APEX_VALIDATION", "Staged destination must be a regular file", EXIT_CODES.validation);
+            if (sha256Bytes(await readFile(path)) !== hash)
+                throw new ApexError("APEX_CONFLICT", `Refusing to overwrite staged file: ${normalized}`, EXIT_CODES.conflict);
+            idempotent = true;
+        }
+        else {
+            const used = await this.directoryBytes(codeRoot);
+            if (used + bytes.byteLength > task.maxOutputBytes)
+                throw new ApexError("APEX_VALIDATION", "Task output exceeds its cumulative size limit", EXIT_CODES.validation);
+            await atomicWriteBytes(path, bytes, { refuseOverwrite: true });
+            await this.append(run, "file.staged", { taskId, path: normalized, hash, bytes: bytes.byteLength });
+            await this.refreshTaskHead(run, task);
+        }
+        return { taskId, path, bytes: bytes.byteLength, hash, idempotent };
+    }
+    async generateIac(taskId, options = {}) {
+        const run = await this.currentRun();
+        const task = await this.readTask(run, taskId);
+        if (task.taskType !== `codegen-${run.iacTool}`)
+            throw new ApexError("APEX_AUTHORIZATION", "Task is not the selected code generation task", EXIT_CODES.authorization);
+        const inputs = await Promise.all(task.inputRefs.map((hash) => this.objects.getJson(hash)));
+        const intent = inputs.find((value) => this.looksLikeIntent(value));
+        const binding = inputs.find((value) => this.looksLikeBinding(value, run.iacTool));
+        const environmentInputs = inputs.find((value) => this.looksLikeEnvironmentInputs(value));
+        if (intent === undefined || binding === undefined || environmentInputs === undefined) {
+            throw new ApexError("APEX_VALIDATION", "Code generation requires accepted intent, binding, and environment inputs", EXIT_CODES.validation);
+        }
+        const tree = run.iacTool === "bicep"
+            ? generateBicepTree(intent, binding, {
+                ...(options.existingResources === undefined ? {} : { existingResources: options.existingResources }),
+            })
+            : generateTerraformTree(intent, binding, {
+                ...(options.existingResources === undefined ? {} : { existingResources: options.existingResources }),
+                ...(options.azurermProviderConstraint === undefined
+                    ? {}
+                    : { azurermProviderConstraint: options.azurermProviderConstraint }),
+                ...(options.azapiProviderConstraint === undefined
+                    ? {}
+                    : { azapiProviderConstraint: options.azapiProviderConstraint }),
+                ...(options.lockFileContent === undefined ? {} : { lockFileContent: options.lockFileContent }),
+            });
+        const files = [];
+        for (const file of tree.files)
+            files.push(await this.stageFile(taskId, file.path, file.content));
+        const intentHash = sha256Json(intent);
+        const bindingHash = sha256Json(binding);
+        const environmentInputsHash = sha256Json(environmentInputs);
+        const handoff = {
+            schemaVersion: CONTRACT_VERSION,
+            projectId: run.projectId,
+            runId: run.runId,
+            track: run.iacTool,
+            rootPath: relative(this.root, resolve(this.root, ".apex", "work", run.runId, taskId, "code")),
+            treeHash: tree.treeHash,
+            intentHash,
+            bindingHash,
+            environmentInputsHash,
+            logicalResourceManifestHash: sha256Json(tree.logicalManifest),
+            requiredToolVersions: options.requiredToolVersions ?? { [run.iacTool]: "system" },
+            generatedAt: this.clock().toISOString(),
+        };
+        const completed = await this.completeTaskOutputs(taskId, [
+            { kind: "logical-resource-manifest", value: tree.logicalManifest },
+            { kind: "iac-handoff", value: handoff },
+        ]);
+        return { files, outputHashes: completed.outputHashes, treeHash: tree.treeHash };
+    }
+    async validateTask(taskId, output) {
+        const run = await this.currentRun();
+        const task = await this.readTask(run, taskId);
+        const head = await this.journal(run).head();
+        if (head === null)
+            throw new ApexError("APEX_STALE", "Task journal is empty", EXIT_CODES.stale);
+        assertTaskCurrent(task, head, run.ownerEpoch, this.clock);
+        const staged = output === undefined
+            ? undefined
+            : Array.isArray(output)
+                ? await Promise.all(output.map((item) => this.stageArtifact(taskId, item)))
+                : await this.stageArtifact(taskId, output);
+        return { valid: true, taskId, ...(staged === undefined ? {} : { staged }) };
+    }
+    async completeTask(taskId, output) {
+        const completed = await this.acceptTaskOutputs(taskId, [output], true);
+        return { outputHash: completed.outputHashes[output.kind], summary: output.summary ?? `${output.kind} accepted` };
+    }
+    async completeTaskOutputs(taskId, outputs) {
+        return this.acceptTaskOutputs(taskId, outputs, false);
+    }
+    async acceptTaskOutputs(taskId, outputs, legacy) {
+        const run = await this.currentRun();
+        const task = await this.readTask(run, taskId);
+        const events = await this.journal(run).replay();
+        const head = events.at(-1)?.hash ?? null;
+        if (head === null)
+            throw new ApexError("APEX_STALE", "Task journal is empty", EXIT_CODES.stale);
+        assertTaskCurrent(task, head, run.ownerEpoch, this.clock);
+        if (outputs.length === 0)
+            throw new ApexError("APEX_VALIDATION", "Task bundle must contain outputs", EXIT_CODES.validation);
+        const kinds = outputs.map(({ kind }) => kind);
+        if (new Set(kinds).size !== kinds.length)
+            throw new ApexError("APEX_VALIDATION", "Task bundle contains duplicate kinds", EXIT_CODES.validation);
+        const descriptor = TASKS.find(({ id }) => id === task.taskType);
+        if (descriptor === undefined)
+            throw new ApexError("APEX_VALIDATION", `Unknown task type ${task.taskType}`, EXIT_CODES.validation);
+        const missing = descriptor.outputs.filter((kind) => !kinds.includes(kind));
+        if (missing.length > 0) {
+            if (legacy && descriptor.id === "plan" && kinds.length === 1 && kinds[0] === "implementation-intent") {
+                outputs = [...outputs, ...this.legacyPlanOutputs(run, outputs[0].value)];
+            }
+            else {
+                throw new ApexError("APEX_VALIDATION", `Task bundle is missing: ${missing.join(", ")}`, EXIT_CODES.validation);
+            }
+        }
+        for (const output of outputs) {
+            if (!task.allowedOutputKinds.includes(output.kind))
+                throw new ApexError("APEX_VALIDATION", `Task does not allow ${output.kind}`, EXIT_CODES.validation);
+            const bytes = Buffer.byteLength(JSON.stringify(output.value));
+            if (bytes > task.maxOutputBytes)
+                throw new ApexError("APEX_VALIDATION", "Task output exceeds its size limit", EXIT_CODES.validation);
+            this.validateOutput(run, output);
+        }
+        await this.validateBundle(run, descriptor, outputs, events);
+        const validation = await this.validateTaskValidators(run, task, descriptor, outputs, events);
+        const completionHead = await this.journal(run).head();
+        if (completionHead === null)
+            throw new ApexError("APEX_STALE", "Task journal is empty", EXIT_CODES.stale);
+        assertTaskCurrent(task, completionHead, run.ownerEpoch, this.clock);
+        const outputHashes = {};
+        for (const output of outputs)
+            outputHashes[output.kind] = await this.objects.putJson(output.value);
+        const requirementsOutput = outputs.find(({ kind }) => kind === "requirements");
+        const requirementsHash = outputHashes.requirements;
+        const renderedDocument = descriptor.id === "requirements"
+            ? requirementsOutput === undefined || requirementsHash === undefined
+                ? (() => {
+                    throw new ApexError("APEX_INTERNAL", "Requirements completion is missing its accepted output", EXIT_CODES.internal);
+                })()
+                : await this.renderRequirementsDocument(requirementsOutput.value, requirementsHash)
+            : undefined;
+        const reviewBlockers = descriptor.reviewSubject === undefined ? [] : this.openReviewFindings(outputs[0].value);
+        const dependencyHash = sha256Json(outputHashes);
+        await this.append(run, "task.completed", {
+            taskId,
+            nodeId: descriptor.id,
+            artifactHashes: outputHashes,
+            ...(renderedDocument === undefined ? {} : { renderedDocuments: [renderedDocument] }),
+            validatorIds: validation.validatorIds,
+            ...(Object.keys(validation.evidenceRefs).length === 0 ? {} : { validatorEvidenceRefs: validation.evidenceRefs }),
+            ...(Object.keys(validation.evidenceModes).length === 0
+                ? {}
+                : { validatorEvidenceModes: validation.evidenceModes }),
+            reviewBlockers,
+            ...(descriptor.reviewSubject === undefined
+                ? {}
+                : {
+                    reviewHash: outputHashes["review-findings"],
+                    subjectHash: outputs[0].value.subjectHash,
+                    dependencyHash,
+                }),
+            legacy,
+        });
+        if (descriptor.reviewSubject !== undefined) {
+            if (reviewBlockers.length === 0 && descriptor.gate !== undefined) {
+                await this.openRunGate(await this.currentRun(), descriptor.gate, dependencyHash);
+            }
+        }
+        else if (legacy && descriptor.id === "requirements") {
+            await this.openRunGate(await this.currentRun(), 1, sha256Json(outputHashes));
+        }
+        return { outputHashes, summary: outputs.map(({ kind }) => kind).join(", ") + " accepted" };
+    }
+    async renderRequirementsDocument(value, artifactHash) {
+        const { content, templateHash } = await this.requirementsDocumentMarkdown(value, artifactHash);
+        return {
+            documentId: "requirements",
+            templateHash,
+            // State transfer exports immutable objects as canonical JSON.
+            outputHash: await this.objects.putJson({ contentType: "text/markdown", content }),
+        };
+    }
+    async requirementsDocumentMarkdown(value, artifactHash) {
+        if (!Value.Check(RequirementsV1Schema, value)) {
+            throw new ApexError("APEX_INTERNAL", "Requirements document source is invalid", EXIT_CODES.internal);
+        }
+        const { content: template, hash: templateHash } = await this.requirementsDocumentTemplateContent();
+        let document;
+        try {
+            document = renderRequirementsDocument(value, template, artifactHash, templateHash);
+        }
+        catch (error) {
+            throw new ApexError("APEX_INTERNAL", error instanceof Error ? error.message : "Requirements document renderer failed", EXIT_CODES.internal);
+        }
+        return {
+            content: document,
+            templateHash,
+        };
+    }
+    async requirementsDocumentTemplateContent() {
+        this.requirementsDocumentTemplate ??= (async () => {
+            const assets = await resolveBundledAssets();
+            const templateDefinition = DOCUMENT_REGISTRY.requirements?.template;
+            if (templateDefinition === undefined) {
+                throw new ApexError("APEX_INTERNAL", "Requirements template is unregistered", EXIT_CODES.internal);
+            }
+            const content = await readFile(join(assets.customizations, templateDefinition.assetPath), "utf8");
+            return { content, hash: sha256Bytes(Buffer.from(content, "utf8")) };
+        })();
+        return this.requirementsDocumentTemplate;
+    }
+    async cancelTask(taskId) {
+        const run = await this.currentRun();
+        await this.readTask(run, taskId);
+        await this.append(run, "task.cancelled", { taskId });
+    }
+    async resolveReview(resolution) {
+        const run = await this.currentRun();
+        const events = await this.journal(run).replay();
+        const reviewEvent = [...events]
+            .reverse()
+            .find((event) => event.type === "task.completed" &&
+            event.payload.reviewHash === resolution.reviewHash);
+        if (reviewEvent === undefined)
+            throw new ApexError("APEX_STALE", "Resolution reviewHash is not the current accepted review", EXIT_CODES.stale);
+        const reviewPayload = reviewEvent.payload;
+        if (reviewPayload.subjectHash !== resolution.subjectHash ||
+            reviewPayload.dependencyHash !== resolution.dependencyHash) {
+            throw new ApexError("APEX_STALE", "Resolution is not bound to the accepted review dependency", EXIT_CODES.stale);
+        }
+        this.assertReviewResolution(resolution);
+        const review = await this.objects.getJson(resolution.reviewHash);
+        const finding = review.findings.find(({ id }) => id === resolution.findingId);
+        if (finding === undefined || finding.disposition !== "open")
+            throw new ApexError("APEX_VALIDATION", "Resolution finding does not exist and remain open", EXIT_CODES.validation);
+        if (resolution.disposition === "accepted-risk" && ["critical", "high"].includes(finding.severity))
+            throw new ApexError("APEX_AUTHORIZATION", `${finding.severity} findings cannot be accepted as risk by default policy`, EXIT_CODES.authorization);
+        const priorResolutions = events.flatMap((event) => {
+            if (event.type !== "review.resolved")
+                return [];
+            const prior = event.payload.resolution;
+            return prior?.reviewHash === resolution.reviewHash && prior.findingId === resolution.findingId ? [prior] : [];
+        });
+        if (priorResolutions.some((prior) => sha256Json(prior) === sha256Json(resolution)))
+            return;
+        const hasCurrentResolution = priorResolutions.some((prior) => prior.disposition === "fixed" ||
+            (prior.expiresAt !== undefined && Date.parse(prior.expiresAt) > this.clock().getTime()));
+        if (hasCurrentResolution)
+            throw new ApexError("APEX_CONFLICT", "Finding already has a conflicting resolution", EXIT_CODES.conflict);
+        await this.append(run, "review.resolved", { resolution: resolution });
+        const updatedEvents = await this.journal(run).replay();
+        const nodeId = reviewPayload.nodeId;
+        const descriptor = typeof nodeId === "string" ? TASKS.find(({ id }) => id === nodeId) : undefined;
+        if (descriptor?.gate !== undefined && this.reviewBlockers(updatedEvents, descriptor.id).length === 0) {
+            const current = await this.currentRun();
+            const gateState = current.gates.find(({ gate }) => gate === descriptor.gate)?.state;
+            if (gateState === "closed" || gateState === "invalidated") {
+                await this.openRunGate(current, descriptor.gate, resolution.dependencyHash);
+            }
+        }
+    }
+    assertReviewResolution(value) {
+        const hashes = [value.reviewHash, value.subjectHash, value.dependencyHash, ...value.evidenceRefs];
+        if (!value.findingId ||
+            !value.actor ||
+            !value.rationale ||
+            !["fixed", "accepted-risk"].includes(value.disposition) ||
+            !hashes.every((hash) => /^[0-9a-f]{64}$/.test(hash))) {
+            throw new ApexError("APEX_VALIDATION", "Invalid review resolution document", EXIT_CODES.validation);
+        }
+        if (value.disposition === "fixed" && value.evidenceRefs.length === 0)
+            throw new ApexError("APEX_VALIDATION", "Fixed findings require evidenceRefs", EXIT_CODES.validation);
+        if (value.disposition === "accepted-risk" &&
+            (value.expiresAt === undefined || Date.parse(value.expiresAt) <= this.clock().getTime())) {
+            throw new ApexError("APEX_VALIDATION", "Accepted risk requires a future expiry", EXIT_CODES.validation);
+        }
+    }
+    async decideGateNumber(gateNumber, decision, actor, options = {}) {
+        const run = await this.currentRun();
+        const gate = run.gates.find(({ gate }) => gate === gateNumber);
+        if (gate === undefined)
+            throw new ApexError("APEX_USAGE", `Unknown gate ${gateNumber}`, EXIT_CODES.usage);
+        const events = await this.journal(run).replay();
+        const previewHash = gateNumber === 4 ? this.latestPayloadHash(events, "preview.created", "previewHash") : undefined;
+        if (gateNumber === 4 && previewHash === undefined) {
+            throw new ApexError("APEX_VALIDATION", "Gate 4 requires a deployment preview", EXIT_CODES.validation);
+        }
+        if (options.recipientIdentity !== undefined && gateNumber !== 4) {
+            throw new ApexError("APEX_VALIDATION", "An explicit approval recipient is limited to TTY Gate 4 decisions", EXIT_CODES.validation);
+        }
+        if (options.recipientIdentity !== undefined && options.recipientIdentity.trim().length === 0) {
+            throw new ApexError("APEX_VALIDATION", "Approval recipient must be nonempty", EXIT_CODES.validation);
+        }
+        const previewObjectHash = gateNumber === 4 ? this.latestPayloadHash(events, "preview.created", "previewObjectHash") : undefined;
+        if (gateNumber === 4 && previewObjectHash === undefined) {
+            throw new ApexError("APEX_VALIDATION", "Gate 4 preview evidence is incomplete", EXIT_CODES.validation);
+        }
+        const preview = previewObjectHash === undefined ? undefined : await this.objects.getJson(previewObjectHash);
+        if (preview !== undefined && Date.parse(preview.expiresAt) <= this.clock().getTime()) {
+            throw new ApexError("APEX_STALE", "Deployment preview has expired", EXIT_CODES.stale);
+        }
+        const transferStore = new WriterTransferStore(this.projects.runDirectory(run.projectId, run.runId), this.clock);
+        if (gateNumber === 4)
+            await this.assertCurrentWriterAuthority(run, transferStore);
+        const writerLease = gateNumber === 4 ? await transferStore.leaseStore().current() : null;
+        const writerTransferClaimHash = preview === undefined || preview.ownerEpoch === run.ownerEpoch
+            ? undefined
+            : await transferStore.proveOneHopPostPreviewLineage(preview.previewHash, preview.ownerEpoch);
+        if (preview !== undefined && preview.ownerEpoch !== run.ownerEpoch && writerTransferClaimHash === null) {
+            throw new ApexError("APEX_STALE", "Preview writer transfer lineage is invalid", EXIT_CODES.stale);
+        }
+        const currentRecipientIdentity = await this.currentRecipientIdentity(run);
+        const approvalRecipientIdentity = options.recipientIdentity ?? currentRecipientIdentity;
+        const decidedAt = this.clock().toISOString();
+        const approvalExpiresAt = preview === undefined
+            ? undefined
+            : new Date(Math.min(Date.parse(preview.expiresAt), writerLease === null ? Number.POSITIVE_INFINITY : Date.parse(writerLease.expiresAt))).toISOString();
+        const commonApproval = {
+            schemaVersion: CONTRACT_VERSION,
+            projectId: run.projectId,
+            runId: run.runId,
+            gate: gateNumber,
+            decision,
+            actor,
+            dependencyHash: gate.dependencyHash,
+            ...(previewHash === undefined ? {} : { previewHash }),
+            ...(writerTransferClaimHash === undefined || writerTransferClaimHash === null ? {} : { writerTransferClaimHash }),
+            writerEpoch: run.ownerEpoch,
+            decidedAt,
+            ...(approvalExpiresAt === undefined ? {} : { expiresAt: approvalExpiresAt }),
+        };
+        const approval = {
+            ...commonApproval,
+            mechanism: "tty",
+            recipientIdentity: approvalRecipientIdentity,
+        };
+        this.assertValid("approval", approval);
+        const validatorIds = decision === "approved"
+            ? await this.validateGateValidators(run, gate, events, approval, approvalRecipientIdentity)
+            : [];
+        if (gateNumber === 4) {
+            await this.assertCurrentWriterAuthority(run, transferStore);
+            if (approval.expiresAt === undefined || Date.parse(approval.expiresAt) <= this.clock().getTime()) {
+                throw new ApexError("APEX_STALE", "Approval authority expired before it could be recorded", EXIT_CODES.stale);
+            }
+        }
+        const approvalHash = await this.objects.putJson(approval);
+        const updated = {
+            ...run,
+            gates: run.gates.map((item) => (item.gate === gateNumber ? decideGate(item, decision, decidedAt) : item)),
+        };
+        await this.mutateRun(run, updated, "gate.decided", {
+            gate: gateNumber,
+            approvalHash,
+            ...(previewHash === undefined ? {} : { previewHash }),
+            ...(validatorIds.length === 0 ? {} : { validatorIds }),
+        }, gateNumber === 4 ? (events.at(-1)?.hash ?? null) : undefined);
+        return approval;
+    }
+    async preview(options) {
+        const run = await this.currentRun();
+        await this.assertCurrentWriterAuthority(run, new WriterTransferStore(this.projects.runDirectory(run.projectId, run.runId), this.clock));
+        const events = await this.journal(run).replay();
+        await this.assertPreviewReady(run, events);
+        const dependencyRevision = this.dependencyRevision(run, events);
+        const intendedExecutionRecipientIdentity = options.recipientIdentity ?? (await this.currentRecipientIdentity(run));
+        const intentHash = this.artifactHash(events, "implementation-intent");
+        if (intentHash === undefined)
+            throw new ApexError("APEX_VALIDATION", "Implementation intent is required", EXIT_CODES.validation);
+        const intent = await this.objects.getJson(intentHash);
+        if (options.provider !== "fake") {
+            if (options.provider !== run.iacTool) {
+                throw new ApexError("APEX_VALIDATION", `Provider '${options.provider}' does not match selected track '${run.iacTool}'`, EXIT_CODES.validation);
+            }
+            const provider = this.providers[options.provider];
+            if (provider === undefined) {
+                throw new ApexError("APEX_VALIDATION", `${options.provider} provider is not configured; inject it through ApexService providers or configure the CLI provider registry`, EXIT_CODES.validation);
+            }
+            const request = {
+                projectId: run.projectId,
+                runId: run.runId,
+                environment: run.environment,
+                target: run.targetScope,
+                commit: dependencyRevision,
+                dependencyRevision,
+                ownerEpoch: run.ownerEpoch,
+                executionRecipientIdentity: intendedExecutionRecipientIdentity,
+                inputHash: intentHash,
+                iacHash: this.artifactHash(events, "iac-handoff") ?? sha256Json(intent.resources),
+                policyHash: this.artifactHash(events, "policy-property-map") ?? run.runtimeLockHash,
+                resources: intent.resources.map((resource) => ({
+                    logicalId: resource.id,
+                    resourceId: `${options.provider}://${run.environment}/${resource.id}`,
+                    type: resource.type,
+                    location: run.environment,
+                    properties: { purpose: resource.purpose },
+                })),
+                blockers: [],
+                ttlMs: options.expiresInMs ?? PREVIEW_TTL_MS,
+            };
+            const preview = options.operation === "apply" ? await provider.previewApply(request) : await provider.previewDestroy(request);
+            this.assertValid("preview", preview);
+            let attestation;
+            if (options.provider === "terraform" && "attestation" in provider && typeof provider.attestation === "function") {
+                attestation = provider.attestation(preview.previewHash);
+                if (attestation !== undefined)
+                    this.assertValid("execution-plan-attestation", attestation);
+            }
+            const validation = await this.validatePreviewValidators(run, events, preview, options.provider, options.operation, intent, attestation, intendedExecutionRecipientIdentity);
+            const previewObjectHash = await this.objects.putJson(preview);
+            const attestationHash = attestation === undefined ? undefined : await this.objects.putJson(attestation);
+            await this.append(run, "preview.requested", {
+                provider: options.provider,
+                operation: options.operation,
+                track: run.iacTool,
+                targetScope: run.targetScope,
+            });
+            await this.append(await this.currentRun(), "preview.created", {
+                previewHash: preview.previewHash,
+                previewObjectHash,
+                provider: options.provider,
+                providerRequestHash: sha256Json(request),
+                commit: preview.commit,
+                validatorIds: validation.validatorIds,
+                evidenceMode: validation.evidenceMode,
+                ...(validation.omittedValidatorIds.length === 0 ? {} : { omittedValidatorIds: validation.omittedValidatorIds }),
+                ...(attestationHash === undefined ? {} : { attestationHash }),
+            });
+            await this.openRunGate(await this.currentRun(), 4, preview.previewHash);
+            return preview;
+        }
+        const createdAt = this.clock().toISOString();
+        const base = {
+            schemaVersion: CONTRACT_VERSION,
+            projectId: run.projectId,
+            runId: run.runId,
+            environment: run.environment,
+            track: run.iacTool,
+            operation: options.operation,
+            target: run.targetScope,
+            commit: dependencyRevision,
+            dependencyRevision,
+            ownerEpoch: run.ownerEpoch,
+            inputHash: intentHash,
+            iacHash: sha256Json(intent.resources),
+            policyHash: this.artifactHash(events, "policy-property-map") ?? run.runtimeLockHash,
+            changes: intent.resources.map((resource) => ({
+                resourceId: `fake://${run.environment}/${resource.id}`,
+                action: options.operation === "destroy" ? "delete" : "create",
+                material: true,
+                details: resource.type,
+            })),
+            blockers: [],
+            createdAt,
+            expiresAt: new Date(this.clock().getTime() + (options.expiresInMs ?? PREVIEW_TTL_MS)).toISOString(),
+        };
+        const preview = { ...base, previewHash: sha256Json(base) };
+        this.assertValid("preview", preview);
+        const validation = await this.validatePreviewValidators(run, events, preview, "fake", options.operation, intent, undefined, intendedExecutionRecipientIdentity);
+        const previewObjectHash = await this.objects.putJson(preview);
+        await this.append(run, "preview.requested", {
+            provider: options.provider,
+            operation: options.operation,
+            track: run.iacTool,
+            targetScope: run.targetScope,
+        });
+        await this.append(run, "preview.created", {
+            previewHash: preview.previewHash,
+            previewObjectHash,
+            provider: options.provider,
+            commit: preview.commit,
+            validatorIds: validation.validatorIds,
+            evidenceMode: validation.evidenceMode,
+            ...(validation.omittedValidatorIds.length === 0 ? {} : { omittedValidatorIds: validation.omittedValidatorIds }),
+        });
+        await this.openRunGate(await this.currentRun(), 4, preview.previewHash);
+        return preview;
+    }
+    async currentPreview() {
+        const run = await this.currentRun();
+        const events = await this.journal(run).replay();
+        await this.assertPreviewReady(run, events);
+        return this.render("preview");
+    }
+    async currentApproval() {
+        const run = await this.currentRun();
+        const approvalHash = this.latestPayloadHash(await this.journal(run).replay(), "gate.decided", "approvalHash", (payload) => payload.gate === 4);
+        if (approvalHash === undefined) {
+            throw new ApexError("APEX_NOT_FOUND", "No Gate 4 approval exists for this run", EXIT_CODES.notFound);
+        }
+        return this.objects.getJson(approvalHash);
+    }
+    async deploy(expectedPreviewHash) {
+        const run = await this.currentRun();
+        const transferStore = new WriterTransferStore(this.projects.runDirectory(run.projectId, run.runId), this.clock);
+        await this.assertCurrentWriterAuthority(run, transferStore);
+        const events = await this.journal(run).replay();
+        await this.assertPreviewReady(run, events);
+        const previewHash = this.latestPayloadHash(events, "preview.created", "previewHash");
+        const previewObjectHash = this.latestPayloadHash(events, "preview.created", "previewObjectHash");
+        const approvalHash = this.latestPayloadHash(events, "gate.decided", "approvalHash", (payload) => payload.gate === 4);
+        if (previewHash === undefined || previewObjectHash === undefined || approvalHash === undefined) {
+            throw new ApexError("APEX_AUTHORIZATION", "Preview and Gate 4 approval are required", EXIT_CODES.authorization);
+        }
+        const completed = [...events]
+            .reverse()
+            .find((event) => event.type === "deployment.completed" &&
+            event.payload.previewHash === previewHash);
+        if (completed !== undefined) {
+            const payload = completed.payload;
+            if (typeof payload.operationHash === "string" && typeof payload.inventoryHash === "string") {
+                return {
+                    operation: await this.objects.getJson(payload.operationHash),
+                    inventory: await this.objects.getJson(payload.inventoryHash),
+                };
+            }
+        }
+        const incompleteExecution = [...events]
+            .reverse()
+            .find((event) => (event.type === "deployment.executed" || event.type === "deployment.indeterminate") &&
+            event.payload.previewHash === previewHash);
+        if (incompleteExecution !== undefined) {
+            throw new ApexError("APEX_CONFLICT", "Deployment outcome is incomplete or indeterminate; run reconcile before retrying", EXIT_CODES.conflict);
+        }
+        if (expectedPreviewHash !== undefined && expectedPreviewHash !== previewHash) {
+            throw new ApexError("APEX_STALE", "Requested preview hash is not current", EXIT_CODES.stale);
+        }
+        const preview = await this.objects.getJson(previewObjectHash);
+        const approval = await this.objects.getJson(approvalHash);
+        if (Date.parse(preview.expiresAt) <= this.clock().getTime())
+            throw new ApexError("APEX_STALE", "Deployment preview has expired", EXIT_CODES.stale);
+        const writerTransferClaimHash = preview.ownerEpoch === run.ownerEpoch
+            ? undefined
+            : approval.writerEpoch === preview.ownerEpoch
+                ? await transferStore.proveOneHopPostApprovalLineage(preview.previewHash, preview.ownerEpoch, approvalHash)
+                : await transferStore.proveOneHopPostPreviewLineage(preview.previewHash, preview.ownerEpoch);
+        const approvalAfterTransfer = approval.writerEpoch === run.ownerEpoch &&
+            approval.writerTransferClaimHash === (writerTransferClaimHash ?? undefined);
+        const approvalBeforeTransfer = preview.ownerEpoch + 1 === run.ownerEpoch &&
+            approval.writerEpoch === preview.ownerEpoch &&
+            approval.writerTransferClaimHash === undefined &&
+            writerTransferClaimHash !== null &&
+            writerTransferClaimHash !== undefined &&
+            approval.recipientIdentity === (await this.currentRecipientIdentity(run));
+        if ((preview.ownerEpoch !== run.ownerEpoch && writerTransferClaimHash === null) ||
+            (!approvalAfterTransfer && !approvalBeforeTransfer))
+            throw new ApexError("APEX_STALE", "Owner epoch changed", EXIT_CODES.stale);
+        const dependencyRevision = this.dependencyRevision(run, events);
+        if (preview.dependencyRevision !== dependencyRevision || preview.commit !== dependencyRevision)
+            throw new ApexError("APEX_STALE", "Deployment dependencies changed after preview", EXIT_CODES.stale);
+        if (approval.decision !== "approved" ||
+            approval.previewHash !== preview.previewHash ||
+            approval.dependencyHash !== preview.previewHash) {
+            throw new ApexError("APEX_AUTHORIZATION", "Approval does not authorize the exact preview", EXIT_CODES.authorization);
+        }
+        const providerName = [...events].reverse().find((event) => event.type === "preview.created")?.payload;
+        const provider = providerName?.provider === "bicep" || providerName?.provider === "terraform" ? providerName.provider : "fake";
+        const commonValidatorIds = await this.validateDeployValidators(run, provider, preview, approval, previewHash, dependencyRevision, "pre", undefined, undefined, undefined, writerTransferClaimHash ?? undefined);
+        const declaredValidatorIds = await this.deployValidatorIds(run);
+        if (providerName?.provider === "bicep" || providerName?.provider === "terraform") {
+            const provider = this.providers[providerName.provider];
+            if (provider === undefined)
+                throw new ApexError("APEX_VALIDATION", `${providerName.provider} provider is no longer configured`, EXIT_CODES.validation);
+            let operation;
+            try {
+                operation =
+                    preview.operation === "apply"
+                        ? await provider.apply(preview, approval, {
+                            head: preview.commit,
+                            dependencyRevision,
+                            ownerEpoch: run.ownerEpoch,
+                            ...(writerTransferClaimHash === undefined || writerTransferClaimHash === null
+                                ? {}
+                                : { previousOwnerEpoch: preview.ownerEpoch, writerTransferClaimHash }),
+                            recipientIdentity: approval.recipientIdentity ?? "local",
+                        })
+                        : await provider.destroy(preview, approval, {
+                            head: preview.commit,
+                            dependencyRevision,
+                            ownerEpoch: run.ownerEpoch,
+                            ...(writerTransferClaimHash === undefined || writerTransferClaimHash === null
+                                ? {}
+                                : { previousOwnerEpoch: preview.ownerEpoch, writerTransferClaimHash }),
+                            recipientIdentity: approval.recipientIdentity ?? "local",
+                        });
+            }
+            catch (error) {
+                await this.append(run, "deployment.indeterminate", {
+                    provider: providerName.provider,
+                    previewHash,
+                    approvalHash,
+                    preValidatorIds: commonValidatorIds,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            const executionEvidence = provider.executionEvidence?.(operation.operationId);
+            await this.append(run, "deployment.executed", {
+                provider: providerName.provider,
+                previewHash,
+                approvalHash,
+                operation: operation,
+                preValidatorIds: commonValidatorIds,
+                ...(executionEvidence === undefined ? {} : { executionEvidence: executionEvidence }),
+            });
+            return this.completeNativeDeployment(run, events, providerName.provider, provider, preview, approval, previewHash, approvalHash, dependencyRevision, commonValidatorIds, operation, executionEvidence, writerTransferClaimHash ?? undefined);
+        }
+        const now = this.clock().toISOString();
+        const operation = {
+            schemaVersion: CONTRACT_VERSION,
+            operationId: this.idSource(),
+            projectId: run.projectId,
+            runId: run.runId,
+            providerOperationId: `fake-${preview.previewHash.slice(0, 16)}`,
+            operation: preview.operation,
+            state: "succeeded",
+            previewHash,
+            approvalHash: sha256Json(approval),
+            ownerEpoch: run.ownerEpoch,
+            updatedAt: now,
+        };
+        this.assertValid("operation", operation);
+        const operationHash = await this.objects.putJson(operation);
+        const inventory = {
+            schemaVersion: CONTRACT_VERSION,
+            projectId: run.projectId,
+            runId: run.runId,
+            deploymentHash: operationHash,
+            collectedAt: now,
+            resources: preview.operation === "destroy"
+                ? []
+                : preview.changes.map((change) => ({
+                    logicalId: basename(change.resourceId),
+                    resourceId: change.resourceId,
+                    type: change.details ?? "fake/resource",
+                    location: run.environment,
+                    properties: { provider: "fake", previewHash },
+                })),
+        };
+        this.assertValid("inventory", inventory);
+        const inventoryValidatorIds = await this.validateInventoryValidators(run, preview, operation, inventory);
+        const inventoryHash = await this.objects.putJson(inventory);
+        const omittedValidatorIds = declaredValidatorIds.filter((id) => !commonValidatorIds.includes(id));
+        await this.append(run, "deployment.completed", {
+            operationHash,
+            inventoryHash,
+            previewHash,
+            approvalHash,
+            provider: "fake",
+            validatorIds: commonValidatorIds,
+            preValidatorIds: commonValidatorIds,
+            postValidatorIds: [],
+            inventoryValidatorIds,
+            ...(omittedValidatorIds.length === 0 ? {} : { omittedValidatorIds }),
+            evidenceMode: "simulated",
+        });
+        return { operation, inventory };
+    }
+    async completeNativeDeployment(run, events, providerName, provider, preview, approval, previewHash, approvalHash, dependencyRevision, commonValidatorIds, operation, executionEvidence, provedPreviewTransferClaimHash) {
+        this.assertValid("operation", operation);
+        let attestation;
+        if (providerName === "terraform") {
+            const attestationHash = this.latestPayloadHash(events, "preview.created", "attestationHash");
+            if (attestationHash !== undefined) {
+                attestation = await this.objects.getJson(attestationHash);
+                this.assertValid("execution-plan-attestation", attestation);
+            }
+        }
+        const providerValidatorIds = await this.validateDeployValidators(run, providerName, preview, approval, previewHash, dependencyRevision, "post", operation, executionEvidence, attestation, provedPreviewTransferClaimHash);
+        const receiptValidatorIds = [...(executionEvidence?.validatorIds ?? [])];
+        if (executionEvidence === undefined ||
+            new Set(receiptValidatorIds).size !== receiptValidatorIds.length ||
+            JSON.stringify(receiptValidatorIds.sort()) !== JSON.stringify([...providerValidatorIds].sort())) {
+            throw new ApexError("APEX_VALIDATION", "Provider execution receipt validator IDs do not match the workflow manifest", EXIT_CODES.validation);
+        }
+        const operationHash = await this.objects.putJson(operation);
+        const inventory = await provider.inventory(run.projectId, run.runId);
+        this.assertValid("inventory", inventory);
+        const inventoryValidatorIds = await this.validateInventoryValidators(run, preview, operation, inventory);
+        const inventoryHash = await this.objects.putJson(inventory);
+        const declaredValidatorIds = await this.deployValidatorIds(run);
+        await this.append(run, "deployment.completed", {
+            operationHash,
+            inventoryHash,
+            previewHash,
+            approvalHash,
+            provider: providerName,
+            validatorIds: declaredValidatorIds.filter((id) => [...commonValidatorIds, ...providerValidatorIds].includes(id)),
+            preValidatorIds: commonValidatorIds,
+            postValidatorIds: providerValidatorIds,
+            inventoryValidatorIds,
+            evidenceMode: "native",
+        });
+        return { operation, inventory };
+    }
+    async inventory() {
+        const run = await this.currentRun();
+        const hash = this.latestPayloadHash(await this.journal(run).replay(), "deployment.completed", "inventoryHash");
+        if (hash === undefined)
+            throw new ApexError("APEX_NOT_FOUND", "No inventory exists for this run", EXIT_CODES.notFound);
+        return this.objects.getJson(hash);
+    }
+    async promote(environment, targetScope) {
+        const source = await this.currentRun();
+        const sourceEvents = await this.journal(source).replay();
+        if (![1, 2, 3].every((gate) => this.gateApproved(source, gate)))
+            throw new ApexError("APEX_AUTHORIZATION", "Promotion requires approved Gates 1-3", EXIT_CODES.authorization);
+        const promoted = await this.projects.createRun(source.projectId, {
+            environment,
+            targetScope,
+            runtimeLockHash: source.runtimeLockHash,
+            iacTool: source.iacTool,
+            parentRunId: source.runId,
+        });
+        const sameScope = source.targetScope === targetScope;
+        const inherited = promoted.gates.map((gate) => {
+            const sourceGate = source.gates.find(({ gate: number }) => number === gate.gate);
+            const inheritable = gate.gate === 1 || (sameScope && gate.gate <= 3);
+            return inheritable && (sourceGate.state === "approved" || sourceGate.state === "inherited")
+                ? inheritGate(sourceGate, source.runId, sourceGate.dependencyHash, this.clock().toISOString())
+                : gate;
+        });
+        const updated = { ...promoted, gates: inherited };
+        await atomicWriteJson(this.runPath(updated), updated);
+        const neutralNodes = new Set([
+            "requirements",
+            "requirements-review",
+            "architecture",
+            "architecture-review",
+            ...(sameScope ? ["plan", "plan-review"] : []),
+            ...(sameScope ? ["governance-discovery", "governance-reconciliation", "governance-review"] : []),
+        ]);
+        const inheritedReviewHashes = new Set();
+        for (const event of sourceEvents) {
+            if (event.type !== "task.completed")
+                continue;
+            const payload = event.payload;
+            if (typeof payload.nodeId !== "string" || !neutralNodes.has(payload.nodeId))
+                continue;
+            if (typeof payload.reviewHash === "string")
+                inheritedReviewHashes.add(payload.reviewHash);
+            await this.append(updated, "task.completed", {
+                ...event.payload,
+                inherited: true,
+                inheritedFromRunId: source.runId,
+                inheritedEventHash: event.hash,
+            });
+        }
+        if (!sameScope) {
+            for (const event of sourceEvents) {
+                if (event.type !== "task.completed")
+                    continue;
+                const payload = event.payload;
+                if (payload.nodeId !== "plan")
+                    continue;
+                await this.append(updated, "artifacts.inherited", {
+                    nodeId: "plan",
+                    artifactHashes: (payload.artifactHashes ?? {}),
+                    inheritedFromRunId: source.runId,
+                    inheritedEventHash: event.hash,
+                    requiresRevalidation: true,
+                });
+            }
+        }
+        for (const event of sourceEvents) {
+            if (event.type !== "review.resolved")
+                continue;
+            const resolution = event.payload.resolution;
+            if (resolution === undefined || !inheritedReviewHashes.has(resolution.reviewHash))
+                continue;
+            await this.append(updated, "review.resolved", {
+                resolution: resolution,
+                inherited: true,
+                inheritedFromRunId: source.runId,
+                inheritedEventHash: event.hash,
+            });
+        }
+        await this.append(updated, "run.promoted", {
+            parentRunId: source.runId,
+            sourceDependencyRevision: this.dependencyRevision(source, sourceEvents),
+            targetScopeChanged: !sameScope,
+            invalidated: [
+                ...(!sameScope ? ["governance", "gate-2", "gate-3"] : []),
+                "codegen",
+                "validation",
+                "preview",
+                "gate-4",
+                "deploy",
+                "inventory",
+            ],
+        });
+        await this.writeSelection({ projectId: updated.projectId, runId: updated.runId });
+        return updated;
+    }
+    async doctor(fix = false, yes = false, live = false) {
+        const apexExists = await this.exists(join(this.root, ".apex"));
+        if (fix && yes && apexExists) {
+            await this.ensureLocalGitBoundary(true);
+            const assets = await resolveBundledAssets();
+            const lock = JSON.parse(await readFile(join(this.root, ".apex", "customizations.lock.json"), "utf8"));
+            const selection = await this.customizationSelection(lock.clientId);
+            if (selection.sourceMode === "custom-source") {
+                throw new ApexError("APEX_USAGE", "Custom-source repair requires an explicit customization source update", EXIT_CODES.usage);
+            }
+            const clientId = selection.clientId;
+            await this.installCustomizations(assets.clientProjections[clientId], true, assets.config, true, clientId);
+            await this.installCapabilityAssets(assets);
+            await atomicWriteJson(join(this.root, ".apex", "apex.lock.json"), await this.createRuntimeLock(assets));
+        }
+        const checks = [
+            {
+                id: "node",
+                ok: Number(process.versions.node.split(".")[0]) >= 24,
+                value: process.versions.node,
+                remedy: "Install Node.js 24 or newer",
+            },
+            { id: "workspace", ok: await this.exists(this.root), value: this.root, remedy: "Restore the workspace root" },
+            { id: "apex", ok: apexExists, value: join(this.root, ".apex"), remedy: "Run apex init" },
+        ];
+        if (apexExists) {
+            const run = await this.currentRun();
+            for (const executable of run.iacTool === "bicep" ? ["az", "bicep"] : ["az", "terraform"]) {
+                checks.push({
+                    id: `executable:${executable}`,
+                    ok: await this.executableChecker(executable),
+                    value: executable,
+                    remedy: `Install ${executable} and add it to PATH`,
+                });
+            }
+            const auth = await this.azureAuthStatus(live);
+            checks.push({
+                id: "azure-auth",
+                ok: auth.authenticated,
+                value: auth.detail,
+                remedy: "Authenticate with Azure outside doctor, then run setup --live",
+            });
+            checks.push(await this.localGitBoundaryCheck());
+            checks.push(...(await this.managedFileChecks()));
+            checks.push(...(await this.runtimeLockChecks(run)));
+            const route = await this.route(run, await this.journal(run).replay());
+            if (route.task !== undefined) {
+                const packStatuses = await this.capabilityPacks().requiredForWorkflows([route.task.id]);
+                checks.push(...packStatuses.map((status) => ({
+                    id: `capability-pack:${status.id}`,
+                    ok: status.state === "installed",
+                    value: status.reason ?? status.state,
+                    remedy: status.action,
+                })));
+            }
+            const providerConfigured = await this.exists(join(this.root, ".apex", "provider-config.json"));
+            checks.push({
+                id: "provider-config",
+                ok: providerConfigured,
+                value: providerConfigured ? "configured" : "missing",
+                remedy: "Provide --provider-config with non-secret backend settings",
+            });
+            checks.push({
+                id: "backend-readiness",
+                ok: providerConfigured,
+                value: providerConfigured ? "configured; connectivity not executed" : "not configured",
+                remedy: "Configure the selected provider backend",
+            });
+            checks.push({
+                id: "ci-plan-transport",
+                ok: false,
+                value: "production CI transport unavailable; local encrypted exact-plan supported",
+                remedy: "Use local exact-plan deployment or provide an approved CI transport implementation",
+            });
+        }
+        const remedies = checks
+            .filter((check) => !check.ok && check.remedy !== undefined)
+            .map((check) => `${fix && !yes ? "Preview: " : ""}${check.remedy}`);
+        const actionable = checks.find((check) => !check.ok && check.id !== "ci-plan-transport");
+        return {
+            healthy: checks.every((check) => check.ok || check.id === "ci-plan-transport"),
+            checks,
+            remedies,
+            nextAction: actionable?.remedy ??
+                (checks.some((check) => check.id === "ci-plan-transport")
+                    ? "Use local exact-plan deployment"
+                    : "No action required"),
+        };
+    }
+    async validate() {
+        const run = await this.currentRun();
+        const head = await this.journal(run).head();
+        const input = {
+            dependencies: { journalHead: head ?? ZERO_HASH },
+            config: { runtimeLockHash: run.runtimeLockHash },
+            toolchain: { cliVersion: APEX_VERSION },
+        };
+        const cached = await this.cache.get(input);
+        if (cached !== null)
+            return cached;
+        const result = { valid: true, events: (await this.journal(run).replay()).length };
+        await this.cache.set(input, result);
+        return result;
+    }
+    async cacheStatus() {
+        const directory = join(this.root, ".apex", "cache", "content");
+        if (!(await this.exists(directory)))
+            return { entries: 0 };
+        return { entries: (await readdir(directory)).filter((name) => /^[0-9a-f]{64}\.json$/.test(name)).length };
+    }
+    async clearCache() {
+        return { cleared: await this.cache.invalidate() };
+    }
+    async createWriterTransfer(input) {
+        const run = await this.currentRun();
+        if (input.commit !== input.currentHead)
+            throw new ApexError("APEX_STALE", "Transfer commit does not match current Git head", EXIT_CODES.stale);
+        const transfers = new WriterTransferStore(this.projects.runDirectory(run.projectId, run.runId), this.clock);
+        const ownership = await transfers.currentOwnership();
+        const expectedSender = ownership === null && run.ownerEpoch === 1 ? "local" : ownership?.ownerId;
+        if (expectedSender === undefined ||
+            (ownership?.ownerEpoch !== undefined && ownership.ownerEpoch !== run.ownerEpoch)) {
+            throw new ApexError("APEX_STALE", "Current writer ownership does not match the run epoch", EXIT_CODES.stale);
+        }
+        if (input.sender !== expectedSender) {
+            throw new ApexError("APEX_AUTHORIZATION", "Transfer sender is not the current writer", EXIT_CODES.authorization);
+        }
+        if (ownership === null) {
+            const lease = await transfers.leaseStore().current();
+            if (lease === null)
+                await transfers.leaseStore().acquireAtEpoch("local", run.ownerEpoch, input.ttlMs);
+            else if (lease.ownerId !== "local" || lease.ownerEpoch !== run.ownerEpoch) {
+                throw new ApexError("APEX_STALE", "Local writer lease does not match the run epoch", EXIT_CODES.stale);
+            }
+        }
+        return transfers.create({
+            projectId: run.projectId,
+            runId: run.runId,
+            repository: input.repository,
+            branch: input.branch,
+            commit: input.commit,
+            workflowId: input.workflowId,
+            sender: input.sender,
+            recipient: input.recipient,
+            ...(input.approvalEnvironment === undefined ? {} : { approvalEnvironment: input.approvalEnvironment }),
+            currentEpoch: run.ownerEpoch,
+            currentGitHead: input.currentHead,
+            ttlMs: input.ttlMs,
+            eventId: this.idSource(),
+        });
+    }
+    async acceptWriterTransfer(claimHash, recipient, currentHead) {
+        const run = await this.currentRun();
+        return new WriterTransferStore(this.projects.runDirectory(run.projectId, run.runId), this.clock).accept({
+            claimHash,
+            recipient,
+            currentGitHead: currentHead,
+            eventId: this.idSource(),
+        });
+    }
+    async currentWriter() {
+        const run = await this.currentRun();
+        return new WriterTransferStore(this.projects.runDirectory(run.projectId, run.runId), this.clock).currentOwnership();
+    }
+    async currentRecipientIdentity(run) {
+        const ownership = await new WriterTransferStore(this.projects.runDirectory(run.projectId, run.runId), this.clock).currentActiveOwnership();
+        return ownership?.ownerEpoch === run.ownerEpoch ? ownership.ownerId : "local";
+    }
+    async assertCurrentWriterAuthority(run, transfers) {
+        const ownership = await transfers.currentOwnership();
+        if (ownership === null && run.ownerEpoch === 1 && !(await transfers.hasPendingTransfer()))
+            return;
+        const active = await transfers.currentActiveOwnership();
+        if (active?.ownerEpoch !== run.ownerEpoch) {
+            throw new ApexError("APEX_STALE", "Current writer authority is missing or expired", EXIT_CODES.stale);
+        }
+    }
+    async acceptEvidence(input) {
+        if ((input.value === undefined) === (input.file === undefined))
+            throw new ApexError("APEX_USAGE", "Evidence requires exactly one value or file", EXIT_CODES.usage);
+        const store = await this.evidenceStore(input.kind, input.contentType);
+        let value = input.file === undefined ? input.value : await readFile(resolve(input.file));
+        if (input.kind === "architecture-availability-v1") {
+            if (input.contentType !== "application/json")
+                throw new ApexError("APEX_VALIDATION", "Architecture availability evidence must use application/json", EXIT_CODES.validation);
+            let parsed;
+            try {
+                parsed = value instanceof Uint8Array ? JSON.parse(Buffer.from(value).toString("utf8")) : value;
+            }
+            catch (error) {
+                throw new ApexError("APEX_VALIDATION", "Architecture availability evidence is not valid JSON", EXIT_CODES.validation, undefined, { cause: error });
+            }
+            this.assertValid("architecture-availability", parsed);
+            const availability = parsed;
+            if (availability.mode === "native") {
+                if (this.architectureAvailabilityAdapter === undefined) {
+                    throw new ApexError("APEX_AUTHORIZATION", "Native architecture availability evidence requires an authorized capability adapter", EXIT_CODES.authorization);
+                }
+                await this.architectureAvailabilityAdapter(availability);
+            }
+            for (const check of Object.values(availability.checks)) {
+                try {
+                    await this.objects.getBytes(check.evidenceRef);
+                }
+                catch (error) {
+                    throw new ApexError("APEX_VALIDATION", `Architecture availability source evidence is unavailable: ${check.evidenceRef}`, EXIT_CODES.validation, undefined, { cause: error });
+                }
+            }
+            value = availability;
+        }
+        const accepted = await store.accept({
+            kind: input.kind,
+            contentType: input.contentType,
+            value,
+            required: input.required,
+        });
+        await this.append(await this.currentRun(), "evidence.accepted", {
+            kind: input.kind,
+            contentType: input.contentType,
+            status: accepted.status,
+            bytes: accepted.bytes,
+            ...(accepted.hash === undefined ? {} : { hash: accepted.hash }),
+        });
+        return accepted;
+    }
+    async setTelemetryConsent(consent) {
+        await (await this.evidenceStore()).setTelemetryConsent(consent);
+        return { consent };
+    }
+    async exportTelemetry() {
+        return (await this.evidenceStore()).exportTelemetry();
+    }
+    async deleteTelemetry() {
+        await (await this.evidenceStore()).deleteTelemetry();
+        return { deleted: true };
+    }
+    async render(kind) {
+        const run = await this.currentRun();
+        if (kind === "status")
+            return renderRunStatus(run);
+        const events = await this.journal(run).replay();
+        if (kind === "requirements") {
+            const hash = this.artifactHash(events, "requirements");
+            if (hash === undefined)
+                throw new ApexError("APEX_NOT_FOUND", "No requirements artifact exists", EXIT_CODES.notFound);
+            return (await this.requirementsDocumentMarkdown(await this.objects.getJson(hash), hash)).content;
+        }
+        const map = {
+            preview: ["preview.created", "previewObjectHash", renderDeploymentPreview],
+            approval: ["gate.decided", "approvalHash", renderApprovalEvidence],
+            inventory: ["deployment.completed", "inventoryHash", renderResourceInventory],
+        };
+        const [eventType, field, renderer] = map[kind];
+        const hash = this.latestPayloadHash(events, eventType, field);
+        if (hash === undefined)
+            throw new ApexError("APEX_NOT_FOUND", `No ${kind} artifact exists`, EXIT_CODES.notFound);
+        return renderer((await this.objects.getJson(hash)));
+    }
+    async diagnose() {
+        return { status: await this.status(), doctor: await this.doctor() };
+    }
+    async reconcile() {
+        const run = await this.currentRun();
+        const events = await this.journal(run).replay();
+        const completedInventoryHash = this.latestPayloadHash(events, "deployment.completed", "inventoryHash");
+        if (completedInventoryHash !== undefined) {
+            const inventory = await this.objects.getJson(completedInventoryHash);
+            await this.append(run, "deployment.reconciled", { deploymentHash: inventory.deploymentHash });
+            return inventory;
+        }
+        const executed = [...events].reverse().find((event) => event.type === "deployment.executed");
+        if (executed === undefined)
+            throw new ApexError("APEX_NOT_FOUND", "No deployment execution exists for this run", EXIT_CODES.notFound);
+        const payload = executed.payload;
+        if ((payload.provider !== "bicep" && payload.provider !== "terraform") ||
+            typeof payload.previewHash !== "string" ||
+            typeof payload.approvalHash !== "string" ||
+            payload.operation === null ||
+            typeof payload.operation !== "object" ||
+            !Array.isArray(payload.preValidatorIds)) {
+            throw new ApexError("APEX_VALIDATION", "Deployment execution receipt is invalid", EXIT_CODES.validation);
+        }
+        const provider = this.providers[payload.provider];
+        if (provider === undefined)
+            throw new ApexError("APEX_VALIDATION", `${payload.provider} provider is required to reconcile deployment inventory`, EXIT_CODES.validation);
+        const previewObjectHash = this.latestPayloadHash(events, "preview.created", "previewObjectHash", (candidate) => candidate.previewHash === payload.previewHash);
+        if (previewObjectHash === undefined)
+            throw new ApexError("APEX_VALIDATION", "Executed deployment preview object is missing", EXIT_CODES.validation);
+        const preview = await this.objects.getJson(previewObjectHash);
+        const approval = await this.objects.getJson(payload.approvalHash);
+        const completed = await this.completeNativeDeployment(run, events, payload.provider, provider, preview, approval, payload.previewHash, payload.approvalHash, preview.dependencyRevision, payload.preValidatorIds.filter((id) => typeof id === "string"), payload.operation, payload.executionEvidence);
+        await this.append(run, "deployment.reconciled", { deploymentHash: completed.inventory.deploymentHash });
+        return completed.inventory;
+    }
+    async setup(live = false) {
+        return this.doctor(false, false, live);
+    }
+    async issueTask(run, descriptor, inputRefs = []) {
+        const head = await this.journal(run).head();
+        if (head === null)
+            throw new ApexError("APEX_STALE", "Cannot issue a task before run initialization", EXIT_CODES.stale);
+        const task = createTaskEnvelope({
+            projectId: run.projectId,
+            runId: run.runId,
+            role: descriptor.role,
+            taskType: descriptor.id,
+            expectedHead: head,
+            ownerEpoch: run.ownerEpoch,
+            inputRefs,
+            allowedOutputKinds: descriptor.outputs,
+            capabilityGrants: (descriptor.capabilities ?? []).map((capability) => ({
+                capability,
+                sideEffect: "remote",
+                expiresAt: new Date(this.clock().getTime() + TASK_TTL_MS).toISOString(),
+            })),
+            maxOutputBytes: 4 * 1024 * 1024,
+            ttlMs: TASK_TTL_MS,
+        }, this.clock, this.idSource);
+        await atomicWriteJson(join(this.projects.runDirectory(run.projectId, run.runId), "tasks", `${task.taskId}.json`), task, { refuseOverwrite: true });
+        await this.append(run, "task.issued", { taskId: task.taskId, taskType: descriptor.id });
+        const currentHead = await this.journal(run).head();
+        const current = { ...task, expectedHead: currentHead };
+        await atomicWriteJson(join(this.projects.runDirectory(run.projectId, run.runId), "tasks", `${task.taskId}.json`), current);
+        return current;
+    }
+    async openRunGate(run, gateNumber, dependencyHash) {
+        const gate = run.gates.find(({ gate }) => gate === gateNumber);
+        const reopened = gateNumber === 4 && ["open", "approved", "rejected"].includes(gate.state);
+        const nextGate = reopened
+            ? { gate: 4, state: "open", dependencyHash }
+            : openGate(gate, dependencyHash);
+        const updated = {
+            ...run,
+            gates: run.gates.map((item) => (item.gate === gateNumber ? nextGate : item)),
+        };
+        await this.mutateRun(run, updated, reopened ? "gate.reopened" : "gate.opened", {
+            gate: gateNumber,
+            dependencyHash,
+            ...(reopened ? { previousState: gate.state } : {}),
+        });
+    }
+    async mutateRun(before, after, eventType, payload, expectedJournalHead) {
+        const repository = this.runRepository(before);
+        try {
+            await repository.mutate({
+                expectedRunHash: sha256Json(before),
+                ...(expectedJournalHead === undefined ? {} : { expectedJournalHead }),
+                event: {
+                    eventId: this.idSource(),
+                    projectId: before.projectId,
+                    runId: before.runId,
+                    type: eventType,
+                    timestamp: this.clock().toISOString(),
+                    ownerEpoch: after.ownerEpoch,
+                    payload,
+                },
+                update: () => after,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                (error.message.startsWith("Stale run hash") || error.message.startsWith("Stale journal head")))
+                throw new ApexError("APEX_STALE", "Run or journal state changed", EXIT_CODES.stale, undefined, error);
+            throw error;
+        }
+    }
+    inputRequest(event, ownerEpoch) {
+        const payload = event.payload;
+        const request = {
+            schemaVersion: CONTRACT_VERSION,
+            requestId: payload.requestId,
+            expectedHead: event.hash,
+            ownerEpoch,
+            intake: payload.intake,
+            questions: payload.questions,
+        };
+        if (!Value.Check(InputRequestV1Schema, request) || !hasValidInputRequestQuestions(request.questions)) {
+            throw new ApexError("APEX_INTERNAL", "Persisted input request is invalid", EXIT_CODES.internal);
+        }
+        return request;
+    }
+    architectureDecisionRequest(event, ownerEpoch) {
+        const payload = event.payload;
+        const request = {
+            schemaVersion: CONTRACT_VERSION,
+            requestId: payload.requestId,
+            expectedHead: event.hash,
+            ownerEpoch,
+            decision: payload.decision,
+            questions: payload.questions,
+        };
+        if (!Value.Check(InputRequestV1Schema, request) ||
+            request.decision === undefined ||
+            !hasValidInputRequestQuestions(request.questions)) {
+            throw new ApexError("APEX_INTERNAL", "Persisted architecture decision request is invalid", EXIT_CODES.internal);
+        }
+        return request;
+    }
+    architectureDecisionState(events, ownerEpoch) {
+        const requested = [...events].reverse().find((event) => event.type === "architecture.decision-requested");
+        if (requested === undefined)
+            return {};
+        const request = this.architectureDecisionRequest(requested, requested.ownerEpoch);
+        const recorded = events.some((event) => event.type === "architecture.decision-recorded" &&
+            event.payload.requestId === request.requestId);
+        if (recorded)
+            return { taskId: request.decision.taskId };
+        if (request.expectedHead !== events.at(-1)?.hash || request.ownerEpoch !== ownerEpoch) {
+            return { staleTaskId: request.decision.taskId };
+        }
+        return { pending: request };
+    }
+    architectureDecisionValues(events, taskId) {
+        const result = {};
+        for (const event of events) {
+            if (event.type !== "architecture.decision-recorded")
+                continue;
+            const payload = event.payload;
+            if (payload.decision?.taskId !== taskId ||
+                typeof payload.decision.id !== "string" ||
+                !Array.isArray(payload.answers)) {
+                continue;
+            }
+            for (const answer of payload.answers) {
+                const value = answer;
+                if (typeof value.questionId === "string" && Value.Check(InputValueV1Schema, value.value)) {
+                    result[value.questionId] = value.value;
+                }
+            }
+        }
+        return result;
+    }
+    async issueArchitectureDecision(run, task) {
+        const decision = ARCHITECTURE_DECISIONS[0];
+        if (!hasValidInputRequestQuestions(decision.questions)) {
+            throw new ApexError("APEX_INTERNAL", "Kernel architecture decision questions are invalid", EXIT_CODES.internal);
+        }
+        const event = await this.append(run, "architecture.decision-requested", {
+            requestId: this.idSource(),
+            decision: { taskId: task.taskId, id: decision.id },
+            questions: decision.questions,
+        });
+        await this.refreshTaskHead(run, task);
+        return this.architectureDecisionRequest(event, run.ownerEpoch);
+    }
+    nextRequirementsIntakeRound(events) {
+        const requests = events.filter((event) => event.type === "requirements.input-requested");
+        if (requests.some((event) => {
+            const intake = event.payload.intake;
+            return intake === null || typeof intake !== "object";
+        })) {
+            throw new ApexError("APEX_CONFLICT", "Requirements intake is incompatible; start a new run", EXIT_CODES.conflict);
+        }
+        const recordedRequestIds = new Set(events.flatMap((event) => event.type === "requirements.input-recorded" &&
+            typeof event.payload.requestId === "string"
+            ? [event.payload.requestId]
+            : []));
+        const latest = requests.at(-1);
+        if (latest !== undefined && !recordedRequestIds.has(latest.payload.requestId)) {
+            const intake = latest.payload.intake;
+            const ordinal = intake.ordinal;
+            const round = typeof ordinal === "number" && Number.isInteger(ordinal) ? REQUIREMENTS_INTAKE[ordinal - 1] : undefined;
+            if (round === undefined || intake.round !== round.round || intake.total !== REQUIREMENTS_INTAKE.length) {
+                throw new ApexError("APEX_CONFLICT", "Requirements intake is incompatible; start a new run", EXIT_CODES.conflict);
+            }
+            return round;
+        }
+        return REQUIREMENTS_INTAKE[recordedRequestIds.size];
+    }
+    async issueRequirementsInput(run, round) {
+        const events = await this.journal(run).replay();
+        const questions = this.requirementsIntakeQuestions(round, events);
+        if (!hasValidInputRequestQuestions(questions)) {
+            throw new ApexError("APEX_INTERNAL", "Kernel input questions are invalid", EXIT_CODES.internal);
+        }
+        const latest = [...events].reverse().find((event) => event.type === "requirements.input-requested");
+        if (latest !== undefined) {
+            const recorded = events.some((event) => event.type === "requirements.input-recorded" &&
+                event.payload.requestId === latest.payload.requestId);
+            if (!recorded && latest.hash === events.at(-1)?.hash && latest.ownerEpoch === run.ownerEpoch) {
+                return this.inputRequest(latest, run.ownerEpoch);
+            }
+        }
+        const ordinal = REQUIREMENTS_INTAKE.findIndex(({ round: id }) => id === round.round) + 1;
+        const event = await this.append(run, "requirements.input-requested", {
+            requestId: this.idSource(),
+            intake: { round: round.round, ordinal, total: 4 },
+            questions,
+        });
+        return this.inputRequest(event, run.ownerEpoch);
+    }
+    requirementsIntakeQuestions(round, events) {
+        if (round.round !== "workload-pattern")
+            return round.questions;
+        const scenario = this.recordedRequirementsInput(events)?.["delivery-scenario"];
+        if (scenario !== "migration" && scenario !== "modernization")
+            return round.questions;
+        return [
+            ...round.questions,
+            { id: "current-platform", prompt: "Describe the current platform and hosting model." },
+            { id: "migration-pain-points", prompt: "Describe the problems the migration or modernization must address." },
+            { id: "preserve-components", prompt: "List components, integrations, or data that must be preserved." },
+        ];
+    }
+    async append(run, type, payload, expectedHead) {
+        const journal = this.journal(run);
+        return await journal.append({
+            eventId: this.idSource(),
+            projectId: run.projectId,
+            runId: run.runId,
+            type,
+            timestamp: this.clock().toISOString(),
+            ownerEpoch: run.ownerEpoch,
+            expectedHead: expectedHead === undefined ? await journal.head() : expectedHead,
+            payload,
+        });
+    }
+    journal(run) {
+        return new EventJournal(join(this.projects.runDirectory(run.projectId, run.runId), "journal"));
+    }
+    runPath(run) {
+        return join(this.projects.runDirectory(run.projectId, run.runId), "run.json");
+    }
+    async currentRun() {
+        await this.recoverCustomizationTransaction();
+        return this.run(await this.selection());
+    }
+    async run(selection) {
+        const run = await this.runRepository(selection).read();
+        const events = await this.journal(run).replay();
+        this.assertRequirementsIntakeAdmitted(events, run.ownerEpoch);
+        const retired = events.some((event) => {
+            if (event.type !== "task.completed")
+                return false;
+            const hashes = event.payload.artifactHashes;
+            return typeof hashes?.["sku-manifest"] === "string";
+        });
+        if (retired) {
+            throw new ApexError("APEX_CONFLICT", "Run uses retired sku-manifest-v1; start a new run and regenerate artifacts", EXIT_CODES.conflict, {
+                retiredArtifact: "sku-manifest-v1",
+                replacementArtifact: "workload-decision-manifest-v1",
+                recovery: "start-new-run",
+            });
+        }
+        return run;
+    }
+    assertRequirementsIntakeAdmitted(events, ownerEpoch) {
+        for (const event of events) {
+            if (event.type !== "requirements.input-requested")
+                continue;
+            let request;
+            try {
+                request = this.inputRequest(event, ownerEpoch);
+            }
+            catch {
+                throw new ApexError("APEX_CONFLICT", "Requirements intake is incompatible; start a new run", EXIT_CODES.conflict);
+            }
+            const intake = request.intake;
+            const round = intake === undefined ? undefined : REQUIREMENTS_INTAKE[intake.ordinal - 1];
+            if (round === undefined ||
+                intake === undefined ||
+                round.round !== intake.round ||
+                intake.total !== REQUIREMENTS_INTAKE.length) {
+                throw new ApexError("APEX_CONFLICT", "Requirements intake is incompatible; start a new run", EXIT_CODES.conflict);
+            }
+        }
+    }
+    runRepository(selection) {
+        return new RunRepository(this.projects.runDirectory(selection.projectId, selection.runId), {
+            clock: this.clock,
+            idSource: this.idSource,
+        });
+    }
+    async selection() {
+        return JSON.parse(await readFile(join(this.root, ".apex", "config.json"), "utf8"));
+    }
+    async writeSelection(selection) {
+        await atomicWriteJson(join(this.root, ".apex", "config.json"), selection);
+    }
+    latestPayloadHash(events, type, field, predicate) {
+        for (const event of [...events].reverse()) {
+            const payload = event.payload;
+            if (event.type === type && (predicate?.(payload) ?? true) && typeof payload[field] === "string")
+                return payload[field];
+        }
+        return undefined;
+    }
+    artifactHash(events, kind) {
+        for (const event of [...events].reverse()) {
+            if (event.type !== "task.completed")
+                continue;
+            const hashes = event.payload.artifactHashes;
+            if (typeof hashes?.[kind] === "string")
+                return hashes[kind];
+        }
+        const legacyFields = {
+            requirements: "requirementsHash",
+            "implementation-intent": "intentHash",
+        };
+        const field = legacyFields[kind];
+        return field === undefined ? undefined : this.latestPayloadHash(events, "task.completed", field);
+    }
+    acceptedArtifactHashes(events) {
+        const hashes = {};
+        const legacyFields = {
+            requirements: "requirementsHash",
+            "implementation-intent": "intentHash",
+        };
+        for (const event of events) {
+            if (event.type !== "task.completed")
+                continue;
+            const payload = event.payload;
+            for (const [kind, hash] of Object.entries(payload.artifactHashes ?? {})) {
+                if (typeof hash === "string")
+                    hashes[kind] = hash;
+            }
+            for (const [kind, field] of Object.entries(legacyFields)) {
+                const hash = payload[field];
+                if (typeof hash === "string" && hashes[kind] === undefined)
+                    hashes[kind] = hash;
+            }
+        }
+        return hashes;
+    }
+    inputRefs(events, descriptor) {
+        const availabilityKinds = new Set([
+            "architecture-availability-v1",
+            "pricing-evidence",
+            "quota-evidence",
+            "regionalAvailability-evidence",
+            "regional-availability-evidence",
+        ]);
+        const hashes = events.flatMap((event) => {
+            if (event.type === "task.completed") {
+                const artifactHashes = event.payload.artifactHashes ?? {};
+                return Object.values(artifactHashes).filter((hash) => typeof hash === "string");
+            }
+            if (event.type === "evidence.accepted" && descriptor.id === "architecture") {
+                const payload = event.payload;
+                return typeof payload.hash === "string" &&
+                    typeof payload.kind === "string" &&
+                    payload.status === "accepted" &&
+                    availabilityKinds.has(payload.kind)
+                    ? [payload.hash]
+                    : [];
+            }
+            if (event.type === "deployment.completed" && descriptor.id === "diagnosis") {
+                const payload = event.payload;
+                return [payload.operationHash, payload.inventoryHash].filter((hash) => typeof hash === "string");
+            }
+            return [];
+        });
+        return [...new Set(hashes)];
+    }
+    recordedRequirementsInput(events) {
+        const result = {};
+        let recorded = false;
+        for (const event of events) {
+            if (event.type !== "requirements.input-recorded")
+                continue;
+            const answers = event.payload.answers;
+            if (!Array.isArray(answers))
+                continue;
+            recorded = true;
+            for (const answer of answers) {
+                const value = answer;
+                if (typeof value.questionId !== "string" || !Value.Check(InputValueV1Schema, value.value)) {
+                    throw new ApexError("APEX_INTERNAL", "Recorded requirements input is invalid", EXIT_CODES.internal);
+                }
+                result[value.questionId] = value.value;
+            }
+        }
+        return recorded ? result : null;
+    }
+    outputTemplate(kind, run, events) {
+        if (kind === "requirements") {
+            const input = this.recordedRequirementsInput(events);
+            return {
+                schemaVersion: CONTRACT_VERSION,
+                projectId: run.projectId,
+                workload: typeof input?.workload === "string" ? input.workload : "",
+                environment: run.environment,
+                ...this.requirementsTemplateFromIntake(input),
+            };
+        }
+        if (kind === "implementation-intent") {
+            const sourceHashes = Object.fromEntries(["requirements", "architecture", "governance-constraints", "policy-property-map"].flatMap((artifact) => {
+                const hash = this.artifactHash(events, artifact);
+                return hash === undefined ? [] : [[artifact, hash]];
+            }));
+            return {
+                schemaVersion: CONTRACT_VERSION,
+                projectId: run.projectId,
+                runId: run.runId,
+                sourceHashes,
+                resources: [
+                    {
+                        id: "RESOURCE_ID",
+                        type: "SERVICE_TYPE",
+                        purpose: "Describe the resource purpose",
+                        dependsOn: [],
+                        controls: [],
+                    },
+                ],
+                outputs: ["OUTPUT_NAME"],
+            };
+        }
+        if (kind === "iac-binding") {
+            return {
+                schemaVersion: CONTRACT_VERSION,
+                projectId: run.projectId,
+                runId: run.runId,
+                track: run.iacTool,
+                intentHash: "0".repeat(64),
+                resourceBindings: {
+                    RESOURCE_ID: {
+                        implementation: "IMPLEMENTATION_ADDRESS",
+                        version: "IMPLEMENTATION_VERSION",
+                        parameters: {},
+                    },
+                },
+            };
+        }
+        if (kind === "environment-inputs") {
+            return {
+                schemaVersion: CONTRACT_VERSION,
+                projectId: run.projectId,
+                runId: run.runId,
+                environment: run.environment,
+                inputs: {
+                    location: { kind: "value", value: "REGION" },
+                    credential: {
+                        kind: "secret-reference",
+                        provider: "azure-key-vault",
+                        reference: "KEY_VAULT_SECRET_REFERENCE",
+                    },
+                },
+            };
+        }
+        return { schemaId: ARTIFACTS[kind][1].$id };
+    }
+    requirementsTemplateFromIntake(input) {
+        const fields = [
+            { id: "availability-recovery", label: "Availability and recovery", priority: "must" },
+            { id: "security-controls", label: "Security controls", priority: "must" },
+            { id: "compliance", label: "Compliance", priority: "should" },
+            { id: "authentication", label: "Authentication", priority: "should" },
+            { id: "operations", label: "Operations", priority: "should" },
+            { id: "budget", label: "Budget", priority: "should" },
+            { id: "iac-preference", label: "IaC preference", priority: "should" },
+            { id: "service-preferences", label: "Service preferences", priority: "should" },
+            { id: "sku-preferences", label: "SKU and sizing preferences", priority: "should" },
+            { id: "environment-overrides", label: "Environment overrides", priority: "should" },
+            { id: "retained-services", label: "Retained services", priority: "should" },
+            { id: "prohibited-services", label: "Prohibited services", priority: "should" },
+            { id: "data-sensitivity", label: "Data sensitivity", priority: "should" },
+            { id: "scale", label: "Scale", priority: "should" },
+            { id: "workload-pattern", label: "Workload pattern", priority: "should" },
+            { id: "delivery-scenario", label: "Delivery scenario", priority: "should" },
+            { id: "region", label: "Region", priority: "should" },
+        ];
+        const requirements = fields.flatMap(({ id, label, priority }, index) => {
+            const value = input?.[id];
+            const text = this.renderInputValue(value);
+            if (typeof text !== "string" || text.length === 0)
+                return [];
+            const status = /^deferred:/iu.test(text.trim())
+                ? "deferred"
+                : /^unknown$/iu.test(text.trim())
+                    ? "unknown"
+                    : "confirmed";
+            return [
+                {
+                    id: `REQ-${String(index + 1).padStart(3, "0")}`,
+                    statement: `${label}: ${text}`,
+                    priority,
+                    status,
+                    source: `intake:${id}`,
+                },
+            ];
+        });
+        const assumptions = ["industry", "target-environments"].flatMap((id) => {
+            const value = input?.[id];
+            const text = this.renderInputValue(value);
+            return typeof text === "string" && text.length > 0 ? [`${id}: ${text}`] : [];
+        });
+        const unknowns = requirements.filter(({ status }) => status !== "confirmed").map(({ statement }) => statement);
+        return {
+            requirements: requirements.length > 0
+                ? requirements
+                : [
+                    {
+                        id: "REQ-001",
+                        statement: "deferred: requirements owner",
+                        priority: "must",
+                        status: "deferred",
+                        source: "intake:missing",
+                    },
+                ],
+            assumptions,
+            unknowns,
+        };
+    }
+    renderInputValue(value) {
+        if (typeof value === "string")
+            return value;
+        if (Array.isArray(value))
+            return value.join(", ");
+        if (value === undefined)
+            return undefined;
+        switch (value.kind) {
+            case "deferred":
+                return `deferred: ${value.owner}`;
+            case "unknown":
+                return "unknown";
+            case "budget":
+                return `${value.currency} ${value.amount} ${value.cadence}`;
+            case "recovery":
+                return `RTO ${value.rtoMinutes} minutes; RPO ${value.rpoMinutes} minutes`;
+            case "data-classification":
+                return value.classification;
+            case "compliance":
+                return value.scopes.join(", ");
+        }
+    }
+    completedNodeIds(events) {
+        return new Set(events.flatMap((event) => {
+            if (event.type !== "task.completed")
+                return [];
+            const nodeId = event.payload.nodeId;
+            return typeof nodeId === "string" ? [nodeId] : [];
+        }));
+    }
+    async lockedWorkflowEngine(run) {
+        const runtimeRoot = join(this.root, ".apex", "runtime");
+        const workflowBytes = await readFile(join(runtimeRoot, "workflow.v1.json"));
+        const lock = JSON.parse(await readFile(join(this.root, ".apex", "apex.lock.json"), "utf8"));
+        this.assertValid("runtime-lock", lock);
+        if (sha256Json(lock) !== run.runtimeLockHash || sha256Bytes(workflowBytes) !== lock.workflowHash) {
+            throw new ApexError("APEX_STALE", "Runtime workflow lock is not current", EXIT_CODES.stale);
+        }
+        return new WorkflowEngine(JSON.parse(workflowBytes.toString("utf8")));
+    }
+    async route(run, events) {
+        const completed = this.completedNodeIds(events);
+        const legacy = events.some((event) => event.type === "task.completed" && event.payload.legacy === true);
+        if (legacy) {
+            if (!completed.has("requirements"))
+                return { task: TASKS[0], blockers: [] };
+            if (!this.gateApproved(run, 1))
+                return { blockers: ["Gate 1 approval is required"] };
+            if (!completed.has("plan"))
+                return { task: TASKS.find(({ id }) => id === "plan"), blockers: [] };
+            return { blockers: [] };
+        }
+        const manifest = (await this.lockedWorkflowEngine(run)).manifest;
+        const ordered = manifest.nodes
+            .flatMap((node) => {
+            const descriptor = TASKS.find(({ id }) => id === node.id);
+            const reviews = TASKS.filter(({ reviewSubject }) => reviewSubject === node.id);
+            return [...(descriptor === undefined ? [] : [descriptor]), ...reviews];
+        })
+            .filter(({ track }) => track === undefined || track === run.iacTool);
+        for (const descriptor of ordered) {
+            if (completed.has(descriptor.id)) {
+                const reviewBlockers = descriptor.reviewSubject === undefined ? [] : this.reviewBlockers(events, descriptor.id);
+                if (reviewBlockers.length > 0)
+                    return {
+                        blockers: reviewBlockers,
+                        ...(descriptor.gate === undefined ? {} : { reviewGate: descriptor.gate }),
+                    };
+                if (descriptor.gate !== undefined && !this.gateApproved(run, descriptor.gate)) {
+                    return { blockers: [`Gate ${descriptor.gate} approval is required`] };
+                }
+                continue;
+            }
+            if (descriptor.id === "diagnosis" && !events.some(({ type }) => type === "deployment.completed")) {
+                if (events.some(({ type }) => type === "deployment.executed" || type === "deployment.indeterminate")) {
+                    return { blockers: ["Deployment executed but requires reconciliation"] };
+                }
+                const preview = this.latestPayloadHash(events, "preview.created", "previewHash");
+                if (preview === undefined)
+                    return { blockers: ["Deployment preview is required"] };
+                if (!this.gateApproved(run, 4))
+                    return { blockers: ["Gate 4 approval is required"] };
+                return { blockers: ["Deployment and inventory are required"] };
+            }
+            return { task: descriptor, blockers: [] };
+        }
+        return { blockers: [] };
+    }
+    gateApproved(run, gateNumber) {
+        const state = run.gates.find(({ gate }) => gate === gateNumber)?.state;
+        return state === "approved" || state === "inherited";
+    }
+    reviewBlockers(events, nodeId) {
+        const event = [...events]
+            .reverse()
+            .find((candidate) => candidate.type === "task.completed" && candidate.payload.nodeId === nodeId);
+        const reviewHash = event?.payload?.reviewHash;
+        const subjectHash = event?.payload?.subjectHash;
+        const dependencyHash = event?.payload?.dependencyHash;
+        const resolutions = new Set(events.flatMap((candidate) => {
+            if (candidate.type !== "review.resolved")
+                return [];
+            const resolution = candidate.payload.resolution;
+            if (resolution === undefined)
+                return [];
+            return resolution.reviewHash === reviewHash &&
+                resolution.subjectHash === subjectHash &&
+                resolution.dependencyHash === dependencyHash &&
+                (resolution.disposition === "fixed" ||
+                    (resolution.expiresAt !== undefined && Date.parse(resolution.expiresAt) > this.clock().getTime()))
+                ? [resolution.findingId]
+                : [];
+        }));
+        const blockers = event?.payload?.reviewBlockers;
+        return Array.isArray(blockers)
+            ? blockers
+                .filter((id) => typeof id === "string" && !resolutions.has(id))
+                .map((id) => `Review finding ${id} must be resolved`)
+            : [];
+    }
+    dependencyRevision(run, events) {
+        return calculateDependencyRevision(run, events);
+    }
+    async assertPreviewReady(run, events) {
+        if (!this.gateApproved(run, 3))
+            throw new ApexError("APEX_AUTHORIZATION", "Gate 3 approval is required before preview", EXIT_CODES.authorization);
+        const engine = await this.lockedWorkflowEngine(run);
+        const aliases = {
+            requirements: "requirements-v1",
+            "workload-decision-manifest": "workload-decision-manifest-v1",
+            architecture: "architecture-v1",
+            "cost-estimate": "cost-estimate-v1",
+            "governance-constraints": "governance-constraints-v1",
+            "policy-property-map": "policy-property-map-v1",
+            "implementation-intent": "implementation-intent-v1",
+            "iac-binding": "iac-binding-v1",
+            "environment-inputs": "environment-inputs-v1",
+            "logical-resource-manifest": "logical-resource-manifest-v1",
+            "iac-handoff": "iac-handoff-v1",
+            "validation-evidence": "validation-evidence-v1",
+        };
+        const artifacts = {
+            "project-config": true,
+            defaults: true,
+            toolchain: true,
+            "runtime-bundle": true,
+            "governance-capability-lock": true,
+            "quota-evidence": true,
+            "pricing-evidence": true,
+            "regional-availability-evidence": true,
+            "quota-evidence-current": true,
+            "accepted-risk-scopes": true,
+            ...(run.iacTool === "bicep"
+                ? { "bicep-tree": true }
+                : { "terraform-tree": true, "terraform-lockfile": true, "terraform-state-lineage-and-serial": true }),
+        };
+        for (const event of events) {
+            if (event.type !== "task.completed")
+                continue;
+            const payload = event.payload;
+            for (const [kind, hash] of Object.entries(payload.artifactHashes ?? {})) {
+                const alias = aliases[kind];
+                if (alias !== undefined && typeof hash === "string")
+                    artifacts[alias] = hash;
+            }
+            if (typeof payload.nodeId === "string" && payload.nodeId.endsWith("-review")) {
+                artifacts[payload.nodeId] = true;
+                if (payload.nodeId === "governance-review")
+                    artifacts["governance-reconciliation-review"] = true;
+            }
+        }
+        const completedNodes = [
+            ...this.completedNodeIds(events),
+            ...run.gates.flatMap((gate) => gate.state === "approved" || gate.state === "inherited" ? [`gate-${gate.gate}`] : []),
+        ];
+        const route = engine.route({
+            run: { iacTool: run.iacTool, targetScope: run.targetScope },
+            artifacts,
+            completedNodes,
+            gateStates: Object.fromEntries(run.gates.map((gate) => [`gate-${gate.gate}`, gate.state])),
+        });
+        const expectedNode = `preview-${run.iacTool}`;
+        if (route.nextTask !== expectedNode) {
+            const blockers = route.blockers.length > 0 ? route.blockers : [`workflow-route:${route.currentNode ?? "none"}`];
+            throw new ApexError("APEX_AUTHORIZATION", `Workflow is not ready for ${expectedNode}: ${blockers.join(", ")}`, EXIT_CODES.authorization, blockers);
+        }
+        for (const reviewNode of ["requirements-review", "architecture-review", "governance-review", "plan-review"]) {
+            const blockers = this.reviewBlockers(events, reviewNode);
+            if (blockers.length > 0)
+                throw new ApexError("APEX_AUTHORIZATION", blockers.join("; "), EXIT_CODES.authorization, blockers);
+        }
+    }
+    openReviewFindings(value) {
+        const review = value;
+        return (review.findings ?? [])
+            .filter((finding) => finding.disposition === "open" && finding.severity !== "info")
+            .map(({ id }) => id);
+    }
+    validateOutput(run, output) {
+        const descriptor = ARTIFACTS[output.kind];
+        this.assertValid(descriptor[0], output.value);
+        if (output.value === null || typeof output.value !== "object")
+            return;
+        const identity = output.value;
+        if (identity.projectId !== undefined && identity.projectId !== run.projectId) {
+            throw new ApexError("APEX_VALIDATION", "Task output project identity does not match the selected run", EXIT_CODES.validation);
+        }
+        if (identity.runId !== undefined && identity.runId !== run.runId) {
+            throw new ApexError("APEX_VALIDATION", "Task output run identity does not match the selected run", EXIT_CODES.validation);
+        }
+        if (identity.track !== undefined && identity.track !== run.iacTool) {
+            throw new ApexError("APEX_VALIDATION", `Artifact track '${String(identity.track)}' does not match selected track '${run.iacTool}'`, EXIT_CODES.validation);
+        }
+        if (output.kind === "environment-inputs") {
+            const inputs = output.value;
+            if (inputs.environment !== run.environment || !hasOnlyTypedSecretReferences(inputs)) {
+                throw new ApexError("APEX_VALIDATION", "Environment inputs do not match the run or contain an invalid secret reference", EXIT_CODES.validation);
+            }
+            for (const [name, input] of Object.entries(inputs.inputs)) {
+                if (input.kind === "value" && /secret|password|token|credential|api[-_]?key/i.test(name)) {
+                    throw new ApexError("APEX_VALIDATION", `Environment input '${name}' must use a secret-reference`, EXIT_CODES.validation);
+                }
+            }
+        }
+        if (output.kind === "cost-estimate" && !hasValidCostArithmetic(output.value)) {
+            throw new ApexError("APEX_VALIDATION", "Cost estimate arithmetic does not reconcile", EXIT_CODES.validation);
+        }
+        if (output.kind === "logical-resource-manifest" &&
+            !hasValidLogicalResourceReferences(output.value)) {
+            throw new ApexError("APEX_VALIDATION", "Logical resource dependencies are invalid", EXIT_CODES.validation);
+        }
+    }
+    async validateBundle(run, descriptor, outputs, events) {
+        const byKind = Object.fromEntries(outputs.map((output) => [output.kind, output.value]));
+        if (descriptor.id === "architecture") {
+            const manifest = byKind["workload-decision-manifest"];
+            const requirementsHash = this.artifactHash(events, "requirements");
+            if (requirementsHash === undefined ||
+                manifest.projectId !== run.projectId ||
+                manifest.runId !== run.runId ||
+                manifest.environment !== run.environment ||
+                !manifest.environments.includes(run.environment) ||
+                manifest.sourceRequirementsHash !== requirementsHash ||
+                manifest.architectureHash !== sha256Json(byKind.architecture) ||
+                manifest.costEstimateHash !== sha256Json(byKind["cost-estimate"])) {
+                throw new ApexError("APEX_VALIDATION", "Workload decision manifest does not bind accepted artifacts", EXIT_CODES.validation);
+            }
+        }
+        if (descriptor.id === "plan") {
+            const intent = byKind["implementation-intent"];
+            const binding = byKind["iac-binding"];
+            const resourceIds = new Set(intent.resources.map(({ id }) => id));
+            const bindingIds = Object.keys(binding.resourceBindings);
+            if (binding.track !== run.iacTool ||
+                binding.intentHash !== sha256Json(intent) ||
+                bindingIds.length !== resourceIds.size ||
+                bindingIds.some((id) => !resourceIds.has(id))) {
+                throw new ApexError("APEX_VALIDATION", "IaC binding track, intent hash, or resource coverage is invalid", EXIT_CODES.validation);
+            }
+        }
+        if (descriptor.id.startsWith("codegen-")) {
+            const manifest = byKind["logical-resource-manifest"];
+            const handoff = byKind["iac-handoff"];
+            if (handoff.logicalResourceManifestHash !== sha256Json(manifest) ||
+                handoff.intentHash !== this.artifactHash(events, "implementation-intent") ||
+                handoff.bindingHash !== this.artifactHash(events, "iac-binding") ||
+                handoff.environmentInputsHash !== this.artifactHash(events, "environment-inputs") ||
+                !/^[0-9a-f]{64}$/.test(handoff.treeHash)) {
+                throw new ApexError("APEX_VALIDATION", "IaC handoff does not bind the accepted logical manifest and code tree", EXIT_CODES.validation);
+            }
+        }
+        if (descriptor.id === "governance-reconciliation") {
+            const policy = byKind["policy-property-map"];
+            if (policy.governanceHash !== this.artifactHash(events, "governance-constraints")) {
+                throw new ApexError("APEX_VALIDATION", "Policy property map does not bind accepted governance constraints", EXIT_CODES.validation);
+            }
+        }
+        if (descriptor.reviewSubject !== undefined) {
+            const review = byKind["review-findings"];
+            const subjectKind = descriptor.reviewSubject === "governance-reconciliation" ? "policy-property-map" : descriptor.reviewSubject;
+            if (review.subjectKind !== subjectKind)
+                throw new ApexError("APEX_VALIDATION", `Review subject must be ${subjectKind}`, EXIT_CODES.validation);
+            const expectedHash = subjectKind === "plan"
+                ? this.artifactHash(events, "implementation-intent")
+                : this.artifactHash(events, subjectKind);
+            if (expectedHash === undefined || review.subjectHash !== expectedHash) {
+                throw new ApexError("APEX_VALIDATION", `Review does not bind the accepted ${subjectKind} artifact`, EXIT_CODES.validation);
+            }
+        }
+    }
+    async validateTaskValidators(run, task, descriptor, outputs, events) {
+        const workflow = await this.lockedWorkflowEngine(run);
+        const nodeId = descriptor.reviewSubject ?? descriptor.id;
+        const node = workflow.manifest.nodes.find(({ id }) => id === nodeId);
+        if (node === undefined)
+            throw new Error(`Workflow task ${nodeId} has no manifest node`);
+        const boundary = descriptor.reviewSubject !== undefined
+            ? "review"
+            : descriptor.id.startsWith("validation-")
+                ? "validation"
+                : descriptor.id === "quality"
+                    ? "quality"
+                    : descriptor.id === "diagnosis"
+                        ? "diagnosis"
+                        : "task-output";
+        const boundaries = new Set([boundary, ...(descriptor.id === "architecture" ? ["external-evidence"] : [])]);
+        const validatorIds = node.validators.filter((id) => {
+            const validatorBoundary = workflowValidatorOwnership(id)?.boundary;
+            return validatorBoundary !== undefined && boundaries.has(validatorBoundary);
+        });
+        const artifactHashes = this.acceptedArtifactHashes(events);
+        const artifacts = Object.fromEntries(await Promise.all(Object.entries(artifactHashes).map(async ([kind, hash]) => [kind, await this.objects.getJson(hash)])));
+        let availabilityEvidence;
+        let availabilityHash;
+        let deploymentOperation;
+        let deploymentInventory;
+        if (descriptor.id === "architecture") {
+            const pinnedRefs = new Set(task.inputRefs);
+            availabilityHash = this.latestPayloadHash(events, "evidence.accepted", "hash", (payload) => payload.kind === "architecture-availability-v1" &&
+                payload.status === "accepted" &&
+                typeof payload.hash === "string" &&
+                pinnedRefs.has(payload.hash));
+            if (availabilityHash !== undefined) {
+                availabilityEvidence = await this.objects.getJson(availabilityHash);
+                this.assertValid("architecture-availability", availabilityEvidence);
+            }
+        }
+        if (descriptor.id === "diagnosis") {
+            const completed = [...events].reverse().find((event) => event.type === "deployment.completed");
+            const payload = completed?.payload;
+            if (typeof payload?.operationHash === "string" &&
+                typeof payload.inventoryHash === "string" &&
+                task.inputRefs.includes(payload.operationHash) &&
+                task.inputRefs.includes(payload.inventoryHash)) {
+                deploymentOperation = await this.objects.getJson(payload.operationHash);
+                deploymentInventory = await this.objects.getJson(payload.inventoryHash);
+                this.assertValid("operation", deploymentOperation);
+                this.assertValid("inventory", deploymentInventory);
+            }
+        }
+        const context = {
+            nodeId,
+            now: this.clock().toISOString(),
+            track: run.iacTool,
+            targetScope: run.targetScope,
+            inputRefs: task.inputRefs,
+            outputs: Object.fromEntries(outputs.map(({ kind, value }) => [kind, value])),
+            artifacts,
+            artifactHashes,
+            ...(availabilityEvidence === undefined ? {} : { availabilityEvidence }),
+            ...(deploymentOperation === undefined ? {} : { deploymentOperation }),
+            ...(deploymentInventory === undefined ? {} : { deploymentInventory }),
+            ...(nodeId === "quality" ? await this.qualityValidatorContext() : {}),
+        };
+        for (const id of validatorIds) {
+            this.assertValid(id, taskWorkflowValidatorInput(id, context));
+        }
+        return {
+            validatorIds,
+            evidenceRefs: availabilityHash === undefined ? {} : { "business:availability-current": availabilityHash },
+            evidenceModes: availabilityEvidence === undefined ? {} : { "business:availability-current": availabilityEvidence.mode },
+        };
+    }
+    async qualityValidatorContext() {
+        let qualityMeasurements;
+        try {
+            qualityMeasurements = JSON.parse(await readFile(join(this.root, ".apex", "quality", "measurements.json"), "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new ApexError("APEX_VALIDATION", "Quality measurements are unavailable; run quality evaluate first", EXIT_CODES.validation);
+            }
+            throw error;
+        }
+        this.assertValid("quality-measurements", qualityMeasurements);
+        return {
+            scorecard: JSON.parse(await readFile(join(this.root, ".apex", "runtime", "quality-scorecard.v1.json"), "utf8")),
+            qualityMeasurements,
+        };
+    }
+    async validateGateValidators(run, gate, events, approval, expectedApprovalRecipientIdentity) {
+        const workflow = await this.lockedWorkflowEngine(run);
+        const nodeId = `gate-${gate.gate}`;
+        const node = workflow.manifest.nodes.find(({ id }) => id === nodeId);
+        if (node === undefined)
+            throw new Error(`Workflow gate ${nodeId} has no manifest node`);
+        const validatorIds = node.validators.filter((id) => workflowValidatorOwnership(id)?.boundary === "gate");
+        const artifactHashes = {};
+        for (const event of events) {
+            if (event.type !== "task.completed")
+                continue;
+            const hashes = event.payload.artifactHashes ?? {};
+            for (const [kind, hash] of Object.entries(hashes))
+                if (typeof hash === "string")
+                    artifactHashes[kind] = hash;
+        }
+        const completedNodes = [...this.completedNodeIds(events)].sort();
+        const reviewNodesByGate = {
+            1: ["requirements-review"],
+            2: ["architecture-review", "governance-review"],
+            3: ["plan-review"],
+            4: ["requirements-review", "architecture-review", "governance-review", "plan-review"],
+        };
+        let reviewNodes = reviewNodesByGate[gate.gate] ?? [];
+        let legacyRequirements = false;
+        let expectedDependencyHash;
+        const dependencyReview = { 1: "requirements-review", 2: "governance-review", 3: "plan-review" }[gate.gate];
+        if (dependencyReview !== undefined) {
+            expectedDependencyHash = this.latestPayloadHash(events, "task.completed", "dependencyHash", (payload) => payload.nodeId === dependencyReview);
+        }
+        if (gate.gate === 1 && expectedDependencyHash === undefined) {
+            const legacyEvent = [...events]
+                .reverse()
+                .find((event) => event.type === "task.completed" &&
+                event.payload.nodeId === "requirements" &&
+                event.payload.legacy === true);
+            const hashes = legacyEvent?.payload?.artifactHashes;
+            if (hashes !== undefined) {
+                legacyRequirements = true;
+                reviewNodes = [];
+                expectedDependencyHash = sha256Json(hashes);
+            }
+        }
+        let preview;
+        if (gate.gate === 4) {
+            const previewObjectHash = this.latestPayloadHash(events, "preview.created", "previewObjectHash");
+            if (previewObjectHash !== undefined)
+                preview = await this.objects.getJson(previewObjectHash);
+            expectedDependencyHash = preview?.previewHash;
+        }
+        const provedPreviewTransferClaimHash = preview === undefined || preview.ownerEpoch === run.ownerEpoch
+            ? undefined
+            : ((await new WriterTransferStore(this.projects.runDirectory(run.projectId, run.runId), this.clock).proveOneHopPostPreviewLineage(preview.previewHash, preview.ownerEpoch)) ?? undefined);
+        const context = {
+            gateNumber: gate.gate,
+            now: this.clock().toISOString(),
+            run,
+            gate,
+            approval,
+            artifactHashes,
+            completedNodes,
+            reviewBlockers: reviewNodes.flatMap((reviewNode) => this.reviewBlockers(events, reviewNode)),
+            currentDependencyRevision: this.dependencyRevision(run, events),
+            legacyRequirements,
+            expectedApprovalRecipientIdentity,
+            ...(provedPreviewTransferClaimHash === undefined ? {} : { provedPreviewTransferClaimHash }),
+            ...(expectedDependencyHash === undefined ? {} : { expectedDependencyHash }),
+            ...(preview === undefined ? {} : { preview }),
+        };
+        for (const id of validatorIds)
+            this.assertValid(id, context);
+        return validatorIds;
+    }
+    async validatePreviewValidators(run, events, preview, provider, expectedOperation, intent, attestation, intendedExecutionRecipientIdentity = "local") {
+        const workflow = await this.lockedWorkflowEngine(run);
+        const nodeId = `preview-${run.iacTool}`;
+        const node = workflow.manifest.nodes.find(({ id }) => id === nodeId);
+        if (node === undefined)
+            throw new Error(`Workflow preview ${nodeId} has no manifest node`);
+        const declaredIds = node.validators.filter((id) => workflowValidatorOwnership(id)?.boundary === "preview");
+        const omittedValidatorIds = provider === "fake" ? declaredIds.filter((id) => id === "terraform:saved-plan-binding") : [];
+        const validatorIds = declaredIds.filter((id) => !omittedValidatorIds.includes(id));
+        const context = {
+            now: this.clock().toISOString(),
+            run,
+            provider,
+            expectedOperation,
+            preview,
+            intent,
+            expectedInputHash: this.artifactHash(events, "implementation-intent") ?? sha256Json(intent),
+            expectedIacHash: provider === "fake"
+                ? sha256Json(intent.resources)
+                : (this.artifactHash(events, "iac-handoff") ?? sha256Json(intent.resources)),
+            expectedPolicyHash: this.artifactHash(events, "policy-property-map") ?? run.runtimeLockHash,
+            currentDependencyRevision: this.dependencyRevision(run, events),
+            expectedResourceIds: intent.resources.map(({ id }) => `${provider}://${run.environment}/${id}`),
+            intendedExecutionRecipientIdentity,
+            ...(attestation === undefined ? {} : { attestation }),
+        };
+        for (const id of validatorIds)
+            this.assertValid(id, context);
+        return { validatorIds, omittedValidatorIds, evidenceMode: provider === "fake" ? "simulated" : "native" };
+    }
+    async validateDeployValidators(run, provider, preview, approval, expectedPreviewHash, currentDependencyRevision, phase, operation, executionEvidence, attestation, provedPreviewTransferClaimHash) {
+        const workflow = await this.lockedWorkflowEngine(run);
+        const nodeId = `deploy-${run.iacTool}`;
+        const node = workflow.manifest.nodes.find(({ id }) => id === nodeId);
+        if (node === undefined)
+            throw new Error(`Workflow deployment ${nodeId} has no manifest node`);
+        const owner = phase === "pre" ? "@apexops/cli" : "@apexops/capabilities";
+        const validatorIds = node.validators.filter((id) => {
+            const ownership = workflowValidatorOwnership(id);
+            return ownership?.boundary === "deploy" && ownership.owner === owner;
+        });
+        const context = {
+            now: this.clock().toISOString(),
+            run,
+            provider,
+            preview,
+            approval,
+            expectedPreviewHash,
+            currentDependencyRevision,
+            ...(provedPreviewTransferClaimHash === undefined ? {} : { provedPreviewTransferClaimHash }),
+            ...(operation === undefined ? {} : { operation }),
+            ...(executionEvidence === undefined ? {} : { executionEvidence }),
+            ...(attestation === undefined ? {} : { attestation }),
+        };
+        for (const id of validatorIds)
+            this.assertValid(id, context);
+        return validatorIds;
+    }
+    async deployValidatorIds(run) {
+        const workflow = await this.lockedWorkflowEngine(run);
+        return (workflow.manifest.nodes
+            .find(({ id }) => id === `deploy-${run.iacTool}`)
+            ?.validators.filter((id) => workflowValidatorOwnership(id)?.boundary === "deploy") ?? []);
+    }
+    async validateInventoryValidators(run, preview, operation, inventory) {
+        const workflow = await this.lockedWorkflowEngine(run);
+        const node = workflow.manifest.nodes.find(({ id }) => id === "inventory");
+        if (node === undefined)
+            throw new Error("Workflow inventory node is missing");
+        const validatorIds = node.validators.filter((id) => workflowValidatorOwnership(id)?.boundary === "inventory");
+        const context = { run, preview, operation, inventory };
+        for (const id of validatorIds)
+            this.assertValid(id, context);
+        return validatorIds;
+    }
+    async ensureTerminalCompletion(run, events) {
+        if (events.some(({ type }) => type === "workflow.completed"))
+            return events;
+        const workflow = await this.lockedWorkflowEngine(run);
+        const legacy = events.some((event) => event.type === "task.completed" && event.payload.legacy === true);
+        const artifactAliases = {
+            requirements: "requirements-v1",
+            "workload-decision-manifest": "workload-decision-manifest-v1",
+            architecture: "architecture-v1",
+            "cost-estimate": "cost-estimate-v1",
+            "governance-constraints": "governance-constraints-v1",
+            "policy-property-map": "policy-property-map-v1",
+            "implementation-intent": "implementation-intent-v1",
+            "iac-binding": "iac-binding-v1",
+            "environment-inputs": "environment-inputs-v1",
+            "logical-resource-manifest": "logical-resource-manifest-v1",
+            "iac-handoff": "iac-handoff-v1",
+            "validation-evidence": "validation-evidence-v1",
+            diagnosis: "diagnosis-report-v1",
+            "quality-report": "quality-report-v1",
+        };
+        const artifacts = {};
+        for (const event of events) {
+            const payload = event.payload;
+            if (event.type === "task.completed") {
+                const hashes = payload.artifactHashes ?? {};
+                for (const [kind, hash] of Object.entries(hashes)) {
+                    if (typeof hash === "string")
+                        artifacts[artifactAliases[kind] ?? kind] = hash;
+                }
+            }
+            if (event.type === "preview.created" && typeof payload.previewHash === "string") {
+                artifacts["deployment-preview-v1"] = payload.previewHash;
+            }
+            if (event.type === "gate.decided" && payload.gate === 4 && typeof payload.approvalHash === "string") {
+                artifacts["approval-evidence-v1"] = payload.approvalHash;
+            }
+            if (event.type === "deployment.completed") {
+                if (typeof payload.operationHash === "string")
+                    artifacts["operation-record-v1"] = payload.operationHash;
+                if (typeof payload.inventoryHash === "string")
+                    artifacts["resource-inventory-v1"] = payload.inventoryHash;
+            }
+        }
+        const activeValidatorIds = legacy
+            ? events.flatMap((event) => {
+                if (event.type !== "task.completed")
+                    return [];
+                const ids = event.payload.validatorIds;
+                return Array.isArray(ids) ? ids.filter((id) => typeof id === "string") : [];
+            })
+            : workflow.activeValidatorIds({
+                run: { iacTool: run.iacTool, targetScope: run.targetScope },
+                artifacts,
+            });
+        const executedValidatorIds = new Set();
+        const simulatedOmittedValidatorIds = new Set();
+        for (const event of events) {
+            const payload = event.payload;
+            for (const ids of [payload.validatorIds, payload.inventoryValidatorIds]) {
+                if (Array.isArray(ids)) {
+                    for (const id of ids)
+                        if (typeof id === "string")
+                            executedValidatorIds.add(id);
+                }
+            }
+            const omissionNodeId = payload.evidenceMode === "simulated" && payload.provider === "fake"
+                ? event.type === "preview.created"
+                    ? `preview-${run.iacTool}`
+                    : event.type === "deployment.completed"
+                        ? `deploy-${run.iacTool}`
+                        : undefined
+                : undefined;
+            const allowedOmissions = new Set(workflow.manifest.nodes
+                .find(({ id }) => id === omissionNodeId)
+                ?.validators.filter((id) => workflowValidatorOwnership(id)?.owner === "@apexops/capabilities") ?? []);
+            if (Array.isArray(payload.omittedValidatorIds)) {
+                for (const id of payload.omittedValidatorIds) {
+                    if (typeof id === "string" && allowedOmissions.has(id))
+                        simulatedOmittedValidatorIds.add(id);
+                }
+            }
+        }
+        for (const gate of run.gates) {
+            if (gate.state !== "inherited")
+                continue;
+            const node = workflow.manifest.nodes.find(({ id }) => id === `gate-${gate.gate}`);
+            for (const id of node?.validators ?? []) {
+                if (workflowValidatorOwnership(id)?.boundary === "gate")
+                    executedValidatorIds.add(id);
+            }
+        }
+        const terminalIds = workflow.manifest.nodes
+            .find(({ id }) => id === "completed")
+            ?.validators.filter((id) => workflowValidatorOwnership(id)?.boundary === "terminal") ?? [];
+        const deduplicatedActiveValidatorIds = [...new Set(activeValidatorIds)].sort();
+        const context = {
+            activeValidatorIds: deduplicatedActiveValidatorIds,
+            executedValidatorIds: [...executedValidatorIds].sort(),
+            simulatedOmittedValidatorIds: [...simulatedOmittedValidatorIds].sort(),
+        };
+        for (const id of terminalIds)
+            this.assertValid(id, context);
+        await this.append(run, "workflow.completed", {
+            validatorIds: terminalIds,
+            activeValidatorIds: deduplicatedActiveValidatorIds,
+            executedValidatorIds: [...context.executedValidatorIds],
+            simulatedOmittedValidatorIds: [...context.simulatedOmittedValidatorIds],
+            ...(legacy ? { legacy: true } : {}),
+        });
+        return this.journal(run).replay();
+    }
+    legacyPlanOutputs(run, intent) {
+        const intentHash = sha256Json(intent);
+        const resources = intent.resources;
+        return [
+            {
+                kind: "iac-binding",
+                value: {
+                    schemaVersion: CONTRACT_VERSION,
+                    projectId: run.projectId,
+                    runId: run.runId,
+                    track: run.iacTool,
+                    intentHash,
+                    resourceBindings: Object.fromEntries(resources.map(({ id, type }) => [id, { implementation: type, version: "legacy", parameters: {} }])),
+                },
+            },
+            {
+                kind: "environment-inputs",
+                value: {
+                    schemaVersion: CONTRACT_VERSION,
+                    projectId: run.projectId,
+                    runId: run.runId,
+                    environment: run.environment,
+                    inputs: {},
+                },
+            },
+        ];
+    }
+    async readTask(run, taskId) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u.test(taskId)) {
+            throw new ApexError("APEX_VALIDATION", "Task ID is invalid", EXIT_CODES.validation);
+        }
+        try {
+            return JSON.parse(await readFile(join(this.projects.runDirectory(run.projectId, run.runId), "tasks", `${taskId}.json`), "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new ApexError("APEX_NOT_FOUND", "Task was not found", EXIT_CODES.notFound, undefined, { cause: error });
+            }
+            throw error;
+        }
+    }
+    async refreshTaskHead(run, task) {
+        const expectedHead = await this.journal(run).head();
+        if (expectedHead === null)
+            throw new ApexError("APEX_STALE", "Task journal is empty", EXIT_CODES.stale);
+        await atomicWriteJson(join(this.projects.runDirectory(run.projectId, run.runId), "tasks", `${task.taskId}.json`), {
+            ...task,
+            expectedHead,
+        });
+    }
+    async assertNoSymlinkPath(root, destination) {
+        await mkdir(root, { recursive: true });
+        const rootStat = await lstat(root);
+        if (rootStat.isSymbolicLink() || !rootStat.isDirectory())
+            throw new ApexError("APEX_VALIDATION", "Code staging root must be a real directory", EXIT_CODES.validation);
+        let current = root;
+        for (const segment of relative(root, destination).split(sep).slice(0, -1)) {
+            current = join(current, segment);
+            if (!(await this.exists(current)))
+                continue;
+            const entry = await lstat(current);
+            if (entry.isSymbolicLink() || !entry.isDirectory())
+                throw new ApexError("APEX_VALIDATION", "Code staging path contains a non-directory or symlink", EXIT_CODES.validation);
+        }
+    }
+    async directoryBytes(directory) {
+        if (!(await this.exists(directory)))
+            return 0;
+        let total = 0;
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new ApexError("APEX_VALIDATION", "Code staging tree contains a symlink", EXIT_CODES.validation);
+            total += entry.isDirectory() ? await this.directoryBytes(path) : (await stat(path)).size;
+        }
+        return total;
+    }
+    looksLikeIntent(value) {
+        return (value !== null &&
+            typeof value === "object" &&
+            Array.isArray(value.resources) &&
+            Array.isArray(value.outputs) &&
+            typeof value.sourceHashes === "object");
+    }
+    looksLikeBinding(value, track) {
+        return (value !== null &&
+            typeof value === "object" &&
+            value.track === track &&
+            typeof value.intentHash === "string" &&
+            typeof value.resourceBindings === "object");
+    }
+    looksLikeEnvironmentInputs(value) {
+        return (value !== null &&
+            typeof value === "object" &&
+            typeof value.environment === "string" &&
+            typeof value.inputs === "object");
+    }
+    assertValid(name, value) {
+        const result = this.validators.validate(name, value);
+        const issues = result.issues.filter((issue) => !issue.message.startsWith("Unknown format 'date"));
+        const invalidDateTimes = name.startsWith("schema:") || !name.includes(":") ? this.invalidDateTimes(value) : [];
+        if (issues.length > 0 || invalidDateTimes.length > 0) {
+            throw new ApexError("APEX_VALIDATION", `${name} validation failed`, EXIT_CODES.validation, [
+                ...issues,
+                ...invalidDateTimes.map((path) => ({ path, message: "Invalid ISO date-time" })),
+            ]);
+        }
+    }
+    invalidDateTimes(value, path = "") {
+        if (Array.isArray(value)) {
+            return value.flatMap((item, index) => this.invalidDateTimes(item, `${path}/${index}`));
+        }
+        if (value === null || typeof value !== "object")
+            return [];
+        return Object.entries(value).flatMap(([key, item]) => {
+            const itemPath = `${path}/${key}`;
+            if ((key.endsWith("At") || key === "expiresAt") && typeof item === "string") {
+                return Number.isNaN(Date.parse(item)) || new Date(item).toISOString() !== item ? [itemPath] : [];
+            }
+            return this.invalidDateTimes(item, itemPath);
+        });
+    }
+    async improvements(run) {
+        if (this.improvementPolicy !== undefined) {
+            this.improvementRuntime ??= new ImprovementStore(this.root, this.improvementPolicy, this.clock);
+            return this.improvementRuntime;
+        }
+        const [policyBytes, lockBytes] = await Promise.all([
+            readFile(join(this.root, ".apex", "runtime", "improvement-policy.v1.json")),
+            readFile(join(this.root, ".apex", "apex.lock.json")),
+        ]);
+        const lock = JSON.parse(lockBytes.toString("utf8"));
+        this.assertValid("runtime-lock", lock);
+        if (sha256Json(lock) !== run.runtimeLockHash || sha256Bytes(policyBytes) !== lock.improvementPolicyHash) {
+            throw new ApexError("APEX_STALE", "Improvement policy lock is not current", EXIT_CODES.stale);
+        }
+        this.improvementRuntime ??= new ImprovementStore(this.root, JSON.parse(policyBytes.toString("utf8")), this.clock);
+        return this.improvementRuntime;
+    }
+    async latestRun(projectId) {
+        const names = await readdir(join(this.projects.projectDirectory(projectId), "runs"));
+        const runs = await Promise.all(names.map((name) => this.projects.getRun(projectId, name)));
+        const latest = runs.sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
+        if (latest === undefined)
+            throw new ApexError("APEX_NOT_FOUND", "Project has no runs", EXIT_CODES.notFound);
+        return latest.runId;
+    }
+    async customizationSelection(legacyClientId = "github-copilot-vscode") {
+        try {
+            const value = JSON.parse(await readFile(join(this.root, ".apex", "customizations.selection.json"), "utf8"));
+            if (value.version !== 1 ||
+                !["github-copilot-cli", "github-copilot-vscode"].includes(value.clientId) ||
+                !["bundled-projection", "custom-source"].includes(value.sourceMode) ||
+                (value.sourceMode === "custom-source" && typeof value.customSource !== "string")) {
+                throw new ApexError("APEX_VALIDATION", "Customization selection is invalid", EXIT_CODES.validation);
+            }
+            return value;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            return { version: 1, clientId: legacyClientId, sourceMode: "bundled-projection" };
+        }
+    }
+    async assertCleanInitialization() {
+        if (await this.exists(join(this.root, ".apex")))
+            throw new ApexError("APEX_CONFLICT", "Workspace is already initialized", EXIT_CODES.conflict);
+    }
+    async createRuntimeLock(assets) {
+        const runtimeRoot = join(this.root, ".apex", "runtime");
+        const packs = JSON.parse(await readFile(join(runtimeRoot, "capability-packs.registry.json"), "utf8"));
+        const requiredCapabilityPacks = (packs.packs ?? []).map((pack) => {
+            const id = typeof pack.id === "string" ? pack.id : pack.name;
+            if (typeof id !== "string" || id.length === 0)
+                throw new ApexError("APEX_VALIDATION", "Capability pack has no identifier", EXIT_CODES.validation);
+            return id;
+        });
+        const validatorPath = (await this.exists(join(runtimeRoot, "runtime-bundle.v1.json")))
+            ? join(runtimeRoot, "runtime-bundle.v1.json")
+            : join(runtimeRoot, "toolchain.v1.json");
+        const lock = {
+            schemaVersion: CONTRACT_VERSION,
+            cliVersion: APEX_VERSION,
+            customizationVersion: assets.manifest.sources.customizations,
+            workflowHash: sha256Bytes(await readFile(join(runtimeRoot, "workflow.v1.json"))),
+            defaultsHash: sha256Bytes(await readFile(join(runtimeRoot, "defaults.v1.json"))),
+            validatorHash: sha256Bytes(await readFile(validatorPath)),
+            qualityScorecardHash: sha256Bytes(await readFile(join(runtimeRoot, "quality-scorecard.v1.json"))),
+            improvementPolicyHash: sha256Bytes(await readFile(join(runtimeRoot, "improvement-policy.v1.json"))),
+            requiredCapabilityPacks: [...new Set(requiredCapabilityPacks)].sort(),
+        };
+        this.assertValid("runtime-lock", lock);
+        return lock;
+    }
+    capabilityPacks(manifestPath) {
+        return new CapabilityPackManager({
+            root: this.root,
+            manifestPath: manifestPath ?? join(this.root, ".apex", "runtime", "capability-packs.registry.json"),
+            processRunner: this.processRunner,
+        });
+    }
+    async runtimeLockChecks(run) {
+        const path = join(this.root, ".apex", "apex.lock.json");
+        try {
+            const lock = JSON.parse(await readFile(path, "utf8"));
+            this.assertValid("runtime-lock", lock);
+            const runtimeRoot = join(this.root, ".apex", "runtime");
+            const validatorPath = (await this.exists(join(runtimeRoot, "runtime-bundle.v1.json")))
+                ? join(runtimeRoot, "runtime-bundle.v1.json")
+                : join(runtimeRoot, "toolchain.v1.json");
+            const hashes = [
+                { id: "runtime-lock:workflow", expected: lock.workflowHash, path: join(runtimeRoot, "workflow.v1.json") },
+                { id: "runtime-lock:defaults", expected: lock.defaultsHash, path: join(runtimeRoot, "defaults.v1.json") },
+                { id: "runtime-lock:validators", expected: lock.validatorHash, path: validatorPath },
+                {
+                    id: "runtime-lock:quality-scorecard",
+                    expected: lock.qualityScorecardHash,
+                    path: join(runtimeRoot, "quality-scorecard.v1.json"),
+                },
+                {
+                    id: "runtime-lock:improvement-policy",
+                    expected: lock.improvementPolicyHash,
+                    path: join(runtimeRoot, "improvement-policy.v1.json"),
+                },
+            ];
+            const checks = await Promise.all(hashes.map(async (item) => {
+                const actual = (await this.exists(item.path)) ? sha256Bytes(await readFile(item.path)) : "missing";
+                return {
+                    id: item.id,
+                    ok: actual === item.expected,
+                    value: actual,
+                    remedy: "Run doctor --fix --yes to reinstall bundled runtime files",
+                };
+            }));
+            checks.unshift({
+                id: "runtime-lock:run-binding",
+                ok: sha256Json(lock) === run.runtimeLockHash,
+                value: sha256Json(lock),
+                remedy: "Reinitialize the run against the installed runtime lock",
+            });
+            const packs = JSON.parse(await readFile(join(runtimeRoot, "capability-packs.registry.json"), "utf8"));
+            const available = new Set((packs.packs ?? []).flatMap(({ id }) => (id === undefined ? [] : [id])));
+            checks.push({
+                id: "capability-packs",
+                ok: lock.requiredCapabilityPacks.every((id) => available.has(id)),
+                value: [...available].sort().join(","),
+                remedy: "Run doctor --fix --yes to reinstall the capability pack manifest",
+            });
+            return checks;
+        }
+        catch (error) {
+            return [
+                {
+                    id: "runtime-lock",
+                    ok: false,
+                    value: error instanceof Error ? error.message : "invalid",
+                    remedy: "Run doctor --fix --yes to reinstall the runtime lock",
+                },
+            ];
+        }
+    }
+    async ensureLocalGitBoundary(repair = false) {
+        const apexRoot = join(this.root, ".apex");
+        const path = join(apexRoot, ".gitignore");
+        await this.assertSafeDestination(apexRoot, path);
+        const current = await this.readOptional(path);
+        if (current?.toString("utf8") === APEX_GITIGNORE)
+            return;
+        if (current !== undefined && !repair)
+            throw new ApexError("APEX_CONFLICT", "APEX local Git boundary was modified", EXIT_CODES.conflict);
+        await atomicWriteBytes(path, Buffer.from(APEX_GITIGNORE));
+    }
+    async ensureWorkspaceRuntime() {
+        const packagePath = join(this.root, "node_modules", "@apexops", "cli", "package.json");
+        try {
+            const installed = JSON.parse(await readFile(packagePath, "utf8"));
+            if (installed.version === APEX_VERSION)
+                return false;
+            if (typeof installed.version === "string") {
+                throw new ApexError("APEX_CONFLICT", `Workspace has @apexops/cli@${installed.version}; expected ${APEX_VERSION}`, EXIT_CODES.conflict);
+            }
+        }
+        catch (error) {
+            if (error instanceof ApexError)
+                throw error;
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        try {
+            await this.processRunner.run({
+                executable: "npm",
+                args: [
+                    "install",
+                    "--save-dev",
+                    "--save-exact",
+                    "--ignore-scripts",
+                    "--no-audit",
+                    "--no-fund",
+                    `@apexops/cli@${APEX_VERSION}`,
+                ],
+                cwd: this.root,
+                timeoutMs: 120_000,
+                maxOutputBytes: 1_048_576,
+            });
+        }
+        catch (error) {
+            throw new ApexError("APEX_INTERNAL", `Unable to install @apexops/cli@${APEX_VERSION} in the workspace`, EXIT_CODES.internal, undefined, { cause: error });
+        }
+        return true;
+    }
+    async ensureWorkspaceGitRepository(createRepository) {
+        const gitPath = join(this.root, ".git");
+        if (await this.pathExistsLstat(gitPath))
+            return;
+        if (!createRepository) {
+            throw new ApexError("APEX_USAGE", "Bootstrap requires a Git repository; rerun with createRepository: true and --yes to initialize one", EXIT_CODES.usage);
+        }
+        try {
+            await this.processRunner.run({
+                executable: "git",
+                args: ["init"],
+                cwd: this.root,
+                timeoutMs: 30_000,
+                maxOutputBytes: 64 * 1024,
+            });
+        }
+        catch (error) {
+            throw new ApexError("APEX_INTERNAL", "Unable to initialize the workspace Git repository", EXIT_CODES.internal, undefined, { cause: error });
+        }
+    }
+    profilePaths() {
+        return {
+            agent: join(this.profileRoot, PROFILE_BOOTSTRAP_FILENAME),
+            receipt: join(this.profileRoot, PROFILE_BOOTSTRAP_RECEIPT),
+        };
+    }
+    async ensureProfileRoot() {
+        await mkdir(this.profileRoot, { recursive: true });
+        const metadata = await lstat(this.profileRoot);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+            throw new ApexError("APEX_VALIDATION", "Profile agent directory must be a real directory", EXIT_CODES.validation);
+        }
+    }
+    async readProfileReceipt(path) {
+        const bytes = await this.readProfileOptional(path);
+        if (bytes === undefined)
+            return undefined;
+        const receipt = JSON.parse(bytes.toString("utf8"));
+        if (receipt.version !== 1 ||
+            typeof receipt.packageVersion !== "string" ||
+            !/^[a-f0-9]{64}$/.test(receipt.contentHash)) {
+            throw new ApexError("APEX_VALIDATION", "Profile APEX bootstrap receipt is invalid", EXIT_CODES.validation);
+        }
+        return receipt;
+    }
+    async readProfileOptional(path) {
+        try {
+            const metadata = await lstat(path);
+            if (metadata.isSymbolicLink() || !metadata.isFile()) {
+                throw new ApexError("APEX_VALIDATION", "Profile APEX bootstrap path must be a regular file", EXIT_CODES.validation);
+            }
+            return await readFile(path);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    async localGitBoundaryCheck() {
+        const path = join(this.root, ".apex", ".gitignore");
+        try {
+            if (!(await this.pathExistsLstat(path))) {
+                return {
+                    id: "local-git-boundary",
+                    ok: false,
+                    value: "missing",
+                    remedy: "Run doctor --fix --yes to restore the APEX local Git boundary",
+                };
+            }
+            await this.assertSafeExistingPath(join(this.root, ".apex"), path);
+            const actual = await readFile(path);
+            const actualHash = sha256Bytes(actual);
+            return {
+                id: "local-git-boundary",
+                ok: actual.toString("utf8") === APEX_GITIGNORE,
+                value: actualHash,
+                remedy: "Run doctor --fix --yes to restore the APEX local Git boundary",
+            };
+        }
+        catch (error) {
+            return {
+                id: "local-git-boundary",
+                ok: false,
+                value: error instanceof Error ? error.message : "invalid",
+                remedy: "Run doctor --fix --yes to restore the APEX local Git boundary",
+            };
+        }
+    }
+    async managedFileChecks() {
+        const path = join(this.root, ".apex", "customizations.lock.json");
+        try {
+            const lock = JSON.parse(await readFile(path, "utf8"));
+            const workspaceFiles = lock.files.map((file) => ({ ...file, root: this.root }));
+            const runtimeRoot = join(this.root, ".apex", "runtime");
+            const runtimeFiles = lock.runtime.map((file) => ({ ...file, root: runtimeRoot }));
+            return await Promise.all([...workspaceFiles, ...runtimeFiles].map(async (file) => {
+                if (!this.safeManagedRelativePath(file.path)) {
+                    throw new ApexError("APEX_VALIDATION", "Managed customization path is unsafe", EXIT_CODES.validation);
+                }
+                const destination = resolve(file.root, file.path);
+                await this.assertSafeDestination(file.root, destination);
+                const actual = (await this.exists(destination)) ? sha256Bytes(await readFile(destination)) : "missing";
+                const hashesValid = [file.sourceHash, file.baseHash, file.currentHash].every((hash) => /^[0-9a-f]{64}$/.test(hash));
+                return {
+                    id: `managed:${relative(this.root, destination)}`,
+                    ok: hashesValid && actual === file.currentHash,
+                    value: actual,
+                    remedy: "Run doctor --fix --yes to reinstall bundled managed files",
+                };
+            }));
+        }
+        catch (error) {
+            return [
+                {
+                    id: "managed-files",
+                    ok: false,
+                    value: error instanceof Error ? error.message : "invalid",
+                    remedy: "Run doctor --fix --yes to reinstall bundled managed files",
+                },
+            ];
+        }
+    }
+    async evidenceStore(kind, contentType) {
+        const defaults = JSON.parse(await readFile(join(this.root, ".apex", "runtime", "defaults.v1.json"), "utf8"));
+        const maxBytes = defaults.evidence?.budgets?.perEntryBytes;
+        if (!Number.isInteger(maxBytes) || maxBytes === undefined || maxBytes < 1)
+            throw new ApexError("APEX_VALIDATION", "Runtime evidence byte budget is invalid", EXIT_CODES.validation);
+        const kinds = kind === undefined
+            ? {}
+            : {
+                [kind]: {
+                    contentTypes: [contentType],
+                    maxBytes,
+                    retention: defaults.evidence?.immutableKinds?.includes(kind)
+                        ? "immutable"
+                        : "project",
+                },
+            };
+        return new EvidenceStore(this.root, new EvidencePolicy({ kinds }));
+    }
+    async pathExecutableExists(executable) {
+        for (const directory of (process.env.PATH ?? "").split(delimiter).filter((item) => item.length > 0)) {
+            try {
+                await access(join(directory, executable), constants.X_OK);
+                return true;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT" && error.code !== "EACCES")
+                    throw error;
+            }
+        }
+        return false;
+    }
+    async installCustomizations(sourcePath, update, runtimeSource, repair = false, clientId = "github-copilot-vscode") {
+        await this.recoverCustomizationTransaction();
+        const source = resolve(sourcePath);
+        const sourceStat = await lstat(source);
+        if (!sourceStat.isDirectory() || sourceStat.isSymbolicLink())
+            throw new ApexError("APEX_VALIDATION", "Customizations source must be a real directory", EXIT_CODES.validation);
+        await this.assertSafeExistingPath(source, source);
+        const lockPath = join(this.root, ".apex", "customizations.lock.json");
+        let previous;
+        if (update)
+            previous = JSON.parse(await readFile(lockPath, "utf8"));
+        const transactionRoot = join(this.root, ".apex", "local", `update-${this.idSource()}`);
+        const entries = [];
+        const prepare = async (sourceRoot, destinationRoot, oldFiles, label) => {
+            const sourceFiles = await this.walkFiles(sourceRoot);
+            const managed = [];
+            const incomingPaths = new Set();
+            for (const absoluteSource of sourceFiles) {
+                const path = relative(sourceRoot, absoluteSource);
+                incomingPaths.add(path);
+                const destination = resolve(destinationRoot, path);
+                if (destination !== destinationRoot && !destination.startsWith(`${destinationRoot}${sep}`))
+                    throw new ApexError("APEX_VALIDATION", `${label} destination escapes its root`, EXIT_CODES.validation);
+                await this.assertSafeDestination(destinationRoot, destination);
+                const incoming = await readFile(absoluteSource);
+                const sourceHash = sha256Bytes(incoming);
+                const old = oldFiles.find((file) => file.path === path);
+                let output = incoming;
+                const existed = await this.pathExistsLstat(destination);
+                if (existed) {
+                    const current = await readFile(destination);
+                    const currentHash = sha256Bytes(current);
+                    if (old === undefined && currentHash !== sourceHash)
+                        throw new ApexError("APEX_CONFLICT", `Existing file conflicts with managed ${label}: ${path}`, EXIT_CODES.conflict);
+                    if (!repair && old !== undefined && currentHash !== old.currentHash && currentHash !== old.baseHash) {
+                        const base = await this.readManagedBase(old.baseRef);
+                        const merged = base === undefined ? undefined : this.mergeText(base, current, incoming);
+                        if (merged === undefined)
+                            throw new ApexError("APEX_CONFLICT", `Managed ${label} conflict: ${path}`, EXIT_CODES.conflict);
+                        output = Buffer.from(merged);
+                    }
+                }
+                const staged = join(transactionRoot, "incoming", label, path);
+                await atomicWriteBytes(staged, output);
+                const backup = existed ? join(transactionRoot, "backup", label, path) : undefined;
+                if (backup !== undefined)
+                    await atomicWriteBytes(backup, await readFile(destination));
+                entries.push({ destination, staged, ...(backup === undefined ? {} : { backup }), existed });
+                const baseRef = join(".apex", "customization-bases", sourceHash, label, path);
+                const baseDestination = join(this.root, baseRef);
+                await this.assertSafeDestination(this.root, baseDestination);
+                entries.push({
+                    destination: baseDestination,
+                    staged: join(transactionRoot, "bases", sourceHash, label, path),
+                    existed: await this.pathExistsLstat(baseDestination),
+                });
+                await atomicWriteBytes(entries.at(-1).staged, incoming);
+                managed.push({ path, sourceHash, baseHash: sourceHash, currentHash: sha256Bytes(output), baseRef });
+            }
+            for (const old of oldFiles.filter((file) => !incomingPaths.has(file.path))) {
+                const destination = resolve(destinationRoot, old.path);
+                await this.assertSafeDestination(destinationRoot, destination);
+                if (!(await this.pathExistsLstat(destination)))
+                    continue;
+                const currentHash = sha256Bytes(await readFile(destination));
+                if (currentHash !== old.currentHash && currentHash !== old.baseHash)
+                    throw new ApexError("APEX_CONFLICT", `Removed managed ${label} was locally modified: ${old.path}`, EXIT_CODES.conflict);
+                const backup = join(transactionRoot, "backup", label, old.path);
+                await atomicWriteBytes(backup, await readFile(destination));
+                entries.push({ destination, backup, existed: true, remove: true });
+            }
+            return managed;
+        };
+        const managed = await prepare(source, this.root, previous?.files ?? [], "customization");
+        const runtime = runtimeSource === undefined
+            ? (previous?.runtime ?? [])
+            : await prepare(resolve(runtimeSource), join(this.root, ".apex", "runtime"), previous?.runtime ?? [], "runtime");
+        let previousLockRef;
+        if (previous !== undefined) {
+            const previousHash = sha256Json(previous);
+            previousLockRef = join(".apex", "customization-bases", "locks", `${previousHash}.json`);
+            const previousLockDestination = join(this.root, previousLockRef);
+            if (!(await this.pathExistsLstat(previousLockDestination))) {
+                const stagedPreviousLock = join(transactionRoot, "previous-lock.json");
+                await atomicWriteJson(stagedPreviousLock, previous);
+                entries.push({ destination: previousLockDestination, staged: stagedPreviousLock, existed: false });
+            }
+        }
+        const nextLock = {
+            version: 1,
+            source,
+            clientId,
+            runtime,
+            files: managed,
+            ...(previousLockRef === undefined ? {} : { previousLockRef }),
+        };
+        const stagedLock = join(transactionRoot, "customizations.lock.json");
+        await atomicWriteJson(stagedLock, nextLock);
+        const lockExisted = await this.pathExistsLstat(lockPath);
+        const lockBackup = lockExisted ? join(transactionRoot, "backup", "customizations.lock.json") : undefined;
+        if (lockBackup !== undefined)
+            await atomicWriteBytes(lockBackup, await readFile(lockPath));
+        entries.push({
+            destination: lockPath,
+            staged: stagedLock,
+            ...(lockBackup === undefined ? {} : { backup: lockBackup }),
+            existed: lockExisted,
+        });
+        const transactionPath = join(transactionRoot, "transaction.json");
+        await atomicWriteJson(transactionPath, {
+            version: 1,
+            status: "applying",
+            entries,
+        });
+        await atomicWriteJson(join(this.root, ".apex", "local", "customization-transaction.json"), { transactionPath });
+        try {
+            for (const [index, entry] of entries.entries()) {
+                await this.customizationFailureInjector?.(index, entry.destination);
+                if (entry.remove)
+                    await rm(entry.destination, { force: true });
+                else {
+                    await mkdir(resolve(entry.destination, ".."), { recursive: true });
+                    await rename(entry.staged, entry.destination);
+                }
+            }
+            await rm(join(this.root, ".apex", "local", "customization-transaction.json"), { force: true });
+            await rm(transactionRoot, { recursive: true, force: true });
+            return managed.map(({ path }) => path);
+        }
+        catch (error) {
+            await this.rollbackCustomizationTransaction({ version: 1, status: "applying", entries });
+            await rm(join(this.root, ".apex", "local", "customization-transaction.json"), { force: true });
+            await rm(transactionRoot, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    async installCapabilityAssets(assets) {
+        const runtimeRoot = join(this.root, ".apex", "runtime");
+        const destination = join(runtimeRoot, "capability-packs");
+        await this.assertSafeExistingPath(assets.capabilityPacks, assets.capabilityPacks);
+        await rm(destination, { recursive: true, force: true });
+        await cp(assets.capabilityPacks, destination, {
+            recursive: true,
+            dereference: false,
+            errorOnExist: true,
+            force: false,
+        });
+        await rename(join(destination, "registry.v1.json"), join(runtimeRoot, "capability-packs.registry.json"));
+    }
+    async recoverCustomizationTransaction() {
+        const pointer = join(this.root, ".apex", "local", "customization-transaction.json");
+        try {
+            const { transactionPath } = JSON.parse(await readFile(pointer, "utf8"));
+            const localRoot = join(this.root, ".apex", "local");
+            const resolvedTransaction = resolve(transactionPath);
+            await this.assertSafeExistingPath(localRoot, resolvedTransaction);
+            const transaction = JSON.parse(await readFile(resolvedTransaction, "utf8"));
+            await this.rollbackCustomizationTransaction(transaction);
+            await rm(resolve(resolvedTransaction, ".."), { recursive: true, force: true });
+            await rm(pointer, { force: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    async rollbackCustomizationTransaction(transaction) {
+        for (const entry of [...transaction.entries].reverse()) {
+            await this.assertSafeDestination(this.root, resolve(entry.destination));
+            if (entry.backup !== undefined && (await this.pathExistsLstat(entry.backup))) {
+                await this.assertSafeExistingPath(join(this.root, ".apex", "local"), resolve(entry.backup));
+            }
+            if (entry.existed && entry.backup !== undefined && (await this.pathExistsLstat(entry.backup)))
+                await atomicWriteBytes(entry.destination, await readFile(entry.backup));
+            else if (!entry.existed)
+                await rm(entry.destination, { force: true });
+        }
+    }
+    safeManagedRelativePath(path) {
+        return (path.length > 0 &&
+            !path.includes("\\") &&
+            !path.includes("\0") &&
+            !isAbsolute(path) &&
+            path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== ".."));
+    }
+    async readManagedBase(baseRef) {
+        if (baseRef === undefined)
+            return undefined;
+        if (!this.safeManagedRelativePath(baseRef)) {
+            throw new ApexError("APEX_VALIDATION", "Managed customization base path is unsafe", EXIT_CODES.validation);
+        }
+        const path = resolve(this.root, baseRef);
+        if (!(await this.pathExistsLstat(path)))
+            return undefined;
+        await this.assertSafeExistingPath(this.root, path);
+        return await readFile(path);
+    }
+    mergeText(base, local, incoming) {
+        if ([base, local, incoming].some((value) => value.includes(0)))
+            return undefined;
+        const baseText = base.toString("utf8");
+        const localText = local.toString("utf8");
+        const incomingText = incoming.toString("utf8");
+        if (localText === baseText)
+            return incoming;
+        if (incomingText === baseText)
+            return local;
+        const baseLines = baseText.split("\n");
+        const localLines = localText.split("\n");
+        const incomingLines = incomingText.split("\n");
+        if (baseLines.length !== localLines.length || baseLines.length !== incomingLines.length)
+            return undefined;
+        const merged = baseLines.map((line, index) => {
+            const localLine = localLines[index];
+            const incomingLine = incomingLines[index];
+            if (localLine !== line && incomingLine !== line && localLine !== incomingLine)
+                return undefined;
+            return localLine !== line ? localLine : incomingLine;
+        });
+        return merged.includes(undefined) ? undefined : Buffer.from(merged.join("\n"));
+    }
+    async assertSafeDestination(root, destination) {
+        const resolvedRoot = resolve(root);
+        const resolvedDestination = resolve(destination);
+        if (resolvedDestination !== resolvedRoot && !resolvedDestination.startsWith(`${resolvedRoot}${sep}`))
+            throw new ApexError("APEX_VALIDATION", "Managed destination escapes its root", EXIT_CODES.validation);
+        let current = resolvedRoot;
+        if (await this.pathExistsLstat(current))
+            await this.assertSafeExistingPath(resolvedRoot, current);
+        for (const segment of relative(resolvedRoot, resolvedDestination).split(sep)) {
+            if (!segment)
+                continue;
+            current = join(current, segment);
+            if (await this.pathExistsLstat(current))
+                await this.assertSafeExistingPath(resolvedRoot, current);
+        }
+    }
+    async assertSafeExistingPath(root, path) {
+        const entry = await lstat(path);
+        if (entry.isSymbolicLink())
+            throw new ApexError("APEX_VALIDATION", `Managed path contains a symlink: ${path}`, EXIT_CODES.validation);
+        const actual = await realpath(path);
+        const actualRoot = await realpath(root);
+        if (actual !== actualRoot && !actual.startsWith(`${actualRoot}${sep}`))
+            throw new ApexError("APEX_VALIDATION", `Managed path escapes its root: ${path}`, EXIT_CODES.validation);
+    }
+    async pathExistsLstat(path) {
+        try {
+            await lstat(path);
+            return true;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+    }
+    async readOptional(path) {
+        try {
+            return await readFile(path);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    async walkFiles(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))) {
+            const path = join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new ApexError("APEX_VALIDATION", `Customization source contains a symlink: ${path}`, EXIT_CODES.validation);
+            if (entry.isDirectory())
+                files.push(...(await this.walkFiles(path)));
+            else if (entry.isFile())
+                files.push(path);
+        }
+        return files;
+    }
+    async exists(path) {
+        try {
+            await stat(path);
+            return true;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=service.js.map