miravo 0.1.4 → 0.2.1

package/src/commands/start.ts

@@ -12,11 +12,13 @@ import {
   validateFullTemplate,
 } from "@miravo/core";
 import { MQTTAdapter } from "@miravo/mqtt";
-import type { DigitalTwinModel, DiscoveredTemplate, MiravoTemplate } from "@miravo/shared";
+import { OPCUAAdapter } from "@miravo/opcua";
+import type { DiscoveredTemplate, MiravoTemplate, TwinModel } from "@miravo/shared";
 import {
   ConfigNotFoundError,
   ConfigValidationError,
   DEFAULT_MQTT_PORT,
+  DEFAULT_OPCUA_PORT,
   DEFAULT_TICK_INTERVAL_MS,
   DEFAULT_TIME_MULTIPLIER,
   MIRAVO_VERSION,
@@ -24,8 +26,8 @@ import {
   SimulationNameSchema,
 } from "@miravo/shared";
 import type { Command } from "commander";
-import { box, colors } from "consola/utils";
-import { startHealthServer } from "../lib/health-server.ts";
+import { box, colors, stripAnsi } from "consola/utils";
+import { startAdminServer } from "../lib/admin-server.ts";
 import {
   parseDurationMs,
   parseNonNegativeInt,
@@ -33,9 +35,10 @@ import {
   parsePositiveFloat,
   parsePositiveInt,
 } from "../lib/parse.ts";
-import { installShutdownHandlers } from "../lib/shutdown.ts";
+import { createShutdownController, printSummaryLine } from "../lib/shutdown.ts";
 import {
   groupTemplatesByCategory,
+  isStressBenchmarkTemplate,
   sortTemplatesByCategoryAndName,
 } from "../lib/template-category.ts";
 import {
@@ -53,27 +56,31 @@ import {
   isPlain,
   lifecycleLog,
   mqttLog,
+  opcuaLog,
   setRuntimeLogContext,
   writeOutput,
 } from "../logger.ts";
-import { formatCount, formatKeyValue, formatTable } from "../output.ts";
+import { formatKeyValue, formatTable } from "../output.ts";
 
 interface StartOptions {
   readonly name?: string;
   readonly template?: string;
   readonly modelsDir?: string;
-  readonly contentDir?: string;
   readonly speed?: number;
   readonly seed?: number;
   readonly tick?: number;
-  readonly port?: number;
+  readonly mqttPort?: number;
   readonly mqttHost?: string;
   readonly mqttMode?: string;
   readonly mqttUrl?: string;
   readonly mqttUsername?: string;
   readonly mqttPassword?: string;
-  readonly healthHost?: string;
-  readonly healthPort?: number;
+  readonly mqtt?: boolean;
+  readonly opcuaPort?: number;
+  readonly opcuaHost?: string;
+  readonly opcua?: boolean;
+  readonly adminHost?: string;
+  readonly adminPort?: number;
   readonly dryRun?: boolean;
   readonly summaryInterval?: number;
 }
@@ -98,47 +105,41 @@ const ERROR_CONTEXT_OVERFLOW = "__overflow__";
 export function registerStartCommand(program: Command): void {
   program
     .command("start")
-    .description("Start the digital twin simulation")
-    .option("--name <name>", "Simulation name for control topics (env: MIRAVO_NAME)")
+    .description("Start the simulation engine")
+    .option("-n, --name <name>", "Simulation name for control topics (env: MIRAVO_NAME)")
     .option(
-      "--template <id|name|path>",
+      "-t, --template <id|name|path>",
       "Template identifier, display name, or .miravo.yaml path (env: MIRAVO_TEMPLATE)",
     )
     .option("--models-dir <path>", "Additional directory to search for .twin.yaml models")
-    .option(
-      "--content-dir <path>",
-      "User content root with /templates and /models (env: MIRAVO_CONTENT_DIR)",
-    )
-    .option("--speed <multiplier>", "Time multiplier override (default: 1)", parsePositiveFloat)
+    .option("-s, --speed <multiplier>", "Time multiplier (default: 1)", parsePositiveFloat)
     .option("--seed <number>", "RNG seed for deterministic simulation", parseNonNegativeInt)
+    .option("--tick <ms>", "Tick interval in milliseconds (default: 1000)", parseDurationMs)
     .option(
-      "--tick <ms>",
-      "Tick interval override in milliseconds (default: 1000)",
-      parseDurationMs,
-    )
-    .option(
-      "--port <number>",
-      "MQTT broker port override (default: 1883, env: MIRAVO_MQTT_PORT)",
+      "-p, --mqtt-port <number>",
+      "MQTT broker port (default: 1883, env: MIRAVO_MQTT_PORT)",
       parsePort,
     )
-    .option(
-      "--mqtt-host <host>",
-      "Embedded MQTT bind host override (default: 127.0.0.1, env: MIRAVO_MQTT_HOST)",
-    )
-    .option("--mqtt-mode <mode>", "MQTT mode override: embedded | external (env: MIRAVO_MQTT_MODE)")
+    .option("--mqtt-host <host>", "MQTT bind host (default: 127.0.0.1, env: MIRAVO_MQTT_HOST)")
+    .option("--mqtt-mode <mode>", "MQTT mode: embedded | external (env: MIRAVO_MQTT_MODE)")
     .option("--mqtt-url <url>", "External MQTT broker URL (env: MIRAVO_MQTT_URL)")
     .option("--mqtt-username <username>", "External MQTT username (env: MIRAVO_MQTT_USERNAME)")
     .option("--mqtt-password <password>", "External MQTT password (env: MIRAVO_MQTT_PASSWORD)")
+    .option("--no-mqtt", "Disable MQTT broker")
+    .option("--opcua", "Enable OPC UA server")
     .option(
-      "--health-host <host>",
-      "Health server host (default: 0.0.0.0, env: MIRAVO_HEALTH_HOST)",
+      "--opcua-port <number>",
+      "OPC UA server port (default: 4840, env: MIRAVO_OPCUA_PORT)",
+      parsePort,
     )
+    .option("--opcua-host <host>", "OPC UA server bind host (env: MIRAVO_OPCUA_HOST)")
+    .option("--admin-host <host>", "Admin server host (default: 127.0.0.1, env: MIRAVO_ADMIN_HOST)")
     .option(
-      "--health-port <number>",
-      "Health server port (default: 8080, env: MIRAVO_HEALTH_PORT)",
+      "--admin-port <number>",
+      "Admin server port (default: 8080, env: MIRAVO_ADMIN_PORT)",
       parsePort,
     )
-    .option("--dry-run", "Validate config and print summary without starting")
+    .option("-d, --dry-run", "Validate config and print summary without starting")
     .option(
       "--summary-interval <seconds>",
       "Seconds between periodic summary lines (default: 5)",
@@ -155,62 +156,128 @@ export function registerStartCommand(program: Command): void {
 
 async function startAction(options: StartOptions): Promise<void> {
   let runtimeLogContextSet = false;
+  let shutdown: ReturnType<typeof createShutdownController> | null = null;
+  let engine: Engine | undefined;
+  let stopCliResources = (): void => {};
   try {
-    const catalog = createCatalog(options.contentDir);
+    const catalog = createCatalog();
 
     // Resolve env-var fallbacks for common options
     const templateOption = options.template ?? Bun.env["MIRAVO_TEMPLATE"];
     const simulationNameEnv = Bun.env["MIRAVO_NAME"];
-    const portEnv = Bun.env["MIRAVO_MQTT_PORT"];
-    const mqttHost = options.mqttHost ?? Bun.env["MIRAVO_MQTT_HOST"];
-    const mqttMode = parseMqttModeOption(options.mqttMode ?? Bun.env["MIRAVO_MQTT_MODE"]);
-    const mqttUrl = options.mqttUrl ?? Bun.env["MIRAVO_MQTT_URL"];
-    const mqttUsername = options.mqttUsername ?? Bun.env["MIRAVO_MQTT_USERNAME"];
-    const mqttPassword = options.mqttPassword ?? Bun.env["MIRAVO_MQTT_PASSWORD"];
-    const healthHost = options.healthHost ?? Bun.env["MIRAVO_HEALTH_HOST"] ?? "0.0.0.0";
-    const healthPortEnv = Bun.env["MIRAVO_HEALTH_PORT"];
-    const mqttOverrides: MqttRunOverrides = {
-      ...(mqttMode !== undefined ? { mode: mqttMode } : {}),
-      ...(mqttHost !== undefined && mqttHost.length > 0 ? { host: mqttHost } : {}),
-      ...(mqttUrl !== undefined && mqttUrl.length > 0 ? { url: mqttUrl } : {}),
-      ...(mqttUsername !== undefined && mqttUsername.length > 0 ? { username: mqttUsername } : {}),
-      ...(mqttPassword !== undefined && mqttPassword.length > 0 ? { password: mqttPassword } : {}),
-    };
-    let portOption = options.port;
-    if (portOption === undefined && portEnv) {
-      try {
-        portOption = parsePort(portEnv);
-      } catch {
-        throw new ConfigValidationError({
-          message: `Invalid MIRAVO_MQTT_PORT environment variable: "${portEnv}".`,
-          fix: "Set MIRAVO_MQTT_PORT to a valid port number between 1 and 65535 (for example, 1883).",
-        });
+    // Protocol selection: CLI flags decide which protocols run
+    const mqttEnabled = options.mqtt !== false; // --no-mqtt disables
+    const opcuaEnabled = options.opcua === true; // --opcua enables
+
+    // Warn on ignored protocol-specific flags
+    if (!mqttEnabled) {
+      if (options.mqttPort !== undefined) {
+        configLog.warn("--mqtt-port ignored because MQTT is disabled.");
+      }
+      if (options.mqttHost !== undefined) {
+        configLog.warn("--mqtt-host ignored because MQTT is disabled.");
+      }
+      if (options.mqttMode !== undefined) {
+        configLog.warn("--mqtt-mode ignored because MQTT is disabled.");
       }
     }
-    if (healthHost.trim().length === 0) {
-      throw new ConfigValidationError({
-        message: "Invalid health server host: value is empty.",
-        fix: "Set --health-host / MIRAVO_HEALTH_HOST to a valid host (for example, 0.0.0.0).",
-      });
+    if (!opcuaEnabled) {
+      if (options.opcuaPort !== undefined) {
+        configLog.warn(
+          "--opcua-port ignored because OPC UA is not enabled. Use --opcua to enable it.",
+        );
+      }
+      if (options.opcuaHost !== undefined) {
+        configLog.warn(
+          "--opcua-host ignored because OPC UA is not enabled. Use --opcua to enable it.",
+        );
+      }
     }
-    if (mqttHost !== undefined && mqttHost.trim().length === 0) {
+
+    const adminHost = options.adminHost ?? Bun.env["MIRAVO_ADMIN_HOST"] ?? "127.0.0.1";
+    const adminPortEnv = Bun.env["MIRAVO_ADMIN_PORT"];
+    if (adminHost.trim().length === 0) {
       throw new ConfigValidationError({
-        message: "Invalid MQTT bind host: value is empty.",
-        fix: "Set --mqtt-host / MIRAVO_MQTT_HOST to a valid host (for example, 127.0.0.1 or 0.0.0.0).",
+        message: "Invalid admin server host: value is empty.",
+        fix: "Set --admin-host / MIRAVO_ADMIN_HOST to a valid host (for example, 127.0.0.1 or 0.0.0.0).",
       });
     }
-    let healthPort = options.healthPort;
-    if (healthPort === undefined && healthPortEnv) {
+
+    // MQTT env overrides — only parsed when MQTT is enabled
+    let portOption = options.mqttPort;
+    let mqttOverrides: MqttRunOverrides = {};
+    if (mqttEnabled) {
+      const portEnv = Bun.env["MIRAVO_MQTT_PORT"];
+      const mqttHost = options.mqttHost ?? Bun.env["MIRAVO_MQTT_HOST"];
+      const mqttMode = parseMqttModeOption(options.mqttMode ?? Bun.env["MIRAVO_MQTT_MODE"]);
+      const mqttUrl = options.mqttUrl ?? Bun.env["MIRAVO_MQTT_URL"];
+      const mqttUsername = options.mqttUsername ?? Bun.env["MIRAVO_MQTT_USERNAME"];
+      const mqttPassword = options.mqttPassword ?? Bun.env["MIRAVO_MQTT_PASSWORD"];
+      mqttOverrides = {
+        ...(mqttMode !== undefined ? { mode: mqttMode } : {}),
+        ...(mqttHost !== undefined && mqttHost.length > 0 ? { host: mqttHost } : {}),
+        ...(mqttUrl !== undefined && mqttUrl.length > 0 ? { url: mqttUrl } : {}),
+        ...(mqttUsername !== undefined && mqttUsername.length > 0
+          ? { username: mqttUsername }
+          : {}),
+        ...(mqttPassword !== undefined && mqttPassword.length > 0
+          ? { password: mqttPassword }
+          : {}),
+      };
+      if (portOption === undefined && portEnv) {
+        try {
+          portOption = parsePort(portEnv);
+        } catch {
+          throw new ConfigValidationError({
+            message: `Invalid MIRAVO_MQTT_PORT environment variable: "${portEnv}".`,
+            fix: "Set MIRAVO_MQTT_PORT to a valid port number between 1 and 65535 (for example, 1883).",
+          });
+        }
+      }
+      if (mqttHost !== undefined && mqttHost.trim().length === 0) {
+        throw new ConfigValidationError({
+          message: "Invalid MQTT bind host: value is empty.",
+          fix: "Set --mqtt-host / MIRAVO_MQTT_HOST to a valid host (for example, 127.0.0.1 or 0.0.0.0).",
+        });
+      }
+    }
+
+    // OPC UA env overrides — only parsed when OPC UA is enabled
+    let opcuaPort: number | undefined = options.opcuaPort;
+    let opcuaHost: string | undefined;
+    if (opcuaEnabled) {
+      const opcuaPortEnv = Bun.env["MIRAVO_OPCUA_PORT"];
+      if (opcuaPort === undefined && opcuaPortEnv) {
+        try {
+          opcuaPort = parsePort(opcuaPortEnv);
+        } catch {
+          throw new ConfigValidationError({
+            message: `Invalid MIRAVO_OPCUA_PORT environment variable: "${opcuaPortEnv}".`,
+            fix: "Set MIRAVO_OPCUA_PORT to a valid port number between 1 and 65535 (for example, 4840).",
+          });
+        }
+      }
+      opcuaHost = options.opcuaHost ?? Bun.env["MIRAVO_OPCUA_HOST"] ?? undefined;
+      if (opcuaHost !== undefined && opcuaHost.trim().length === 0) {
+        throw new ConfigValidationError({
+          message: "Invalid OPC UA bind host: value is empty.",
+          fix: "Set --opcua-host / MIRAVO_OPCUA_HOST to a valid host (for example, 0.0.0.0).",
+        });
+      }
+    }
+
+    let adminPort = options.adminPort;
+    if (adminPort === undefined && adminPortEnv) {
       try {
-        healthPort = parsePort(healthPortEnv);
+        adminPort = parsePort(adminPortEnv);
       } catch {
         throw new ConfigValidationError({
-          message: `Invalid MIRAVO_HEALTH_PORT environment variable: "${healthPortEnv}".`,
-          fix: "Set MIRAVO_HEALTH_PORT to a valid port number between 1 and 65535 (for example, 8080).",
+          message: `Invalid MIRAVO_ADMIN_PORT environment variable: "${adminPortEnv}".`,
+          fix: "Set MIRAVO_ADMIN_PORT to a valid port number between 1 and 65535 (for example, 8080).",
         });
       }
     }
-    healthPort ??= 8080;
+    adminPort ??= 8080;
 
     // Step 1: Resolve template path
     const templatePath = await resolveTemplatePath(templateOption, catalog);
@@ -241,28 +308,60 @@ async function startAction(options: StartOptions): Promise<void> {
     runtimeLogContextSet = true;
     controlLog.info(`Run ID: ${runId}`);
 
-    // Step 4: Create engine and populate
-    const engine = createAndPopulateEngine(
-      template,
-      models,
+    shutdown = createShutdownController({
       seed,
-      options,
-      templatePath,
-      simulationName,
-    );
+      seedExplicit,
+    });
+    const shutdownRequested = shutdown.waitForShutdownRequest();
+    shutdown.addTask("finalize", "runtime log context", () => {
+      if (runtimeLogContextSet) {
+        clearRuntimeLogContext();
+        runtimeLogContextSet = false;
+      }
+    });
 
-    // Step 5: Start MQTT adapter
-    const mqttStartResult = await startMQTTAdapter(
-      engine,
-      template,
-      portOption,
-      mqttOverrides,
-      simulationName,
-    );
+    // Step 4: Create engine and populate
+    engine = createAndPopulateEngine(template, models, seed, options, templatePath, simulationName);
+    shutdown.setEngine(engine);
+
+    let controlPlane: ControlPlane | null = null;
+    let adminServer: { endpoint: string; stop: () => void } | null = null;
+    let lastTickProgressAt = performance.now();
+    let tickProgressSubscribed = false;
+    const onTickProgress = (): void => {
+      lastTickProgressAt = performance.now();
+    };
+    let unsubscribeEvents = (): void => {};
+    let summaryTimer: ReturnType<typeof setInterval> | null = null;
+
+    stopCliResources = (): void => {
+      controlPlane?.stop();
+      adminServer?.stop();
+      if (summaryTimer !== null) {
+        clearInterval(summaryTimer);
+        summaryTimer = null;
+      }
+      if (tickProgressSubscribed && engine) {
+        engine.bus.off("tick:complete", onTickProgress);
+        tickProgressSubscribed = false;
+      }
+      unsubscribeEvents();
+    };
+
+    shutdown.addTask("cleanup", "CLI resources", stopCliResources);
+
+    // Step 5: Start MQTT adapter (unless --no-mqtt)
+    const mqttStartResult = mqttEnabled
+      ? await startMQTTAdapter(engine, template, portOption, mqttOverrides, simulationName)
+      : null;
     const adapter = mqttStartResult?.adapter ?? null;
 
+    // Step 5a: Start OPC UA adapter (only when --opcua)
+    const opcuaResult = opcuaEnabled
+      ? await startOPCUAAdapter(engine, template, opcuaPort, opcuaHost, simulationName)
+      : null;
+
     // Step 5b: Wire control plane
-    let controlPlane: ControlPlane | null = null;
     if (adapter) {
       const transport = adapter.getControlTransport();
       if (transport) {
@@ -273,33 +372,33 @@ async function startAction(options: StartOptions): Promise<void> {
           bus: engine.bus,
         });
         controlPlane.start();
-        controlLog.info("Control plane active on $miravo/* topics");
+        controlLog.info(`active on $miravo/${simulationName}/* topics`);
       }
     }
 
-    // Step 5c: Start health probe server
-    let healthServer: { endpoint: string; stop: () => void } | null = null;
-    let lastTickProgressAt = Date.now();
-    const onTickProgress = (): void => {
-      lastTickProgressAt = Date.now();
-    };
+    // Step 5c: Start admin HTTP server
     engine.bus.on("tick:complete", onTickProgress);
+    tickProgressSubscribed = true;
     try {
-      healthServer = startHealthServer({
+      adminServer = startAdminServer({
         engine,
-        host: healthHost,
-        port: healthPort,
+        host: adminHost,
+        port: adminPort,
+        tickIntervalMs: engine.getState().config.tickIntervalMs,
         mqttEnabled: adapter !== null,
         isMqttConnected: () => (adapter ? adapter.getMetrics().connected : false),
+        opcuaEnabled: opcuaResult !== null,
+        isOpcuaConnected: () => (opcuaResult ? opcuaResult.adapter.getMetrics().connected : false),
         getLastTickProgressAt: () => lastTickProgressAt,
       });
-      controlLog.info(`Health server active on ${healthServer.endpoint}`);
+      controlLog.info(`admin server ready · endpoint: ${colors.cyan(adminServer.endpoint)}`);
     } catch (error) {
+      tickProgressSubscribed = false;
       engine.bus.off("tick:complete", onTickProgress);
       const message = error instanceof Error ? error.message : String(error);
       throw new MiravoError(
-        `Health server failed to start on ${healthHost}:${healthPort}: ${message}`,
-        "Set --health-port / MIRAVO_HEALTH_PORT to a free port, or change --health-host.",
+        `Admin server failed to start on ${adminHost}:${adminPort}: ${message}`,
+        "Set --admin-port / MIRAVO_ADMIN_PORT to a free port, or change --admin-host.",
       );
     }
 
@@ -310,49 +409,38 @@ async function startAction(options: StartOptions): Promise<void> {
       seed,
       seedExplicit,
       mqttStartResult?.endpoint ?? null,
+      opcuaResult?.endpoint ?? null,
       simulationName,
       runId,
-      healthServer.endpoint,
+      adminServer.endpoint,
     );
 
     // Step 7: Subscribe to events + periodic summary
     const errorContextCounts = new Map<string, number>();
-    const unsubscribeEvents = subscribeToEvents(engine, errorContextCounts);
+    unsubscribeEvents = subscribeToEvents(engine, errorContextCounts);
+    shutdown.setErrorContextCounts(errorContextCounts);
     const summaryInterval = options.summaryInterval ?? 5;
-    const summaryTimer = startPeriodicSummary(engine, summaryInterval);
+    summaryTimer = startPeriodicSummary(engine, summaryInterval);
 
-    // Step 8: Install shutdown handler and start
-    const teardownShutdown = installShutdownHandlers({
-      engine,
-      seed,
-      seedExplicit,
-      cleanup: () => {
-        controlPlane?.stop();
-        healthServer?.stop();
-        engine.bus.off("tick:complete", onTickProgress);
-        clearInterval(summaryTimer);
-        unsubscribeEvents();
-        clearRuntimeLogContext();
-        runtimeLogContextSet = false;
-      },
-      errorContextCounts,
-    });
-
-    try {
-      engine.start();
-    } catch (error) {
-      teardownShutdown();
-      controlPlane?.stop();
-      healthServer?.stop();
-      engine.bus.off("tick:complete", onTickProgress);
-      clearInterval(summaryTimer);
-      unsubscribeEvents();
-      clearRuntimeLogContext();
-      runtimeLogContextSet = false;
-      throw error;
-    }
+    engine.start();
+    shutdown.markRunning();
     engineLog.success("Simulation started.");
+    await shutdownRequested;
+    await shutdown.runShutdown();
+    shutdown.teardown();
   } catch (error) {
+    if (shutdown?.isShuttingDown()) {
+      await shutdown.runShutdown();
+      shutdown.teardown();
+      return;
+    }
+    shutdown?.teardown();
+    stopCliResources();
+    try {
+      await engine?.stop("boot error");
+    } catch {
+      // engine may not exist yet or stop may fail — swallow
+    }
     if (runtimeLogContextSet) {
       clearRuntimeLogContext();
       runtimeLogContextSet = false;
@@ -404,9 +492,11 @@ async function resolveTemplatePath(
   const builtinTemplateDir = catalog.getBuiltinTemplatesDir();
   let builtinTemplates: readonly DiscoveredTemplate[] = [];
   try {
-    builtinTemplates = await discoverTemplates(builtinTemplateDir);
+    const discovered = await discoverTemplates(builtinTemplateDir);
+    // Exclude stress/benchmark templates from built-in list (same as standalone binaries).
+    builtinTemplates = discovered.filter((t) => !isStressBenchmarkTemplate(t.id));
   } catch {
-    // Builtin dir may not exist (e.g. MIRAVO_BUILTIN_DIR pointing to a missing path)
+    // Builtin dir may not exist in edge cases (e.g. standalone binary extraction failure)
   }
   if (builtinTemplates.length > 0) {
     if (process.stdout.isTTY && process.stdin.isTTY) {
@@ -495,7 +585,7 @@ async function loadAndValidateTemplate(
   catalog: ContentCatalog,
 ): Promise<{
   template: MiravoTemplate;
-  models: Map<string, DigitalTwinModel>;
+  models: Map<string, TwinModel>;
   seed: number;
   seedExplicit: boolean;
 }> {
@@ -528,13 +618,10 @@ async function loadAndValidateTemplate(
   }
 
   // Build inline models map
-  const models = new Map<string, DigitalTwinModel>();
+  const models = new Map<string, TwinModel>();
   if (template.models) {
     for (const inlineModel of template.models) {
-      models.set(inlineModel.name, {
-        ...inlineModel,
-        version: inlineModel.version ?? "1",
-      });
+      models.set(inlineModel.model.name, inlineModel);
     }
   }
 
@@ -605,7 +692,7 @@ export function resolveSimulationName(input: {
 
 function createAndPopulateEngine(
   template: MiravoTemplate,
-  models: Map<string, DigitalTwinModel>,
+  models: Map<string, TwinModel>,
   seed: number,
   options: StartOptions,
   templatePath: string,
@@ -728,7 +815,9 @@ async function startMQTTAdapter(
   }
 
   const endpoint = embedded ? `mqtt://localhost:${port}` : (external as string);
-  mqttLog.debug(`Starting MQTT adapter on ${endpoint}`);
+  mqttLog.debug(
+    `starting adapter · mode: ${embedded ? "embedded" : "external"} · endpoint: ${endpoint}`,
+  );
 
   const adapter = new MQTTAdapter(engine.bus);
   try {
@@ -745,24 +834,69 @@ async function startMQTTAdapter(
       ...(password !== undefined ? { password } : {}),
       ...(mqttConfig?.reconnect !== undefined ? { reconnect: mqttConfig.reconnect } : {}),
       ...(mqttConfig?.rbe !== undefined ? { rbe: mqttConfig.rbe } : {}),
+      ...(mqttConfig?.metadata !== undefined ? { metadata: mqttConfig.metadata } : {}),
     };
 
-    await adapter.start({
-      ...resolvedConfig,
-    });
+    await adapter.start(resolvedConfig);
     engine.registerAdapter(adapter);
-    mqttLog.ready(`MQTT connected: ${colors.cyan(endpoint)}`);
+    mqttLog.ready(`connected · broker: ${colors.cyan(endpoint)}`);
     return { adapter, endpoint };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const isPortConflict = message.includes("EADDRINUSE") || message.includes("in use");
     const fix = isPortConflict
-      ? `Port ${port} is in use. Use '--port ${port + 1}' or set protocols.mqtt.port in template.`
+      ? `Port ${port} is in use. Use '--mqtt-port ${port + 1}' or set protocols.mqtt.port in template.`
       : "Check the MQTT configuration in your template file.";
     throw new MiravoError(`MQTT adapter failed to start: ${message}`, fix);
   }
 }
 
+// ---------------------------------------------------------------------------
+// Step 5a: OPC UA adapter
+// ---------------------------------------------------------------------------
+
+async function startOPCUAAdapter(
+  engine: Engine,
+  template: MiravoTemplate,
+  portOverride: number | undefined,
+  hostOverride: string | undefined,
+  simulationName: string,
+): Promise<{ adapter: OPCUAAdapter; endpoint: string } | null> {
+  const opcuaConfig = template.protocols?.opcua;
+
+  const port = portOverride ?? opcuaConfig?.port ?? DEFAULT_OPCUA_PORT;
+  const host = hostOverride ?? opcuaConfig?.host ?? "0.0.0.0";
+
+  opcuaLog.debug(`starting adapter · endpoint: opc.tcp://${host}:${port}`);
+
+  const opcuaAdapter = new OPCUAAdapter(engine.bus, engine);
+  try {
+    const resolvedConfig = {
+      name: "opcua" as const,
+      enabled: true,
+      port,
+      host,
+      security: opcuaConfig?.security ?? "none",
+      simulationName,
+      ...(opcuaConfig?.buildInfo ? { buildInfo: opcuaConfig.buildInfo } : {}),
+    };
+
+    await opcuaAdapter.start(resolvedConfig);
+    engine.registerAdapter(opcuaAdapter);
+
+    const endpoint = `opc.tcp://${host === "0.0.0.0" ? "localhost" : host}:${port}`;
+    opcuaLog.ready(`server ready · endpoint: ${colors.cyan(endpoint)}`);
+    return { adapter: opcuaAdapter, endpoint };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const isPortConflict = message.includes("EADDRINUSE") || message.includes("in use");
+    const fix = isPortConflict
+      ? `Port ${port} is in use. Use '--opcua-port ${port + 1}'.`
+      : "Check the OPC UA port/network settings and retry.";
+    throw new MiravoError(`OPC UA adapter failed to start: ${message}`, fix);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Step 6: Startup banner
 // ---------------------------------------------------------------------------
@@ -773,32 +907,55 @@ function printStartupBanner(
   seed: number,
   seedExplicit: boolean,
   mqttEndpoint: string | null,
+  opcuaEndpoint: string | null,
   simulationName: string,
   runId: string,
-  healthEndpoint: string,
+  adminEndpoint: string,
 ): void {
   const state = engine.getState();
-  const modelSummary =
-    state.models
-      .map((m) => `${colors.bold(m.name)} ${colors.dim(`(${m.sensorCount} sensors)`)}`)
-      .join(", ") || colors.dim("(none)");
+
+  // Build model summary: one model per line for readability
+  const modelLines = state.models.map(
+    (m) => `${colors.bold(m.name)} ${colors.dim(`(${m.memberCount} members)`)}`,
+  );
+  const modelCount = `${colors.bold(String(state.models.length))} ${colors.dim("models")}`;
 
   const seedValue = seedExplicit
     ? colors.bold(String(seed))
     : `${colors.bold(String(seed))} ${colors.gray("(random — add seed to config to reproduce)")}`;
 
-  const content = formatKeyValue([
+  const mqttValue = mqttEndpoint ? colors.cyan(mqttEndpoint) : colors.dim("disabled");
+  const opcuaValue = opcuaEndpoint ? colors.cyan(opcuaEndpoint) : colors.dim("disabled");
+
+  const allEntries: ReadonlyArray<readonly [string, string]> = [
     [colors.dim("Simulation"), colors.bold(simulationName)],
     [colors.dim("Run ID"), colors.bold(runId)],
     [colors.dim("Template"), templatePath],
-    [colors.dim("Models"), modelSummary],
+    [colors.dim("Models"), modelCount],
     [colors.dim("Instances"), colors.bold(String(state.instances.length))],
-    [colors.dim("MQTT"), mqttEndpoint ? colors.cyan(mqttEndpoint) : colors.dim("disabled")],
-    [colors.dim("Health"), colors.cyan(`${healthEndpoint}/healthz`)],
+    [colors.dim("MQTT"), mqttValue],
+    [colors.dim("OPC UA"), opcuaValue],
+    [colors.dim("Admin"), colors.cyan(adminEndpoint)],
     [colors.dim("Tick interval"), colors.bold(`${state.config.tickIntervalMs}ms`)],
     [colors.dim("Time multiplier"), colors.bold(`${state.config.timeMultiplier}x`)],
     [colors.dim("Seed"), seedValue],
-  ]);
+  ];
+
+  const kvBlock = formatKeyValue(allEntries);
+
+  // Compute the value column offset used by formatKeyValue so model detail
+  // lines align with the value of the "Models" row.
+  const maxKeyWidth = Math.max(...allEntries.map(([key]) => stripAnsi(key).length));
+  const valueIndent = 4 + maxKeyWidth + 3; // "    " + key + ":" + padding(2) + " "
+
+  // Inject per-model detail lines right after the "Models" row
+  const kvLines = kvBlock.split("\n");
+  const modelsIdx = kvLines.findIndex((line) => stripAnsi(line).includes("Models:"));
+  if (modelsIdx !== -1 && modelLines.length > 0) {
+    const detailLines = modelLines.map((line) => `${"".padEnd(valueIndent)}${line}`);
+    kvLines.splice(modelsIdx + 1, 0, ...detailLines);
+  }
+  const content = kvLines.join("\n");
 
   const header = `${colors.cyan(colors.bold("Miravo"))} ${colors.dim(`v${MIRAVO_VERSION}`)}`;
 
@@ -856,7 +1013,11 @@ function subscribeToEvents(engine: Engine, errorContextCounts: Map<string, numbe
   };
 
   const onFaultCleared = (event: { instanceId: string; fault: string }): void => {
-    faultLog.success(`${event.instanceId} ${event.fault} cleared`);
+    faultLog.debug(`${event.instanceId} ${event.fault} cleared`);
+  };
+
+  const onWarn = (event: { message: string; context: string }): void => {
+    engineLog.debug(event.message, { context: event.context });
   };
 
   const onError = (event: { context: string; error: Error }): void => {
@@ -875,12 +1036,14 @@ function subscribeToEvents(engine: Engine, errorContextCounts: Map<string, numbe
   engine.bus.on("lifecycle:changed", onLifecycle);
   engine.bus.on("fault:triggered", onFaultTriggered);
   engine.bus.on("fault:cleared", onFaultCleared);
+  engine.bus.on("engine:warn", onWarn);
   engine.bus.on("engine:error", onError);
 
   return () => {
     engine.bus.off("lifecycle:changed", onLifecycle);
     engine.bus.off("fault:triggered", onFaultTriggered);
     engine.bus.off("fault:cleared", onFaultCleared);
+    engine.bus.off("engine:warn", onWarn);
     engine.bus.off("engine:error", onError);
   };
 }
@@ -913,29 +1076,7 @@ function startPeriodicSummary(
 ): ReturnType<typeof setInterval> {
   return setInterval(() => {
     const metrics = engine.getMetrics();
-    const { core } = metrics;
-    const mqttAdapter = metrics.adapters.find((a) => a.name === "mqtt");
-
-    const sep = colors.dim(" · ");
-
-    let mqttStatus: string;
-    if (mqttAdapter) {
-      const errCount = mqttAdapter.metrics.errorsCount;
-      const errStr =
-        errCount === 0 ? colors.green(formatCount(errCount)) : colors.yellow(formatCount(errCount));
-      mqttStatus = `MQTT: ${colors.bold(formatCount(mqttAdapter.metrics.messagesPublished))} published${sep}${errStr} errors`;
-    } else {
-      mqttStatus = colors.dim("MQTT: not connected");
-    }
-
-    const tps =
-      core.actualTicksPerSecond > 0
-        ? `${colors.bold(core.actualTicksPerSecond.toFixed(1))} tps`
-        : "";
-
-    engineLog.info(
-      `tick #${colors.bold(formatCount(core.tickCount))}${sep}${colors.bold(formatCount(core.instanceCount))} instances${sep}${colors.bold(formatCount(core.unsEntryCount))} UNS topics${sep}sim: ${colors.bold(core.simulationTimeSeconds.toFixed(1))}s${sep}${tps}${tps ? sep : ""}${mqttStatus}`,
-    );
+    printSummaryLine(metrics);
   }, intervalSeconds * 1_000);
 }
 
@@ -945,7 +1086,7 @@ function startPeriodicSummary(
 
 function printDryRunSummary(
   template: MiravoTemplate,
-  models: Map<string, DigitalTwinModel>,
+  models: Map<string, TwinModel>,
   seed: number,
   seedExplicit: boolean,
   templatePath: string,
@@ -967,8 +1108,8 @@ function printDryRunSummary(
 
   // Model table
   const modelRows = [...models.values()].map((m) => ({
-    name: colors.cyan(m.name),
-    sensors: String(m.sensors.length),
+    name: colors.cyan(m.model.name),
+    members: String(Object.keys(m.members).length),
     faults: String(m.faults?.length ?? 0),
     lifecycle: m.lifecycle ? `${m.lifecycle.stages.length} stages` : colors.dim("none"),
   }));
@@ -980,7 +1121,7 @@ function printDryRunSummary(
       formatTable(
         {
           name: colors.dim("Name"),
-          sensors: colors.dim("Sensors"),
+          members: colors.dim("Members"),
           faults: colors.dim("Faults"),
           lifecycle: colors.dim("Lifecycle"),
         },
@@ -991,14 +1132,14 @@ function printDryRunSummary(
 
   // Instance summary
   let totalInstances = 0;
-  let totalSensors = 0;
+  let totalMembers = 0;
   for (const area of template.areas) {
     for (const line of area.lines) {
       for (const twin of line.twins) {
         totalInstances += twin.count;
         const model = models.get(twin.model);
         if (model) {
-          totalSensors += twin.count * model.sensors.length;
+          totalMembers += twin.count * Object.keys(model.members).length;
         }
       }
     }
@@ -1008,8 +1149,7 @@ function printDryRunSummary(
   lines.push(
     formatKeyValue([
       [colors.dim("Total instances"), colors.bold(String(totalInstances))],
-      [colors.dim("Total sensors"), colors.bold(String(totalSensors))],
-      [colors.dim("Total UNS paths"), colors.bold(String(totalSensors))],
+      [colors.dim("Total members"), colors.bold(String(totalMembers))],
     ]),
   );