@mh-gg/relay-runtime 0.1.1-alpha.20260613T085325975Z

package/test/plugin-runtime-manager.test.cjs

@@ -0,0 +1,651 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { manifestHash } = require("@mh-gg/base");
+const { createMemoryOperationLog, createMemoryRoomStore } = require("@mh-gg/host-runtime");
+const { createRelayPluginRuntimeManager } = require("../src/index.cjs");
+const { kanbanAppPack, kanbanHostPlugins, kanbanHostPlugin, KANBAN_PLUGIN_ID } = require("../../../examples/kanban/src/sdk-app.mjs");
+const { COMMENTS_PLUGIN_ID } = require("@mh-gg/base-plugins");
+const { ensureOperationIdentity } = require("@mh-gg/protocol");
+
+function actor(role = "admin", memberId = "admin") {
+  return { memberId, deviceId: `dev_${memberId}`, role, displayName: memberId };
+}
+
+function operation(overrides = {}) {
+  const op = {
+    clientOperationId: overrides.id || "op_1",
+    roomId: "room_resilient_board",
+    appPackId: kanbanAppPack.id,
+    appPackHash: manifestHash(kanbanAppPack),
+    pluginId: overrides.pluginId || KANBAN_PLUGIN_ID,
+    type: overrides.type || "list.create",
+    actor: overrides.actor || actor(),
+    seq: overrides.seq || 1,
+    createdAt: overrides.createdAt || 1000,
+    payload: overrides.payload || { title: "Backlog" },
+    auth: { credentialId: "cred", signature: "sig" },
+    ...overrides
+  };
+  delete op.id;
+  return ensureOperationIdentity(op, { now: op.createdAt, nodeId: op.actor?.deviceId || "dev_admin" });
+}
+
+async function enable(manager, extra = {}) {
+  return manager.enableRoomComposition({
+    roomName: "room_resilient_board",
+    appPack: kanbanAppPack,
+    plugins: kanbanHostPlugins,
+    authenticateActor: async (_auth, opActor) => opActor,
+    now: () => 1700000000000,
+    ...extra
+  });
+}
+
+test("relay plugin runtime manager enables every plugin in the composition set", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await enable(manager);
+
+  assert.equal(manager.hasRoom("room_resilient_board"), true);
+  assert.deepEqual(manager.enabledPlugins("room_resilient_board").map((plugin) => plugin.id), kanbanHostPlugins.map((plugin) => plugin.id));
+  assert.ok(manager.enabledPlugins("room_resilient_board").some((plugin) => plugin.id === COMMENTS_PLUGIN_ID), "shared comments plugin should be enabled too");
+});
+
+test("relay plugin runtime manager exposes partial capabilities and preserves missing plugin state", async () => {
+  const source = createRelayPluginRuntimeManager();
+  await enable(source);
+  const fullSnapshot = await source.snapshot("room_resilient_board");
+  const partialPlugins = kanbanHostPlugins.filter((plugin) => plugin.id !== COMMENTS_PLUGIN_ID);
+  const partial = createRelayPluginRuntimeManager();
+  await partial.enableRoomComposition({
+    roomName: "room_resilient_board",
+    appPack: kanbanAppPack,
+    plugins: partialPlugins,
+    expectedPlugins: kanbanHostPlugins,
+    authenticateActor: async (_auth, opActor) => opActor,
+    state: fullSnapshot.state,
+    now: () => 1700000000000
+  });
+
+  const capabilities = partial.runtimeCapabilities("room_resilient_board");
+  assert.equal(capabilities.mode, "partial");
+  assert.equal(capabilities.unavailablePlugins.some((plugin) => plugin.id === COMMENTS_PLUGIN_ID), true);
+  assert.equal(capabilities.unavailableOperations.some((item) => item.pluginId === COMMENTS_PLUGIN_ID && item.type === "comments.add"), true);
+  assert.equal(partial.roomApp("room_resilient_board").runtimeCapabilities.mode, "partial");
+  assert.ok((await partial.snapshot("room_resilient_board")).state.plugins[COMMENTS_PLUGIN_ID], "missing plugin state should remain opaque");
+
+  const available = await partial.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "alice", operation: operation({ id: "partial_available", seq: 1 }) },
+    sendToClient: () => {},
+    broadcastToRoom: () => {}
+  });
+  assert.equal(available.ok, true);
+
+  const sent = [];
+  const missing = await partial.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: {
+      type: "client/operation",
+      protocol: 1,
+      roomName: "room_resilient_board",
+      clientId: "alice",
+      operation: operation({
+        id: "partial_missing_comments",
+        seq: 2,
+        pluginId: COMMENTS_PLUGIN_ID,
+        type: "comments.add",
+        payload: { scopeType: "card", scopeId: "card-1", body: "Needs discussion" }
+      })
+    },
+    sendToClient: (peerId, message) => sent.push({ peerId, message }),
+    broadcastToRoom: () => {}
+  });
+
+  assert.equal(missing.ok, false);
+  assert.equal(missing.code, "PLUGIN_UNAVAILABLE");
+  assert.equal(missing.retryableWhenCapabilityAvailable, true);
+  assert.equal(sent[0].message.result.code, "PLUGIN_UNAVAILABLE");
+  assert.equal(sent[0].message.result.retryableWhenCapabilityAvailable, true);
+});
+
+test("relay plugin runtime manager logs authoritative runtime decisions", async () => {
+  const logs = [];
+  const logger = {
+    info: (message, fields) => logs.push({ level: "info", message, fields }),
+    warn: (message, fields) => logs.push({ level: "warn", message, fields })
+  };
+  const manager = createRelayPluginRuntimeManager({ logger });
+  await enable(manager);
+
+  const acceptedOperation = operation({ id: "logged_accept" });
+  const accepted = await manager.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", operation: acceptedOperation },
+    sendToClient: () => {},
+    broadcastToRoom: () => {}
+  });
+  assert.equal(accepted.ok, true);
+
+  const rejected = await manager.handleRelayOperation({
+    roomName: "room_resilient_board",
+    operation: { nope: true }
+  });
+  assert.equal(rejected.ok, false);
+
+  assert.equal(logs.some((entry) =>
+    entry.level === "info" &&
+    entry.message.includes("relay runtime accepted") &&
+    entry.fields.roomName === "room_resilient_board" &&
+    entry.fields.operationId === acceptedOperation.id
+  ), true);
+  assert.equal(logs.some((entry) =>
+    entry.level === "warn" &&
+    entry.message.includes("relay runtime rejected") &&
+    entry.fields.roomName === "room_resilient_board" &&
+    entry.fields.relayDirection === "relay"
+  ), true);
+});
+
+test("relay plugin runtime manager refreshes room app metadata", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await enable(manager, {
+    roomApp: { appPack: { id: kanbanAppPack.id, hash: "sha256-stale" }, frontends: [{ id: "player", integrity: "sha256-old" }] }
+  });
+
+  assert.equal(manager.roomApp("room_resilient_board").frontends[0].integrity, "sha256-old");
+  assert.equal(manager.roomApp("room_resilient_board").appPack.hash, manifestHash(kanbanAppPack));
+  assert.equal(manager.updateRoomApp("room_resilient_board", { frontends: [{ id: "player", dynamic: true, integrity: "sha256-new" }] }), true);
+  assert.equal(manager.roomApp("room_resilient_board").frontends[0].dynamic, true);
+  assert.equal(manager.roomApp("room_resilient_board").frontends[0].integrity, "sha256-new");
+  assert.equal(manager.updateRoomApp("missing", { frontends: [] }), false);
+
+  await enable(manager, {
+    roomApp: { frontends: [{ id: "player", integrity: "sha256-reregistered" }] }
+  });
+  assert.equal(manager.roomApp("room_resilient_board").frontends[0].integrity, "sha256-reregistered");
+});
+
+test("relay plugin runtime manager does not retain failed plugin starts", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await assert.rejects(() => manager.enableRoomComposition({
+    roomName: "room_bad_start",
+    appPack: kanbanAppPack,
+    plugins: [{ id: KANBAN_PLUGIN_ID, version: "0.0.0" }],
+    authenticateActor: async (_auth, opActor) => opActor
+  }), /createInitialState is required/);
+
+  assert.equal(manager.hasRoom("room_bad_start"), false);
+
+  await manager.enableRoomComposition({
+    roomName: "room_bad_start",
+    appPack: kanbanAppPack,
+    plugins: kanbanHostPlugins,
+    authenticateActor: async (_auth, opActor) => opActor
+  });
+  assert.equal(manager.hasRoom("room_bad_start"), true);
+  assert.deepEqual(manager.enabledPlugins("room_bad_start").map((plugin) => plugin.id), kanbanHostPlugins.map((plugin) => plugin.id));
+});
+
+test("relay plugin runtime manager repairs stale non-executable room entries", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  const appPack = {
+    id: kanbanAppPack.id,
+    version: kanbanAppPack.version,
+    hash: manifestHash(kanbanAppPack),
+    protocolHash: kanbanAppPack.compatibility.appProtocolHash
+  };
+  const room = { id: "room_stale_bad_start", appPack };
+  manager.rooms.set(room.id, {
+    roomName: room.id,
+    room,
+    hostPack: null,
+    plugins: [{ id: KANBAN_PLUGIN_ID, version: "0.0.0" }],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    roomApp: {},
+    runtime: { authenticateActor: async (_auth, opActor) => opActor, capabilities: [] }
+  });
+
+  await manager.enableRoomComposition({
+    roomName: room.id,
+    appPack: kanbanAppPack,
+    plugins: kanbanHostPlugins,
+    authenticateActor: async (_auth, opActor) => opActor
+  });
+
+  assert.equal(manager.hasRoom(room.id), true);
+  assert.deepEqual(manager.enabledPlugins(room.id).map((plugin) => plugin.id), kanbanHostPlugins.map((plugin) => plugin.id));
+  assert.equal((await manager.snapshot(room.id)).state.appPack.hash, appPack.hash);
+});
+
+test("relay plugin runtime manager upgrades same-app hash without dropping state", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await enable(manager);
+  await manager.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", operation: operation({ id: "before_upgrade" }) },
+    sendToClient: () => {}
+  });
+
+  const upgradedAppPack = { ...kanbanAppPack, hash: "sha256-upgraded-kanban" };
+  await enable(manager, { appPack: upgradedAppPack });
+  const upgraded = await manager.snapshot("room_resilient_board");
+
+  assert.equal(upgraded.room.appPack.hash, upgradedAppPack.hash);
+  assert.equal(upgraded.state.appPack.hash, upgradedAppPack.hash);
+  assert.equal(upgraded.state.version, 1);
+  assert.equal(Object.keys(upgraded.state.plugins[KANBAN_PLUGIN_ID].lists).length, 1);
+
+  const afterOperation = operation({ id: "after_upgrade", seq: 2, appPackHash: upgradedAppPack.hash, payload: { title: "Later" } });
+  const after = await manager.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", operation: afterOperation },
+    sendToClient: () => {},
+    broadcastToRoom: async (roomName, createMessage) => {
+      assert.equal(roomName, "room_resilient_board");
+      assert.equal((await createMessage()).acceptedOperationId, afterOperation.id);
+      assert.equal((await createMessage(actor("member", "viewer"))).state.roomId, "room_resilient_board");
+    }
+  });
+
+  assert.equal(after.ok, true);
+  assert.equal((await manager.snapshot("room_resilient_board")).state.version, 2);
+});
+
+test("relay plugin runtime manager rolls back failed same-app runtime swaps", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await enable(manager);
+  await manager.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", operation: operation({ id: "before_failed_swap" }) },
+    sendToClient: () => {}
+  });
+  const before = await manager.snapshot("room_resilient_board");
+  const failingPlugins = kanbanHostPlugins.map((plugin) => plugin.id === KANBAN_PLUGIN_ID
+    ? {
+        ...plugin,
+        schemas: {
+          ...plugin.schemas,
+          state: {
+            parse() {
+              throw new Error("schema upgrade rejected");
+            }
+          }
+        }
+      }
+    : plugin);
+
+  await assert.rejects(() => enable(manager, {
+    appPack: { ...kanbanAppPack, hash: "sha256-bad-upgrade" },
+    plugins: failingPlugins
+  }), /schema upgrade rejected/);
+  const after = await manager.snapshot("room_resilient_board");
+
+  assert.deepEqual(after.state, before.state);
+  assert.equal(after.room.appPack.hash, before.room.appPack.hash);
+  assert.deepEqual(manager.enabledPlugins("room_resilient_board").map((plugin) => plugin.id), kanbanHostPlugins.map((plugin) => plugin.id));
+});
+
+test("relay plugin runtime manager applies same-app historical operations during catch-up", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await enable(manager);
+  const oldHashOperation = operation({
+    id: "op_old_hash_catchup",
+    appPackHash: "sha256-older-kanban-schema",
+    payload: { title: "Catch-up state" }
+  });
+
+  const result = await manager.handleRelayOperation({
+    type: "relay.matterhorn-operation",
+    roomName: "room_resilient_board",
+    operation: oldHashOperation
+  });
+  const snapshot = await manager.snapshot("room_resilient_board");
+
+  assert.equal(result.ok, true, result.reason);
+  assert.equal(snapshot.state.plugins[KANBAN_PLUGIN_ID].lists[0].title, "Catch-up state");
+});
+
+test("relay plugin runtime manager ignores relay operations for another app", async () => {
+  const warnings = [];
+  const logger = {
+    debug() {},
+    info() {},
+    warn(...args) { warnings.push(args); },
+    error() {}
+  };
+  const manager = createRelayPluginRuntimeManager({ logger });
+  await enable(manager);
+  const wrongAppOperation = operation({
+    id: "op_wrong_app_catchup",
+    appPackId: "com.matterhorn.other"
+  });
+
+  const result = await manager.handleRelayOperation({
+    type: "relay.matterhorn-operation",
+    roomName: "room_resilient_board",
+    operation: wrongAppOperation
+  });
+  const snapshot = await manager.snapshot("room_resilient_board");
+
+  assert.equal(result.ok, false);
+  assert.equal(result.ignored, true);
+  assert.equal(result.code, "APP_PACK_MISMATCH");
+  assert.equal(result.reason, "app-mismatch");
+  assert.equal(snapshot.state.version, 0);
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0][0], /relay runtime rejected/);
+  assert.equal(warnings[0][1].reason, "app-mismatch");
+});
+
+test("relay plugin runtimes keep a room running and converge when a peer relay returns", async () => {
+  const sentFromA = [];
+  const sentFromB = [];
+  const relayA = createRelayPluginRuntimeManager({ relayAddress: "relay-a", sendRelayEnvelope: (message) => sentFromA.push(message) });
+  const relayB = createRelayPluginRuntimeManager({ relayAddress: "relay-b", sendRelayEnvelope: (message) => sentFromB.push(message) });
+  await enable(relayA);
+  await enable(relayB);
+
+  const result1 = await relayA.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "alice-peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "alice", operation: operation({ id: "op_list", seq: 1 }) },
+    sendToClient: () => {},
+    broadcastToRoom: () => {}
+  });
+  assert.equal(result1.ok, true);
+  assert.equal(sentFromA[0].type, "relay.matterhorn-operation");
+
+  const replayOnB = await relayB.handleRelayOperation(sentFromA[0]);
+  assert.equal(replayOnB.ok, true);
+  assert.equal((await relayB.snapshot("room_resilient_board")).state.plugins[KANBAN_PLUGIN_ID].lists[0].title, "Backlog");
+
+  const backlogId = (await relayB.snapshot("room_resilient_board")).state.plugins[KANBAN_PLUGIN_ID].lists[0].id;
+  const result2 = await relayB.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "bob-peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "bob", operation: operation({ id: "op_card", seq: 2, type: "card.create", payload: { listId: backlogId, title: "Continue while relay A is down" }, actor: actor("member", "bob"), createdAt: 1001 }) },
+    sendToClient: () => {},
+    broadcastToRoom: () => {}
+  });
+  assert.equal(result2.ok, true);
+
+  const snapshotWhileADown = await relayB.snapshot("room_resilient_board");
+  assert.equal(snapshotWhileADown.state.version, 2);
+  assert.equal(snapshotWhileADown.state.plugins[KANBAN_PLUGIN_ID].lists[0].cardIds.length, 1);
+
+  const staleA = await relayA.snapshot("room_resilient_board");
+  assert.equal(staleA.state.version, 1);
+  const synced = await relayA.syncSnapshot("room_resilient_board", snapshotWhileADown.state);
+  assert.equal(synced.updated, true);
+  assert.equal((await relayA.snapshot("room_resilient_board")).state.version, 2);
+});
+
+test("relay plugin runtimes reject host re-registration snapshots that are older than relay state", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await enable(manager);
+  await manager.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "alice", operation: operation({ id: "op_list", seq: 1 }) },
+    sendToClient: () => {},
+    broadcastToRoom: () => {}
+  });
+  const fresh = await manager.snapshot("room_resilient_board");
+  const stale = { ...fresh.state, version: 0, plugins: {} };
+
+  const result = await manager.syncSnapshot("room_resilient_board", stale);
+  assert.equal(result.updated, false);
+  assert.equal((await manager.snapshot("room_resilient_board")).state.version, 1);
+});
+
+test("relay plugin runtimes reject destructive newer snapshots without operation proof", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await enable(manager);
+  await manager.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "alice", operation: operation({ id: "op_list_before_destructive", seq: 1 }) },
+    sendToClient: () => {},
+    broadcastToRoom: () => {}
+  });
+  const fresh = await manager.snapshot("room_resilient_board");
+  const destructive = {
+    ...fresh.state,
+    version: fresh.state.version + 1,
+    updatedAt: fresh.state.updatedAt + 1,
+    plugins: {
+      ...fresh.state.plugins,
+      [KANBAN_PLUGIN_ID]: { lists: [], cards: {}, activity: [] }
+    },
+    seenOperations: []
+  };
+
+  const result = await manager.syncSnapshot("room_resilient_board", destructive);
+  const after = await manager.snapshot("room_resilient_board");
+
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, "snapshot-operation-proof-required");
+  assert.equal(after.state.version, fresh.state.version);
+  assert.equal(after.state.plugins[KANBAN_PLUGIN_ID].lists[0].title, "Backlog");
+  assert.deepEqual(after.state.seenOperations, fresh.state.seenOperations);
+});
+
+test("relay plugin runtime manager pulls newer same-app snapshot state across hash changes", async () => {
+  const host = createRelayPluginRuntimeManager();
+  await enable(host);
+  await host.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "alice", operation: operation({ id: "op_host_state", seq: 1, payload: { title: "Host snapshot state" } }) },
+    sendToClient: () => {},
+    broadcastToRoom: () => {}
+  });
+  const hostSnapshot = await host.snapshot("room_resilient_board");
+  const relay = createRelayPluginRuntimeManager();
+  await enable(relay);
+
+  const synced = await relay.syncSnapshot("room_resilient_board", {
+    ...hostSnapshot.state,
+    appPack: { ...hostSnapshot.state.appPack, hash: "sha256-older-kanban-schema" }
+  });
+  const relaySnapshot = await relay.snapshot("room_resilient_board");
+
+  assert.equal(synced.updated, true);
+  assert.equal(relaySnapshot.state.appPack.hash, manifestHash(kanbanAppPack));
+  assert.equal(relaySnapshot.state.plugins[KANBAN_PLUGIN_ID].lists[0].title, "Host snapshot state");
+});
+
+test("relay plugin runtime manager reuses existing rooms and trusts newer registration snapshots", async () => {
+  const source = createRelayPluginRuntimeManager();
+  await enable(source);
+  await source.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "alice", operation: operation({ id: "op_existing_list", seq: 1 }) },
+    sendToClient: () => {},
+    broadcastToRoom: () => {}
+  });
+  const newerSnapshot = await source.snapshot("room_resilient_board");
+
+  const manager = createRelayPluginRuntimeManager();
+  const existing = await enable(manager);
+  const reused = await manager.enableRoomComposition({
+    roomName: "room_resilient_board",
+    appPack: kanbanAppPack,
+    plugins: kanbanHostPlugins,
+    authenticateActor: async (_auth, opActor) => opActor
+  });
+  assert.equal(reused, existing);
+  assert.equal((await manager.snapshot("room_resilient_board")).state.version, 0);
+
+  const synced = await manager.enableRoomComposition({
+    roomName: "room_resilient_board",
+    appPack: kanbanAppPack,
+    plugins: kanbanHostPlugins,
+    authenticateActor: async (_auth, opActor) => opActor,
+    state: newerSnapshot.state
+  });
+  assert.equal(synced, existing);
+  assert.equal((await manager.snapshot("room_resilient_board")).state.version, 1);
+});
+
+test("relay plugin runtime manager exposes stable error paths and timestamp freshness", async () => {
+  const { isNewerRoomState } = require("../src/index.cjs");
+  assert.equal(isNewerRoomState({ version: 1, updatedAt: 20 }, { version: 1, updatedAt: 10 }), true);
+  assert.equal(isNewerRoomState({ version: 1, updatedAt: 5 }, { version: 2, updatedAt: 1 }), false);
+
+  const manager = createRelayPluginRuntimeManager();
+  await assert.rejects(() => manager.enableRoomComposition({ plugins: kanbanHostPlugins }), /roomName/);
+  await assert.rejects(() => manager.enableRoomComposition({ roomName: "missing_plugins", appPack: kanbanAppPack, plugins: [] }), /at least one plugin/);
+  assert.deepEqual(manager.enabledPlugins("missing"), []);
+  assert.equal(manager.roomApp("missing"), undefined);
+  assert.equal(await manager.snapshot("missing"), undefined);
+  assert.deepEqual(await manager.syncSnapshot("missing", {}), { ok: false, updated: false, reason: "room-not-enabled" });
+  assert.deepEqual(manager.runtimeCapabilities("missing"), { mode: "unavailable", availablePlugins: [], unavailablePlugins: [], availableOperations: [], unavailableOperations: [] });
+
+  const sent = [];
+  const rejected = await manager.handleClientOperation({
+    roomName: "missing",
+    peerId: "peer",
+    message: {},
+    sendToClient: (peerId, message) => sent.push({ peerId, message })
+  });
+  assert.equal(rejected.ok, false);
+  assert.equal(sent[0].message.code, "room-runtime-unavailable");
+});
+
+test("relay plugin runtime manager rejects bad operations and invalid snapshots without corrupting state", async () => {
+  const manager = createRelayPluginRuntimeManager({ authenticateActor: async (_auth, opActor) => opActor });
+  await enable(manager);
+  const state = (await manager.snapshot("room_resilient_board")).state;
+
+  assert.equal((await manager.syncSnapshot("room_resilient_board", null)).reason, "snapshot-required");
+  assert.equal((await manager.syncSnapshot("room_resilient_board", { ...state, roomId: "other" })).reason, "room-mismatch");
+  assert.equal((await manager.syncSnapshot("room_resilient_board", { ...state, appPack: { ...state.appPack, id: "other-app" } })).reason, "app-mismatch");
+  const sameAppHash = await manager.syncSnapshot("room_resilient_board", {
+    ...state,
+    appPack: { ...state.appPack, hash: "sha256-older-schema" },
+    version: state.version + 1,
+    updatedAt: state.updatedAt + 1
+  });
+  assert.equal(sameAppHash.updated, true);
+  assert.equal((await manager.snapshot("room_resilient_board")).state.appPack.hash, manifestHash(kanbanAppPack));
+  const current = (await manager.snapshot("room_resilient_board")).state;
+  const invalidMigratedSnapshot = await manager.syncSnapshot("room_resilient_board", {
+    ...current,
+    version: current.version + 1,
+    updatedAt: current.updatedAt + 1,
+    pluginVersions: {
+      ...current.pluginVersions,
+      [KANBAN_PLUGIN_ID]: "0.9.0"
+    }
+  });
+  assert.equal(invalidMigratedSnapshot.ok, false);
+  assert.match(invalidMigratedSnapshot.reason, /No migration/);
+
+  const sent = [];
+  const bad = await manager.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "alice", operation: { nope: true } },
+    sendToClient: (peerId, message) => sent.push({ peerId, message })
+  });
+  assert.equal(bad.ok, false);
+  assert.equal(sent[0].message.code, "bad-operation");
+
+  const relayBad = await manager.handleRelayOperation({ roomName: "room_resilient_board", operation: { nope: true } });
+  assert.equal(relayBad.ok, false);
+});
+
+test("relay plugin runtime manager can be created from installed metadata and refuses missing authenticators", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await manager.enableRoomComposition({
+    room: { id: "room_installed", appPack: { id: kanbanAppPack.id, version: kanbanAppPack.version, hash: manifestHash(kanbanAppPack), protocolHash: kanbanAppPack.compatibility.appProtocolHash } },
+    hostPack: { id: "host", version: "1.0.0", hash: "sha256-host", compatibility: { pluginGraphHash: "sha256-plugins" }, capabilities: { required: [] } },
+    installed: { plugins: kanbanHostPlugins }
+  });
+  assert.equal(manager.roomApp("room_installed").hostPack.id, "host");
+  const rejected = await manager.handleClientOperation({
+    roomName: "room_installed",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_installed", clientId: "alice", operation: operation({ roomId: "room_installed" }) },
+    sendToClient: () => {}
+  });
+  assert.equal(rejected.ok, false);
+  assert.match(rejected.reason, /authenticateActor/);
+});
+
+test("relay plugin runtime manager handles expectedPlugins with operation descriptors", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await manager.enableRoomComposition({
+    roomName: "room_descriptor_test",
+    appPack: kanbanAppPack,
+    plugins: kanbanHostPlugins,
+    expectedPlugins: [
+      { id: KANBAN_PLUGIN_ID, version: "1.0.0", operations: ["list.create", "card.create"] }
+    ],
+    authenticateActor: async (_auth, opActor) => opActor
+  });
+  assert.equal(manager.hasRoom("room_descriptor_test"), true);
+  const capabilities = manager.runtimeCapabilities("room_descriptor_test");
+  assert.equal(capabilities.mode, "full");
+});
+
+test("relay plugin runtime manager rejects invalid device-signed operations", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await enable(manager);
+  const sent = [];
+  const badDeviceOp = operation({
+    id: "bad_device_op",
+    seq: 99,
+    auth: {
+      scheme: "matterhorn.device-signing.v1",
+      keyId: "bad",
+      memberId: "bad",
+      deviceId: "bad",
+      rootPublicKey: "bad",
+      publicKey: "bad",
+      publicKeyFingerprint: "bad",
+      claim: { roomName: "room_resilient_board", roomId: "room_resilient_board", memberId: "bad", deviceId: "bad", keyId: "bad", rootPublicKey: "bad", publicKey: "bad", publicKeyFingerprint: "bad" },
+      signature: "00"
+    }
+  });
+  const result = await manager.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "alice", operation: badDeviceOp },
+    sendToClient: (peerId, message) => sent.push({ peerId, message })
+  });
+  assert.equal(result.ok, false);
+  assert.equal(sent[0].message.code, "bad-operation");
+});
+
+test("relay plugin runtime manager detects destructive snapshots with meaningful primitive data", async () => {
+  const manager = createRelayPluginRuntimeManager();
+  await enable(manager);
+  await manager.handleClientOperation({
+    roomName: "room_resilient_board",
+    peerId: "peer",
+    message: { type: "client/operation", protocol: 1, roomName: "room_resilient_board", clientId: "alice", operation: operation({ id: "op_list", seq: 1 }) },
+    sendToClient: () => {},
+    broadcastToRoom: () => {}
+  });
+  const current = (await manager.snapshot("room_resilient_board")).state;
+  const destructive = {
+    ...current,
+    version: current.version + 1,
+    updatedAt: current.updatedAt + 1,
+    plugins: {}
+  };
+  const result = await manager.syncSnapshot("room_resilient_board", destructive);
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, "snapshot-operation-proof-required");
+});