ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/mock-scenario-pack.mjs

@@ -0,0 +1,687 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { requireSha256, sha256File } from "./artifact-files.mjs";
+import { assertPathInside, atomicWrite } from "./fs-utils.mjs";
+import {
+  parsePrototypeCatalogCsv,
+  validatePrototypeRevision,
+} from "./prototype-revision.mjs";
+import { parse as parseYaml, stringify as stringifyYaml } from "./yaml-runtime.mjs";
+import { sameStableValue } from "./stable-value.mjs";
+
+const mappingHeader = [
+  "review_scene_id",
+  "mock_id",
+  "mock_kind",
+  "scenario_id",
+  "data_source",
+  "data_classification",
+  "sanitization_status",
+  "sanitization_evidence_ref",
+].join(",");
+
+function sha256Bytes(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function requireRelativeRef(value, label, prefix = null) {
+  const ref = String(value || "");
+  if (!ref
+    || ref.includes("\\")
+    || ref.includes("\0")
+    || path.posix.isAbsolute(ref)
+    || path.posix.normalize(ref) !== ref
+    || ref === ".."
+    || ref.startsWith("../")
+    || (prefix && !ref.startsWith(prefix))) {
+    throw new Error(`${label} is outside its allowed relative path boundary: ${ref || "<empty>"}`);
+  }
+  return ref;
+}
+
+function containedFile(root, ref, label, prefix = null) {
+  const normalized = requireRelativeRef(ref, label, prefix);
+  const file = path.resolve(root, ...normalized.split("/"));
+  assertPathInside(root, file);
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile() || fs.lstatSync(file).isSymbolicLink()) {
+    throw new Error(`${label} is missing or is not a regular file: ${normalized}`);
+  }
+  return { ref: normalized, file };
+}
+
+function boundFile(root, binding, label, prefix = null) {
+  if (binding?.algorithm !== "sha256") throw new Error(`${label} must use sha256`);
+  const resolved = containedFile(root, binding.ref, label, prefix);
+  const checksum = requireSha256(binding.checksum, label);
+  if (sha256File(resolved.file) !== checksum) throw new Error(`${label} checksum mismatch`);
+  return { ...resolved, checksum };
+}
+
+function readYamlFile(file, label) {
+  try {
+    return parseYaml(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(`${label} is invalid YAML: ${error.message}`);
+  }
+}
+
+function requireExperienceRoot(projectRoot, relative) {
+  const ref = requireRelativeRef(relative, "Scenario Pack experience directory");
+  const root = path.resolve(projectRoot, ...ref.split("/"));
+  assertPathInside(projectRoot, root);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory() || fs.lstatSync(root).isSymbolicLink()) {
+    throw new Error(`Scenario Pack experience directory is missing: ${ref}`);
+  }
+  return { ref, root };
+}
+
+function validateAdminExportMetadata(value) {
+  if (value?.schema_version !== 1 || value?.source !== "microcks-managed-ui") {
+    throw new Error("Mock admin export must use schema 1 and source microcks-managed-ui");
+  }
+  if (!value.exported_at || Number.isNaN(Date.parse(value.exported_at))) {
+    throw new Error("Mock admin export requires exported_at");
+  }
+  if (value.security?.production_traffic_recording !== false) {
+    throw new Error("Production traffic recording is prohibited in a Mock Scenario Pack");
+  }
+  if (value.security?.production_credentials !== false) {
+    throw new Error("Production credentials are prohibited in a Mock Scenario Pack");
+  }
+  if (value.security?.unsanitized_personal_data !== false) {
+    throw new Error("Unsanitized personal data is prohibited in a Mock Scenario Pack");
+  }
+}
+
+function validateAdminExportArtifacts(
+  experienceRoot,
+  adminExport,
+  catalogs,
+  mappings,
+  validateMockDefinition,
+) {
+  if (!Array.isArray(adminExport.artifacts) || adminExport.artifacts.length === 0) {
+    throw new Error("Mock admin export requires bound export artifacts");
+  }
+  const requiredIdentities = new Map();
+  for (const mapping of mappings) {
+    const key = `${mapping.mock_kind}:${mapping.mock_id}`;
+    if (!requiredIdentities.has(key)) requiredIdentities.set(key, new Set());
+    requiredIdentities.get(key).add(mapping.scenario_id);
+  }
+  const entriesByIdentity = new Map();
+  for (const { catalogEntry } of catalogs.entries) {
+    const key = `${catalogEntry.mock_kind}:${catalogEntry.mock_id}`;
+    if (!entriesByIdentity.has(key)) entriesByIdentity.set(key, []);
+    entriesByIdentity.get(key).push(catalogEntry);
+  }
+  const seen = new Set();
+  const artifacts = adminExport.artifacts.map((artifact, index) => {
+    const label = `Mock admin export artifact ${index + 1}`;
+    const mockKind = requireText(artifact?.mock_kind, `${label} mock_kind`);
+    const mockId = requireText(artifact?.mock_id, `${label} mock_id`);
+    const protocol = requireText(artifact?.protocol, `${label} protocol`);
+    const key = `${mockKind}:${mockId}`;
+    const scenarioIds = requiredIdentities.get(key);
+    if (!scenarioIds) throw new Error(`${label} is not used by an active Review Scene: ${key}`);
+    if (seen.has(key)) throw new Error(`Duplicate Mock admin export artifact identity: ${key}`);
+    seen.add(key);
+    const catalogEntries = entriesByIdentity.get(key) || [];
+    if (catalogEntries.some((entry) => entry.protocol !== protocol)) {
+      throw new Error(`Mock admin export artifact ${mockId} protocol does not match its catalog`);
+    }
+    const binding = boundFile(
+      experienceRoot,
+      artifact,
+      `Mock admin export artifact ${mockId}`,
+      "mock-admin-exports/",
+    );
+    const definition = readYamlFile(binding.file, `Mock admin export artifact ${mockId}`);
+    for (const scenarioId of scenarioIds) {
+      const entry = catalogEntries.find((candidate) => candidate.scenario_id === scenarioId);
+      if (!entry) throw new Error(`Mock admin export artifact ${mockId} has no catalog entry for ${scenarioId}`);
+      validateMockDefinition(definition, entry);
+    }
+    return {
+      mock_kind: mockKind,
+      mock_id: mockId,
+      protocol,
+      ref: binding.ref,
+      algorithm: "sha256",
+      checksum: binding.checksum,
+      scenario_ids: [...scenarioIds].sort(),
+    };
+  });
+  for (const key of requiredIdentities.keys()) {
+    if (!seen.has(key)) throw new Error(`Mock admin export has no artifact for ${key}`);
+  }
+  return artifacts.sort((left, right) =>
+    `${left.mock_kind}:${left.mock_id}`.localeCompare(`${right.mock_kind}:${right.mock_id}`));
+}
+
+function readActiveReviewScenes(experienceRoot, revisionFile, revision) {
+  const revisionRoot = path.dirname(revisionFile);
+  const bundleRef = requireRelativeRef(revision.review_bundle?.ref, "Prototype review bundle");
+  const bundleRoot = path.resolve(revisionRoot, ...bundleRef.split("/"));
+  assertPathInside(experienceRoot, bundleRoot);
+  const sceneBinding = revision.catalogs?.review_scenes;
+  if (sceneBinding?.algorithm !== "sha256") {
+    throw new Error("Prototype Review Scene catalog must use sha256");
+  }
+  const sceneCatalog = containedFile(
+    bundleRoot,
+    sceneBinding.ref,
+    "Prototype Review Scene catalog",
+  );
+  if (sha256File(sceneCatalog.file) !== requireSha256(
+    sceneBinding.checksum,
+    "Prototype Review Scene catalog",
+  )) {
+    throw new Error("Prototype Review Scene catalog checksum mismatch");
+  }
+  const parsed = parsePrototypeCatalogCsv(
+    fs.readFileSync(sceneCatalog.file, "utf8"),
+    "Prototype Review Scene catalog",
+  );
+  return parsed.rows.filter((row) => row.lifecycle_status === "active");
+}
+
+function requireText(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is required`);
+  return value.trim();
+}
+
+function normalizeMappings(experienceRoot, rows, activeScenes, catalogs) {
+  const activeSceneIds = new Set(activeScenes.map((scene) => scene.review_scene_id));
+  const mappings = new Map();
+  const catalogEntries = new Map(catalogs.entries.map(({ catalogEntry, contractFile }) => [
+    `${catalogEntry.mock_kind}:${catalogEntry.mock_id}:${catalogEntry.scenario_id}`,
+    { catalogEntry, contractFile },
+  ]));
+  for (const row of rows) {
+    const reviewSceneId = requireText(row.review_scene_id, "Mock Scenario mapping review_scene_id");
+    if (!activeSceneIds.has(reviewSceneId)) {
+      throw new Error(`Mock Scenario mapping references an inactive or unknown Review Scene: ${reviewSceneId}`);
+    }
+    if (mappings.has(reviewSceneId)) {
+      throw new Error(`Duplicate Mock Scenario mapping for Review Scene ${reviewSceneId}`);
+    }
+    const mockKind = requireText(row.mock_kind, `Review Scene ${reviewSceneId} mock_kind`);
+    if (!new Set(["external-dependency", "product-backend"]).has(mockKind)) {
+      throw new Error(`Review Scene ${reviewSceneId} has invalid mock_kind ${mockKind}`);
+    }
+    const mockId = requireText(row.mock_id, `Review Scene ${reviewSceneId} mock_id`);
+    const scenarioId = requireText(row.scenario_id, `Review Scene ${reviewSceneId} scenario_id`);
+    const selected = catalogEntries.get(`${mockKind}:${mockId}:${scenarioId}`);
+    if (!selected) {
+      throw new Error(
+        `Review Scene ${reviewSceneId} Mock Scenario ${mockKind}:${mockId}:${scenarioId} is not present in a validated catalog`,
+      );
+    }
+    const dataSource = requireText(row.data_source, `Review Scene ${reviewSceneId} data_source`);
+    const dataClassification = requireText(
+      row.data_classification,
+      `Review Scene ${reviewSceneId} data_classification`,
+    );
+    const sanitizationStatus = requireText(
+      row.sanitization_status,
+      `Review Scene ${reviewSceneId} sanitization_status`,
+    );
+    let sanitizationEvidence = null;
+    if (dataSource === "explicit-import") {
+      if (!new Set(["anonymized", "public"]).has(dataClassification)
+        || sanitizationStatus !== "passed"
+        || !row.sanitization_evidence_ref) {
+        throw new Error(
+          `Review Scene ${reviewSceneId} explicit import requires anonymized/public classification, sanitization passed, and evidence`,
+        );
+      }
+      const evidence = containedFile(
+        experienceRoot,
+        row.sanitization_evidence_ref,
+        `Review Scene ${reviewSceneId} sanitization evidence`,
+      );
+      sanitizationEvidence = {
+        ref: evidence.ref,
+        algorithm: "sha256",
+        checksum: sha256File(evidence.file),
+      };
+    } else if (dataSource === "synthetic") {
+      if (!new Set(["synthetic", "public"]).has(dataClassification)
+        || sanitizationStatus !== "not-required"
+        || row.sanitization_evidence_ref) {
+        throw new Error(
+          `Review Scene ${reviewSceneId} synthetic data must use synthetic/public classification and sanitization not-required without evidence`,
+        );
+      }
+    } else {
+      throw new Error(`Review Scene ${reviewSceneId} has forbidden data_source ${dataSource}`);
+    }
+    const entry = selected.catalogEntry;
+    mappings.set(reviewSceneId, {
+      review_scene_id: reviewSceneId,
+      mock_id: mockId,
+      mock_kind: mockKind,
+      scenario_id: scenarioId,
+      owner: entry.owner,
+      protocol: entry.protocol,
+      operation_or_channel: entry.operation_or_channel,
+      replacement_condition: entry.replacement_condition,
+      contract: {
+        ref: entry.contract_ref,
+        algorithm: "sha256",
+        checksum: sha256File(selected.contractFile),
+        approval_ref: entry.contract_approval_ref,
+      },
+      data: {
+        source: dataSource,
+        classification: dataClassification,
+        sanitization_status: sanitizationStatus,
+        sanitization_evidence: sanitizationEvidence,
+      },
+    });
+  }
+  for (const scene of activeScenes) {
+    if (!mappings.has(scene.review_scene_id)) {
+      throw new Error(`Review Scene ${scene.review_scene_id} has no Mock Scenario mapping`);
+    }
+  }
+  return [...mappings.values()].sort((left, right) =>
+    left.review_scene_id.localeCompare(right.review_scene_id));
+}
+
+function requireRequestIdentity(request, revision) {
+  if (request?.schema_version !== 1
+    || request?.artifact_type !== "mock-scenario-pack-request"
+    || !/^MOCK-SCENARIO-PACK-[A-Z0-9][A-Z0-9-]*$/.test(String(request?.artifact_id || ""))
+    || !Number.isInteger(request?.version)
+    || request.version < 1) {
+    throw new Error("Mock Scenario Pack request identity or schema is invalid");
+  }
+  if (request.iteration_id !== revision.iteration_id) {
+    throw new Error("Mock Scenario Pack iteration_id does not match its Prototype revision");
+  }
+}
+
+function validateHumanConfirmation(value, candidateChecksum) {
+  if (value?.required !== true
+    || value?.decision !== "approved"
+    || !/^human:[^\s]+$/.test(String(value?.actor || ""))
+    || !value?.decided_at
+    || Number.isNaN(Date.parse(value.decided_at))
+    || value?.candidate_checksum !== candidateChecksum) {
+    throw new Error("Mock Scenario Pack requires human confirmation bound to the exact candidate checksum");
+  }
+}
+
+const scenarioPackCandidateFields = Object.freeze([
+  "schema_version",
+  "artifact_id",
+  "version",
+  "iteration_id",
+  "prototype_revision",
+  "scenario_mapping",
+  "admin_export",
+  "scenario_mappings",
+  "data_policy",
+  "assurance",
+]);
+
+function scenarioPackCandidate(value) {
+  return Object.fromEntries(scenarioPackCandidateFields.map((field) => [field, value[field]]));
+}
+
+export function validateFrozenMockScenarioPack(projectRoot, options = {}, dependencies = {}) {
+  const validateMockDefinition = dependencies.validateMockDefinition;
+  const protocolExpectation = dependencies.protocolExpectation;
+  if (typeof validateMockDefinition !== "function" || typeof protocolExpectation !== "function") {
+    throw new Error("Mock Scenario Pack protocol validators are unavailable");
+  }
+  const experience = requireExperienceRoot(projectRoot, options.experience);
+  const packBinding = containedFile(experience.root, options.scenarioPack, "Frozen Mock Scenario Pack");
+  const pack = readYamlFile(packBinding.file, "Frozen Mock Scenario Pack");
+  if (pack?.schema_version !== 1
+      || pack?.artifact_type !== "mock-scenario-pack"
+      || pack?.status !== "frozen"
+      || !/^MOCK-SCENARIO-PACK-[A-Z0-9][A-Z0-9-]*$/.test(String(pack?.artifact_id || ""))
+      || !Number.isInteger(pack?.version) || pack.version < 1) {
+    throw new Error("Frozen Mock Scenario Pack identity or schema is invalid");
+  }
+  const candidateChecksum = sha256Bytes(JSON.stringify(scenarioPackCandidate(pack)));
+  if (pack.candidate?.algorithm !== "sha256" || pack.candidate?.checksum !== candidateChecksum) {
+    throw new Error("Frozen Mock Scenario Pack candidate checksum mismatch");
+  }
+  validateHumanConfirmation(pack.human_confirmation, candidateChecksum);
+  if (pack.authority?.formal_registration_required !== true
+      || pack.authority?.registration_artifact_type !== "mock-scenario-pack"
+      || pack.authority?.registration_status !== "submitted"
+      || !sameStableValue(pack.data_policy, {
+        production_traffic_recording: "prohibited",
+        production_credentials: "prohibited",
+        unsanitized_personal_data: "prohibited",
+        explicit_imports: "sanitized-only",
+      })
+      || pack.assurance?.real_product_backend_evidence !== false
+      || pack.assurance?.end_to_end_acceptance_evidence !== false) {
+    throw new Error("Frozen Mock Scenario Pack authority, data policy, or assurance boundary is invalid");
+  }
+
+  const revisionBinding = boundFile(
+    experience.root,
+    pack.prototype_revision,
+    "Frozen Mock Scenario Pack Prototype revision",
+  );
+  const revisionReport = validatePrototypeRevision(projectRoot, {
+    experience: experience.ref,
+    revision: revisionBinding.ref,
+  });
+  const revision = readYamlFile(revisionBinding.file, "Frozen Mock Scenario Pack Prototype revision");
+  if (pack.prototype_revision.artifact_id !== revisionReport.revision_id
+      || pack.prototype_revision.source_checksum !== revision.source?.checksum
+      || pack.prototype_revision.review_bundle_checksum !== revision.review_bundle?.checksum
+      || pack.iteration_id !== revision.iteration_id) {
+    throw new Error("Frozen Mock Scenario Pack Prototype revision binding is inconsistent");
+  }
+  const mappingBinding = boundFile(
+    experience.root,
+    pack.scenario_mapping,
+    "Frozen Mock Scenario mapping",
+  );
+  const mappingCatalog = parsePrototypeCatalogCsv(
+    fs.readFileSync(mappingBinding.file, "utf8"),
+    "Frozen Mock Scenario mapping",
+  );
+  if (mappingCatalog.header !== mappingHeader) {
+    throw new Error("Frozen Mock Scenario mapping header is invalid");
+  }
+  const adminBinding = boundFile(
+    experience.root,
+    pack.admin_export,
+    "Frozen Mock admin export",
+  );
+  const adminExport = readYamlFile(adminBinding.file, "Frozen Mock admin export");
+  validateAdminExportMetadata(adminExport);
+  if (pack.admin_export.source !== adminExport.source
+      || pack.admin_export.exported_at !== adminExport.exported_at) {
+    throw new Error("Frozen Mock admin export metadata is inconsistent");
+  }
+
+  const activeScenes = readActiveReviewScenes(experience.root, revisionBinding.file, revision);
+  const activeSceneIds = new Set(activeScenes.map((scene) => scene.review_scene_id));
+  const rowsByScene = new Map(mappingCatalog.rows.map((row) => [row.review_scene_id, row]));
+  const mappings = Array.isArray(pack.scenario_mappings) ? pack.scenario_mappings : [];
+  const mappingsByScene = new Map();
+  for (const mapping of mappings) {
+    const sceneId = requireText(mapping?.review_scene_id, "Frozen Scenario review_scene_id");
+    if (!activeSceneIds.has(sceneId) || mappingsByScene.has(sceneId)) {
+      throw new Error(`Frozen Mock Scenario Pack has an unknown or duplicate Review Scene: ${sceneId}`);
+    }
+    const row = rowsByScene.get(sceneId);
+    if (!row || row.mock_id !== mapping.mock_id || row.mock_kind !== mapping.mock_kind
+        || row.scenario_id !== mapping.scenario_id
+        || row.data_source !== mapping.data?.source
+        || row.data_classification !== mapping.data?.classification
+        || row.sanitization_status !== mapping.data?.sanitization_status) {
+      throw new Error(`Frozen Mock Scenario mapping is inconsistent for Review Scene ${sceneId}`);
+    }
+    if (!new Set(["external-dependency", "product-backend"]).has(mapping.mock_kind)
+        || !mapping.owner || !mapping.operation_or_channel || !mapping.replacement_condition
+        || !mapping.contract?.approval_ref) {
+      throw new Error(`Frozen Mock Scenario ${sceneId} is missing its authority or protocol identity`);
+    }
+    if (mapping.data?.sanitization_evidence) {
+      boundFile(
+        experience.root,
+        mapping.data.sanitization_evidence,
+        `Frozen Mock Scenario ${sceneId} sanitization evidence`,
+      );
+    }
+    mappingsByScene.set(sceneId, mapping);
+  }
+  if (mappingsByScene.size !== activeSceneIds.size
+      || [...activeSceneIds].some((sceneId) => !mappingsByScene.has(sceneId))) {
+    throw new Error("Frozen Mock Scenario Pack does not cover every active Review Scene");
+  }
+
+  const adminArtifacts = Array.isArray(adminExport.artifacts) ? adminExport.artifacts : [];
+  const packedArtifacts = Array.isArray(pack.admin_export.artifacts) ? pack.admin_export.artifacts : [];
+  const actualByIdentity = new Map(adminArtifacts.map((artifact) => [
+    `${artifact.mock_kind}:${artifact.mock_id}`,
+    artifact,
+  ]));
+  const packedByIdentity = new Map(packedArtifacts.map((artifact) => [
+    `${artifact.mock_kind}:${artifact.mock_id}`,
+    artifact,
+  ]));
+  if (actualByIdentity.size !== adminArtifacts.length
+      || packedByIdentity.size !== packedArtifacts.length
+      || actualByIdentity.size !== packedByIdentity.size) {
+    throw new Error("Frozen Mock admin export artifacts are missing or duplicated");
+  }
+  const expectations = new Map();
+  for (const [sceneId, mapping] of mappingsByScene) {
+    const identity = `${mapping.mock_kind}:${mapping.mock_id}`;
+    const actualArtifact = actualByIdentity.get(identity);
+    const packedArtifact = packedByIdentity.get(identity);
+    if (!actualArtifact || !packedArtifact
+        || actualArtifact.protocol !== mapping.protocol
+        || packedArtifact.protocol !== mapping.protocol
+        || actualArtifact.ref !== packedArtifact.ref
+        || actualArtifact.algorithm !== packedArtifact.algorithm
+        || actualArtifact.checksum !== packedArtifact.checksum
+        || !Array.isArray(packedArtifact.scenario_ids)
+        || !packedArtifact.scenario_ids.includes(mapping.scenario_id)) {
+      throw new Error(`Frozen Mock admin export does not bind Scenario ${mapping.scenario_id}`);
+    }
+    const contractBinding = boundFile(
+      projectRoot,
+      mapping.contract,
+      `Frozen Mock Scenario contract ${mapping.mock_id}`,
+      ".workflow/mock-system/definitions/",
+    );
+    const contractDefinition = readYamlFile(
+      contractBinding.file,
+      `Frozen Mock Scenario contract ${mapping.mock_id}`,
+    );
+    const entry = { ...mapping, contract_ref: mapping.contract.ref };
+    validateMockDefinition(contractDefinition, entry);
+    const exportBinding = boundFile(
+      experience.root,
+      packedArtifact,
+      `Mock admin export artifact ${mapping.mock_id}`,
+      "mock-admin-exports/",
+    );
+    const exportDefinition = readYamlFile(
+      exportBinding.file,
+      `Mock admin export artifact ${mapping.mock_id}`,
+    );
+    validateMockDefinition(exportDefinition, entry);
+    const contractExpectation = protocolExpectation(contractDefinition, entry);
+    const exportExpectation = protocolExpectation(exportDefinition, entry);
+    if (!sameStableValue(contractExpectation, exportExpectation)) {
+      throw new Error(`Mock admin export artifact ${mapping.mock_id} differs from its frozen contract`);
+    }
+    expectations.set(sceneId, exportExpectation);
+  }
+  return {
+    pack,
+    file: packBinding.file,
+    checksum: sha256File(packBinding.file),
+    revisionReport,
+    expectations,
+  };
+}
+
+export function freezeMockScenarioPack(projectRoot, options = {}, dependencies = {}) {
+  const readMockCatalogs = dependencies.readMockCatalogs;
+  const validateMockDefinition = dependencies.validateMockDefinition;
+  if (typeof readMockCatalogs !== "function") throw new Error("Mock catalog reader is unavailable");
+  if (typeof validateMockDefinition !== "function") {
+    throw new Error("Mock protocol validator is unavailable");
+  }
+  const experience = requireExperienceRoot(projectRoot, options.experience);
+  const requestBinding = containedFile(
+    experience.root,
+    options.scenarioPack,
+    "Mock Scenario Pack request",
+  );
+  const request = readYamlFile(requestBinding.file, "Mock Scenario Pack request");
+  const revisionBinding = boundFile(
+    experience.root,
+    request.prototype_revision,
+    "Mock Scenario Pack Prototype revision",
+  );
+  const revisionReport = validatePrototypeRevision(projectRoot, {
+    experience: experience.ref,
+    revision: revisionBinding.ref,
+  });
+  const revision = readYamlFile(revisionBinding.file, "Mock Scenario Pack Prototype revision");
+  requireRequestIdentity(request, revision);
+  const mappingBinding = boundFile(
+    experience.root,
+    request.scenario_mapping,
+    "Mock Scenario mapping",
+  );
+  const mappingCatalog = parsePrototypeCatalogCsv(
+    fs.readFileSync(mappingBinding.file, "utf8"),
+    "Mock Scenario mapping",
+  );
+  if (mappingCatalog.header !== mappingHeader) {
+    throw new Error("Mock Scenario mapping header is invalid");
+  }
+  const exportBinding = boundFile(
+    experience.root,
+    request.admin_export,
+    "Mock admin export",
+  );
+  const adminExport = readYamlFile(exportBinding.file, "Mock admin export");
+  validateAdminExportMetadata(adminExport);
+  const catalogs = readMockCatalogs(projectRoot);
+  const activeScenes = readActiveReviewScenes(experience.root, revisionBinding.file, revision);
+  const mappings = normalizeMappings(
+    experience.root,
+    mappingCatalog.rows,
+    activeScenes,
+    catalogs,
+  );
+  const exportArtifacts = validateAdminExportArtifacts(
+    experience.root,
+    adminExport,
+    catalogs,
+    mappings,
+    validateMockDefinition,
+  );
+  const candidate = scenarioPackCandidate({
+    schema_version: 1,
+    artifact_id: request.artifact_id,
+    version: request.version,
+    iteration_id: request.iteration_id,
+    prototype_revision: {
+      artifact_id: revisionReport.revision_id,
+      ref: revisionBinding.ref,
+      algorithm: "sha256",
+      checksum: revisionBinding.checksum,
+      source_checksum: revision.source.checksum,
+      review_bundle_checksum: revision.review_bundle.checksum,
+    },
+    scenario_mapping: {
+      ref: mappingBinding.ref,
+      algorithm: "sha256",
+      checksum: mappingBinding.checksum,
+    },
+    admin_export: {
+      ref: exportBinding.ref,
+      algorithm: "sha256",
+      checksum: exportBinding.checksum,
+      source: adminExport.source,
+      exported_at: adminExport.exported_at,
+      artifacts: exportArtifacts,
+    },
+    scenario_mappings: mappings,
+    data_policy: {
+      production_traffic_recording: "prohibited",
+      production_credentials: "prohibited",
+      unsanitized_personal_data: "prohibited",
+      explicit_imports: "sanitized-only",
+    },
+    assurance: {
+      real_product_backend_evidence: false,
+      end_to_end_acceptance_evidence: false,
+    },
+  });
+  const candidateChecksum = sha256Bytes(JSON.stringify(candidate));
+  const mockKinds = [...new Set(mappings.map((mapping) => mapping.mock_kind))].sort();
+  const planned = {
+    provider: "microcks",
+    action: "freeze",
+    dry_run: true,
+    artifact_id: request.artifact_id,
+    candidate_checksum: candidateChecksum,
+    prototype_revision_id: revisionReport.revision_id,
+    review_scene_count: activeScenes.length,
+    mock_kinds: mockKinds,
+    confirmation_required: true,
+    output_ref: request.output_ref,
+  };
+  if (options.dryRun) return planned;
+
+  validateHumanConfirmation(request.human_confirmation, candidateChecksum);
+  const output = containedFileForWrite(
+    experience.root,
+    request.output_ref,
+    request.artifact_id,
+  );
+  const pack = {
+    artifact_id: request.artifact_id,
+    artifact_type: "mock-scenario-pack",
+    version: request.version,
+    iteration_id: request.iteration_id,
+    status: "frozen",
+    candidate: { algorithm: "sha256", checksum: candidateChecksum },
+    ...candidate,
+    human_confirmation: {
+      required: true,
+      decision: "approved",
+      actor: request.human_confirmation.actor,
+      decided_at: request.human_confirmation.decided_at,
+      candidate_checksum: candidateChecksum,
+    },
+    authority: {
+      formal_registration_required: true,
+      registration_artifact_type: "mock-scenario-pack",
+      registration_status: "submitted",
+    },
+  };
+  const text = stringifyYaml(pack, { lineWidth: 0 });
+  if (fs.existsSync(output.file)) {
+    if (fs.readFileSync(output.file, "utf8") !== text) {
+      throw new Error(`Immutable Mock Scenario Pack already exists with different content: ${output.ref}`);
+    }
+  } else {
+    fs.mkdirSync(path.dirname(output.file), { recursive: true });
+    atomicWrite(output.file, text);
+  }
+  return {
+    ...planned,
+    dry_run: false,
+    frozen: true,
+    output_ref: output.ref,
+    file_checksum: sha256File(output.file),
+    formal_registration_required: true,
+  };
+}
+
+function containedFileForWrite(experienceRoot, ref, artifactId) {
+  const normalized = requireRelativeRef(
+    ref,
+    "Mock Scenario Pack output",
+    "mock-scenario-packs/",
+  );
+  if (normalized !== `mock-scenario-packs/${artifactId}.yaml`) {
+    throw new Error("Mock Scenario Pack output_ref must match its immutable artifact_id");
+  }
+  const file = path.resolve(experienceRoot, ...normalized.split("/"));
+  assertPathInside(experienceRoot, file);
+  return { ref: normalized, file };
+}