@apexops/cli 0.10.0-next.3 → 0.10.0-next.5

package/dist/service.js

@@ -1,11 +1,11 @@
 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 { ContentCache, EvidencePolicy, EvidenceStore, EventJournal, ImprovementStore, ObjectStore, ProjectStore, RunRepository, ValidatorRegistry, WriterTransferStore, WorkflowEngine, assertTaskCurrent, atomicWriteBytes, atomicWriteJson, createTaskEnvelope, decideGate, inheritGate, invalidateGate, 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 { homedir, userInfo } 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";
@@ -106,7 +106,7 @@ const TASKS = [
     { id: "diagnosis", role: "diagnostic-operator", outputs: ["diagnosis"] },
     { id: "quality", role: "quality-evaluator", outputs: ["quality-report"] },
 ];
-const REQUIREMENTS_INTAKE = [
+const LEGACY_REQUIREMENTS_INTAKE = [
     {
         round: "business-discovery",
         questions: [
@@ -129,6 +129,11 @@ const REQUIREMENTS_INTAKE = [
                 id: "delivery-scenario",
                 prompt: "Is this a greenfield build, migration, modernization, or extension?",
                 options: ["greenfield", "migration", "modernization", "extension"],
+                recommendation: {
+                    value: "greenfield",
+                    source: "default",
+                    rationale: "Use greenfield unless an existing workload must be migrated, modernized, or extended.",
+                },
             },
             {
                 id: "target-environments",
@@ -136,6 +141,11 @@ const REQUIREMENTS_INTAKE = [
                 options: ["dev", "test", "staging", "prod"],
                 multiSelect: true,
                 valueType: "environment-set",
+                recommendation: {
+                    value: ["dev", "prod"],
+                    source: "default",
+                    rationale: "Plan development and production intent; each environment remains a separate governed run.",
+                },
             },
         ],
     },
@@ -154,6 +164,11 @@ const REQUIREMENTS_INTAKE = [
                 prompt: "Choose the data classification or explicitly defer it.",
                 options: ["public", "internal", "confidential", "restricted"],
                 valueType: "data-classification",
+                recommendation: {
+                    value: "internal",
+                    source: "default",
+                    rationale: "Use internal as the baseline unless the workload handles public-only or more sensitive data.",
+                },
             },
             { id: "iac-preference", prompt: "Choose the preferred infrastructure tool.", options: ["bicep", "terraform"] },
         ],
@@ -161,7 +176,10 @@ const REQUIREMENTS_INTAKE = [
     {
         round: "service-preferences",
         questions: [
-            { id: "prohibited-services", prompt: "List prohibited services, or explicitly defer the constraint." },
+            {
+                id: "prohibited-services",
+                prompt: "List prohibited services, use 'none', or explicitly defer the constraint.",
+            },
             {
                 id: "service-preferences",
                 prompt: "Select preferred Azure services. Select all that apply; architecture chooses the exact combination.",
@@ -209,17 +227,32 @@ const REQUIREMENTS_INTAKE = [
                     "diagnostic-logging",
                 ],
                 multiSelect: true,
+                recommendation: {
+                    value: ["managed-identity", "key-vault", "platform-managed-encryption", "diagnostic-logging"],
+                    source: "default",
+                    rationale: "APEX security baseline; confirm additions or exceptions for this workload.",
+                },
             },
             {
                 id: "authentication",
                 prompt: "Select the required authentication and authorization mechanisms.",
                 options: ["microsoft-entra-id", "managed-identity", "external-oidc", "api-key", "anonymous"],
                 multiSelect: true,
+                recommendation: {
+                    value: ["microsoft-entra-id", "managed-identity"],
+                    source: "default",
+                    rationale: "Use Entra ID for people and managed identity for workload-to-service access.",
+                },
             },
             {
                 id: "region",
                 prompt: "Choose the Azure region, or explicitly defer the decision.",
                 options: ["swedencentral", "westeurope", "germanywestcentral"],
+                recommendation: {
+                    value: "swedencentral",
+                    source: "default",
+                    rationale: "Repository default for EU data residency and service deployment.",
+                },
             },
             {
                 id: "availability-recovery",
@@ -248,6 +281,17 @@ const REQUIREMENTS_INTAKE = [
         ],
     },
 ];
+const REQUIREMENTS_INTAKE = [
+    LEGACY_REQUIREMENTS_INTAKE[0],
+    {
+        round: "workload-pattern",
+        questions: [
+            ...LEGACY_REQUIREMENTS_INTAKE[1].questions.filter(({ id }) => id !== "iac-preference"),
+            ...LEGACY_REQUIREMENTS_INTAKE[2].questions,
+        ],
+    },
+    LEGACY_REQUIREMENTS_INTAKE[3],
+];
 const ARCHITECTURE_DECISIONS = [
     {
         id: "network-exposure",
@@ -379,6 +423,8 @@ export class ApexService {
             await this.installCapabilityAssets(assets);
             const runtimeLock = await this.createRuntimeLock(assets);
             await atomicWriteJson(join(this.root, ".apex", "apex.lock.json"), runtimeLock);
+            await atomicWriteJson(join(this.root, ".apex", "runtime", "apex.lock.json"), runtimeLock);
+            await this.installRuntimeGeneration(runtimeLock);
             return this.createProject(input);
         }
         catch (error) {
@@ -486,6 +532,8 @@ export class ApexService {
         const selection = await this.selection();
         await this.ensureLocalGitBoundary();
         const assets = await resolveBundledAssets();
+        const previousRuntimeLock = JSON.parse(await readFile(join(this.root, ".apex", "apex.lock.json"), "utf8"));
+        await this.installRuntimeGeneration(previousRuntimeLock);
         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;
@@ -494,6 +542,11 @@ export class ApexService {
         }
         const source = customizationsSource ?? assets.clientProjections[clientId];
         const updated = await this.installCustomizations(source, true, assets.config, false, clientId);
+        await this.installCapabilityAssets(assets);
+        const runtimeLock = await this.createRuntimeLock(assets);
+        await atomicWriteJson(join(this.root, ".apex", "apex.lock.json"), runtimeLock);
+        await atomicWriteJson(join(this.root, ".apex", "runtime", "apex.lock.json"), runtimeLock);
+        await this.installRuntimeGeneration(runtimeLock);
         await this.append(await this.run(selection), "customizations.updated", { source: resolve(source), updated });
         return { updated };
     }
@@ -730,6 +783,9 @@ export class ApexService {
             return { status: "task", task: await this.issueTask(run, TASKS[0], []) };
         }
         const route = await this.route(run, events);
+        if (route.blockers.length > 0 && route.reviewGate !== undefined) {
+            return { status: "needs_review", review: await this.pendingReview(events, route.reviewGate) };
+        }
         if (route.blockers.length > 0)
             throw new ApexError("APEX_AUTHORIZATION", route.blockers.join("; "), EXIT_CODES.authorization, route.blockers);
         if (route.task === undefined)
@@ -847,12 +903,12 @@ export class ApexService {
         const events = await this.journal(run).replay();
         const route = await this.route(run, events);
         const outputTemplates = {};
-        if (task.taskType === "requirements" || task.taskType === "plan") {
+        if (task.taskType === "requirements" || task.taskType === "plan" || task.taskType.endsWith("-review")) {
             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);
+                outputTemplates[kind] = this.outputTemplate(kind, run, events, task.taskType);
             }
         }
         const artifactHashes = this.acceptedArtifactHashes(events);
@@ -868,6 +924,35 @@ export class ApexService {
             blockers: route.blockers,
         };
     }
+    async readTaskInput(taskId, offset = 0, limit = 6_000) {
+        const run = await this.currentRun();
+        const task = await this.readTask(run, taskId);
+        const descriptor = TASKS.find(({ id }) => id === task.taskType);
+        if (descriptor?.reviewSubject === undefined)
+            throw new ApexError("APEX_AUTHORIZATION", "Only review tasks may read their accepted input", EXIT_CODES.authorization);
+        if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 6_000) {
+            throw new ApexError("APEX_VALIDATION", "Input read range is invalid", EXIT_CODES.validation);
+        }
+        const subjectKind = descriptor.reviewSubject === "governance-reconciliation" ? "policy-property-map" : descriptor.reviewSubject;
+        const events = await this.journal(run).replay();
+        const subjectHash = this.artifactHash(events, subjectKind);
+        if (subjectHash === undefined || !task.inputRefs.includes(subjectHash)) {
+            throw new ApexError("APEX_STALE", "Review task input is unavailable or stale", EXIT_CODES.stale);
+        }
+        const serialized = JSON.stringify(await this.objects.getJson(subjectHash));
+        if (offset >= serialized.length) {
+            throw new ApexError("APEX_VALIDATION", "Input read offset is outside the review subject", EXIT_CODES.validation);
+        }
+        const content = serialized.slice(offset, offset + limit);
+        const nextOffset = offset + content.length;
+        return {
+            subjectHash,
+            content,
+            offset,
+            ...(offset === 0 ? { outputTemplate: this.outputTemplate("review-findings", run, events, task.taskType) } : {}),
+            ...(nextOffset < serialized.length ? { nextOffset } : {}),
+        };
+    }
     async stageArtifact(taskId, output) {
         const run = await this.currentRun();
         const task = await this.readTask(run, taskId);
@@ -1016,6 +1101,54 @@ export class ApexService {
     async completeTaskOutputs(taskId, outputs) {
         return this.acceptTaskOutputs(taskId, outputs, false);
     }
+    async completeRequirements(taskId, requirements) {
+        await this.assertTaskType(taskId, "requirements");
+        return this.completeTaskOutputs(taskId, [{ kind: "requirements", value: requirements }]);
+    }
+    async completeArchitecture(taskId, architecture, costEstimate, decisionManifest) {
+        await this.assertTaskType(taskId, "architecture");
+        return this.completeTaskOutputs(taskId, [
+            { kind: "architecture", value: architecture },
+            { kind: "cost-estimate", value: costEstimate },
+            { kind: "workload-decision-manifest", value: decisionManifest },
+        ]);
+    }
+    async completeReview(taskId, findings) {
+        const context = await this.taskContext(taskId);
+        if (!context.task.taskType.endsWith("-review")) {
+            throw new ApexError("APEX_AUTHORIZATION", "Task is not a review task", EXIT_CODES.authorization);
+        }
+        const template = context.outputTemplates["review-findings"];
+        if (template === undefined)
+            throw new ApexError("APEX_STALE", "Review template is unavailable", EXIT_CODES.stale);
+        return this.completeTaskOutputs(taskId, [
+            {
+                kind: "review-findings",
+                value: {
+                    ...template,
+                    findings: findings.map((finding) => ({
+                        ...finding,
+                        disposition: "open",
+                        evidenceRefs: [template.subjectHash],
+                    })),
+                },
+            },
+        ]);
+    }
+    async completePlan(taskId, intent, binding, environmentInputs) {
+        return this.completeTaskOutputs(taskId, [
+            { kind: "implementation-intent", value: intent },
+            { kind: "iac-binding", value: { ...binding, intentHash: sha256Json(intent) } },
+            { kind: "environment-inputs", value: environmentInputs },
+        ]);
+    }
+    async assertTaskType(taskId, expected) {
+        const run = await this.currentRun();
+        const task = await this.readTask(run, taskId);
+        if (task.taskType !== expected) {
+            throw new ApexError("APEX_AUTHORIZATION", `Task is not the ${expected} task`, EXIT_CODES.authorization);
+        }
+    }
     async acceptTaskOutputs(taskId, outputs, legacy) {
         const run = await this.currentRun();
         const task = await this.readTask(run, taskId);
@@ -1389,6 +1522,114 @@ export class ApexService {
             }
         }
     }
+    async decideReview(reviewHash, decisions) {
+        if (decisions.length === 0 || new Set(decisions.map(({ findingId }) => findingId)).size !== decisions.length) {
+            throw new ApexError("APEX_VALIDATION", "Review decisions must be nonempty and unique", EXIT_CODES.validation);
+        }
+        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 === reviewHash);
+        if (reviewEvent === undefined)
+            throw new ApexError("APEX_STALE", "Review is not current", EXIT_CODES.stale);
+        const payload = reviewEvent.payload;
+        const openIds = this.reviewBlockers(events, String(payload.nodeId)).map((blocker) => blocker.split(" ")[2]);
+        if (decisions.some(({ findingId }) => !openIds.includes(findingId))) {
+            throw new ApexError("APEX_STALE", "Review decisions do not match current open findings", EXIT_CODES.stale);
+        }
+        const revisions = decisions.filter(({ action }) => action === "revise");
+        if (revisions.length > 0) {
+            await this.reviseReview(reviewHash, revisions.map(({ findingId }) => findingId), revisions.map(({ rationale }) => rationale).join("; "));
+            return { status: "revision_requested" };
+        }
+        if (decisions.length !== openIds.length) {
+            throw new ApexError("APEX_VALIDATION", "Every open finding requires a decision", EXIT_CODES.validation);
+        }
+        for (const decision of decisions) {
+            await this.resolveReview({
+                findingId: decision.findingId,
+                reviewHash,
+                subjectHash: String(payload.subjectHash),
+                dependencyHash: String(payload.dependencyHash),
+                disposition: "accepted-risk",
+                actor: userInfo().username,
+                rationale: decision.rationale,
+                evidenceRefs: [],
+                ...(decision.expiresAt === undefined ? {} : { expiresAt: decision.expiresAt }),
+            });
+        }
+        return { status: "resolved" };
+    }
+    async pendingReview(events, gate) {
+        const reviewEvent = [...events]
+            .reverse()
+            .find((event) => event.type === "task.completed" &&
+            typeof event.payload.reviewHash === "string" &&
+            this.reviewBlockers(events, String(event.payload.nodeId)).length > 0);
+        const reviewHash = reviewEvent?.payload?.reviewHash;
+        if (typeof reviewHash !== "string")
+            throw new ApexError("APEX_STALE", "Open review is unavailable", EXIT_CODES.stale);
+        const review = await this.objects.getJson(reviewHash);
+        const unresolved = new Set(this.reviewBlockers(events, String(reviewEvent.payload.nodeId)).map((blocker) => blocker.split(" ")[2]));
+        return {
+            gate,
+            reviewHash,
+            findings: review.findings
+                .filter(({ id }) => unresolved.has(id))
+                .map(({ id, severity, title, detail }) => ({
+                id,
+                severity,
+                title,
+                detail,
+                actions: ["revise", ...(["critical", "high"].includes(severity) ? [] : ["accept-risk"])],
+            })),
+        };
+    }
+    async reviseReview(reviewHash, findingIds, correction) {
+        if (!/^[0-9a-f]{64}$/u.test(reviewHash) || findingIds.length === 0 || correction.trim().length === 0) {
+            throw new ApexError("APEX_VALIDATION", "Review revision request is incomplete", EXIT_CODES.validation);
+        }
+        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 === reviewHash);
+        if (reviewEvent === undefined) {
+            throw new ApexError("APEX_STALE", "Review is not current", EXIT_CODES.stale);
+        }
+        const reviewNode = String(reviewEvent.payload.nodeId);
+        const descriptor = TASKS.find(({ id }) => id === reviewNode);
+        const subjectNode = descriptor?.reviewSubject;
+        if (subjectNode === undefined)
+            throw new ApexError("APEX_STALE", "Review subject is unavailable", EXIT_CODES.stale);
+        const openIds = new Set(this.reviewBlockers(events, reviewNode).map((blocker) => blocker.split(" ")[2]));
+        if (findingIds.some((id) => !openIds.has(id))) {
+            throw new ApexError("APEX_STALE", "Revision does not match current open findings", EXIT_CODES.stale);
+        }
+        const workflow = await this.lockedWorkflowEngine(run);
+        const invalidatedNodes = [
+            subjectNode,
+            reviewNode,
+            ...workflow.invalidationPlan(subjectNode, correction.trim()).map(({ nodeId }) => nodeId),
+        ];
+        const uniqueNodes = [...new Set(invalidatedNodes)];
+        const artifactKinds = TASKS.filter(({ id }) => uniqueNodes.includes(id)).flatMap(({ outputs }) => outputs);
+        await this.append(run, "workflow.invalidated", {
+            reason: correction.trim(),
+            findingIds,
+            reviewHash,
+            nodeIds: uniqueNodes,
+            artifactKinds: [...new Set(artifactKinds)],
+        });
+        const dependencyHash = this.dependencyRevision(run, await this.journal(run).replay());
+        await atomicWriteJson(this.runPath(run), {
+            ...run,
+            gates: run.gates.map((gate) => uniqueNodes.includes(`gate-${gate.gate}`)
+                ? invalidateGate(gate, dependencyHash, `${subjectNode} revision requested`)
+                : gate),
+        });
+    }
     assertReviewResolution(value) {
         const hashes = [value.reviewHash, value.subjectHash, value.dependencyHash, ...value.evidenceRefs];
         if (!value.findingId ||
@@ -1489,6 +1730,16 @@ export class ApexService {
             await this.materializeOperationsApprovalPackage(run, approval, approvalHash);
         return approval;
     }
+    async decideInteractiveGate(gateNumber, decision) {
+        let actor = "local-user";
+        try {
+            actor = userInfo().username.trim() || actor;
+        }
+        catch {
+            // Some minimal container identities do not have an OS user entry.
+        }
+        return this.decideGateNumber(gateNumber, decision, actor);
+    }
     async preview(options) {
         const run = await this.currentRun();
         await this.assertCurrentWriterAuthority(run, new WriterTransferStore(this.projects.runDirectory(run.projectId, run.runId), this.clock));
@@ -2437,17 +2688,22 @@ export class ApexService {
             typeof event.payload.requestId === "string"
             ? [event.payload.requestId]
             : []));
+        const catalog = this.requirementsIntakeCatalog(requests);
         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) {
+            const round = typeof ordinal === "number" && Number.isInteger(ordinal) ? catalog[ordinal - 1] : undefined;
+            if (round === undefined || intake.round !== round.round || intake.total !== catalog.length) {
                 throw new ApexError("APEX_CONFLICT", "Requirements intake is incompatible; start a new run", EXIT_CODES.conflict);
             }
             return round;
         }
-        return REQUIREMENTS_INTAKE[recordedRequestIds.size];
+        return catalog[recordedRequestIds.size];
+    }
+    requirementsIntakeCatalog(requests) {
+        const total = requests[0]?.payload?.intake?.total;
+        return total === LEGACY_REQUIREMENTS_INTAKE.length ? LEGACY_REQUIREMENTS_INTAKE : REQUIREMENTS_INTAKE;
     }
     async issueRequirementsInput(run, round) {
         const events = await this.journal(run).replay();
@@ -2463,36 +2719,129 @@ export class ApexService {
                 return this.inputRequest(latest, run.ownerEpoch);
             }
         }
-        const ordinal = REQUIREMENTS_INTAKE.findIndex(({ round: id }) => id === round.round) + 1;
+        const catalog = this.requirementsIntakeCatalog(events.filter((event) => event.type === "requirements.input-requested"));
+        const ordinal = catalog.findIndex((candidate) => candidate === round) + 1;
         const event = await this.append(run, "requirements.input-requested", {
             requestId: this.idSource(),
-            intake: { round: round.round, ordinal, total: 4 },
+            intake: { round: round.round, ordinal, total: catalog.length },
             questions,
         });
         return this.inputRequest(event, run.ownerEpoch);
     }
     requirementsIntakeQuestions(round, events) {
-        if (round.round === "service-preferences") {
-            const scenario = this.recordedRequirementsInput(events)?.["delivery-scenario"];
-            if (scenario !== "migration" && scenario !== "modernization" && scenario !== "extension")
-                return round.questions;
-            return [
-                { id: "retained-services", prompt: "List Azure services or integrations that must be retained." },
-                ...round.questions,
-            ];
+        const hasServicePreferences = round.questions.some(({ id }) => id === "service-preferences");
+        if (round.round === "service-preferences" || (round.round === "workload-pattern" && hasServicePreferences)) {
+            const input = this.recordedRequirementsInput(events);
+            const scenario = input?.["delivery-scenario"];
+            const workload = typeof input?.workload === "string" ? input.workload : "";
+            const pattern = this.recommendedWorkloadPattern(workload);
+            const recommendationInput = { ...(input ?? {}), "workload-pattern": pattern };
+            const questions = round.questions.map((question) => question.id === "service-preferences"
+                ? {
+                    ...question,
+                    prompt: "Confirm the recommended Azure service candidates or select alternatives; Architecture makes the final choice.",
+                    recommendation: {
+                        value: this.recommendedServiceCandidates(recommendationInput),
+                        source: "prior-answer",
+                        rationale: "Derived from the confirmed workload description as non-binding Architecture candidates.",
+                    },
+                }
+                : question.id === "workload-pattern"
+                    ? {
+                        ...question,
+                        recommendation: {
+                            value: pattern,
+                            source: "derived",
+                            rationale: "Derived from the confirmed workload description; confirm or choose another pattern.",
+                        },
+                    }
+                    : question.id === "scale"
+                        ? { ...question, prompt: this.workloadScalePrompt(pattern) }
+                        : question);
+            const retained = scenario === "migration" || scenario === "modernization" || scenario === "extension"
+                ? [{ id: "retained-services", prompt: "List Azure services or integrations that must be retained." }]
+                : [];
+            if (round.round === "service-preferences")
+                return [...retained, ...questions];
+            const migration = scenario === "migration" || scenario === "modernization"
+                ? [
+                    { 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." },
+                ]
+                : [];
+            return [...questions, ...retained, ...migration];
         }
         if (round.round !== "workload-pattern")
             return round.questions;
-        const scenario = this.recordedRequirementsInput(events)?.["delivery-scenario"];
+        const input = this.recordedRequirementsInput(events);
+        const scenario = input?.["delivery-scenario"];
+        const workload = typeof input?.workload === "string" ? input.workload : "";
+        const pattern = this.recommendedWorkloadPattern(workload);
+        const questions = round.questions.map((question) => question.id === "workload-pattern"
+            ? {
+                ...question,
+                recommendation: {
+                    value: pattern,
+                    source: "derived",
+                    rationale: "Derived from the confirmed workload description; confirm or choose another pattern.",
+                },
+            }
+            : question.id === "scale"
+                ? { ...question, prompt: this.workloadScalePrompt(pattern) }
+                : question);
         if (scenario !== "migration" && scenario !== "modernization")
-            return round.questions;
+            return questions;
         return [
-            ...round.questions,
+            ...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." },
         ];
     }
+    recommendedWorkloadPattern(workload) {
+        const normalized = workload.toLowerCase();
+        if (/\b(iot|device|sensor|telemetry)\b/u.test(normalized))
+            return "iot";
+        if (/\b(analytics|warehouse|lakehouse|reporting|etl)\b/u.test(normalized))
+            return "data-analytics";
+        if (/\b(batch|scheduled|nightly|cron)\b/u.test(normalized))
+            return "batch";
+        if (/\b(event|queue|stream|message|asynchronous)\b/u.test(normalized))
+            return "event-driven";
+        return "web-api";
+    }
+    workloadScalePrompt(pattern) {
+        const prompts = {
+            "web-api": "Describe normal and peak concurrency, request or order rate, and latency expectations.",
+            "event-driven": "Describe normal and peak event rates, ordering requirements, and delivery guarantees.",
+            "data-analytics": "Describe ingest rate, retained volume, growth, and data-freshness expectations.",
+            iot: "Describe device count, message rate, payload size, and offline behavior.",
+            batch: "Describe schedule, data volume, expected duration, and completion window.",
+        };
+        return prompts[pattern];
+    }
+    recommendedServiceCandidates(input) {
+        const pattern = input?.["workload-pattern"];
+        const budget = input?.budget;
+        const lowBudget = typeof budget === "object" && budget !== null && !Array.isArray(budget) && budget.kind === "budget"
+            ? budget.amount < 1_000
+            : false;
+        const candidates = {
+            "web-api": [lowBudget ? "azure-functions" : "app-service", "azure-sql", "storage", "service-bus"],
+            "event-driven": ["azure-functions", "service-bus", "storage"],
+            "data-analytics": ["azure-functions", "storage", "event-hubs"],
+            iot: ["azure-functions", "event-hubs", "storage"],
+            batch: ["azure-functions", "storage", "service-bus"],
+        };
+        const selected = typeof pattern === "string" && pattern in candidates
+            ? candidates[pattern]
+            : candidates["web-api"];
+        return [...selected, "azure-monitor", "application-insights"];
+    }
     async append(run, type, payload, expectedHead) {
         const journal = this.journal(run);
         return await journal.append({
@@ -2547,11 +2896,12 @@ export class ApexService {
                 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];
+            const catalog = intake?.total === LEGACY_REQUIREMENTS_INTAKE.length ? LEGACY_REQUIREMENTS_INTAKE : REQUIREMENTS_INTAKE;
+            const round = intake === undefined ? undefined : catalog[intake.ordinal - 1];
             if (round === undefined ||
                 intake === undefined ||
                 round.round !== intake.round ||
-                intake.total !== REQUIREMENTS_INTAKE.length) {
+                intake.total !== catalog.length) {
                 throw new ApexError("APEX_CONFLICT", "Requirements intake is incompatible; start a new run", EXIT_CODES.conflict);
             }
         }
@@ -2578,6 +2928,10 @@ export class ApexService {
     }
     artifactHash(events, kind) {
         for (const event of [...events].reverse()) {
+            if (event.type === "workflow.invalidated" &&
+                event.payload.artifactKinds?.includes?.(kind)) {
+                return undefined;
+            }
             if (event.type !== "task.completed")
                 continue;
             const hashes = event.payload.artifactHashes;
@@ -2598,6 +2952,14 @@ export class ApexService {
             "implementation-intent": "intentHash",
         };
         for (const event of events) {
+            if (event.type === "workflow.invalidated") {
+                const kinds = event.payload.artifactKinds;
+                if (Array.isArray(kinds))
+                    for (const kind of kinds)
+                        if (typeof kind === "string")
+                            delete hashes[kind];
+                continue;
+            }
             if (event.type !== "task.completed")
                 continue;
             const payload = event.payload;
@@ -2663,7 +3025,7 @@ export class ApexService {
         }
         return recorded ? result : null;
     }
-    outputTemplate(kind, run, events) {
+    outputTemplate(kind, run, events, taskType) {
         if (kind === "requirements") {
             const input = this.recordedRequirementsInput(events);
             return {
@@ -2671,7 +3033,34 @@ export class ApexService {
                 projectId: run.projectId,
                 workload: typeof input?.workload === "string" ? input.workload : "",
                 environment: run.environment,
-                ...this.requirementsTemplateFromIntake(input),
+                ...this.requirementsTemplateFromIntake({ ...(input ?? {}), "iac-preference": run.iacTool }),
+            };
+        }
+        if (kind === "review-findings") {
+            const review = TASKS.find(({ id }) => id === taskType);
+            const subjectKind = review?.reviewSubject === "governance-reconciliation" ? "policy-property-map" : review?.reviewSubject;
+            const artifactKind = subjectKind === "plan" ? "implementation-intent" : subjectKind;
+            const subjectHash = artifactKind === undefined ? undefined : this.artifactHash(events, artifactKind);
+            if (subjectKind === undefined || subjectHash === undefined) {
+                throw new ApexError("APEX_STALE", "Review subject is unavailable", EXIT_CODES.stale);
+            }
+            return {
+                schemaVersion: CONTRACT_VERSION,
+                projectId: run.projectId,
+                runId: run.runId,
+                subjectKind,
+                subjectHash,
+                reviewedAt: this.clock().toISOString(),
+                findings: [
+                    {
+                        id: "FINDING-001",
+                        severity: "medium",
+                        disposition: "open",
+                        title: "Concise finding title",
+                        detail: "Evidence, impact, and concrete remediation.",
+                        evidenceRefs: [subjectHash],
+                    },
+                ],
             };
         }
         if (kind === "implementation-intent") {
@@ -2833,17 +3222,28 @@ export class ApexService {
         }
     }
     completedNodeIds(events) {
-        return new Set(events.flatMap((event) => {
+        const completed = new Set();
+        for (const event of events) {
+            if (event.type === "workflow.invalidated") {
+                const nodeIds = event.payload.nodeIds;
+                if (Array.isArray(nodeIds))
+                    for (const nodeId of nodeIds)
+                        if (typeof nodeId === "string")
+                            completed.delete(nodeId);
+                continue;
+            }
             if (event.type !== "task.completed")
-                return [];
+                continue;
             const nodeId = event.payload.nodeId;
-            return typeof nodeId === "string" ? [nodeId] : [];
-        }));
+            if (typeof nodeId === "string")
+                completed.add(nodeId);
+        }
+        return completed;
     }
     async lockedWorkflowEngine(run) {
-        const runtimeRoot = join(this.root, ".apex", "runtime");
+        const runtimeRoot = await this.runtimeRootForRun(run);
         const workflowBytes = await readFile(join(runtimeRoot, "workflow.v1.json"));
-        const lock = JSON.parse(await readFile(join(this.root, ".apex", "apex.lock.json"), "utf8"));
+        const lock = JSON.parse(await readFile(join(runtimeRoot, "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);
@@ -3162,7 +3562,7 @@ export class ApexService {
             ...(availabilityEvidence === undefined ? {} : { availabilityEvidence }),
             ...(deploymentOperation === undefined ? {} : { deploymentOperation }),
             ...(deploymentInventory === undefined ? {} : { deploymentInventory }),
-            ...(nodeId === "quality" ? await this.qualityValidatorContext() : {}),
+            ...(nodeId === "quality" ? await this.qualityValidatorContext(run) : {}),
         };
         for (const id of validatorIds) {
             this.assertValid(id, taskWorkflowValidatorInput(id, context));
@@ -3173,7 +3573,7 @@ export class ApexService {
             evidenceModes: availabilityEvidence === undefined ? {} : { "business:availability-current": availabilityEvidence.mode },
         };
     }
-    async qualityValidatorContext() {
+    async qualityValidatorContext(run) {
         let qualityMeasurements;
         try {
             qualityMeasurements = JSON.parse(await readFile(join(this.root, ".apex", "quality", "measurements.json"), "utf8"));
@@ -3185,8 +3585,9 @@ export class ApexService {
             throw error;
         }
         this.assertValid("quality-measurements", qualityMeasurements);
+        const runtimeRoot = await this.runtimeRootForRun(run);
         return {
-            scorecard: JSON.parse(await readFile(join(this.root, ".apex", "runtime", "quality-scorecard.v1.json"), "utf8")),
+            scorecard: JSON.parse(await readFile(join(runtimeRoot, "quality-scorecard.v1.json"), "utf8")),
             qualityMeasurements,
         };
     }
@@ -3577,9 +3978,10 @@ export class ApexService {
             this.improvementRuntime ??= new ImprovementStore(this.root, this.improvementPolicy, this.clock);
             return this.improvementRuntime;
         }
+        const runtimeRoot = await this.runtimeRootForRun(run);
         const [policyBytes, lockBytes] = await Promise.all([
-            readFile(join(this.root, ".apex", "runtime", "improvement-policy.v1.json")),
-            readFile(join(this.root, ".apex", "apex.lock.json")),
+            readFile(join(runtimeRoot, "improvement-policy.v1.json")),
+            readFile(join(runtimeRoot, "apex.lock.json")),
         ]);
         const lock = JSON.parse(lockBytes.toString("utf8"));
         this.assertValid("runtime-lock", lock);
@@ -3644,6 +4046,28 @@ export class ApexService {
         this.assertValid("runtime-lock", lock);
         return lock;
     }
+    async installRuntimeGeneration(lock) {
+        const hash = sha256Json(lock);
+        const generationsRoot = join(this.root, ".apex", "runtime-generations");
+        const destination = join(generationsRoot, hash);
+        if (!(await this.exists(destination))) {
+            await mkdir(generationsRoot, { recursive: true });
+            const staging = join(generationsRoot, `.incoming-${this.idSource()}`);
+            await cp(join(this.root, ".apex", "runtime"), staging, {
+                recursive: true,
+                dereference: false,
+                errorOnExist: true,
+                force: false,
+            });
+            await atomicWriteJson(join(staging, "apex.lock.json"), lock);
+            await rename(staging, destination);
+        }
+        return destination;
+    }
+    async runtimeRootForRun(run) {
+        const generation = join(this.root, ".apex", "runtime-generations", run.runtimeLockHash);
+        return (await this.exists(join(generation, "apex.lock.json"))) ? generation : join(this.root, ".apex", "runtime");
+    }
     capabilityPacks(manifestPath) {
         return new CapabilityPackManager({
             root: this.root,
@@ -3652,11 +4076,11 @@ export class ApexService {
         });
     }
     async runtimeLockChecks(run) {
-        const path = join(this.root, ".apex", "apex.lock.json");
         try {
-            const lock = JSON.parse(await readFile(path, "utf8"));
+            const runtimeRoot = await this.runtimeRootForRun(run);
+            const lockPath = join(runtimeRoot, "apex.lock.json");
+            const lock = JSON.parse(await readFile(lockPath, "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");
@@ -3884,7 +4308,8 @@ export class ApexService {
         }
     }
     async evidenceStore(kind, contentType) {
-        const defaults = JSON.parse(await readFile(join(this.root, ".apex", "runtime", "defaults.v1.json"), "utf8"));
+        const runtimeRoot = await this.runtimeRootForRun(await this.currentRun());
+        const defaults = JSON.parse(await readFile(join(runtimeRoot, "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);