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

package/test/matterhorn-host-runtime.test.cjs

@@ -0,0 +1,1629 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const {
+  HostPluginRuntime,
+  CORE_DIRECT_MESSAGE_PUBLISH_TYPE,
+  CORE_PLUGIN_ID,
+  CORE_READ_TAG_SET_TYPE,
+  MatterhornRuntimeError,
+  RoomStateSchema,
+  allow,
+  createHostPluginRuntimeFromPack,
+  createMemoryOperationLog,
+  createMemoryRoomStore,
+  createOperationSchemaDescriptor,
+  createOperationRoleKeyGrant,
+  defineHostPlugin,
+  deny,
+  generateOperationRoleKeyPair,
+  installAppPack,
+  installHostPack,
+  normalizeRuntimeFailure,
+  parseRoomState,
+  resolveHostPlugins,
+  runMigrations,
+  signOperationWithRoleKey,
+  startRoomHost
+} = require("../src/index.cjs");
+const { manifestHash } = require("@mh-gg/base");
+const { ensureOperationIdentity, isSnowflakeId, parseHostOperationBatch, parseHostSnapshot } = require("@mh-gg/protocol");
+
+const appPack = {
+  id: "com.matterhorn.tasks",
+  version: "1.0.0",
+  hash: "sha256-app",
+  protocolHash: "sha256-protocol"
+};
+
+function schema(parse) {
+  return { parse };
+}
+
+function rolesPlugin() {
+  return {
+    id: "@mh-gg/plugin-roles",
+    version: "1.0.0",
+    operationSchemaDescriptor: createOperationSchemaDescriptor({ plugin: "@mh-gg/plugin-roles", version: "1.0.0", operations: {} }),
+    schemas: {
+      state: schema((state) => {
+        assert.equal(typeof state.permissions, "object");
+        return state;
+      }),
+      operations: {}
+    },
+    createInitialState() {
+      return {
+        permissions: {
+          admin: ["tasks.task.create", "tasks.task.complete", "tasks.task.archive"],
+          member: ["tasks.task.create", "tasks.task.complete"],
+          guest: []
+        }
+      };
+    },
+    authorize() {
+      return deny("Roles plugin has no direct operations");
+    },
+    reduce(ctx, state) {
+      return state;
+    },
+    methods: {
+      hasPermission(ctx, input) {
+        return !!ctx.state.permissions[input.memberId]?.includes(input.permission);
+      }
+    }
+  };
+}
+
+function tasksPlugin(afterCommitCalls = []) {
+  return {
+    id: "@mh-gg/plugin-tasks",
+    version: "1.0.0",
+    operationSchemaDescriptor: createOperationSchemaDescriptor({ plugin: "@mh-gg/plugin-tasks", version: "1.0.0", operations: {
+      "task.create": { authorize: { roles: ["member"] } },
+      "task.complete": { authorize: { roles: ["member"] } }
+    } }),
+    schemas: {
+      state: schema((state) => {
+        assert.ok(Array.isArray(state.taskOrder));
+        assert.equal(typeof state.tasks, "object");
+        return state;
+      }),
+      operations: {
+        "task.create": schema((payload) => {
+          assert.equal(typeof payload.title, "string");
+          return { title: payload.title.trim() };
+        }),
+        "task.complete": schema((payload) => {
+          assert.equal(typeof payload.taskId, "string");
+          return payload;
+        })
+      },
+      publicView: schema((view) => view)
+    },
+    createInitialState() {
+      return { taskOrder: [], tasks: {} };
+    },
+    async authorize(ctx, op) {
+      assert.equal(ctx.plugins.has("@mh-gg/plugin-roles"), true);
+      assert.equal(ctx.crypto.verifySignature(), false);
+      const allowed = await ctx.plugins.call("@mh-gg/plugin-roles", "hasPermission", {
+        memberId: ctx.actor.memberId,
+        permission: `tasks.${op.type}`
+      });
+      return allowed ? allow() : deny("Missing task permission");
+    },
+    reduce(ctx, state, op) {
+      if (op.type === "task.create") {
+        const task = {
+          id: ctx.crypto.randomId("task"),
+          title: op.payload.title,
+          done: false,
+          createdBy: ctx.actor.memberId,
+          createdAt: op.createdAt
+        };
+        return {
+          taskOrder: [...state.taskOrder, task.id],
+          tasks: { ...state.tasks, [task.id]: task }
+        };
+      }
+      if (op.type === "task.complete") {
+        const task = state.tasks[op.payload.taskId];
+        return {
+          ...state,
+          tasks: {
+            ...state.tasks,
+            [task.id]: { ...task, done: true, completedAt: op.createdAt }
+          }
+        };
+      }
+      return state;
+    },
+    getPublicView(ctx, state, actor) {
+      if (actor.role === "guest") return { count: state.taskOrder.length };
+      return state;
+    },
+    async afterCommit(ctx, event) {
+      await ctx.storage.put("lastOperationId", event.op.id);
+      await ctx.events.append({ type: "task.afterCommit", operationId: event.op.id });
+      afterCommitCalls.push({ operationId: event.op.id, version: ctx.roomState.version });
+    }
+  };
+}
+
+function operation(overrides = {}) {
+  const op = {
+    id: "op_1",
+    roomId: "room_tasks",
+    appPackId: appPack.id,
+    appPackHash: appPack.hash,
+    pluginId: "@mh-gg/plugin-tasks",
+    type: "task.create",
+    actor: {
+      memberId: "admin",
+      deviceId: "dev_admin",
+      role: "admin"
+    },
+    seq: 1,
+    createdAt: 1000,
+    payload: {
+      title: "Write tests"
+    },
+    auth: {
+      credentialId: "cred_admin",
+      signature: "sig"
+    },
+    ...overrides
+  };
+  return ensureOperationIdentity(op, { nodeId: op.actor?.deviceId || "test", now: op.createdAt });
+}
+
+function repeatedHex(char, length) {
+  return char.repeat(length);
+}
+
+function opaqueGiftWrap({ idChar, wrapperPubkeyChar, createdAt = 900 }) {
+  return {
+    id: repeatedHex(idChar, 64),
+    pubkey: repeatedHex(wrapperPubkeyChar, 64),
+    created_at: createdAt,
+    kind: 1059,
+    tags: [["opaque", "true"]],
+    content: `nip44-ciphertext-${idChar}`,
+    sig: repeatedHex("f", 128)
+  };
+}
+
+function directPublishOperation(overrides = {}) {
+  const recipients = overrides.recipients || [
+    { recipientId: "alice", idChar: "1", wrapperPubkeyChar: "4" },
+    { recipientId: "lee", idChar: "2", wrapperPubkeyChar: "5" },
+    { recipientId: "sam", idChar: "3", wrapperPubkeyChar: "6" }
+  ];
+  const giftWraps = {};
+  for (const recipient of recipients) giftWraps[recipient.recipientId] = opaqueGiftWrap(recipient);
+  return operation({
+    id: overrides.id || "op_direct_1",
+    pluginId: CORE_PLUGIN_ID,
+    type: CORE_DIRECT_MESSAGE_PUBLISH_TYPE,
+    actor: overrides.actor || { memberId: "alice", deviceId: "dev_alice", role: "member" },
+    payload: {
+      userIds: recipients.map((recipient) => recipient.recipientId),
+      topicKey: "launch",
+      giftWraps,
+      ...(overrides.payload || {})
+    },
+    ...overrides.operation
+  });
+}
+
+function runtimeWithPlugins(options = {}) {
+  const calls = [];
+  const store = createMemoryRoomStore();
+  const operationLog = createMemoryOperationLog();
+  const runtime = new HostPluginRuntime({
+    room: {
+      id: "room_tasks",
+      appPack
+    },
+    plugins: [rolesPlugin(), tasksPlugin(calls)],
+    store,
+    operationLog,
+    authenticateActor: async (auth, actor) => {
+      if (auth.signature !== "sig") throw new Error("bad signature");
+      return actor;
+    },
+    ...options
+  });
+  return { calls, operationLog, runtime, store };
+}
+
+function createAtomicMemoryStore(initialState = null, operationLog = createMemoryOperationLog()) {
+  const store = createMemoryRoomStore(initialState);
+  store.commitStateAndOperation = async ({ operation: logEntry, nextState, expectedPreviousVersion }) => {
+    const current = await store.load();
+    const currentVersion = Number.isInteger(current?.version) ? current.version : 0;
+    if (Number.isInteger(expectedPreviousVersion) && currentVersion !== expectedPreviousVersion) throw new Error("version conflict");
+    if (Number.isInteger(expectedPreviousVersion) && nextState?.version !== expectedPreviousVersion + 1) throw new Error("next version conflict");
+    await operationLog.append(logEntry);
+    await store.save(nextState);
+  };
+  return store;
+}
+
+test("initializes plugin state and commits authorized operations", async () => {
+  const { calls, operationLog, runtime, store } = runtimeWithPlugins();
+  await runtime.start();
+
+  const firstOperation = operation();
+  const ack = await runtime.handleOperation(firstOperation);
+  const state = await store.load();
+  const taskId = state.plugins["@mh-gg/plugin-tasks"].taskOrder[0];
+
+  assert.equal(ack.ok, true);
+  assert.equal(ack.acceptedOperationId, firstOperation.id);
+  assert.equal(ack.roomVersion, 1);
+  assert.match(taskId, /^task_\d+$/);
+  assert.equal(isSnowflakeId(operationLog.entries[0].ledgerId), true);
+  assert.equal(taskId, `task_${operationLog.entries[0].ledgerId}`);
+  assert.equal(ack.acceptedLedgerId, operationLog.entries[0].ledgerId);
+  assert.equal(state.plugins["@mh-gg/plugin-tasks"].tasks[taskId].title, "Write tests");
+  assert.equal(operationLog.entries[0].id, firstOperation.id);
+  assert.deepEqual(calls, [{ operationId: firstOperation.id, version: 1 }]);
+  assert.equal(await runtime.pluginStorage("@mh-gg/plugin-tasks").get("lastOperationId"), firstOperation.id);
+  await runtime.pluginStorage("@mh-gg/plugin-tasks").delete("lastOperationId");
+  assert.equal(await runtime.pluginStorage("@mh-gg/plugin-tasks").get("lastOperationId"), null);
+  assert.deepEqual((await runtime.pluginEvents("@mh-gg/plugin-tasks").query({}))[0], {
+    type: "task.afterCommit",
+    operationId: firstOperation.id
+  });
+  assert.equal((await runtime.pluginEvents("@mh-gg/plugin-tasks").query({ type: "task.afterCommit" })).length, 1);
+
+  const duplicate = await runtime.handleOperation(firstOperation);
+  assert.deepEqual(duplicate, ack);
+  assert.equal(operationLog.entries.length, 1);
+});
+
+test("operation append failure does not advance room state", async () => {
+  const baseStore = createMemoryRoomStore();
+  const operationLog = createMemoryOperationLog();
+  const failingLog = {
+    entries: operationLog.entries,
+    append() {
+      throw new Error("append failed");
+    },
+    list: operationLog.list,
+    findById: operationLog.findById
+  };
+  const { runtime } = runtimeWithPlugins({ store: baseStore, operationLog: failingLog });
+  await runtime.start();
+  const before = await baseStore.load();
+
+  const ack = await runtime.handleOperation(operation());
+  const after = await baseStore.load();
+
+  assert.equal(ack.ok, false);
+  assert.equal(after.version, before.version);
+  assert.equal(after.plugins["@mh-gg/plugin-tasks"].taskOrder.length, 0);
+  assert.equal(operationLog.entries.length, 0);
+});
+
+test("state save failure rolls back appended operation log entry", async () => {
+  const baseStore = createMemoryRoomStore();
+  const operationLog = createMemoryOperationLog();
+  let saves = 0;
+  const failingStore = {
+    load: baseStore.load,
+    async save(nextState) {
+      saves += 1;
+      if (saves > 1) throw new Error("save failed");
+      await baseStore.save(nextState);
+    }
+  };
+  const { runtime } = runtimeWithPlugins({ store: failingStore, operationLog });
+  await runtime.start();
+  const before = await baseStore.load();
+
+  const ack = await runtime.handleOperation(operation());
+  const after = await baseStore.load();
+
+  assert.equal(ack.ok, false);
+  assert.equal(after.version, before.version);
+  assert.equal(operationLog.entries.length, 0);
+});
+
+test("production and relay-executed runtimes require atomic state and operation commits", () => {
+  assert.throws(
+    () => runtimeWithPlugins({ productionRuntime: true }),
+    (error) => {
+      assert.equal(error.code, "ATOMIC_COMMIT_REQUIRED");
+      return true;
+    }
+  );
+  assert.throws(
+    () => runtimeWithPlugins({ relayExecuted: true }),
+    (error) => {
+      assert.equal(error.code, "ATOMIC_COMMIT_REQUIRED");
+      return true;
+    }
+  );
+});
+
+test("production startup requires bootstrap authority and keeps custom authenticators strict", async () => {
+  const operationLog = createMemoryOperationLog();
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), tasksPlugin()],
+    store: createAtomicMemoryStore(null, operationLog),
+    operationLog,
+    productionRuntime: true,
+    authenticateActor: async (_auth, actor) => actor
+  });
+  assert.equal(runtime.strictStanding, true);
+  await assert.rejects(() => runtime.start(), (error) => {
+    assert.equal(error.code, "BOOTSTRAP_AUTHORITY_REQUIRED");
+    return true;
+  });
+
+  const bootstrapped = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), tasksPlugin()],
+    store: createAtomicMemoryStore(null, createMemoryOperationLog()),
+    operationLog: createMemoryOperationLog(),
+    productionRuntime: true,
+    initialOwners: ["admin"],
+    authenticateActor: async (_auth, actor) => actor
+  });
+  const state = await bootstrapped.start();
+  assert.equal(state.adminIds.includes("admin"), true);
+});
+
+test("atomic commit failures do not partially advance state or operation log", async () => {
+  const baseStore = createMemoryRoomStore();
+  const operationLog = createMemoryOperationLog();
+  const atomicStore = {
+    load: baseStore.load,
+    async save(nextState) {
+      await baseStore.save(nextState);
+    },
+    async commitStateAndOperation() {
+      throw new Error("atomic commit failed");
+    }
+  };
+  const { runtime } = runtimeWithPlugins({ store: atomicStore, operationLog, productionRuntime: true, initialOwners: ["admin"] });
+  await runtime.start();
+  const before = await baseStore.load();
+
+  const ack = await runtime.handleOperation(operation());
+  const after = await baseStore.load();
+
+  assert.equal(ack.ok, false);
+  assert.equal(after.version, before.version);
+  assert.equal(operationLog.entries.length, 0);
+});
+
+test("rejects invalid operations before commit", async () => {
+  const { calls, operationLog, runtime, store } = runtimeWithPlugins();
+  await runtime.start();
+  const before = await store.load();
+
+  assert.equal((await runtime.handleOperation(operation({ pluginId: "@mh-gg/missing" }))).code, "PLUGIN_NOT_INSTALLED");
+  assert.equal((await runtime.handleOperation(operation({ type: "task.unknown" }))).code, "UNKNOWN_OPERATION_TYPE");
+  assert.equal((await runtime.handleOperation(operation({
+    actor: { memberId: "guest", deviceId: "dev_guest", role: "guest" },
+    id: "op_guest"
+  }))).code, "FORBIDDEN");
+
+  assert.deepEqual(await store.load(), before);
+  assert.equal(operationLog.entries.length, 0);
+  assert.deepEqual(calls, []);
+});
+
+test("host pack composition requires schema action tags", async () => {
+  const hostPack = taskHostPack({
+    hostPack: {
+      composition: {
+        primaryPlugin: { id: "@mh-gg/plugin-tasks", version: "1.0.0" },
+        plugins: [],
+        sharedScopes: {},
+        views: [],
+        actions: [
+          { name: "taskCreate", plugin: "primary", type: "task.create", requiredRole: "admin" }
+        ]
+      }
+    }
+  });
+  const { runtime } = runtimeWithPlugins({ hostPack });
+  await runtime.start();
+
+  assert.equal((await runtime.handleOperation(operation({ id: "op_schema_missing" }))).code, "SCHEMA_ACTION_REQUIRED");
+  assert.equal((await runtime.handleOperation(operation({
+    id: "op_schema_mismatch",
+    schemaAction: "taskCreate",
+    type: "task.complete",
+    payload: { taskId: "task_1" }
+  }))).code, "SCHEMA_ACTION_MISMATCH");
+  assert.equal((await runtime.handleOperation(operation({
+    id: "op_schema_member",
+    schemaAction: "taskCreate",
+    actor: { memberId: "member", deviceId: "dev_member", role: "member" }
+  }))).code, "FORBIDDEN");
+
+  const accepted = await runtime.handleOperation(operation({ id: "op_schema_ok", schemaAction: "taskCreate" }));
+  assert.equal(accepted.ok, true);
+});
+
+test("rejects room mismatches, missing schemas, and missing plugin methods", async () => {
+  const missingSchemaPlugin = {
+    ...tasksPlugin(),
+    operationSchemaDescriptor: createOperationSchemaDescriptor({
+      plugin: "@mh-gg/plugin-tasks",
+      version: "1.0.0",
+      operations: {
+        "task.create": { authorize: { roles: ["member"] } },
+        "task.complete": { authorize: { roles: ["member"] } },
+        "task.bad": { authorize: { roles: ["member"] } }
+      }
+    }),
+    schemas: {
+      ...tasksPlugin().schemas,
+      operations: {
+        ...tasksPlugin().schemas.operations,
+        "task.bad": {}
+      }
+    }
+  };
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), missingSchemaPlugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (auth, actor) => actor
+  });
+  await runtime.start();
+
+  assert.equal((await runtime.handleOperation(operation({ roomId: "other" }))).code, "ROOM_MISMATCH");
+  assert.equal((await runtime.handleOperation(operation({ appPackId: "other" }))).code, "APP_PACK_MISMATCH");
+  assert.equal((await runtime.handleOperation(operation({ appPackHash: "sha256-other" }))).code, "APP_PACK_HASH_MISMATCH");
+  assert.equal((await runtime.handleOperation(operation({ id: "op_bad", type: "task.bad" }))).code, "SCHEMA_MISSING");
+
+  const methodPlugin = {
+    ...tasksPlugin(),
+    async authorize(ctx) {
+      await ctx.plugins.call("@mh-gg/plugin-roles", "missing", {});
+      return allow();
+    }
+  };
+  const methodRuntime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), methodPlugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (auth, actor) => actor
+  });
+  await methodRuntime.start();
+  assert.equal((await methodRuntime.handleOperation(operation())).code, "PLUGIN_METHOD_NOT_FOUND");
+});
+
+test("validates runtime construction and capability requirements", async () => {
+  assert.throws(() => new HostPluginRuntime(), /room\.id is required/);
+  assert.throws(() => new HostPluginRuntime({ room: { id: "room" }, plugins: [rolesPlugin()] }), /room\.appPack id and hash/);
+  assert.throws(() => new HostPluginRuntime({ room: { id: "room", appPack }, plugins: [] }), /At least one plugin/);
+  assert.throws(() => new HostPluginRuntime({ room: { id: "room", appPack }, plugins: [{}] }), /Plugin id and version/);
+  assert.throws(() => new HostPluginRuntime({ room: { id: "room", appPack }, plugins: [rolesPlugin(), rolesPlugin()] }), /Duplicate plugin/);
+  assert.equal(defineHostPlugin(rolesPlugin()).id, "@mh-gg/plugin-roles");
+
+  const capabilityPlugin = {
+    ...tasksPlugin(),
+    authorize(ctx) {
+      ctx.capabilities.require("network.fetch");
+      return allow();
+    }
+  };
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), capabilityPlugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (auth, actor) => actor
+  });
+  await runtime.start();
+  assert.equal((await runtime.handleOperation(operation())).code, "CAPABILITY_MISSING");
+});
+
+test("rejects operations by default when no actor authenticator is installed", async () => {
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), tasksPlugin()],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog()
+  });
+  await runtime.start();
+  const result = await runtime.handleOperation(operation());
+  assert.equal(result.code, "AUTHENTICATOR_MISSING");
+});
+
+test("serves per-actor public plugin views", async () => {
+  const { runtime } = runtimeWithPlugins({
+    initialMembers: {
+      admin: { id: "admin", memberId: "admin", name: "Admin", role: "admin" },
+      member: { id: "member", memberId: "member", name: "Member", role: "member", credentialId: "cred_member" }
+    }
+  });
+  await runtime.start();
+  await runtime.handleOperation(operation());
+
+  const memberView = await runtime.publicView({ memberId: "member", role: "member" });
+  const guestView = await runtime.publicView({ memberId: "guest", role: "guest" });
+
+  assert.deepEqual(memberView.members.member, { id: "member", memberId: "member", name: "Member", displayName: undefined, role: "member", status: undefined, revokedAt: undefined, bannedAt: undefined });
+  assert.equal("credentialId" in memberView.members.member, false);
+  assert.equal(memberView.plugins["@mh-gg/plugin-tasks"].taskOrder.length, 1);
+  assert.deepEqual(guestView.plugins["@mh-gg/plugin-tasks"], { count: 1 });
+});
+
+test("stores authenticated actor display data in room members", async () => {
+  const { runtime, store } = runtimeWithPlugins();
+  await runtime.start();
+  const first = await runtime.handleOperation(operation({
+    id: "op_member_profile_1",
+    seq: 1,
+    actor: { memberId: "member", deviceId: "dev_member", role: "member", displayName: "Mina", avatar: "M" },
+    auth: { credentialId: "cred_member", signature: "sig" }
+  }));
+  assert.equal(first.ok, true, first.reason);
+
+  let state = await store.load();
+  assert.equal(state.members.member.displayName, "Mina");
+  assert.equal(state.members.member.name, "Mina");
+  assert.equal(state.members.member.avatar, "M");
+  assert.equal(state.members.member.role, "member");
+  assert.equal(state.members.member.profileOnly, true);
+
+  const second = await runtime.handleOperation(operation({
+    id: "op_member_profile_2",
+    seq: 2,
+    createdAt: 1001,
+    actor: { memberId: "member", deviceId: "dev_member", role: "member", displayName: "Mina Room", avatar: "R" },
+    auth: { credentialId: "cred_member", signature: "sig" }
+  }));
+  assert.equal(second.ok, true, second.reason);
+
+  state = await store.load();
+  assert.equal(state.members.member.displayName, "Mina Room");
+  assert.equal(state.members.member.avatar, "R");
+  assert.equal(state.members.member.profileOnly, true);
+  const view = await runtime.publicView({ memberId: "admin", role: "admin" });
+  assert.equal(view.members.member.displayName, "Mina Room");
+  assert.equal(view.members.member.avatar, "R");
+});
+
+test("publishes NIP-17 direct messages as actor-filtered gift wraps", async () => {
+  const { runtime, store } = runtimeWithPlugins({
+    initialMembers: {
+      alice: { id: "alice", memberId: "alice", name: "Alice", role: "member" },
+      lee: { id: "lee", memberId: "lee", name: "Lee", role: "member" },
+      sam: { id: "sam", memberId: "sam", name: "Sam", role: "member" },
+      max: { id: "max", memberId: "max", name: "Max", role: "member" }
+    }
+  });
+  await runtime.start();
+
+  const publish = directPublishOperation();
+  const result = await runtime.handleOperation(publish);
+  const state = await store.load();
+  const thread = Object.values(state.directThreads)[0];
+  const message = Object.values(state.directMessages)[0];
+
+  assert.equal(result.ok, true);
+  assert.equal(thread.protocol, "nostr.nip17");
+  assert.deepEqual(thread.userIds, ["alice", "lee", "sam"]);
+  assert.equal(thread.topicKey, "launch");
+  assert.equal("roomId" in thread, false);
+  assert.equal(message.protocol, "nostr.nip17");
+  assert.equal("body" in message, false);
+  assert.equal("roomId" in message, false);
+  assert.deepEqual(Object.keys(message.giftWraps).sort(), ["alice", "lee", "sam"]);
+
+  const aliceView = await runtime.publicView({ memberId: "alice", role: "member" });
+  const leeView = await runtime.publicView({ memberId: "lee", role: "member" });
+  const maxView = await runtime.publicView({ memberId: "max", role: "member" });
+  const publicMessageId = Object.keys(aliceView.direct.messages)[0];
+
+  assert.equal(Object.keys(aliceView.direct.threads).length, 1);
+  assert.deepEqual(Object.keys(aliceView.direct.messages[publicMessageId].giftWraps), ["alice"]);
+  assert.deepEqual(Object.keys(leeView.direct.messages[publicMessageId].giftWraps), ["lee"]);
+  assert.deepEqual(maxView.direct, { threads: {}, messages: {}, keys: {} });
+});
+
+
+test("stores direct-message read tags in the reader member state", async () => {
+  const { runtime, store } = runtimeWithPlugins({
+    initialMembers: {
+      alice: { id: "alice", memberId: "alice", name: "Alice", role: "member" },
+      lee: { id: "lee", memberId: "lee", name: "Lee", role: "member" },
+      sam: { id: "sam", memberId: "sam", name: "Sam", role: "member" }
+    }
+  });
+  await runtime.start();
+
+  const publish = directPublishOperation();
+  const publishAck = await runtime.handleOperation(publish);
+  assert.equal(publishAck.ok, true, publishAck.reason);
+
+  let state = await store.load();
+  const thread = Object.values(state.directThreads)[0];
+  const message = Object.values(state.directMessages)[0];
+  assert.equal(isSnowflakeId(message.ledgerId), true);
+  assert.equal(message.id, `direct_message_${message.ledgerId}`);
+
+  const read = operation({
+    pluginId: CORE_PLUGIN_ID,
+    type: CORE_READ_TAG_SET_TYPE,
+    actor: { memberId: "alice", deviceId: "dev_alice", role: "member" },
+    seq: 2,
+    createdAt: 1002,
+    payload: {
+      scopeType: "direct.thread",
+      scopeId: thread.id,
+      ledgerId: message.ledgerId,
+      messageId: message.id,
+      operationId: message.operationId
+    },
+    auth: { credentialId: "cred_alice", signature: "sig" }
+  });
+  const readAck = await runtime.handleOperation(read);
+  assert.equal(readAck.ok, true, readAck.reason);
+
+  state = await store.load();
+  const key = `direct.thread:${thread.id}`;
+  const tag = state.members.alice.readTags[key];
+  assert.equal(tag.ledgerId, message.ledgerId);
+  assert.equal(tag.messageId, message.id);
+  assert.equal(tag.operationId, message.operationId);
+
+  const aliceView = await runtime.publicView({ memberId: "alice", role: "member" });
+  const leeView = await runtime.publicView({ memberId: "lee", role: "member" });
+  assert.equal(aliceView.members.alice.readTags[key].ledgerId, message.ledgerId);
+  assert.equal(aliceView.direct.threads[thread.id].readTag.ledgerId, message.ledgerId);
+  assert.equal(leeView.members.alice.readTags, undefined);
+  assert.equal(leeView.direct.threads[thread.id].readTag, undefined);
+});
+
+
+test("rejects direct messages that are not complete NIP-17 gift-wrap fanout", async () => {
+  const { runtime } = runtimeWithPlugins({
+    initialMembers: {
+      alice: { id: "alice", memberId: "alice", name: "Alice", role: "member" },
+      lee: { id: "lee", memberId: "lee", name: "Lee", role: "member" },
+      sam: { id: "sam", memberId: "sam", name: "Sam", role: "member" }
+    }
+  });
+  await runtime.start();
+
+  const plaintext = await runtime.handleOperation(directPublishOperation({ id: "op_direct_plaintext", payload: { body: "hello" } }));
+  const missingWrap = await runtime.handleOperation(directPublishOperation({
+    id: "op_direct_missing_wrap",
+    recipients: [
+      { recipientId: "alice", idChar: "1", wrapperPubkeyChar: "4" },
+      { recipientId: "lee", idChar: "2", wrapperPubkeyChar: "5" }
+    ],
+    payload: { userIds: ["alice", "lee", "sam"] }
+  }));
+  const wrongRecipient = directPublishOperation({
+    id: "op_direct_wrong_recipient",
+    recipients: [
+      { recipientId: "alice", idChar: "1", wrapperPubkeyChar: "4" },
+      { recipientId: "lee", idChar: "2", wrapperPubkeyChar: "5" }
+    ],
+    payload: {
+      giftWraps: {
+        alice: opaqueGiftWrap({ idChar: "1", wrapperPubkeyChar: "4" }),
+        lee: opaqueGiftWrap({ idChar: "2", wrapperPubkeyChar: "5" }),
+        mallory: opaqueGiftWrap({ idChar: "7", wrapperPubkeyChar: "8" })
+      }
+    }
+  });
+
+  assert.equal(plaintext.code, "SCHEMA_INVALID");
+  assert.match(plaintext.reason, /unknown field body/);
+  assert.equal(missingWrap.code, "SCHEMA_INVALID");
+  assert.match(missingWrap.reason, /must include sam/);
+  assert.equal((await runtime.handleOperation(wrongRecipient)).code, "SCHEMA_INVALID");
+  const staleReactionAlias = await runtime.handleOperation(directPublishOperation({
+    id: "op_direct_stale_reaction",
+    operation: { type: "dm.react" }
+  }));
+  assert.notEqual(staleReactionAlias.ok, true);
+});
+
+test("bounds dedupe and ack caches while preserving idempotent recent retries", async () => {
+  const { operationLog, runtime, store } = runtimeWithPlugins({ maxSeenOperations: 2, maxAckCache: 1 });
+  await runtime.start();
+  const opA = operation({ id: "op_a", seq: 1, payload: { title: "A" } });
+  const opB = operation({ id: "op_b", seq: 2, payload: { title: "B" } });
+  const opC = operation({ id: "op_c", seq: 3, payload: { title: "C" } });
+  await runtime.handleOperation(opA);
+  const ackB = await runtime.handleOperation(opB);
+  await runtime.handleOperation(opC);
+
+  assert.deepEqual((await store.load()).seenOperations, [opB.id, opC.id]);
+  assert.equal(operationLog.entries.length, 3);
+  assert.equal(operationLog.entries[2].committedRoomVersion, 3);
+  assert.deepEqual(await runtime.handleOperation(opB), {
+    ...ackB,
+    duplicate: true
+  });
+});
+
+test("serves operation batches, snapshots, and plugin queries", async () => {
+  const queryPlugin = {
+    ...tasksPlugin(),
+    queries: {
+      taskCount(ctx, state) {
+        return { count: state.taskOrder.length, actorRole: ctx.actor.role };
+      }
+    }
+  };
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), queryPlugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (auth, actor) => actor,
+    now: () => 5000
+  });
+  await runtime.start();
+  await runtime.handleOperation(operation());
+
+  const batch = await runtime.operationBatchSince(0);
+  assert.equal(batch.kind, "matterhorn.host-operation-batch");
+  assert.equal(batch.appPackId, appPack.id);
+  assert.equal(batch.appPackHash, appPack.hash);
+  assert.equal(batch.operations.length, 1);
+  assert.equal(batch.headVersion, 1);
+  assert.equal(parseHostOperationBatch(batch).headVersion, 1);
+  const snapshot = await runtime.createSnapshot();
+  assert.equal(snapshot.kind, "matterhorn.host-snapshot");
+  assert.equal(snapshot.version, 1);
+  assert.equal(snapshot.appPackId, appPack.id);
+  assert.equal(snapshot.appPackHash, appPack.hash);
+  assert.equal(snapshot.createdAt, 5000);
+  assert.equal(parseHostSnapshot(snapshot).version, 1);
+  assert.deepEqual(await runtime.handleQuery("@mh-gg/plugin-tasks", "taskCount", {}, { memberId: "admin", role: "admin" }), {
+    count: 1,
+    actorRole: "admin"
+  });
+  await assert.rejects(() => runtime.handleQuery("@mh-gg/plugin-tasks", "missing", {}, { role: "admin" }), (error) => {
+    assert.equal(error instanceof MatterhornRuntimeError, true);
+    assert.equal(error.code, "PLUGIN_QUERY_NOT_FOUND");
+    return true;
+  });
+});
+
+test("validates room state and schema-backed query results without storing query mutations", async () => {
+  const queryPlugin = {
+    ...tasksPlugin(),
+    schemas: {
+      ...tasksPlugin().schemas,
+      queries: {
+        summary: schema((result) => {
+          assert.equal(typeof result.count, "number");
+          return { count: result.count, validated: true };
+        }),
+        broken: schema((result) => {
+          assert.equal(typeof result.count, "number");
+          return result;
+        })
+      }
+    },
+    queries: {
+      summary(ctx, state) {
+        state.taskOrder.push("query_mutation");
+        ctx.roomState.plugins["@mh-gg/plugin-tasks"].taskOrder.push("context_mutation");
+        return { count: state.taskOrder.length };
+      },
+      broken() {
+        return { count: "bad" };
+      }
+    }
+  };
+  const store = createMemoryRoomStore();
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [queryPlugin],
+    store,
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+
+  const startedState = await runtime.start();
+  assert.equal(RoomStateSchema.parse(startedState).roomId, "room_tasks");
+  assert.equal(parseRoomState(startedState).appPack.id, appPack.id);
+  assert.deepEqual(await runtime.query("@mh-gg/plugin-tasks", "summary", {}, { role: "admin" }), {
+    count: 1,
+    validated: true
+  });
+  assert.deepEqual((await store.load()).plugins["@mh-gg/plugin-tasks"].taskOrder, []);
+  await assert.rejects(() => runtime.query("@mh-gg/plugin-tasks", "broken", {}, { role: "admin" }), (error) => {
+    assert.equal(error.code, "SCHEMA_INVALID");
+    return true;
+  });
+  assert.throws(() => parseRoomState({ ...startedState, version: -1 }), (error) => {
+    assert.equal(error.code, "ROOM_STATE_INVALID");
+    return true;
+  });
+});
+
+test("isolates plugin reducer failures as operation rejections", async () => {
+  const badPlugin = {
+    ...tasksPlugin(),
+    reduce() {
+      throw new Error("boom");
+    }
+  };
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), badPlugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (auth, actor) => actor
+  });
+  await runtime.start();
+  const result = await runtime.handleOperation(operation());
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "PLUGIN_REDUCE_FAILED");
+  assert.match(result.reason, /boom/);
+});
+
+test("constructs a runtime from pinned app and host pack manifests", async () => {
+  const hostPack = {
+    kind: "matterhorn.host-pack",
+    id: "com.matterhorn.tasks.host",
+    appPackId: appPack.id,
+    version: "1.0.0",
+    plugins: [
+      { id: "@mh-gg/plugin-tasks", version: "1.0.0", source: "workspace:tasks", integrity: "sha256-plugin" }
+    ],
+    compatibility: {
+      appProtocolHash: appPack.protocolHash,
+      pluginGraphHash: "sha256-graph"
+    },
+    runtime: { minMatterhornVersion: "0.1.0", sandbox: "process" },
+    capabilities: { required: ["room.state"], optional: [] },
+    trust: { signatures: [{ publicKey: "rk_pub", signature: "sig" }] }
+  };
+  const appPackManifest = {
+    kind: "matterhorn.app-pack",
+    id: appPack.id,
+    name: "Tasks",
+    version: appPack.version,
+    publisher: { id: "com.matterhorn", name: "Matterhorn", publicKey: "rk_pub" },
+    matterhornVersion: ">=0.1 <0.2",
+    hostPack: { url: "workspace:tasks-host", integrity: manifestHash(hostPack) },
+    playerPacks: [
+      { id: "com.matterhorn.tasks.player", name: "Tasks Player", url: "workspace:tasks-player", integrity: "sha256-player" }
+    ],
+    compatibility: {
+      appProtocolHash: appPack.protocolHash,
+      operationSchemaHash: "sha256-ops",
+      stateSchemaHash: "sha256-state"
+    },
+    capabilities: { required: ["room.state"], optional: [] },
+    trust: { createdAt: "2026-05-27T00:00:00Z", signatures: [{ publicKey: "rk_pub", signature: "sig" }] }
+  };
+
+  const runtime = createHostPluginRuntimeFromPack({
+    appPack: appPackManifest,
+    hostPack,
+    room: { id: "room_tasks" },
+    plugins: [tasksPlugin()],
+    authenticateActor: async (auth, actor) => actor
+  });
+  await runtime.start();
+  const state = await runtime.getState();
+  assert.equal(state.appPack.id, appPack.id);
+  assert.equal(state.appPack.hash, manifestHash(appPackManifest));
+
+  assert.throws(() => createHostPluginRuntimeFromPack({
+    appPack: { ...appPackManifest, hostPack: { ...appPackManifest.hostPack, integrity: "sha256-wrong" } },
+    hostPack,
+    room: { id: "room_tasks" },
+    plugins: [tasksPlugin()]
+  }), (error) => {
+    assert.equal(error instanceof MatterhornRuntimeError, true);
+    assert.equal(error.code, "HOST_PACK_INTEGRITY_MISMATCH");
+    return true;
+  });
+});
+
+test("isolates reducer and afterCommit failures without corrupting room state", async () => {
+  const afterCommitLogger = { debug() {}, info() {}, warn() {}, error() {} };
+  const failingReducerPlugin = {
+    ...tasksPlugin(),
+    reduce() {
+      throw new Error("boom");
+    }
+  };
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), failingReducerPlugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    logger: afterCommitLogger,
+    authenticateActor: async (auth, actor) => actor
+  });
+  await runtime.start();
+  const before = await runtime.getState();
+  const result = await runtime.handleOperation(operation());
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "PLUGIN_REDUCE_FAILED");
+  assert.deepEqual(await runtime.getState(), before);
+
+  const calls = [];
+  const sideEffectRuntime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), {
+      ...tasksPlugin(calls),
+      async afterCommit() {
+        throw new Error("webhook failed");
+      }
+    }],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    logger: afterCommitLogger,
+    authenticateActor: async (auth, actor) => actor
+  });
+  await sideEffectRuntime.start();
+  const ack = await sideEffectRuntime.handleOperation(operation({ id: "op_side" }));
+  assert.equal(ack.ok, true);
+  assert.equal((await sideEffectRuntime.getState()).version, 1);
+});
+
+test("bounds seen operations and ack cache", async () => {
+  const { runtime, store } = runtimeWithPlugins({ maxSeenOperations: 2, maxAcks: 1 });
+  await runtime.start();
+  const opA = operation({ id: "op_a", seq: 1 });
+  const opB = operation({ id: "op_b", seq: 2 });
+  const opC = operation({ id: "op_c", seq: 3 });
+  await runtime.handleOperation(opA);
+  await runtime.handleOperation(opB);
+  await runtime.handleOperation(opC);
+
+  const state = await store.load();
+  assert.deepEqual(state.seenOperations, [opB.id, opC.id]);
+  assert.equal(runtime.acks.has(opA.id), false);
+  assert.equal(runtime.acks.has(opC.id), true);
+});
+
+test("migrates plugin state, serves queries, and exposes room info", async () => {
+  const oldState = {
+    schemaVersion: 1,
+    roomId: "room_tasks",
+    appPack,
+    version: 4,
+    createdAt: 1,
+    updatedAt: 2,
+    members: {},
+    pluginVersions: {
+      "@mh-gg/plugin-roles": "1.0.0",
+      "@mh-gg/plugin-tasks": "0.9.0"
+    },
+    plugins: {
+      "@mh-gg/plugin-roles": { permissions: { admin: ["tasks.task.create"] } },
+      "@mh-gg/plugin-tasks": { taskOrder: ["old"], tasks: { old: { id: "old", title: "Old", done: false } } }
+    },
+    seenOperations: ["a", "b", "c"]
+  };
+  const migratedTasks = {
+    ...tasksPlugin(),
+    version: "1.0.0",
+    migrations: {
+      "0.9.0->1.0.0"(_ctx, state) {
+        return { ...state, migrated: true };
+      }
+    },
+    schemas: {
+      ...tasksPlugin().schemas,
+      state: schema((state) => {
+        assert.ok(Array.isArray(state.taskOrder));
+        assert.equal(typeof state.tasks, "object");
+        assert.equal(state.migrated, true);
+        return state;
+      })
+    },
+    queries: {
+      taskCount(_ctx, state) {
+        return { count: state.taskOrder.length };
+      }
+    }
+  };
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), migratedTasks],
+    store: createMemoryRoomStore(oldState),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (auth, actor) => actor
+  });
+
+  const state = await runtime.start();
+  assert.equal(state.plugins["@mh-gg/plugin-tasks"].migrated, true);
+  assert.equal(state.pluginVersions["@mh-gg/plugin-tasks"], "1.0.0");
+  assert.deepEqual(await runtime.query("@mh-gg/plugin-tasks", "taskCount", {}, { role: "admin" }), { count: 1 });
+  const info = await runtime.roomInfo();
+  assert.equal(info.type, "room/info");
+  assert.equal(info.appPack.id, appPack.id);
+  assert.equal(info.plugins.some((plugin) => plugin.id === "@mh-gg/plugin-tasks"), true);
+});
+
+test("migrates existing state to the current same-app pack hash", async () => {
+  const store = createMemoryRoomStore({
+    schemaVersion: 1,
+    roomId: "room_upgrade",
+    appPack: { ...appPack, hash: "sha256-old-app" },
+    version: 1,
+    createdAt: 1,
+    updatedAt: 2,
+    members: {},
+    revokedCredentialIds: [],
+    pluginVersions: { [tasksPlugin().id]: "1.0.0" },
+    plugins: { [tasksPlugin().id]: { taskOrder: [], tasks: {} } },
+    seenOperations: []
+  });
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_upgrade", appPack },
+    plugins: [tasksPlugin()],
+    store,
+    authenticateActor: async (_auth, opActor) => opActor
+  });
+
+  const state = await runtime.getState();
+
+  assert.equal(state.appPack.id, appPack.id);
+  assert.equal(state.appPack.hash, appPack.hash);
+});
+
+test("installs host packs from pinned app packs and plugin registries", () => {
+  const hostPlugin = { ...tasksPlugin(), integrity: "sha256-plugin" };
+  const hostPack = {
+    kind: "matterhorn.host-pack",
+    id: "com.matterhorn.tasks.host",
+    appPackId: appPack.id,
+    version: "1.0.0",
+    plugins: [{ id: hostPlugin.id, version: hostPlugin.version, source: "registry:tasks", integrity: hostPlugin.integrity }],
+    compatibility: { appProtocolHash: appPack.protocolHash, pluginGraphHash: "sha256-plugin-graph" },
+    runtime: { minMatterhornVersion: "0.1.0", sandbox: "process" },
+    capabilities: { required: ["room.state"], optional: [] },
+    trust: { signatures: [{ publicKey: "pub", signature: "sig" }] }
+  };
+  const appPackManifest = {
+    kind: "matterhorn.app-pack",
+    id: appPack.id,
+    name: "Tasks",
+    version: appPack.version,
+    publisher: { id: "pub", name: "Publisher", publicKey: "pub" },
+    matterhornVersion: ">=0.1 <0.2",
+    hostPack: { url: "registry:host", integrity: require("@mh-gg/base").manifestHash(hostPack) },
+    playerPacks: [{ id: "player", name: "Player", url: "registry:player", integrity: "sha256-player" }],
+    compatibility: { appProtocolHash: appPack.protocolHash, operationSchemaHash: "sha256-op", stateSchemaHash: "sha256-state" },
+    capabilities: { required: ["room.state"], optional: [] },
+    trust: { createdAt: "2026-05-27T00:00:00Z", signatures: [{ publicKey: "pub", signature: "sig" }] }
+  };
+  const install = installHostPack({ appPack: appPackManifest, hostPack, pluginRegistry: { [hostPlugin.id]: hostPlugin } });
+  assert.equal(install.plugins[0].id, hostPlugin.id);
+  assert.equal(install.roomAppPack.hash, require("@mh-gg/base").manifestHash(appPackManifest));
+  assert.throws(() => resolveHostPlugins(hostPack, {}), /not available/);
+});
+
+
+function taskHostPack(extra = {}) {
+  const pluginRef = {
+    id: "@mh-gg/plugin-tasks",
+    version: "1.0.0",
+    source: "workspace:tasks-plugin",
+    integrity: "sha256-plugin",
+    ...(extra.pluginRef || {})
+  };
+  const pack = {
+    kind: "matterhorn.host-pack",
+    id: "com.matterhorn.tasks.host",
+    appPackId: appPack.id,
+    version: "1.0.0",
+    plugins: [pluginRef, ...(extra.plugins || [])],
+    compatibility: {
+      appProtocolHash: appPack.protocolHash,
+      pluginGraphHash: "sha256-plugin-graph",
+      ...(extra.compatibility || {})
+    },
+    runtime: { minMatterhornVersion: "0.1.0", sandbox: "process", ...(extra.runtime || {}) },
+    capabilities: { required: ["room.state"], optional: [], ...(extra.capabilities || {}) },
+    trust: { signatures: [{ publicKey: "rk_pub", signature: "sig" }], ...(extra.trust || {}) },
+    ...extra.hostPack
+  };
+  return pack;
+}
+
+function taskAppPack(hostPack, extra = {}) {
+  return {
+    kind: "matterhorn.app-pack",
+    id: appPack.id,
+    name: "Tasks",
+    version: appPack.version,
+    publisher: { id: "com.matterhorn", name: "Matterhorn", publicKey: "rk_pub" },
+    matterhornVersion: ">=0.1 <0.2",
+    hostPack: { url: "workspace:tasks-host", integrity: manifestHash(hostPack) },
+    playerPacks: [{ id: "player", name: "Player", url: "workspace:player", integrity: "sha256-player" }],
+    compatibility: {
+      appProtocolHash: appPack.protocolHash,
+      operationSchemaHash: "sha256-ops",
+      stateSchemaHash: "sha256-state"
+    },
+    capabilities: { required: ["room.state"], optional: [] },
+    trust: { createdAt: "2026-05-27T00:00:00Z", signatures: [{ publicKey: "rk_pub", signature: "sig" }] },
+    ...extra
+  };
+}
+
+test("normalizes non-runtime failures into stable rejection payloads", () => {
+  const result = normalizeRuntimeFailure(new Error("plain failure"), "op_plain");
+  assert.deepEqual(result, {
+    ok: false,
+    code: "PLUGIN_FAILURE",
+    reason: "plain failure",
+    operationId: "op_plain"
+  });
+});
+
+test("rejects bad host plugin graphs before runtime creation", () => {
+  assert.throws(() => resolveHostPlugins(taskHostPack({
+    plugins: [{
+      id: "@mh-gg/plugin-extra",
+      version: "1.0.0",
+      source: "workspace:extra",
+      integrity: "sha256-extra",
+      dependsOn: [{ id: "@mh-gg/plugin-missing", version: "1.0.0" }]
+    }]
+  }), {
+    "@mh-gg/plugin-tasks": tasksPlugin(),
+    "@mh-gg/plugin-extra": { ...tasksPlugin(), id: "@mh-gg/plugin-extra", integrity: "sha256-extra" }
+  }), (error) => {
+    assert.equal(error.code, "PLUGIN_DEPENDENCY_MISSING");
+    return true;
+  });
+
+  assert.throws(() => resolveHostPlugins(taskHostPack({
+    plugins: [{
+      id: "@mh-gg/plugin-extra",
+      version: "1.0.0",
+      source: "workspace:extra",
+      integrity: "sha256-extra",
+      dependsOn: [{ id: "@mh-gg/plugin-tasks", version: "2.0.0" }]
+    }]
+  }), {
+    "@mh-gg/plugin-tasks": tasksPlugin(),
+    "@mh-gg/plugin-extra": { ...tasksPlugin(), id: "@mh-gg/plugin-extra", integrity: "sha256-extra" }
+  }), (error) => {
+    assert.equal(error.code, "PLUGIN_DEPENDENCY_VERSION");
+    return true;
+  });
+
+  assert.throws(() => resolveHostPlugins(taskHostPack({
+    plugins: [{
+      id: "@mh-gg/plugin-extra",
+      version: "1.0.0",
+      source: "workspace:extra",
+      integrity: "sha256-extra",
+      conflictsWith: ["@mh-gg/plugin-tasks"]
+    }]
+  }), {
+    "@mh-gg/plugin-tasks": tasksPlugin(),
+    "@mh-gg/plugin-extra": { ...tasksPlugin(), id: "@mh-gg/plugin-extra", integrity: "sha256-extra" }
+  }), (error) => {
+    assert.equal(error.code, "PLUGIN_CONFLICT");
+    return true;
+  });
+});
+
+test("installHostPack rejects app protocol mismatches and plugin integrity mismatches", () => {
+  const hostPack = taskHostPack({ compatibility: { appProtocolHash: "sha256-other-protocol" } });
+  assert.throws(() => installHostPack({ appPack: taskAppPack(hostPack), hostPack, pluginRegistry: { "@mh-gg/plugin-tasks": tasksPlugin() } }), (error) => {
+    assert.equal(error.code, "APP_PROTOCOL_MISMATCH");
+    return true;
+  });
+
+  const goodHostPack = taskHostPack();
+  assert.throws(() => installHostPack({
+    appPack: taskAppPack(goodHostPack),
+    hostPack: goodHostPack,
+    pluginRegistry: { "@mh-gg/plugin-tasks": { ...tasksPlugin(), integrity: "sha256-different" } }
+  }), (error) => {
+    assert.equal(error.code, "PLUGIN_INTEGRITY_MISMATCH");
+    return true;
+  });
+});
+
+test("start lifecycle creates missing migrated plugin state and isolates migration failures", async () => {
+  const store = createMemoryRoomStore({
+    schemaVersion: 1,
+    roomId: "room_tasks",
+    appPack,
+    version: 0,
+    createdAt: 1,
+    updatedAt: 1,
+    members: {},
+    pluginVersions: { "@mh-gg/plugin-roles": "1.0.0" },
+    plugins: { "@mh-gg/plugin-roles": { permissions: {} } },
+    seenOperations: []
+  });
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [rolesPlugin(), tasksPlugin()],
+    store,
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+  const state = await runtime.start();
+  assert.deepEqual(state.plugins["@mh-gg/plugin-tasks"], { taskOrder: [], tasks: {} });
+
+  const failingMigrationPlugin = {
+    ...tasksPlugin(),
+    migrations: {
+      "0.9.0->1.0.0"() {
+        throw new Error("bad migration");
+      }
+    }
+  };
+  const failingStore = createMemoryRoomStore({
+    schemaVersion: 1,
+    roomId: "room_tasks",
+    appPack,
+    version: 0,
+    createdAt: 1,
+    updatedAt: 1,
+    members: {},
+    pluginVersions: { "@mh-gg/plugin-tasks": "0.9.0" },
+    plugins: { "@mh-gg/plugin-tasks": { taskOrder: [], tasks: {} } },
+    seenOperations: []
+  });
+  const failingRuntime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [failingMigrationPlugin],
+    store: failingStore,
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+  await assert.rejects(() => failingRuntime.start(), (error) => {
+    assert.equal(error.code, "MIGRATION_FAILED");
+    return true;
+  });
+});
+
+test("start lifecycle does not save or mutate persisted state when migration startup fails", async () => {
+  const persistedState = {
+    schemaVersion: 1,
+    roomId: "room_tasks",
+    appPack: { ...appPack, hash: "sha256-old-app" },
+    version: 3,
+    createdAt: 1,
+    updatedAt: 2,
+    members: {},
+    revokedCredentialIds: [],
+    pluginVersions: { "@mh-gg/plugin-tasks": "1.0.0" },
+    plugins: {
+      "@mh-gg/plugin-tasks": {
+        taskOrder: ["task_existing"],
+        tasks: {
+          task_existing: {
+            id: "task_existing",
+            title: "Keep me",
+            done: false,
+            createdBy: "admin",
+            createdAt: 1
+          }
+        }
+      }
+    },
+    seenOperations: ["op_existing"]
+  };
+  const store = {
+    saveCalls: 0,
+    async load() {
+      return persistedState;
+    },
+    async save(nextState) {
+      this.saveCalls += 1;
+      this.saved = nextState;
+    }
+  };
+  const failingInstallPlugin = {
+    id: "@mh-gg/plugin-failing-install",
+    version: "1.0.0",
+    operationSchemaDescriptor: createOperationSchemaDescriptor({ plugin: "@mh-gg/plugin-failing-install", version: "1.0.0", operations: {} }),
+    schemas: {
+      state: schema((state) => state),
+      operations: {}
+    },
+    createInitialState(ctx) {
+      ctx.roomState.plugins["@mh-gg/plugin-tasks"].taskOrder.push("mutated-before-failure");
+      throw new Error("extra plugin initial state failed");
+    },
+    authorize() {
+      return deny("no operations");
+    },
+    reduce(ctx, state) {
+      return state;
+    }
+  };
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [tasksPlugin(), failingInstallPlugin],
+    store,
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+
+  await assert.rejects(() => runtime.start(), /extra plugin initial state failed/);
+
+  assert.equal(store.saveCalls, 0);
+  assert.equal(store.saved, undefined);
+  assert.deepEqual(persistedState.plugins["@mh-gg/plugin-tasks"].taskOrder, ["task_existing"]);
+  assert.equal(persistedState.plugins["@mh-gg/plugin-failing-install"], undefined);
+  assert.equal(persistedState.pluginVersions["@mh-gg/plugin-failing-install"], undefined);
+  assert.equal(persistedState.appPack.hash, "sha256-old-app");
+});
+
+test("lifecycle hooks, snapshots, operation fallbacks, and room info expose plugin packs", async () => {
+  let stopped = false;
+  const playerPack = {
+    kind: "matterhorn.player-pack",
+    id: "com.matterhorn.tasks.player",
+    name: "Tasks Player",
+    version: "1.0.0",
+    publisher: { id: "com.matterhorn", name: "Matterhorn", publicKey: "rk_pub" },
+    entrypoints: { default: "./player.js" },
+    supports: [{ appPackId: appPack.id, appPackRange: ">=1.0.0", appProtocolHash: appPack.protocolHash }],
+    mode: "embedded",
+    trust: { signatures: [{ publicKey: "rk_pub", signature: "sig" }] }
+  };
+  const hostPack = taskHostPack();
+  const fallbackLog = {
+    entries: [],
+    async append(entry) { this.entries.push(entry); return entry; }
+  };
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    hostPack,
+    playerPacks: [playerPack],
+    plugins: [rolesPlugin(), { ...tasksPlugin(), onRoomStop() { stopped = true; } }],
+    store: createMemoryRoomStore(),
+    operationLog: fallbackLog,
+    operationPublicKey: "op_pub",
+    authenticateActor: async (_auth, actor) => actor,
+    now: () => 42
+  });
+  await runtime.start();
+  await runtime.handleOperation(operation());
+  assert.equal((await runtime.operations()).length, 1);
+  const batch = await runtime.operationBatchSince(0);
+  assert.equal(batch.operations.length, 1);
+  const snapshot = await runtime.createSnapshot();
+  assert.equal(snapshot.createdAt, 42);
+  const info = await runtime.roomInfo();
+  assert.equal(info.hostPack.id, hostPack.id);
+  assert.equal(info.playerRecommendations[0].id, playerPack.id);
+  assert.equal(info.operationPublicKey, "op_pub");
+  await runtime.stop();
+  assert.equal(stopped, true);
+});
+
+test("runs stop and uninstall lifecycle hooks in reverse order and reports failing plugins", async () => {
+  const calls = [];
+  function lifecyclePlugin(id, hooks = {}) {
+    return {
+      id,
+      version: "1.0.0",
+      operationSchemaDescriptor: createOperationSchemaDescriptor({ plugin: id, version: "1.0.0", operations: {} }),
+      schemas: {
+        state: schema((state) => {
+          assert.equal(typeof state.ready, "boolean");
+          return state;
+        }),
+        operations: {}
+      },
+      createInitialState() {
+        return { ready: true };
+      },
+      authorize() {
+        return deny();
+      },
+      reduce(_ctx, state) {
+        return state;
+      },
+      onInstall: hooks.onInstall || (() => calls.push(`${id}:install`)),
+      onRoomStart: hooks.onRoomStart || (() => calls.push(`${id}:start`)),
+      afterStart: hooks.afterStart || (() => calls.push(`${id}:afterStart`)),
+      onRoomStop: hooks.onRoomStop || (() => calls.push(`${id}:stop`)),
+      onUninstall: hooks.onUninstall || (() => calls.push(`${id}:uninstall`))
+    };
+  }
+
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [lifecyclePlugin("base"), lifecyclePlugin("child")],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+  await runtime.start();
+  await runtime.stop();
+  await runtime.uninstall();
+  assert.deepEqual(calls, [
+    "base:install",
+    "child:install",
+    "base:start",
+    "child:start",
+    "base:afterStart",
+    "child:afterStart",
+    "child:stop",
+    "base:stop",
+    "child:uninstall",
+    "base:uninstall"
+  ]);
+
+  const failingRuntime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [lifecyclePlugin("ok"), lifecyclePlugin("bad", {
+      onRoomStop() {
+        throw new Error("stop failed");
+      }
+    })],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+  await failingRuntime.start();
+  await assert.rejects(() => failingRuntime.stop(), (error) => {
+    assert.equal(error.code, "LIFECYCLE_HOOK_FAILED");
+    assert.match(error.message, /bad\.onRoomStop failed/);
+    return true;
+  });
+});
+
+test("installAppPack and startRoomHost wire workspace manifests into a runnable host", async () => {
+  const hostPack = taskHostPack();
+  const appManifest = taskAppPack(hostPack);
+  const graphSafeTasks = { ...tasksPlugin(), stateSchemaHash: "sha256-state", operationSchemaHash: "sha256-ops" };
+  const installed = await installAppPack({ url: "workspace:tasks-app", integrity: manifestHash(appManifest) }, {
+    workspace: {
+      "workspace:tasks-app": appManifest,
+      "tasks-app": appManifest,
+      "workspace:tasks-host": hostPack,
+      "tasks-host": hostPack
+    },
+    pluginRegistry: { "@mh-gg/plugin-tasks": graphSafeTasks },
+    skipPluginGraphHash: true
+  });
+  assert.equal(installed.plugins[0].id, "@mh-gg/plugin-tasks");
+
+  const calls = [];
+  const started = await startRoomHost({
+    installed,
+    roomName: "room_tasks",
+    authenticateActor: async (_auth, actor) => actor,
+    store: createMemoryRoomStore(),
+    relay: { async registerRoom(input) { calls.push(input); } },
+    createInviteUrl: ({ room }) => `matterhorn://custom/${room.id}`
+  });
+  assert.equal(started.room.id, "room_tasks");
+  assert.equal(started.inviteUrl, "matterhorn://custom/room_tasks");
+  assert.equal(calls[0].room.id, "room_tasks");
+  assert.equal(calls[0].appPack.id, appManifest.id);
+  assert.equal(calls[0].hostPack.id, hostPack.id);
+  assert.equal(calls[0].plugins[0].id, "@mh-gg/plugin-tasks");
+  assert.equal(calls[0].state.roomId, "room_tasks");
+  assert.deepEqual(calls[0].operations, []);
+  assert.equal((await started.runtime.getState()).roomId, "room_tasks");
+
+  await assert.rejects(() => startRoomHost({ installed }), (error) => {
+    assert.equal(error.code, "INVALID_ROOM");
+    return true;
+  });
+  await assert.rejects(() => startRoomHost({
+    installed,
+    roomName: "room_tasks",
+    relay: { async registerRoom() { throw new Error("relay down"); } }
+  }), (error) => {
+    assert.equal(error.code, "RELAY_REGISTRATION_FAILED");
+    return true;
+  });
+});
+
+test("startRoomHost production role-key grants reject unsigned grants by default", async () => {
+  const hostPack = taskHostPack();
+  const appManifest = taskAppPack(hostPack);
+  const installed = installHostPack({
+    appPack: appManifest,
+    hostPack,
+    pluginRegistry: { "@mh-gg/plugin-tasks": tasksPlugin() },
+    skipPluginGraphHash: true
+  });
+  const operationLog = createMemoryOperationLog();
+  const roleKey = generateOperationRoleKeyPair({ role: "admin" });
+  const grant = createOperationRoleKeyGrant({
+    roomId: "room_tasks",
+    appPackId: installed.roomAppPack.id,
+    appPackHash: installed.roomAppPack.hash,
+    credentialId: "cred_prod_unsigned",
+    memberId: "admin",
+    deviceId: "dev_admin",
+    role: "admin",
+    publicKeyPem: roleKey.publicKeyPem,
+    issuedAt: 1
+  });
+  const started = await startRoomHost({
+    installed,
+    roomName: "room_tasks",
+    productionRuntime: true,
+    initialOwners: ["admin"],
+    store: createAtomicMemoryStore(null, operationLog),
+    operationLog,
+    operationRoleKeyGrants: [grant]
+  });
+  const signed = signOperationWithRoleKey(operation({
+    id: "op_unsigned_prod_host",
+    appPackId: installed.roomAppPack.id,
+    appPackHash: installed.roomAppPack.hash,
+    auth: { credentialId: grant.credentialId },
+    actor: { memberId: "admin", deviceId: "dev_admin", role: "admin" }
+  }), {
+    grant,
+    privateKeyPem: roleKey.privateKeyPem,
+    issuedAt: 1000
+  });
+
+  const result = await started.runtime.handleOperation(signed);
+
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /signed|authority/i);
+  assert.equal(operationLog.entries.length, 0);
+});
+
+test("runMigrations reports unchanged stores and rejects unparseable initial state", async () => {
+  const hostPack = taskHostPack();
+  const installed = installHostPack({ appPack: taskAppPack(hostPack), hostPack, pluginRegistry: { "@mh-gg/plugin-tasks": tasksPlugin() } });
+  assert.deepEqual(await runMigrations(createMemoryRoomStore(), installed), { ok: true, migrated: [] });
+  const oldHashStore = createMemoryRoomStore({
+    schemaVersion: 1,
+    roomId: "room_tasks",
+    appPack: { ...installed.roomAppPack, hash: "sha256-old-task-schema" },
+    version: 1,
+    createdAt: 1,
+    updatedAt: 2,
+    members: {},
+    revokedCredentialIds: [],
+    pluginVersions: { "@mh-gg/plugin-tasks": "1.0.0" },
+    plugins: { "@mh-gg/plugin-tasks": { taskOrder: [], tasks: {} } },
+    seenOperations: []
+  });
+  const migrated = await runMigrations(oldHashStore, installed, { room: { id: "room_tasks", appPack: installed.roomAppPack } });
+  assert.equal(migrated.state.appPack.hash, installed.roomAppPack.hash);
+  assert.equal((await oldHashStore.load()).appPack.hash, installed.roomAppPack.hash);
+
+  const badPlugin = {
+    ...tasksPlugin(),
+    createInitialState() {
+      return null;
+    }
+  };
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_tasks", appPack },
+    plugins: [badPlugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+  await assert.rejects(() => runtime.start(), (error) => {
+    assert.equal(error.code, "SCHEMA_INVALID");
+    return true;
+  });
+});