miravo 0.1.4 → 0.2.0

package/src/__tests__/integration/executable-methods.integration.ts

@@ -0,0 +1,1688 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  type CommandResult,
+  controlTopicCmd,
+  controlTopicCmdResult,
+  EngineMetricsSnapshotSchema,
+  EngineStateSnapshotSchema,
+  type TwinModel,
+} from "@miravo/shared";
+import type { MqttClient } from "mqtt";
+import { connect } from "mqtt";
+import {
+  type ClientSession,
+  MessageSecurityMode,
+  OPCUAClient,
+  SecurityPolicy,
+} from "node-opcua-client";
+import { DataType } from "node-opcua-variant";
+import { stringify as stringifyYAML } from "yaml";
+
+interface MQTTMessageRecord {
+  readonly topic: string;
+  readonly raw: string;
+  readonly parsed: unknown;
+}
+
+interface SmokeRuntimeReady {
+  readonly simulationName: string;
+  readonly adminUrl: string;
+  readonly mqttBrokerUrl: string;
+  readonly opcuaEndpointUrl: string;
+  readonly instanceId: string;
+  readonly instancePath: string;
+}
+
+interface SmokeRuntimeHandle {
+  readonly process: Bun.Subprocess<"ignore", "pipe", "pipe">;
+  readonly tmpDir: string;
+  readonly ready: SmokeRuntimeReady;
+}
+
+interface InvokeMethodCommandPayload {
+  readonly type: "invokeMethod";
+  readonly instanceId: string;
+  readonly method: string;
+  readonly arguments?: Readonly<Record<string, number | string | boolean>> | undefined;
+}
+
+interface AdminHealthPayload {
+  readonly status: "ok" | "fail";
+  readonly simulationState: string;
+  readonly tickCount: number;
+  readonly stalled: boolean;
+  readonly reason?: string;
+}
+
+function createSmokePumpModel(): TwinModel {
+  return {
+    schema_version: "2",
+    model: {
+      name: "method-smoke-pump",
+      namespace: "com.miravo.testing.method-smoke-pump",
+      description: "Deterministic smoke-test pump for executable method transport validation.",
+    },
+    parameters: {
+      target_value: {
+        type: "float",
+        default: 5,
+        min: 0,
+        max: 100,
+        unit: "bar",
+      },
+    },
+    methods: {
+      Start: {
+        description: "Start the smoke-test pump.",
+        runtime: {
+          type: "set-members",
+          writes: [
+            { member: "run_command", value: true },
+            { member: "speed_command", value: 1200 },
+          ],
+        },
+        output_arguments: {
+          accepted: {
+            data_type: "Boolean",
+          },
+        },
+      },
+      Stop: {
+        description: "Stop the smoke-test pump.",
+        runtime: {
+          type: "set-members",
+          writes: [
+            { member: "run_command", value: false },
+            { member: "speed_command", value: 0 },
+          ],
+        },
+        output_arguments: {
+          accepted: {
+            data_type: "Boolean",
+          },
+        },
+      },
+      SetSpeed: {
+        description: "Set the pump speed command.",
+        input_arguments: {
+          speed_rpm: {
+            data_type: "Double",
+            unit: "rpm",
+          },
+        },
+        runtime: {
+          type: "set-members",
+          writes: [{ member: "speed_command", argument: "speed_rpm" }],
+        },
+        output_arguments: {
+          accepted: {
+            data_type: "Boolean",
+          },
+        },
+      },
+      SetTarget: {
+        description: "Set the parameter echo value.",
+        input_arguments: {
+          target_value: {
+            data_type: "Double",
+            unit: "bar",
+          },
+        },
+        runtime: {
+          type: "set-parameters",
+          writes: [{ parameter: "target_value", argument: "target_value" }],
+        },
+        output_arguments: {
+          accepted: {
+            data_type: "Boolean",
+          },
+        },
+      },
+      ResetFault: {
+        description: "Reset active smoke-test pump faults.",
+        runtime: {
+          type: "clear-faults",
+        },
+        output_arguments: {
+          accepted: {
+            data_type: "Boolean",
+          },
+        },
+      },
+    },
+    members: {
+      manufacturer: {
+        kind: "property",
+        data_type: "String",
+        access: "read",
+        default: "Miravo Labs",
+      },
+      serial_number: {
+        kind: "property",
+        data_type: "String",
+        access: "read",
+        default: "SMOKE-001",
+      },
+      run_command: {
+        kind: "variable",
+        data_type: "Boolean",
+        access: "readwrite",
+        default: false,
+      },
+      speed_command: {
+        kind: "variable",
+        data_type: "Double",
+        access: "readwrite",
+        unit: "rpm",
+        default: 0,
+      },
+      speed_feedback: {
+        kind: "variable",
+        data_type: "Double",
+        access: "read",
+        unit: "rpm",
+        generator: {
+          type: "gate",
+          enabled_member: "run_command",
+          disabled_value: 0,
+          input: { member: "speed_command" },
+        },
+      },
+      flow_rate: {
+        kind: "variable",
+        data_type: "Double",
+        access: "read",
+        unit: "m3/h",
+        generator: {
+          type: "correlated",
+          source: "speed_feedback",
+          factor: 0.02,
+          offset: 0,
+        },
+      },
+      parameter_echo: {
+        kind: "variable",
+        data_type: "Double",
+        access: "read",
+        unit: "bar",
+        generator: {
+          type: "weighted-sum",
+          bias: 0,
+          terms: [
+            {
+              weight: 1,
+              input: { param: "target_value" },
+            },
+          ],
+          min: 0,
+          max: 100,
+        },
+      },
+      running: {
+        kind: "variable",
+        data_type: "Boolean",
+        access: "read",
+        binding: {
+          type: "threshold",
+          member: "speed_feedback",
+          operator: ">",
+          threshold: 1,
+        },
+        default: false,
+      },
+      fault_active: {
+        kind: "variable",
+        data_type: "Boolean",
+        access: "read",
+        binding: {
+          type: "fault-active",
+        },
+        default: false,
+      },
+      fault_count: {
+        kind: "variable",
+        data_type: "UInt16",
+        access: "read",
+        unit: "count",
+        binding: {
+          type: "fault-count",
+        },
+        default: 0,
+      },
+      active_fault_code: {
+        kind: "variable",
+        data_type: "String",
+        access: "read",
+        enum_values: ["none", "trip"],
+        binding: {
+          type: "active-fault-code",
+          fallback: "none",
+        },
+        default: "none",
+      },
+      availability_state: {
+        kind: "variable",
+        data_type: "String",
+        access: "read",
+        enum_values: ["stopped", "running", "faulted"],
+        binding: {
+          type: "availability-state",
+          member: "speed_feedback",
+          operator: ">",
+          threshold: 1,
+          running_state: "running",
+          stopped_state: "stopped",
+          faulted_state: "faulted",
+        },
+        default: "stopped",
+      },
+    },
+    faults: [
+      {
+        name: "trip",
+        trigger: {
+          probability: 0,
+        },
+        effects: {
+          speed_feedback: {
+            offset: -100,
+          },
+        },
+      },
+    ],
+  };
+}
+
+function createLifecycleTestModel(): TwinModel {
+  return {
+    schema_version: "2",
+    model: {
+      name: "lifecycle-test-pump",
+      namespace: "com.miravo.testing.lifecycle-test",
+      description: "Deterministic pump for lifecycle effects integration testing.",
+    },
+    parameters: {
+      baseline_pressure: {
+        type: "float",
+        default: 100,
+        min: 0,
+        max: 200,
+        unit: "bar",
+      },
+    },
+    lifecycle: {
+      stages: [
+        {
+          name: "healthy",
+          duration_hours: [3.0, 3.0],
+          effects: {},
+        },
+        {
+          name: "degraded",
+          duration_hours: [1.5, 1.5],
+          effects: {
+            pressure: { multiplier: 0.8, offset: -5 },
+          },
+        },
+        {
+          name: "critical",
+          duration_hours: [10000, 10000],
+          effects: {
+            pressure: { multiplier: 0.5, offset: -20 },
+          },
+        },
+      ],
+    },
+    methods: {},
+    members: {
+      pressure: {
+        kind: "variable",
+        data_type: "Double",
+        access: "read",
+        unit: "bar",
+        generator: {
+          type: "weighted-sum",
+          bias: 0,
+          terms: [{ weight: 1, input: { param: "baseline_pressure" } }],
+          min: 0,
+          max: 200,
+        },
+      },
+    },
+    faults: [],
+  };
+}
+
+function createConditionalFaultTestModel(): TwinModel {
+  return {
+    schema_version: "2",
+    model: {
+      name: "fault-test-pump",
+      namespace: "com.miravo.testing.fault-test",
+      description: "Deterministic pump for conditional fault integration testing.",
+    },
+    parameters: {},
+    methods: {
+      SetSpeed: {
+        description: "Set the speed command.",
+        input_arguments: {
+          speed: { data_type: "Double", unit: "rpm" },
+        },
+        runtime: {
+          type: "set-members",
+          writes: [{ member: "speed_command", argument: "speed" }],
+        },
+        output_arguments: {
+          accepted: { data_type: "Boolean" },
+        },
+      },
+      ResetFault: {
+        description: "Clear active faults.",
+        runtime: { type: "clear-faults" },
+        output_arguments: {
+          accepted: { data_type: "Boolean" },
+        },
+      },
+    },
+    members: {
+      speed_command: {
+        kind: "variable",
+        data_type: "Double",
+        access: "readwrite",
+        unit: "rpm",
+        default: 0,
+      },
+      pressure: {
+        kind: "variable",
+        data_type: "Double",
+        access: "read",
+        unit: "bar",
+        generator: {
+          type: "correlated",
+          source: "speed_command",
+          factor: 0.1,
+          offset: 0,
+        },
+      },
+      fault_active: {
+        kind: "variable",
+        data_type: "Boolean",
+        access: "read",
+        binding: { type: "fault-active" },
+        default: false,
+      },
+      fault_count: {
+        kind: "variable",
+        data_type: "UInt16",
+        access: "read",
+        unit: "count",
+        binding: { type: "fault-count" },
+        default: 0,
+      },
+    },
+    faults: [
+      {
+        name: "overpressure",
+        trigger: {
+          condition: "pressure > 80",
+          probability: 1,
+        },
+        effects: {
+          pressure: { multiplier: 0.5 },
+        },
+      },
+    ],
+  };
+}
+
+async function waitFor<T>(label: string, read: () => T | undefined, timeoutMs = 5000): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = read();
+    if (value !== undefined) {
+      return value;
+    }
+    await Bun.sleep(20);
+  }
+  throw new Error(`Timed out waiting for ${label}.`);
+}
+
+async function waitForAsync<T>(
+  label: string,
+  read: () => Promise<T | undefined>,
+  timeoutMs = 5000,
+): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await read();
+    if (value !== undefined) {
+      return value;
+    }
+    await Bun.sleep(20);
+  }
+  throw new Error(`Timed out waiting for ${label}.`);
+}
+
+async function readAdminJson<T>(
+  runtime: SmokeRuntimeHandle,
+  path: string,
+  schema: {
+    safeParse(value: unknown): { success: boolean; data?: T };
+  },
+): Promise<T> {
+  const response = await fetch(new URL(path, `${runtime.ready.adminUrl}/`));
+  if (!response.ok) {
+    throw new Error(`Admin request ${path} failed with HTTP ${response.status}.`);
+  }
+  const payload = (await response.json()) as unknown;
+  const parsed = schema.safeParse(payload);
+  if (!parsed.success || parsed.data === undefined) {
+    throw new Error(`Admin request ${path} returned an unexpected payload.`);
+  }
+  return parsed.data;
+}
+
+async function readAdminHealth(runtime: SmokeRuntimeHandle, path: "/healthz" | "/readyz") {
+  const response = await fetch(new URL(path, `${runtime.ready.adminUrl}/`));
+  const payload = (await response.json()) as AdminHealthPayload;
+  return { response, payload };
+}
+
+async function postAdminCommand(
+  runtime: SmokeRuntimeHandle,
+  payload: Readonly<Record<string, unknown>>,
+): Promise<CommandResult> {
+  const response = await fetch(new URL("/commands", `${runtime.ready.adminUrl}/`), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Admin command failed with HTTP ${response.status}: ${text}`);
+  }
+  return (await response.json()) as CommandResult;
+}
+
+async function waitForAdminMetricsState(
+  runtime: SmokeRuntimeHandle,
+  expectedState: "running" | "paused" | "stopped",
+) {
+  return waitForAsync(`admin metrics state ${expectedState}`, async () => {
+    const metrics = await readAdminJson(runtime, "/metrics", EngineMetricsSnapshotSchema);
+    return metrics.core.state === expectedState ? metrics : undefined;
+  });
+}
+
+async function waitForAdminInstanceCount(runtime: SmokeRuntimeHandle, expectedCount: number) {
+  return waitForAsync(`admin instance count ${expectedCount}`, async () => {
+    const state = await readAdminJson(runtime, "/state", EngineStateSnapshotSchema);
+    return state.instances.length === expectedCount ? state : undefined;
+  });
+}
+
+function readPayloadValue(payload: unknown): number | string | boolean | undefined {
+  if (typeof payload !== "object" || payload === null) {
+    return undefined;
+  }
+  if (!("value" in payload)) {
+    return undefined;
+  }
+  const value = (payload as { readonly value?: unknown }).value;
+  return typeof value === "number" || typeof value === "string" || typeof value === "boolean"
+    ? value
+    : undefined;
+}
+
+function readPayloadQuality(payload: unknown): string | undefined {
+  if (typeof payload !== "object" || payload === null) {
+    return undefined;
+  }
+  if (!("quality" in payload)) {
+    return undefined;
+  }
+  const quality = (payload as { readonly quality?: unknown }).quality;
+  return typeof quality === "string" ? quality : undefined;
+}
+
+async function waitForMQTTConnect(client: MqttClient, timeoutMs = 5000): Promise<void> {
+  if (client.connected) {
+    return;
+  }
+
+  await new Promise<void>((resolvePromise, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error(`MQTT client did not connect within ${timeoutMs}ms.`));
+    }, timeoutMs);
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      client.off("connect", onConnect);
+      client.off("error", onError);
+    };
+
+    const onConnect = () => {
+      cleanup();
+      resolvePromise();
+    };
+
+    const onError = (error: Error) => {
+      cleanup();
+      reject(error);
+    };
+
+    client.once("connect", onConnect);
+    client.once("error", onError);
+  });
+}
+
+async function stopMQTTClient(client: MqttClient): Promise<void> {
+  await new Promise<void>((resolvePromise) => {
+    client.end(true, {}, () => resolvePromise());
+  });
+}
+
+async function subscribeMQTT(client: MqttClient, topics: readonly string[]): Promise<void> {
+  await new Promise<void>((resolvePromise, reject) => {
+    client.subscribe([...topics], (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolvePromise();
+    });
+  });
+}
+
+function createMQTTRecorder(client: MqttClient) {
+  const messages: MQTTMessageRecord[] = [];
+  const latestByTopic = new Map<string, MQTTMessageRecord>();
+  const onMessage = (topic: string, payload: Buffer) => {
+    const raw = payload.toString();
+    let parsed: unknown = raw;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      // Keep raw payload when it is not JSON.
+    }
+    const record = { topic, raw, parsed };
+    messages.push(record);
+    latestByTopic.set(topic, record);
+  };
+  client.on("message", onMessage);
+  return {
+    messages,
+    latestByTopic,
+    dispose() {
+      client.off("message", onMessage);
+    },
+  };
+}
+
+async function publishControlCommand(
+  client: MqttClient,
+  recorder: ReturnType<typeof createMQTTRecorder>,
+  simulationName: string,
+  payload: Readonly<Record<string, unknown>>,
+): Promise<CommandResult> {
+  const correlationId = crypto.randomUUID();
+  const commandTopic = controlTopicCmd(simulationName);
+  const resultTopic = controlTopicCmdResult(simulationName);
+  client.publish(
+    commandTopic,
+    JSON.stringify({
+      correlationId,
+      ...payload,
+    }),
+  );
+
+  return waitFor(`MQTT command result for ${String(payload["type"])}`, () => {
+    const result = recorder.messages
+      .filter((message) => message.topic === resultTopic)
+      .map((message) => message.parsed)
+      .find((parsed): parsed is CommandResult => {
+        if (typeof parsed !== "object" || parsed === null) {
+          return false;
+        }
+        return (parsed as { readonly correlationId?: string }).correlationId === correlationId;
+      });
+    return result;
+  });
+}
+
+async function waitForMQTTTopicValue(
+  recorder: ReturnType<typeof createMQTTRecorder>,
+  topic: string,
+  expected?: number | string | boolean,
+): Promise<number | string | boolean> {
+  return waitFor(`MQTT topic ${topic}`, () => {
+    const payload = recorder.latestByTopic.get(topic)?.parsed;
+    const value = readPayloadValue(payload);
+    if (value === undefined) {
+      return undefined;
+    }
+    return expected === undefined || value === expected ? value : undefined;
+  });
+}
+
+async function waitForMQTTTopicQuality(
+  recorder: ReturnType<typeof createMQTTRecorder>,
+  topic: string,
+  expected: string,
+): Promise<string> {
+  return waitFor(`MQTT topic ${topic} quality=${expected}`, () => {
+    const record = recorder.latestByTopic.get(topic);
+    if (!record) {
+      return undefined;
+    }
+    const quality = readPayloadQuality(record.parsed);
+    return quality === expected ? quality : undefined;
+  });
+}
+
+async function waitForOPCUAValue<T extends number | string | boolean>(
+  session: ClientSession,
+  nodeId: string,
+  expected?: T,
+): Promise<T> {
+  return waitForAsync(`OPC UA value ${nodeId}`, async () => {
+    const dataValue = await session.readVariableValue(nodeId);
+    const value = dataValue.value.value;
+    if (typeof value !== "number" && typeof value !== "string" && typeof value !== "boolean") {
+      return undefined;
+    }
+    return expected === undefined || value === expected ? (value as T) : undefined;
+  });
+}
+
+async function callOPCUAMethod(
+  session: ClientSession,
+  objectPath: string,
+  methodName: string,
+  inputArguments: Array<{
+    readonly dataType: DataType;
+    readonly value: number | string | boolean;
+  }> = [],
+): Promise<void> {
+  const result = await callOPCUAMethodResult(session, objectPath, methodName, inputArguments);
+  expect(result.statusCode.isGood()).toBe(true);
+  expect(result.outputArguments?.[0]?.value).toBe(true);
+}
+
+async function callOPCUAMethodResult(
+  session: ClientSession,
+  objectPath: string,
+  methodName: string,
+  inputArguments: Array<{
+    readonly dataType: DataType;
+    readonly value: number | string | boolean;
+  }> = [],
+) {
+  const result = await session.call({
+    objectId: `ns=1;s=${objectPath}`,
+    methodId: `ns=1;s=${objectPath}/${methodName}`,
+    inputArguments,
+  });
+  return result;
+}
+
+async function collectProcessOutput(
+  process: SmokeRuntimeHandle["process"],
+): Promise<{ readonly stdout: string; readonly stderr: string }> {
+  const stdout = process.stdout ? await new Response(process.stdout).text() : "";
+  const stderr = process.stderr ? await new Response(process.stderr).text() : "";
+  return { stdout, stderr };
+}
+
+interface SmokeRuntimeOptions {
+  readonly model?: TwinModel;
+  readonly namespacePrefix?: string;
+  readonly templateSettings?: {
+    readonly tick_interval_ms?: number;
+    readonly time_multiplier?: number;
+    readonly seed?: number;
+  };
+  readonly rbe?: {
+    readonly enabled: boolean;
+    readonly deadband: number;
+  };
+}
+
+async function createSmokeRuntime(options?: SmokeRuntimeOptions): Promise<SmokeRuntimeHandle> {
+  const model = options?.model ?? createSmokePumpModel();
+  const prefix = options?.namespacePrefix ?? "method-smoke";
+  const tickIntervalMs = options?.templateSettings?.tick_interval_ms ?? 100;
+  const timeMultiplier = options?.templateSettings?.time_multiplier ?? 1;
+  const seed = options?.templateSettings?.seed ?? 42;
+
+  const tmpDir = await mkdtemp(join(tmpdir(), `miravo-${prefix}-`));
+  const modelsDir = join(tmpDir, "models");
+  const templatePath = join(tmpDir, `${prefix}.miravo.yaml`);
+  const modelPath = join(modelsDir, `${model.model.name}.twin.yaml`);
+  const readyFile = join(tmpDir, "ready.json");
+
+  await mkdir(modelsDir, { recursive: true });
+  await Bun.write(modelPath, stringifyYAML(model));
+  await Bun.write(
+    templatePath,
+    stringifyYAML({
+      kind: "MiravoTemplate",
+      version: "1",
+      name: `${prefix} Template`,
+      namespace: {
+        prefix,
+      },
+      areas: [
+        {
+          name: "validation",
+          lines: [
+            {
+              name: "protocols",
+              twins: [
+                {
+                  model: model.model.name,
+                  count: 1,
+                  variation: 0,
+                },
+              ],
+            },
+          ],
+        },
+      ],
+      settings: {
+        seed,
+        tick_interval_ms: tickIntervalMs,
+        time_multiplier: timeMultiplier,
+      },
+    }),
+  );
+
+  const cmd = [
+    "bun",
+    "run",
+    resolve(import.meta.dir, "executable-methods-runner.ts"),
+    "--template",
+    templatePath,
+    "--models-dir",
+    modelsDir,
+    "--ready-file",
+    readyFile,
+  ];
+  if (options?.rbe?.enabled) {
+    cmd.push("--rbe-enabled", "true", "--rbe-deadband", String(options.rbe.deadband));
+  }
+
+  const process = Bun.spawn({
+    cmd,
+    cwd: resolve("."),
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  try {
+    const ready = await waitForAsync(
+      "smoke runtime ready file",
+      async () => {
+        if (!(await Bun.file(readyFile).exists())) {
+          return undefined;
+        }
+        return (await Bun.file(readyFile).json()) as SmokeRuntimeReady;
+      },
+      15000,
+    );
+
+    return { process, tmpDir, ready };
+  } catch (error) {
+    process.kill("SIGTERM");
+    await process.exited;
+    const output = await collectProcessOutput(process);
+    await rm(tmpDir, { recursive: true, force: true });
+    throw new Error(
+      [
+        `Failed to start smoke runtime: ${error instanceof Error ? error.message : String(error)}`,
+        output.stdout.trim().length > 0 ? `stdout:\n${output.stdout.trim()}` : "",
+        output.stderr.trim().length > 0 ? `stderr:\n${output.stderr.trim()}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n\n"),
+    );
+  }
+}
+
+async function stopSmokeRuntime(handle: SmokeRuntimeHandle): Promise<void> {
+  handle.process.kill("SIGTERM");
+  const exitResult = await Promise.race([
+    handle.process.exited.then(() => "exited"),
+    Bun.sleep(5000).then(() => "timeout"),
+  ]);
+  if (exitResult === "timeout") {
+    handle.process.kill("SIGKILL");
+    await handle.process.exited;
+  }
+  await collectProcessOutput(handle.process);
+  await rm(handle.tmpDir, { recursive: true, force: true });
+}
+
+async function stopSmokeRuntimeWithFailure(
+  handle: SmokeRuntimeHandle,
+  cause: unknown,
+): Promise<never> {
+  handle.process.kill("SIGTERM");
+  const exitResult = await Promise.race([
+    handle.process.exited.then(() => "exited"),
+    Bun.sleep(5000).then(() => "timeout"),
+  ]);
+  if (exitResult === "timeout") {
+    handle.process.kill("SIGKILL");
+    await handle.process.exited;
+  }
+
+  const output = await collectProcessOutput(handle.process);
+  await rm(handle.tmpDir, { recursive: true, force: true });
+
+  throw new Error(
+    [
+      cause instanceof Error ? cause.message : String(cause),
+      output.stdout.trim().length > 0 ? `runner stdout:\n${output.stdout.trim()}` : "",
+      output.stderr.trim().length > 0 ? `runner stderr:\n${output.stderr.trim()}` : "",
+    ]
+      .filter(Boolean)
+      .join("\n\n"),
+  );
+}
+
+describe("executable methods integration", () => {
+  test("admin HTTP server exposes runtime state, executes core commands, and drives published twin behavior", async () => {
+    const runtime = await createSmokeRuntime();
+    let client: MqttClient | undefined;
+    let stage = "connect MQTT observer";
+
+    try {
+      const { ready } = runtime;
+      const topicPrefix = ready.instancePath;
+      client = connect(ready.mqttBrokerUrl, { reconnectPeriod: 0 });
+
+      await waitForMQTTConnect(client);
+      await subscribeMQTT(client, [`${topicPrefix}/#`]);
+
+      const recorder = createMQTTRecorder(client);
+      try {
+        stage = "read admin health and readiness";
+        const health = await readAdminHealth(runtime, "/healthz");
+        const readyz = await readAdminHealth(runtime, "/readyz");
+        expect(health.response.status).toBe(200);
+        expect(health.payload.status).toBe("ok");
+        expect(readyz.response.status).toBe(200);
+        expect(readyz.payload.status).toBe("ok");
+
+        stage = "read admin metrics and state";
+        const initialMetrics = await readAdminJson(
+          runtime,
+          "/metrics",
+          EngineMetricsSnapshotSchema,
+        );
+        const initialState = await readAdminJson(runtime, "/state", EngineStateSnapshotSchema);
+        expect(initialMetrics.simulationName).toBe(ready.simulationName);
+        expect(initialMetrics.core.state).toBe("running");
+        expect(initialState.simulationName).toBe(ready.simulationName);
+        expect(initialState.instances).toHaveLength(1);
+        expect(initialState.config.adapters).toContain("mqtt");
+        expect(initialState.config.adapters).toContain("opcua");
+
+        stage = "reject malformed admin command";
+        const invalidResponse = await fetch(new URL("/commands", `${ready.adminUrl}/`), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ type: "setSpeed" }),
+        });
+        expect(invalidResponse.status).toBe(400);
+
+        stage = "invoke method through admin server";
+        const startResult = await postAdminCommand(runtime, {
+          type: "invokeMethod",
+          instanceId: ready.instanceId,
+          method: "Start",
+        });
+        expect(startResult.success).toBe(true);
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/run_command`, true)).toBe(
+          true,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/speed_feedback`, 1200)).toBe(
+          1200,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/running`, true)).toBe(true);
+
+        stage = "pause and resume through admin server";
+        const pauseResult = await postAdminCommand(runtime, { type: "pause" });
+        expect(pauseResult.success).toBe(true);
+        expect((await waitForAdminMetricsState(runtime, "paused")).core.state).toBe("paused");
+        const pausedReady = await readAdminHealth(runtime, "/readyz");
+        expect(pausedReady.response.status).toBe(503);
+        expect(pausedReady.payload.status).toBe("fail");
+
+        const resumeResult = await postAdminCommand(runtime, { type: "resume" });
+        expect(resumeResult.success).toBe(true);
+        expect((await waitForAdminMetricsState(runtime, "running")).core.state).toBe("running");
+        const resumedReady = await readAdminHealth(runtime, "/readyz");
+        expect(resumedReady.response.status).toBe(200);
+        expect(resumedReady.payload.status).toBe("ok");
+
+        stage = "change simulation speed through admin server";
+        const speedResult = await postAdminCommand(runtime, { type: "setSpeed", multiplier: 5 });
+        expect(speedResult.success).toBe(true);
+        const updatedState = await waitForAsync("admin time multiplier 5", async () => {
+          const state = await readAdminJson(runtime, "/state", EngineStateSnapshotSchema);
+          return state.config.timeMultiplier === 5 ? state : undefined;
+        });
+        expect(updatedState.config.timeMultiplier).toBe(5);
+
+        stage = "spawn and remove instances through admin server";
+        const spawnResult = await postAdminCommand(runtime, {
+          type: "spawn",
+          model: "method-smoke-pump",
+          count: 1,
+          variation: 0,
+          unsBasePath: "method-smoke/validation/protocols",
+        });
+        expect(spawnResult.success).toBe(true);
+        const spawnedIds = Array.isArray(spawnResult.data)
+          ? spawnResult.data.filter((value): value is string => typeof value === "string")
+          : [];
+        expect(spawnedIds).toHaveLength(1);
+        const spawnedState = await waitForAdminInstanceCount(runtime, 2);
+        expect(spawnedState.instances.some((instance) => instance.id === spawnedIds[0])).toBe(true);
+
+        const removeResult = await postAdminCommand(runtime, {
+          type: "removeInstance",
+          instanceId: spawnedIds[0],
+        });
+        expect(removeResult.success).toBe(true);
+        const removedState = await waitForAdminInstanceCount(runtime, 1);
+        expect(removedState.instances.some((instance) => instance.id === spawnedIds[0])).toBe(
+          false,
+        );
+      } finally {
+        recorder.dispose();
+      }
+
+      await stopMQTTClient(client);
+      await stopSmokeRuntime(runtime);
+    } catch (error) {
+      if (client) {
+        await stopMQTTClient(client).catch(() => {});
+      }
+      await stopSmokeRuntimeWithFailure(
+        runtime,
+        new Error(
+          `Admin integration failure during "${stage}": ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      );
+    }
+  }, 30000);
+
+  test("mqtt.js invokes methods through the control plane and template-backed twin topics reflect the result", async () => {
+    const runtime = await createSmokeRuntime();
+    let client: MqttClient | undefined;
+    let stage = "connect MQTT client";
+
+    try {
+      const { ready } = runtime;
+      const cmdResultTopic = controlTopicCmdResult(ready.simulationName);
+      const topicPrefix = ready.instancePath;
+      client = connect(ready.mqttBrokerUrl, { reconnectPeriod: 0 });
+
+      await waitForMQTTConnect(client);
+      await subscribeMQTT(client, [`${topicPrefix}/#`, cmdResultTopic]);
+
+      const recorder = createMQTTRecorder(client);
+      try {
+        // MQTT now uses a delta-driven publish pipeline. With retain disabled in this
+        // smoke runtime, a late subscriber is only guaranteed to observe values that
+        // change after it subscribes. The test therefore validates post-subscription
+        // command-driven changes rather than initial state replay.
+
+        stage = "start asset through MQTT";
+        const startResult = await publishControlCommand(client, recorder, ready.simulationName, {
+          type: "invokeMethod",
+          instanceId: ready.instanceId,
+          method: "Start",
+        } satisfies InvokeMethodCommandPayload);
+        expect(startResult.success).toBe(true);
+        expect(
+          (startResult.data as { readonly outputs?: { readonly accepted?: boolean } }).outputs
+            ?.accepted,
+        ).toBe(true);
+
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/run_command`, true)).toBe(
+          true,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/speed_feedback`, 1200)).toBe(
+          1200,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/flow_rate`, 24)).toBe(24);
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/running`, true)).toBe(true);
+        expect(
+          await waitForMQTTTopicValue(recorder, `${topicPrefix}/availability_state`, "running"),
+        ).toBe("running");
+
+        stage = "set speed through MQTT";
+        const setSpeedResult = await publishControlCommand(client, recorder, ready.simulationName, {
+          type: "invokeMethod",
+          instanceId: ready.instanceId,
+          method: "SetSpeed",
+          arguments: { speed_rpm: 800 },
+        } satisfies InvokeMethodCommandPayload);
+        expect(setSpeedResult.success).toBe(true);
+
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/speed_command`, 800)).toBe(
+          800,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/speed_feedback`, 800)).toBe(
+          800,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/flow_rate`, 16)).toBe(16);
+
+        stage = "reject invalid MQTT method invocation";
+        const invalidSetSpeedResult = await publishControlCommand(
+          client,
+          recorder,
+          ready.simulationName,
+          {
+            type: "invokeMethod",
+            instanceId: ready.instanceId,
+            method: "SetSpeed",
+          } satisfies InvokeMethodCommandPayload,
+        );
+        expect(invalidSetSpeedResult.success).toBe(false);
+        expect(
+          (invalidSetSpeedResult.data as { readonly outputs?: { readonly accepted?: boolean } })
+            .outputs?.accepted,
+        ).toBe(false);
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/speed_command`, 800)).toBe(
+          800,
+        );
+
+        stage = "trigger fault through control plane";
+        const triggerFaultResult = await publishControlCommand(
+          client,
+          recorder,
+          ready.simulationName,
+          {
+            type: "triggerFault",
+            instanceId: ready.instanceId,
+            fault: "trip",
+          },
+        );
+        expect(triggerFaultResult.success).toBe(true);
+
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/fault_active`, true)).toBe(
+          true,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/fault_count`, 1)).toBe(1);
+        expect(
+          await waitForMQTTTopicValue(recorder, `${topicPrefix}/active_fault_code`, "trip"),
+        ).toBe("trip");
+
+        stage = "reset fault through MQTT";
+        const resetFaultResult = await publishControlCommand(
+          client,
+          recorder,
+          ready.simulationName,
+          {
+            type: "invokeMethod",
+            instanceId: ready.instanceId,
+            method: "ResetFault",
+          } satisfies InvokeMethodCommandPayload,
+        );
+        expect(resetFaultResult.success).toBe(true);
+
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/fault_active`, false)).toBe(
+          false,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/fault_count`, 0)).toBe(0);
+        expect(
+          await waitForMQTTTopicValue(recorder, `${topicPrefix}/active_fault_code`, "none"),
+        ).toBe("none");
+
+        stage = "set parameter through MQTT";
+        const setTargetResult = await publishControlCommand(
+          client,
+          recorder,
+          ready.simulationName,
+          {
+            type: "invokeMethod",
+            instanceId: ready.instanceId,
+            method: "SetTarget",
+            arguments: { target_value: 9.5 },
+          } satisfies InvokeMethodCommandPayload,
+        );
+        expect(setTargetResult.success).toBe(true);
+
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/parameter_echo`, 9.5)).toBe(
+          9.5,
+        );
+
+        stage = "stop asset through MQTT";
+        const stopResult = await publishControlCommand(client, recorder, ready.simulationName, {
+          type: "invokeMethod",
+          instanceId: ready.instanceId,
+          method: "Stop",
+        } satisfies InvokeMethodCommandPayload);
+        expect(stopResult.success).toBe(true);
+
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/run_command`, false)).toBe(
+          false,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/speed_feedback`, 0)).toBe(0);
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/flow_rate`, 0)).toBe(0);
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/running`, false)).toBe(false);
+        expect(
+          await waitForMQTTTopicValue(recorder, `${topicPrefix}/availability_state`, "stopped"),
+        ).toBe("stopped");
+      } finally {
+        recorder.dispose();
+      }
+      await stopMQTTClient(client);
+      await stopSmokeRuntime(runtime);
+    } catch (error) {
+      if (client) {
+        await stopMQTTClient(client).catch(() => {});
+      }
+      await stopSmokeRuntimeWithFailure(
+        runtime,
+        new Error(
+          `MQTT integration failure during "${stage}": ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      );
+    }
+  }, 30000);
+
+  test("OPC UA method calls update template-backed runtime state and exposed variable values", async () => {
+    const runtime = await createSmokeRuntime();
+    let mqttClient: MqttClient | undefined;
+    let opcuaClient: ReturnType<typeof OPCUAClient.create> | undefined;
+    let session: ClientSession | undefined;
+    let stage = "connect OPC UA client";
+
+    try {
+      const { ready } = runtime;
+      const objectPath = ready.instancePath;
+      mqttClient = connect(ready.mqttBrokerUrl, { reconnectPeriod: 0 });
+      opcuaClient = OPCUAClient.create({
+        securityMode: MessageSecurityMode.None,
+        securityPolicy: SecurityPolicy.None,
+        endpointMustExist: false,
+      });
+
+      await waitForMQTTConnect(mqttClient);
+      await subscribeMQTT(mqttClient, [controlTopicCmdResult(ready.simulationName)]);
+      const recorder = createMQTTRecorder(mqttClient);
+      try {
+        await opcuaClient.connect(ready.opcuaEndpointUrl);
+        session = await opcuaClient.createSession();
+
+        stage = "verify startup publication through OPC UA";
+        expect(
+          await waitForOPCUAValue<string>(
+            session,
+            `ns=1;s=${objectPath}/manufacturer`,
+            "Miravo Labs",
+          ),
+        ).toBe("Miravo Labs");
+        expect(
+          await waitForOPCUAValue<string>(
+            session,
+            `ns=1;s=${objectPath}/serial_number`,
+            "SMOKE-001",
+          ),
+        ).toBe("SMOKE-001");
+        expect(
+          await waitForOPCUAValue<boolean>(session, `ns=1;s=${objectPath}/running`, false),
+        ).toBe(false);
+        expect(
+          await waitForOPCUAValue<string>(
+            session,
+            `ns=1;s=${objectPath}/availability_state`,
+            "stopped",
+          ),
+        ).toBe("stopped");
+
+        stage = "start asset through OPC UA";
+        await callOPCUAMethod(session, objectPath, "Start");
+
+        expect(
+          await waitForOPCUAValue<boolean>(session, `ns=1;s=${objectPath}/run_command`, true),
+        ).toBe(true);
+        expect(
+          await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/speed_feedback`, 1200),
+        ).toBe(1200);
+        expect(await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/flow_rate`, 24)).toBe(
+          24,
+        );
+        expect(
+          await waitForOPCUAValue<boolean>(session, `ns=1;s=${objectPath}/running`, true),
+        ).toBe(true);
+        expect(
+          await waitForOPCUAValue<string>(
+            session,
+            `ns=1;s=${objectPath}/manufacturer`,
+            "Miravo Labs",
+          ),
+        ).toBe("Miravo Labs");
+
+        stage = "set speed through OPC UA";
+        await callOPCUAMethod(session, objectPath, "SetSpeed", [
+          { dataType: DataType.Double, value: 800 },
+        ]);
+
+        expect(
+          await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/speed_command`, 800),
+        ).toBe(800);
+        expect(
+          await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/speed_feedback`, 800),
+        ).toBe(800);
+        expect(await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/flow_rate`, 16)).toBe(
+          16,
+        );
+
+        stage = "reject invalid OPC UA method invocation";
+        const invalidSetSpeedResult = await callOPCUAMethodResult(session, objectPath, "SetSpeed");
+        expect(invalidSetSpeedResult.statusCode.isGood()).toBe(false);
+        expect(
+          await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/speed_command`, 800),
+        ).toBe(800);
+
+        stage = "trigger fault through control plane";
+        const triggerFaultResult = await publishControlCommand(
+          mqttClient,
+          recorder,
+          ready.simulationName,
+          {
+            type: "triggerFault",
+            instanceId: ready.instanceId,
+            fault: "trip",
+          },
+        );
+        expect(triggerFaultResult.success).toBe(true);
+
+        expect(
+          await waitForOPCUAValue<boolean>(session, `ns=1;s=${objectPath}/fault_active`, true),
+        ).toBe(true);
+        expect(
+          await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/fault_count`, 1),
+        ).toBe(1);
+        expect(
+          await waitForOPCUAValue<string>(
+            session,
+            `ns=1;s=${objectPath}/active_fault_code`,
+            "trip",
+          ),
+        ).toBe("trip");
+        expect(
+          await waitForOPCUAValue<string>(
+            session,
+            `ns=1;s=${objectPath}/manufacturer`,
+            "Miravo Labs",
+          ),
+        ).toBe("Miravo Labs");
+
+        stage = "reset fault through OPC UA";
+        await callOPCUAMethod(session, objectPath, "ResetFault");
+
+        expect(
+          await waitForOPCUAValue<boolean>(session, `ns=1;s=${objectPath}/fault_active`, false),
+        ).toBe(false);
+        expect(
+          await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/fault_count`, 0),
+        ).toBe(0);
+        expect(
+          await waitForOPCUAValue<string>(
+            session,
+            `ns=1;s=${objectPath}/active_fault_code`,
+            "none",
+          ),
+        ).toBe("none");
+
+        stage = "set parameter through OPC UA";
+        await callOPCUAMethod(session, objectPath, "SetTarget", [
+          { dataType: DataType.Double, value: 9.5 },
+        ]);
+
+        expect(
+          await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/parameter_echo`, 9.5),
+        ).toBe(9.5);
+
+        stage = "stop asset through OPC UA";
+        await callOPCUAMethod(session, objectPath, "Stop");
+
+        expect(
+          await waitForOPCUAValue<boolean>(session, `ns=1;s=${objectPath}/run_command`, false),
+        ).toBe(false);
+        expect(
+          await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/speed_feedback`, 0),
+        ).toBe(0);
+        expect(await waitForOPCUAValue<number>(session, `ns=1;s=${objectPath}/flow_rate`, 0)).toBe(
+          0,
+        );
+        expect(
+          await waitForOPCUAValue<boolean>(session, `ns=1;s=${objectPath}/running`, false),
+        ).toBe(false);
+        expect(
+          await waitForOPCUAValue<string>(
+            session,
+            `ns=1;s=${objectPath}/availability_state`,
+            "stopped",
+          ),
+        ).toBe("stopped");
+        expect(
+          await waitForOPCUAValue<string>(
+            session,
+            `ns=1;s=${objectPath}/manufacturer`,
+            "Miravo Labs",
+          ),
+        ).toBe("Miravo Labs");
+      } finally {
+        recorder.dispose();
+      }
+      if (session) {
+        await session.close();
+      }
+      await opcuaClient.disconnect();
+      await stopMQTTClient(mqttClient);
+      await stopSmokeRuntime(runtime);
+    } catch (error) {
+      if (session) {
+        await session.close().catch(() => {});
+      }
+      await opcuaClient?.disconnect().catch(() => {});
+      if (mqttClient) {
+        await stopMQTTClient(mqttClient).catch(() => {});
+      }
+      await stopSmokeRuntimeWithFailure(
+        runtime,
+        new Error(
+          `OPC UA integration failure during "${stage}": ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      );
+    }
+  }, 30000);
+
+  test("lifecycle effects apply multiplier-then-offset and fleet metrics track stage transitions", async () => {
+    // time_multiplier=10000: each 100ms tick = 0.278 simulated hours.
+    // healthy: 3.0h (~11 ticks), degraded: 1.5h (~5 ticks), critical: terminal.
+    // Runner waits ~3 ticks (0.83h) before ready. Test observes healthy→degraded→critical.
+    const runtime = await createSmokeRuntime({
+      model: createLifecycleTestModel(),
+      namespacePrefix: "lifecycle-test",
+      templateSettings: { tick_interval_ms: 100, time_multiplier: 10000, seed: 42 },
+    });
+    let client: MqttClient | undefined;
+    let stage = "connect MQTT observer";
+
+    try {
+      const { ready } = runtime;
+      const topicPrefix = ready.instancePath;
+      client = connect(ready.mqttBrokerUrl, { reconnectPeriod: 0 });
+      await waitForMQTTConnect(client);
+      await subscribeMQTT(client, [`${topicPrefix}/#`]);
+
+      const recorder = createMQTTRecorder(client);
+      try {
+        stage = "verify healthy lifecycle metrics";
+        const healthyMetrics = await waitForAsync("fleet lifecycle healthy", async () => {
+          const m = await readAdminJson(runtime, "/metrics", EngineMetricsSnapshotSchema);
+          return m.fleet.lifecycleBreakdown["healthy"] === 1 ? m : undefined;
+        });
+        expect(healthyMetrics.fleet.lifecycleBreakdown["healthy"]).toBe(1);
+
+        stage = "wait for degraded stage (pressure = 100 * 0.8 - 5 = 75)";
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/pressure`, 75)).toBe(75);
+
+        const degradedMetrics = await waitForAsync("fleet lifecycle degraded", async () => {
+          const m = await readAdminJson(runtime, "/metrics", EngineMetricsSnapshotSchema);
+          return m.fleet.lifecycleBreakdown["degraded"] === 1 ? m : undefined;
+        });
+        expect(degradedMetrics.fleet.lifecycleBreakdown["degraded"]).toBe(1);
+
+        stage = "wait for critical stage (pressure = 100 * 0.5 - 20 = 30)";
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/pressure`, 30)).toBe(30);
+
+        const criticalMetrics = await waitForAsync("fleet lifecycle critical", async () => {
+          const m = await readAdminJson(runtime, "/metrics", EngineMetricsSnapshotSchema);
+          return m.fleet.lifecycleBreakdown["critical"] === 1 ? m : undefined;
+        });
+        expect(criticalMetrics.fleet.lifecycleBreakdown["critical"]).toBe(1);
+      } finally {
+        recorder.dispose();
+      }
+
+      await stopMQTTClient(client);
+      await stopSmokeRuntime(runtime);
+    } catch (error) {
+      if (client) {
+        await stopMQTTClient(client).catch(() => {});
+      }
+      await stopSmokeRuntimeWithFailure(
+        runtime,
+        new Error(
+          `Lifecycle integration failure during "${stage}": ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      );
+    }
+  }, 30000);
+
+  test("condition-based faults auto-trigger when member exceeds threshold and quality reflects fault state", async () => {
+    const runtime = await createSmokeRuntime({
+      model: createConditionalFaultTestModel(),
+      namespacePrefix: "fault-test",
+      templateSettings: { seed: 42 },
+    });
+    let client: MqttClient | undefined;
+    let stage = "connect MQTT client";
+
+    try {
+      const { ready } = runtime;
+      const topicPrefix = ready.instancePath;
+      const cmdResultTopic = controlTopicCmdResult(ready.simulationName);
+      client = connect(ready.mqttBrokerUrl, { reconnectPeriod: 0 });
+      await waitForMQTTConnect(client);
+      await subscribeMQTT(client, [`${topicPrefix}/#`, cmdResultTopic]);
+
+      const recorder = createMQTTRecorder(client);
+      try {
+        stage = "set speed to trigger overpressure (pressure = 1000 * 0.1 = 100 > 80)";
+        const setSpeedResult = await publishControlCommand(client, recorder, ready.simulationName, {
+          type: "invokeMethod",
+          instanceId: ready.instanceId,
+          method: "SetSpeed",
+          arguments: { speed: 1000 },
+        } satisfies InvokeMethodCommandPayload);
+        expect(setSpeedResult.success).toBe(true);
+
+        // Fault triggers on next tick after condition evaluates against pressure=100.
+        // Fault effect: pressure = 100 * 0.5 = 50.
+        stage = "verify fault auto-triggered";
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/fault_active`, true)).toBe(
+          true,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/fault_count`, 1)).toBe(1);
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/pressure`, 50)).toBe(50);
+
+        stage = "verify quality is uncertain during active fault";
+        expect(
+          await waitForMQTTTopicQuality(recorder, `${topicPrefix}/pressure`, "uncertain"),
+        ).toBe("uncertain");
+
+        // Verify fleet metrics show active fault
+        const faultMetrics = await readAdminJson(runtime, "/metrics", EngineMetricsSnapshotSchema);
+        expect(faultMetrics.fleet.activeFaultCount).toBe(1);
+        expect(faultMetrics.fleet.faultBreakdown).toContainEqual({
+          fault: "overpressure",
+          count: 1,
+        });
+
+        // Lower speed below threshold BEFORE clearing to prevent re-trigger.
+        // speed=500 → pressure=50 (with fault: 50*0.5=25, without: 50).
+        stage = "lower speed and clear fault";
+        const lowerSpeedResult = await publishControlCommand(
+          client,
+          recorder,
+          ready.simulationName,
+          {
+            type: "invokeMethod",
+            instanceId: ready.instanceId,
+            method: "SetSpeed",
+            arguments: { speed: 500 },
+          } satisfies InvokeMethodCommandPayload,
+        );
+        expect(lowerSpeedResult.success).toBe(true);
+
+        const resetResult = await publishControlCommand(client, recorder, ready.simulationName, {
+          type: "invokeMethod",
+          instanceId: ready.instanceId,
+          method: "ResetFault",
+        } satisfies InvokeMethodCommandPayload);
+        expect(resetResult.success).toBe(true);
+
+        // After fault cleared: pressure = 500 * 0.1 = 50, condition 50>80 = false.
+        stage = "verify fault cleared and quality recovered";
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/fault_active`, false)).toBe(
+          false,
+        );
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/pressure`, 50)).toBe(50);
+        expect(await waitForMQTTTopicQuality(recorder, `${topicPrefix}/pressure`, "good")).toBe(
+          "good",
+        );
+
+        // Fleet metrics should show zero active faults
+        const clearedMetrics = await waitForAsync("fleet fault count 0", async () => {
+          const m = await readAdminJson(runtime, "/metrics", EngineMetricsSnapshotSchema);
+          return m.fleet.activeFaultCount === 0 ? m : undefined;
+        });
+        expect(clearedMetrics.fleet.activeFaultCount).toBe(0);
+      } finally {
+        recorder.dispose();
+      }
+
+      await stopMQTTClient(client);
+      await stopSmokeRuntime(runtime);
+    } catch (error) {
+      if (client) {
+        await stopMQTTClient(client).catch(() => {});
+      }
+      await stopSmokeRuntimeWithFailure(
+        runtime,
+        new Error(
+          `Fault integration failure during "${stage}": ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      );
+    }
+  }, 30000);
+
+  test("RBE filtering suppresses redundant MQTT messages within deadband", async () => {
+    const runtime = await createSmokeRuntime({
+      rbe: { enabled: true, deadband: 50 },
+      templateSettings: { seed: 42 },
+    });
+    let client: MqttClient | undefined;
+    let stage = "connect MQTT observer";
+
+    try {
+      const { ready } = runtime;
+      const topicPrefix = ready.instancePath;
+      client = connect(ready.mqttBrokerUrl, { reconnectPeriod: 0 });
+      await waitForMQTTConnect(client);
+      await subscribeMQTT(client, [`${topicPrefix}/#`]);
+
+      const recorder = createMQTTRecorder(client);
+      try {
+        stage = "start pump to establish RBE baseline";
+        const startResult = await postAdminCommand(runtime, {
+          type: "invokeMethod",
+          instanceId: ready.instanceId,
+          method: "Start",
+        });
+        expect(startResult.success).toBe(true);
+
+        // speed_feedback=1200 should be published (|1200 - 0| > 50).
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/speed_feedback`, 1200)).toBe(
+          1200,
+        );
+
+        const baselineMetrics = await readAdminJson(
+          runtime,
+          "/metrics",
+          EngineMetricsSnapshotSchema,
+        );
+        const baselineMqtt = baselineMetrics.adapters.find((a) => a.name === "mqtt")?.metrics;
+        expect(baselineMqtt).toBeDefined();
+        const filteredBefore = baselineMqtt?.messagesFiltered ?? 0;
+        const publishedBefore = baselineMqtt?.messagesPublished ?? 0;
+
+        stage = "set speed within RBE deadband";
+        const smallChangeResult = await postAdminCommand(runtime, {
+          type: "invokeMethod",
+          instanceId: ready.instanceId,
+          method: "SetSpeed",
+          arguments: { speed_rpm: 1230 },
+        });
+        expect(smallChangeResult.success).toBe(true);
+
+        const filteredMetrics = await waitForAsync("messagesFiltered increased", async () => {
+          const m = await readAdminJson(runtime, "/metrics", EngineMetricsSnapshotSchema);
+          const mqtt = m.adapters.find((a) => a.name === "mqtt");
+          return mqtt && mqtt.metrics.messagesFiltered > filteredBefore ? mqtt.metrics : undefined;
+        });
+        expect(filteredMetrics.messagesFiltered).toBeGreaterThan(filteredBefore);
+        expect(
+          readPayloadValue(recorder.latestByTopic.get(`${topicPrefix}/speed_feedback`)?.parsed),
+        ).toBe(1200);
+
+        stage = "set speed beyond RBE deadband";
+        const largeChangeResult = await postAdminCommand(runtime, {
+          type: "invokeMethod",
+          instanceId: ready.instanceId,
+          method: "SetSpeed",
+          arguments: { speed_rpm: 1300 },
+        });
+        expect(largeChangeResult.success).toBe(true);
+
+        expect(await waitForMQTTTopicValue(recorder, `${topicPrefix}/speed_feedback`, 1300)).toBe(
+          1300,
+        );
+
+        // Verify published count increased after the large value change.
+        const afterMetrics = await waitForAsync("messagesPublished increased", async () => {
+          const m = await readAdminJson(runtime, "/metrics", EngineMetricsSnapshotSchema);
+          const mqtt = m.adapters.find((a) => a.name === "mqtt");
+          return mqtt && mqtt.metrics.messagesPublished > publishedBefore
+            ? mqtt.metrics
+            : undefined;
+        });
+        expect(afterMetrics.messagesPublished).toBeGreaterThan(publishedBefore);
+      } finally {
+        recorder.dispose();
+      }
+
+      await stopMQTTClient(client);
+      await stopSmokeRuntime(runtime);
+    } catch (error) {
+      if (client) {
+        await stopMQTTClient(client).catch(() => {});
+      }
+      await stopSmokeRuntimeWithFailure(
+        runtime,
+        new Error(
+          `RBE integration failure during "${stage}": ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      );
+    }
+  }, 30000);
+});