ai-delivery-workflow 0.3.0 → 0.4.0

package/lib/mock-system.mjs

@@ -0,0 +1,897 @@
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { assertPathInside, atomicWrite } from "./fs-utils.mjs";
+import { freezeMockScenarioPack } from "./mock-scenario-pack.mjs";
+import { parse as parseYaml, stringify as stringifyYaml } from "./yaml-runtime.mjs";
+import { readWorkspaceConfiguration } from "./workspace.mjs";
+
+export const MICROCKS_IMAGE = "quay.io/microcks/microcks-uber:1.15.0"
+  + "@sha256:97e74ff545d020f9f20141a0edc4ec1a99f32b7bfeacc81aadd47d8ffc642ffe";
+
+function defaultRunner(command, args, options = {}) {
+  return spawnSync(command, args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: options.timeout,
+  });
+}
+
+function selectContainerEngine(runner, projectRoot) {
+  const args = ["version", "--format", "{{.Client.Version}}"];
+  for (const command of ["docker", "podman"]) {
+    const probe = runner(command, args, { cwd: projectRoot, timeout: 5000 });
+    if (probe?.status === 0) return { command, version: probe.stdout.trim() || null };
+  }
+  throw new Error(
+    "Docker or Podman is unavailable; install and start one explicitly before using the Mock System. "
+    + "The workflow will not install a container engine automatically.",
+  );
+}
+
+function commandFailure(result) {
+  return String(result?.stderr || result?.stdout || result?.error?.message || "no output")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 500);
+}
+
+function requireCommand(result, description) {
+  if (result?.status !== 0) throw new Error(`${description} failed: ${commandFailure(result)}`);
+}
+
+const MOCK_CATALOG_DEFINITIONS = Object.freeze([
+  Object.freeze({
+    kind: "external-dependency",
+    label: "External Dependency Mock",
+    catalogRef: ".workflow/mock-system/external-dependencies.yaml",
+    collection: "external_dependencies",
+    definitionPrefix: ".workflow/mock-system/definitions/external/",
+  }),
+  Object.freeze({
+    kind: "product-backend",
+    label: "Product Backend Mock",
+    catalogRef: ".workflow/mock-system/product-backends.yaml",
+    collection: "product_backends",
+    definitionPrefix: ".workflow/mock-system/definitions/product-backend/",
+  }),
+]);
+const MOCK_CATALOG_DEFINITIONS_BY_KIND = Object.freeze(Object.fromEntries(
+  MOCK_CATALOG_DEFINITIONS.map((definition) => [definition.kind, definition]),
+));
+
+function mockKindLabel(kind) {
+  return MOCK_CATALOG_DEFINITIONS_BY_KIND[kind]?.label || `Mock (${kind})`;
+}
+
+function mockContractLabel(contractRef) {
+  return MOCK_CATALOG_DEFINITIONS.find((definition) =>
+    contractRef.startsWith(definition.definitionPrefix))?.label || "Mock";
+}
+
+function initializeMockCatalogs(projectRoot) {
+  const mockRoot = path.join(projectRoot, ".workflow", "mock-system");
+  assertPathInside(projectRoot, mockRoot);
+  const catalogPaths = {};
+  for (const definition of MOCK_CATALOG_DEFINITIONS) {
+    const definitionsRoot = path.join(
+      projectRoot,
+      ...definition.definitionPrefix.slice(0, -1).split("/"),
+    );
+    const catalogFile = path.join(projectRoot, ...definition.catalogRef.split("/"));
+    assertPathInside(projectRoot, definitionsRoot);
+    assertPathInside(projectRoot, catalogFile);
+    fs.mkdirSync(definitionsRoot, { recursive: true });
+    const marker = path.join(definitionsRoot, ".gitkeep");
+    if (!fs.existsSync(marker)) atomicWrite(marker, "");
+    if (!fs.existsSync(catalogFile)) {
+      atomicWrite(catalogFile, stringifyYaml({
+        schema_version: 1,
+        mock_system: {
+          provider: "microcks",
+          image: MICROCKS_IMAGE,
+          management_url: "http://127.0.0.1:8585",
+        },
+        [definition.collection]: [],
+      }, { lineWidth: 0 }));
+    }
+    catalogPaths[definition.kind] = definition.catalogRef;
+  }
+  return catalogPaths;
+}
+
+function mockRuntime(projectRoot) {
+  const workspace = readWorkspaceConfiguration(projectRoot);
+  const workspaceSlug = String(workspace.configuration.workspace_id)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  const containerName = `ai-delivery-${workspaceSlug}-microcks`;
+  const managementUrl = "http://127.0.0.1:8585";
+  const catalogFile = path.join(projectRoot, ".workflow", "mock-system", "external-dependencies.yaml");
+  if (!fs.existsSync(catalogFile)) {
+    throw new Error("Mock System is not initialized; run ai-delivery mock setup first");
+  }
+  return {
+    workspaceId: workspace.configuration.workspace_id,
+    containerName,
+    managementUrl,
+    runArgs: [
+      "run", "--detach", "--rm", "--pull=never",
+      "--name", containerName,
+      "--label", "io.ai-delivery.mock-system=microcks",
+      "--label", `io.ai-delivery.workspace-id=${workspace.configuration.workspace_id}`,
+      "--publish", "127.0.0.1:8585:8080",
+      MICROCKS_IMAGE,
+    ],
+  };
+}
+
+async function waitForHealth(url, options = {}) {
+  const request = options.request || globalThis.fetch;
+  const pause = options.sleep || ((milliseconds) =>
+    new Promise((resolve) => setTimeout(resolve, milliseconds)));
+  const attempts = options.healthAttempts || 60;
+  let detail = "no response";
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      const response = await request(url, { method: "GET" });
+      if (response?.status === 200) return;
+      detail = `HTTP ${response?.status ?? "unknown"}`;
+    } catch (error) {
+      detail = error.message;
+    }
+    if (attempt + 1 < attempts) await pause(options.healthDelayMs ?? 1000);
+  }
+  throw new Error(`Microcks health check failed at ${url}: ${detail}`);
+}
+
+async function inspectHealth(url, request = globalThis.fetch) {
+  try {
+    const response = await request(url, { method: "GET" });
+    return response?.status === 200;
+  } catch {
+    return false;
+  }
+}
+
+function requireLoopbackUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`Mock System URL is invalid: ${value}`);
+  }
+  const loopbackHosts = new Set(["127.0.0.1", "localhost", "[::1]"]);
+  if (parsed.protocol !== "http:"
+    || !loopbackHosts.has(parsed.hostname)
+    || parsed.username
+    || parsed.password
+    || !new Set(["", "/"]).has(parsed.pathname)
+    || parsed.search
+    || parsed.hash) {
+    throw new Error(`Mock System URL must be a credential-free loopback HTTP origin: ${value}`);
+  }
+  return parsed.origin;
+}
+
+function readContractDefinition(contractFile, contractRef) {
+  try {
+    return parseYaml(fs.readFileSync(contractFile, "utf8"));
+  } catch (error) {
+    throw new Error(`${mockContractLabel(contractRef)} contract is invalid YAML: ${contractRef}: ${error.message}`);
+  }
+}
+
+function resolveLocalReference(definition, value, contractRef) {
+  let resolved = value;
+  const visited = new Set();
+  while (resolved && typeof resolved === "object" && typeof resolved.$ref === "string") {
+    const reference = resolved.$ref;
+    if (!reference.startsWith("#/")) {
+      throw new Error(`${mockContractLabel(contractRef)} contract uses an unsupported external reference in ${contractRef}: ${reference}`);
+    }
+    if (visited.has(reference)) {
+      throw new Error(`${mockContractLabel(contractRef)} contract has a circular reference in ${contractRef}: ${reference}`);
+    }
+    visited.add(reference);
+    resolved = reference.slice(2).split("/").reduce((node, segment) => {
+      const key = segment.replaceAll("~1", "/").replaceAll("~0", "~");
+      return node?.[key];
+    }, definition);
+    if (resolved === undefined) {
+      throw new Error(`${mockContractLabel(contractRef)} contract reference is missing in ${contractRef}: ${reference}`);
+    }
+  }
+  return resolved;
+}
+
+function openApiResponseScenarios(definition, operation, contractRef) {
+  const scenarios = new Set();
+  for (const responseValue of Object.values(operation.responses || {})) {
+    const response = resolveLocalReference(definition, responseValue, contractRef);
+    for (const scenarioId of response?.["x-microcks-refs"] || []) scenarios.add(scenarioId);
+    for (const mediaValue of Object.values(response?.content || {})) {
+      const media = resolveLocalReference(definition, mediaValue, contractRef);
+      const examples = resolveLocalReference(definition, media?.examples, contractRef);
+      if (examples && typeof examples === "object") {
+        for (const scenarioId of Object.keys(examples)) scenarios.add(scenarioId);
+      }
+    }
+  }
+  return scenarios;
+}
+
+function hasNamedParameterExample(definition, parameter, scenarioId, contractRef) {
+  const examples = resolveLocalReference(definition, parameter?.examples, contractRef);
+  if (!examples || typeof examples !== "object" || !Object.hasOwn(examples, scenarioId)) return false;
+  const example = resolveLocalReference(definition, examples[scenarioId], contractRef);
+  return example && typeof example === "object"
+    && (Object.hasOwn(example, "value") || typeof example.externalValue === "string");
+}
+
+function dispatcherRuleNames(rules, dispatcher, entry) {
+  if (typeof rules !== "string" || !rules.trim()) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} dispatcher ${dispatcher} requires dispatcherRules in ${entry.operation_or_channel}`,
+    );
+  }
+  return rules.split(/\s*&&\s*/).map((name) => name.trim()).filter(Boolean);
+}
+
+function requireDispatcherInputs(definition, parameters, names, location, entry) {
+  for (const name of names) {
+    const parameter = parameters.find((candidate) =>
+      candidate?.in === location && candidate?.name === name);
+    if (!hasNamedParameterExample(definition, parameter, entry.scenario_id, entry.contract_ref)) {
+      throw new Error(
+        `${mockKindLabel(entry.mock_kind)} dispatcher input ${location} parameter ${name} has no example for ${entry.scenario_id}`,
+      );
+    }
+  }
+}
+
+function validateOpenApiOperation(definition, entry) {
+  const match = /^([A-Za-z]+) (\/\S+)$/.exec(entry.operation_or_channel);
+  const method = match?.[1]?.toLowerCase();
+  const route = match?.[2];
+  const pathItem = route
+    ? resolveLocalReference(definition, definition?.paths?.[route], entry.contract_ref)
+    : undefined;
+  const operation = resolveLocalReference(definition, pathItem?.[method], entry.contract_ref);
+  if (!operation || typeof operation !== "object" || Array.isArray(operation)) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} operation_or_channel ${entry.operation_or_channel} is not present in ${entry.contract_ref}`,
+    );
+  }
+  const responseScenarios = openApiResponseScenarios(definition, operation, entry.contract_ref);
+  if (!responseScenarios.has(entry.scenario_id)) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} scenario_id ${entry.scenario_id} is not present in ${entry.operation_or_channel}`,
+    );
+  }
+  const parameters = [...(pathItem?.parameters || []), ...(operation.parameters || [])]
+    .map((parameter) => resolveLocalReference(definition, parameter, entry.contract_ref));
+  const operationParameters = (operation.parameters || [])
+    .map((parameter) => resolveLocalReference(definition, parameter, entry.contract_ref));
+  const pathVariables = [...route.matchAll(/\{([^{}]+)\}/g)].map((matchValue) => matchValue[1]);
+  const queryParameters = operationParameters.filter((parameter) => parameter?.in === "query");
+  const dispatcherMetadata = operation["x-microcks-operation"];
+  const configuredDispatcher = typeof dispatcherMetadata?.dispatcher === "string"
+    ? dispatcherMetadata.dispatcher.trim().toUpperCase()
+    : null;
+  const effectiveDispatcher = configuredDispatcher
+    || (pathVariables.length > 0 && queryParameters.length > 0 ? "URI_ELEMENTS"
+      : pathVariables.length > 0 ? "URI_PARTS"
+        : queryParameters.length > 0 ? "URI_PARAMS"
+          : null);
+
+  if (effectiveDispatcher === "URI_PARTS") {
+    const names = configuredDispatcher
+      ? dispatcherRuleNames(dispatcherMetadata.dispatcherRules, effectiveDispatcher, entry)
+      : pathVariables;
+    requireDispatcherInputs(definition, parameters, names, "path", entry);
+  } else if (effectiveDispatcher === "URI_PARAMS") {
+    const names = configuredDispatcher
+      ? dispatcherRuleNames(dispatcherMetadata.dispatcherRules, effectiveDispatcher, entry)
+      : queryParameters.map((parameter) => parameter.name);
+    requireDispatcherInputs(definition, operationParameters, names, "query", entry);
+  } else if (effectiveDispatcher === "URI_ELEMENTS") {
+    let pathNames = pathVariables;
+    let queryNames = queryParameters.map((parameter) => parameter.name);
+    if (configuredDispatcher) {
+      const ruleParts = String(dispatcherMetadata.dispatcherRules || "").split(/\s*\?\?\s*/);
+      if (ruleParts.length !== 2) {
+        throw new Error(
+          `${mockKindLabel(entry.mock_kind)} dispatcher URI_ELEMENTS requires path ?? query dispatcherRules in ${entry.operation_or_channel}`,
+        );
+      }
+      pathNames = dispatcherRuleNames(ruleParts[0], effectiveDispatcher, entry);
+      queryNames = dispatcherRuleNames(ruleParts[1], effectiveDispatcher, entry);
+    }
+    requireDispatcherInputs(definition, parameters, pathNames, "path", entry);
+    requireDispatcherInputs(definition, operationParameters, queryNames, "query", entry);
+  } else if (effectiveDispatcher === "QUERY_HEADER") {
+    const names = dispatcherRuleNames(dispatcherMetadata.dispatcherRules, effectiveDispatcher, entry);
+    requireDispatcherInputs(definition, operationParameters, names, "header", entry);
+  } else if (effectiveDispatcher === "RANDOM" || effectiveDispatcher === "SEQUENCE") {
+    if (responseScenarios.size > 1) {
+      throw new Error(
+        `${mockKindLabel(entry.mock_kind)} ${entry.operation_or_channel} has ${responseScenarios.size} named scenarios but dispatcher ${effectiveDispatcher} is not deterministic`,
+      );
+    }
+  } else if (effectiveDispatcher) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} dispatcher ${effectiveDispatcher} cannot be validated locally for deterministic scenario selection`,
+    );
+  } else if (responseScenarios.size > 1) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} ${entry.operation_or_channel} has ${responseScenarios.size} named scenarios but no deterministic dispatcher`,
+    );
+  }
+}
+
+function asyncApiOperationHasScenario(definition, operation, scenarioId, contractRef) {
+  for (const messageValue of operation?.messages || []) {
+    const message = resolveLocalReference(definition, messageValue, contractRef);
+    for (const exampleValue of message?.examples || []) {
+      const example = resolveLocalReference(definition, exampleValue, contractRef);
+      if (example?.name === scenarioId) return true;
+      if (example && typeof example === "object" && Object.hasOwn(example, scenarioId)) return true;
+    }
+  }
+  return false;
+}
+
+function validateAsyncApiIdentity(definition, entry) {
+  const channels = Object.entries(definition.channels || {}).map(([key, channelValue]) => ({
+    key,
+    channel: resolveLocalReference(definition, channelValue, entry.contract_ref),
+  }));
+  const majorVersion = Number.parseInt(definition.asyncapi, 10);
+  const operations = majorVersion >= 3
+    ? Object.entries(definition.operations || {}).map(([key, operationValue]) => {
+      const operation = resolveLocalReference(definition, operationValue, entry.contract_ref);
+      return {
+        key,
+        identity: `${String(operation?.action || "").toUpperCase()} ${key}`,
+        operation,
+        channel: resolveLocalReference(definition, operation?.channel, entry.contract_ref),
+      };
+    })
+    : channels.flatMap(({ key, channel }) => ["publish", "subscribe"].flatMap((action) => {
+      const operation = resolveLocalReference(definition, channel?.[action], entry.contract_ref);
+      if (!operation) return [];
+      return [{
+        key,
+        identity: `${action.toUpperCase()} ${key}`,
+        operation: { ...operation, action, messages: [operation.message] },
+        channel,
+      }];
+    }));
+  const directOperation = operations.find(({ key, identity }) =>
+    entry.operation_or_channel === identity
+    || (majorVersion >= 3 && entry.operation_or_channel === key));
+  const candidates = directOperation ? [directOperation] : (() => {
+    const selectedChannel = channels.find(({ key, channel }) =>
+      entry.operation_or_channel === key || entry.operation_or_channel === channel?.address);
+    return selectedChannel
+      ? operations.filter(({ channel }) => channel === selectedChannel.channel)
+      : [];
+  })();
+  if (candidates.length === 0) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} operation_or_channel ${entry.operation_or_channel} is not present in ${entry.contract_ref}`,
+    );
+  }
+  const selectedOperation = candidates.find(({ operation }) => asyncApiOperationHasScenario(
+    definition, operation, entry.scenario_id, entry.contract_ref,
+  ));
+  if (!selectedOperation) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} scenario_id ${entry.scenario_id} is not present in ${entry.operation_or_channel}`,
+    );
+  }
+}
+
+export function validateMockDefinition(definition, entry) {
+  mockProtocolHandler(definition, entry).validate(definition, entry);
+}
+
+function inlineExampleValue(definition, examplesValue, scenarioId, contractRef, label) {
+  const examples = resolveLocalReference(definition, examplesValue, contractRef);
+  if (!examples || !Object.hasOwn(examples, scenarioId)) return undefined;
+  const example = resolveLocalReference(definition, examples[scenarioId], contractRef);
+  if (!example || typeof example !== "object" || !Object.hasOwn(example, "value")) {
+    throw new Error(`${label} requires an inline value for UI Acceptance`);
+  }
+  return example.value;
+}
+
+function openApiProtocolExpectation(definition, entry) {
+  validateOpenApiOperation(definition, entry);
+  const match = /^([A-Za-z]+) (\/\S+)$/.exec(entry.operation_or_channel);
+  const method = match?.[1]?.toLowerCase();
+  const route = match?.[2];
+  const pathItem = resolveLocalReference(definition, definition?.paths?.[route], entry.contract_ref);
+  const operation = resolveLocalReference(definition, pathItem?.[method], entry.contract_ref);
+  for (const [statusValue, responseValue] of Object.entries(operation.responses || {})) {
+    const status = Number(statusValue);
+    if (!Number.isInteger(status) || status < 100 || status > 599) continue;
+    const response = resolveLocalReference(definition, responseValue, entry.contract_ref);
+    for (const [contentType, mediaValue] of Object.entries(response?.content || {})) {
+      const media = resolveLocalReference(definition, mediaValue, entry.contract_ref);
+      const responseBody = inlineExampleValue(
+        definition,
+        media?.examples,
+        entry.scenario_id,
+        entry.contract_ref,
+        `${mockKindLabel(entry.mock_kind)} scenario ${entry.scenario_id} response`,
+      );
+      if (responseBody === undefined) continue;
+      const parameters = [...(pathItem?.parameters || []), ...(operation.parameters || [])]
+        .map((parameter) => resolveLocalReference(definition, parameter, entry.contract_ref));
+      const request = { method: method.toUpperCase(), path: route };
+      for (const location of ["path", "query", "header"]) {
+        const values = {};
+        for (const parameter of parameters.filter((item) => item?.in === location)) {
+          const value = inlineExampleValue(
+            definition,
+            parameter.examples,
+            entry.scenario_id,
+            entry.contract_ref,
+            `${mockKindLabel(entry.mock_kind)} ${location} parameter ${parameter.name}`,
+          );
+          if (value !== undefined) values[parameter.name] = value;
+        }
+        if (Object.keys(values).length) request[`${location}_parameters`] = values;
+      }
+      const requestBody = resolveLocalReference(definition, operation.requestBody, entry.contract_ref);
+      for (const [requestContentType, requestMediaValue] of Object.entries(requestBody?.content || {})) {
+        const requestMedia = resolveLocalReference(definition, requestMediaValue, entry.contract_ref);
+        const body = inlineExampleValue(
+          definition,
+          requestMedia?.examples,
+          entry.scenario_id,
+          entry.contract_ref,
+          `${mockKindLabel(entry.mock_kind)} scenario ${entry.scenario_id} request body`,
+        );
+        if (body !== undefined) {
+          request.content_type = requestContentType;
+          request.body = body;
+          break;
+        }
+      }
+      return {
+        request,
+        response: { status, content_type: contentType, body: responseBody },
+      };
+    }
+  }
+  throw new Error(
+    `${mockKindLabel(entry.mock_kind)} scenario ${entry.scenario_id} has no deterministic response example for UI Acceptance`,
+  );
+}
+
+function asyncApiProtocolExpectation(definition, entry) {
+  validateAsyncApiIdentity(definition, entry);
+  const candidates = [];
+  const collect = (messageValue) => {
+    const message = resolveLocalReference(definition, messageValue, entry.contract_ref);
+    for (const exampleValue of message?.examples || []) {
+      const example = resolveLocalReference(definition, exampleValue, entry.contract_ref);
+      if (example?.name === entry.scenario_id && Object.hasOwn(example, "payload")) {
+        candidates.push(example.payload);
+      } else if (example && typeof example === "object"
+          && Object.hasOwn(example, entry.scenario_id)) {
+        const named = resolveLocalReference(definition, example[entry.scenario_id], entry.contract_ref);
+        candidates.push(named?.payload ?? named?.value ?? named);
+      }
+    }
+  };
+  const majorVersion = Number.parseInt(definition.asyncapi, 10);
+  if (majorVersion >= 3) {
+    for (const operationValue of Object.values(definition.operations || {})) {
+      const operation = resolveLocalReference(definition, operationValue, entry.contract_ref);
+      for (const message of operation?.messages || []) collect(message);
+    }
+  } else {
+    for (const channelValue of Object.values(definition.channels || {})) {
+      const channel = resolveLocalReference(definition, channelValue, entry.contract_ref);
+      for (const action of ["publish", "subscribe"]) {
+        const operation = resolveLocalReference(definition, channel?.[action], entry.contract_ref);
+        if (operation?.message) collect(operation.message);
+      }
+    }
+  }
+  if (candidates.length !== 1 || candidates[0] === undefined) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} scenario ${entry.scenario_id} has no unique deterministic message example for UI Acceptance`,
+    );
+  }
+  return {
+    request: {
+      operation_or_channel: entry.operation_or_channel,
+      scenario_id: entry.scenario_id,
+    },
+    response: { payload: candidates[0] },
+  };
+}
+
+const mockProtocolHandlers = Object.freeze([
+  Object.freeze({
+    format: "OpenAPI",
+    matches: (definition) => typeof definition?.openapi === "string",
+    protocol: "http",
+    validate: validateOpenApiOperation,
+    expectation: openApiProtocolExpectation,
+  }),
+  Object.freeze({
+    format: "AsyncAPI",
+    matches: (definition) => typeof definition?.asyncapi === "string",
+    protocol: "asyncapi",
+    validate: validateAsyncApiIdentity,
+    expectation: asyncApiProtocolExpectation,
+  }),
+]);
+
+function mockProtocolHandler(definition, entry) {
+  const handler = mockProtocolHandlers.find((candidate) => candidate.matches(definition));
+  if (!handler) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} contract must be an OpenAPI or AsyncAPI definition: ${entry.contract_ref}`,
+    );
+  }
+  if (entry.protocol !== handler.protocol) {
+    throw new Error(
+      `${mockKindLabel(entry.mock_kind)} protocol ${entry.protocol} does not match ${handler.format}`,
+    );
+  }
+  return handler;
+}
+
+export function mockProtocolExpectation(definition, entry) {
+  const handler = mockProtocolHandler(definition, entry);
+  return { protocol: handler.protocol, ...handler.expectation(definition, entry) };
+}
+
+function readMockCatalog(projectRoot, definition) {
+  const catalogFile = path.join(projectRoot, ...definition.catalogRef.split("/"));
+  assertPathInside(projectRoot, catalogFile);
+  if (!fs.existsSync(catalogFile)) {
+    throw new Error("Mock System is not initialized; run ai-delivery mock setup first");
+  }
+  let catalog;
+  try {
+    catalog = parseYaml(fs.readFileSync(catalogFile, "utf8"));
+  } catch (error) {
+    throw new Error(`${definition.label} catalog is invalid YAML: ${error.message}`);
+  }
+  if (catalog?.schema_version !== 1
+    || catalog?.mock_system?.provider !== "microcks"
+    || catalog?.mock_system?.image !== MICROCKS_IMAGE
+    || !Array.isArray(catalog?.[definition.collection])) {
+    throw new Error(`${definition.label} catalog has an invalid schema, provider, or pinned image`);
+  }
+  const requiredFields = [
+    "mock_kind", "mock_id", "owner", "contract_ref", "contract_approval_ref",
+    "replacement_condition", "protocol", "operation_or_channel", "scenario_id",
+  ];
+  const identityFields = [
+    "owner", "contract_ref", "contract_approval_ref", "replacement_condition", "protocol",
+  ];
+  const identities = new Map();
+  const scenarioKeys = new Set();
+  const entries = catalog[definition.collection].map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`${definition.label} entry ${index + 1} must be an object`);
+    }
+    for (const field of requiredFields) {
+      if (typeof entry[field] !== "string" || !entry[field].trim()) {
+        throw new Error(`${definition.label} entry ${index + 1} requires ${field}`);
+      }
+    }
+    const catalogEntry = Object.fromEntries(
+      requiredFields.map((field) => [field, entry[field].trim()]),
+    );
+    if (catalogEntry.mock_kind !== definition.kind) {
+      throw new Error(`${definition.label} mock_kind must be ${definition.kind}`);
+    }
+    const existingIdentity = identities.get(catalogEntry.mock_id);
+    if (existingIdentity) {
+      for (const field of identityFields) {
+        if (catalogEntry[field] !== existingIdentity[field]) {
+          throw new Error(
+            `${definition.label} ${catalogEntry.mock_id} must keep ${field} consistent across scenarios`,
+          );
+        }
+      }
+    } else {
+      identities.set(catalogEntry.mock_id, catalogEntry);
+    }
+    const scenarioKey = JSON.stringify([catalogEntry.mock_id, catalogEntry.scenario_id]);
+    if (scenarioKeys.has(scenarioKey)) {
+      throw new Error(
+        `Duplicate ${definition.label} scenario: ${catalogEntry.mock_id} / ${catalogEntry.scenario_id}`,
+      );
+    }
+    scenarioKeys.add(scenarioKey);
+    const contractRef = catalogEntry.contract_ref;
+    const prefix = definition.definitionPrefix;
+    if (contractRef.includes("\\")
+      || contractRef.includes("\0")
+      || path.posix.isAbsolute(contractRef)
+      || path.posix.normalize(contractRef) !== contractRef
+      || !contractRef.startsWith(prefix)) {
+      throw new Error(`${definition.label} contract_ref is outside ${prefix}: ${contractRef}`);
+    }
+    const contractFile = path.resolve(projectRoot, ...contractRef.split("/"));
+    assertPathInside(projectRoot, contractFile);
+    if (!fs.existsSync(contractFile) || !fs.statSync(contractFile).isFile()) {
+      throw new Error(`${definition.label} contract is missing: ${contractRef}`);
+    }
+    assertPathInside(projectRoot, contractFile);
+    const contractDefinition = readContractDefinition(contractFile, contractRef);
+    validateMockDefinition(contractDefinition, catalogEntry);
+    return {
+      catalogEntry,
+      contractFile,
+    };
+  });
+  return {
+    baseUrl: requireLoopbackUrl(catalog.mock_system.management_url),
+    definition,
+    entries,
+  };
+}
+
+function readMockCatalogs(projectRoot) {
+  const catalogs = MOCK_CATALOG_DEFINITIONS.map((definition) =>
+    readMockCatalog(projectRoot, definition));
+  const baseUrls = new Set(catalogs.map((catalog) => catalog.baseUrl));
+  if (baseUrls.size !== 1) {
+    throw new Error("External Dependency and Product Backend Mock catalogs must use the same loopback management URL");
+  }
+  const kindsById = new Map();
+  for (const { entries } of catalogs) {
+    for (const entry of entries) {
+      const { mock_id: mockId, mock_kind: mockKind } = entry.catalogEntry;
+      const existingKind = kindsById.get(mockId);
+      if (existingKind && existingKind !== mockKind) {
+        throw new Error(`Mock ID is duplicated across catalog kinds: ${entry.catalogEntry.mock_id}`);
+      }
+      kindsById.set(mockId, mockKind);
+    }
+  }
+  return {
+    baseUrl: catalogs[0].baseUrl,
+    catalogs,
+    entries: catalogs.flatMap((catalog) => catalog.entries),
+  };
+}
+
+function multipartArtifact(file) {
+  const boundary = `----ai-delivery-${crypto.randomUUID()}`;
+  const filename = path.basename(file).replace(/["\r\n]/g, "_");
+  const prefix = Buffer.from(
+    `--${boundary}\r\n`
+    + `Content-Disposition: form-data; name="file"; filename="${filename}"\r\n`
+    + "Content-Type: application/octet-stream\r\n\r\n",
+  );
+  const suffix = Buffer.from(`\r\n--${boundary}--\r\n`);
+  return {
+    body: Buffer.concat([prefix, fs.readFileSync(file), suffix]),
+    contentType: `multipart/form-data; boundary=${boundary}`,
+  };
+}
+
+function reportCatalogEntries(catalogs) {
+  return Object.fromEntries(catalogs.map(({ definition, entries }) => [
+    definition.collection,
+    entries.map((entry) => entry.catalogEntry),
+  ]));
+}
+
+async function syncMockCatalogs(projectRoot, options = {}) {
+  const catalog = readMockCatalogs(projectRoot);
+  const baseUrl = requireLoopbackUrl(options.baseUrl || catalog.baseUrl);
+  const contracts = new Map();
+  for (const entry of catalog.entries) {
+    if (!contracts.has(entry.catalogEntry.contract_ref)) {
+      contracts.set(entry.catalogEntry.contract_ref, entry.contractFile);
+    }
+  }
+  if (options.dryRun) {
+    return {
+      provider: "microcks",
+      action: "sync",
+      dry_run: true,
+      base_url: baseUrl,
+      planned_contracts: [...contracts.keys()],
+      ...reportCatalogEntries(catalog.catalogs),
+    };
+  }
+  const request = options.request || globalThis.fetch;
+  const healthUrl = `${baseUrl}/api/health`;
+  if (!await inspectHealth(healthUrl, request)) {
+    throw new Error(`Microcks is not healthy at ${healthUrl}; start the Mock System before sync`);
+  }
+  for (const [contractRef, contractFile] of contracts) {
+    const multipart = multipartArtifact(contractFile);
+    const response = await request(`${baseUrl}/api/artifact/upload?mainArtifact=true`, {
+      method: "POST",
+      headers: { "content-type": multipart.contentType },
+      body: multipart.body,
+    });
+    if (response?.status !== 201) {
+      throw new Error(`Microcks rejected ${contractRef}: HTTP ${response?.status ?? "unknown"}`);
+    }
+  }
+  return {
+    provider: "microcks",
+    action: "sync",
+    base_url: baseUrl,
+    health_url: healthUrl,
+    uploaded_contracts: contracts.size,
+    ...reportCatalogEntries(catalog.catalogs),
+  };
+}
+
+export async function runMockSystemAction(projectRoot, action, options = {}) {
+  if (!new Set(["setup", "start", "stop", "status", "sync", "freeze"]).has(action)) {
+    throw new Error(`Unknown Mock System action: ${action}`);
+  }
+  if (action === "sync") return syncMockCatalogs(projectRoot, options);
+  if (action === "freeze") {
+    return freezeMockScenarioPack(projectRoot, options, {
+      readMockCatalogs,
+      validateMockDefinition,
+    });
+  }
+  const runner = options.runner || defaultRunner;
+  const engine = selectContainerEngine(runner, projectRoot);
+  if (action === "stop") {
+    const runtime = mockRuntime(projectRoot);
+    if (options.dryRun) {
+      return {
+        provider: "microcks",
+        action,
+        dry_run: true,
+        engine: engine.command,
+        image: MICROCKS_IMAGE,
+        container_name: runtime.containerName,
+        planned_command: [engine.command, "stop", runtime.containerName],
+      };
+    }
+    const stopped = runner(engine.command, [
+      "stop", runtime.containerName,
+    ], { cwd: projectRoot });
+    requireCommand(stopped, "Stopping the Microcks container");
+    return {
+      provider: "microcks",
+      action,
+      engine: engine.command,
+      image: MICROCKS_IMAGE,
+      container_name: runtime.containerName,
+      stopped: true,
+      running: false,
+    };
+  }
+  if (action === "status") {
+    const runtime = mockRuntime(projectRoot);
+    const inspected = runner(engine.command, [
+      "inspect", "--format", "{{json .State}}", runtime.containerName,
+    ], { cwd: projectRoot });
+    if (inspected?.status !== 0) {
+      return {
+        provider: "microcks",
+        action,
+        engine: engine.command,
+        image: MICROCKS_IMAGE,
+        container_name: runtime.containerName,
+        management_url: runtime.managementUrl,
+        container_state: "absent",
+        running: false,
+        healthy: false,
+      };
+    }
+    let state;
+    try {
+      state = JSON.parse(inspected.stdout);
+    } catch {
+      throw new Error(`Microcks container state is invalid: ${commandFailure(inspected)}`);
+    }
+    const running = state.Running === true;
+    const healthUrl = `${runtime.managementUrl}/api/health`;
+    return {
+      provider: "microcks",
+      action,
+      engine: engine.command,
+      image: MICROCKS_IMAGE,
+      container_name: runtime.containerName,
+      management_url: runtime.managementUrl,
+      health_url: healthUrl,
+      container_state: String(state.Status || (running ? "running" : "stopped")),
+      running,
+      healthy: running && await inspectHealth(healthUrl, options.request),
+    };
+  }
+  if (action === "start") {
+    const runtime = mockRuntime(projectRoot);
+    if (options.dryRun) {
+      return {
+        provider: "microcks",
+        action,
+        dry_run: true,
+        engine: engine.command,
+        engine_version: engine.version,
+        image: MICROCKS_IMAGE,
+        container_name: runtime.containerName,
+        management_url: runtime.managementUrl,
+        planned_command: [engine.command, ...runtime.runArgs],
+      };
+    }
+    const started = runner(engine.command, runtime.runArgs, {
+      cwd: projectRoot,
+    });
+    requireCommand(started, "Starting the Microcks container");
+    const healthUrl = `${runtime.managementUrl}/api/health`;
+    try {
+      await waitForHealth(healthUrl, options);
+    } catch (healthError) {
+      const stopped = runner(engine.command, ["stop", runtime.containerName], { cwd: projectRoot });
+      if (stopped?.status !== 0) {
+        throw new Error(
+          `${healthError.message}; cleaning the unhealthy Microcks container failed: ${commandFailure(stopped)}`,
+          { cause: healthError },
+        );
+      }
+      throw healthError;
+    }
+    return {
+      provider: "microcks",
+      action,
+      engine: engine.command,
+      engine_version: engine.version,
+      image: MICROCKS_IMAGE,
+      container_name: runtime.containerName,
+      container_id: started.stdout.trim() || null,
+      management_url: runtime.managementUrl,
+      health_url: healthUrl,
+      running: true,
+      healthy: true,
+    };
+  }
+  if (options.dryRun) {
+    return {
+      provider: "microcks",
+      action,
+      dry_run: true,
+      engine: engine.command,
+      engine_version: engine.version,
+      image: MICROCKS_IMAGE,
+      planned_actions: [
+        "create the isolated tracked External Dependency and Product Backend Mock catalogs",
+        `pull ${MICROCKS_IMAGE}`,
+      ],
+    };
+  }
+  const pulled = runner(engine.command, ["pull", MICROCKS_IMAGE], {
+    cwd: projectRoot,
+  });
+  requireCommand(pulled, "Pulling the pinned Microcks image");
+  const catalogPaths = initializeMockCatalogs(projectRoot);
+  return {
+    provider: "microcks",
+    action,
+    engine: engine.command,
+    engine_version: engine.version,
+    image: MICROCKS_IMAGE,
+    initialized: true,
+    catalog_path: catalogPaths["external-dependency"],
+    catalog_paths: catalogPaths,
+  };
+}