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

package/src/pluginRuntimeHost.cjs

@@ -0,0 +1,779 @@
+const { manifestHash } = require("@mh-gg/base");
+const { canonicalJson, createRoleKeyAuthenticator, operationKeyRoleToActorRole, publicOperationGrantAuthorities, publicOperationRoleKeyGrants, verifyOperationRoleKeyGrant } = require("@mh-gg/host-runtime");
+const {
+  HostPluginRuntime,
+  createMemoryOperationLog,
+  createMemoryRoomStore
+} = require("@mh-gg/host-runtime");
+const { safeValidate, validateRoomOperation, verifyRoomDeviceSignedOperation } = require("@mh-gg/protocol");
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function roomStateVersion(state) {
+  return Number.isInteger(state?.version) ? state.version : -1;
+}
+
+function roomStateUpdatedAt(state) {
+  return Number(state?.updatedAt || state?.createdAt || 0);
+}
+
+function isNewerRoomState(candidate, current) {
+  const candidateVersion = roomStateVersion(candidate);
+  const currentVersion = roomStateVersion(current);
+  if (candidateVersion !== currentVersion) return candidateVersion > currentVersion;
+  return roomStateUpdatedAt(candidate) > roomStateUpdatedAt(current);
+}
+
+function appPackForRoom(input) {
+  const appPack = input.room?.appPack || input.appPack || input.installed?.roomAppPack || input.installed?.appPack;
+  if (!appPack?.id) throw new Error("Relay room composition requires an app pack");
+  return {
+    id: appPack.id,
+    version: appPack.version,
+    hash: appPack.hash || manifestHash(appPack),
+    protocolHash: appPack.protocolHash || appPack.compatibility?.appProtocolHash,
+    ...(appPack.matterhorn ? { matterhorn: clone(appPack.matterhorn) } : {}),
+    ...(appPack.metadata ? { metadata: clone(appPack.metadata) } : {})
+  };
+}
+
+function roomForComposition(input) {
+  const roomName = input.roomName || input.room?.id || input.roomId;
+  if (typeof roomName !== "string" || roomName.length === 0) throw new Error("Relay room composition requires roomName");
+  return {
+    ...(input.room || {}),
+    id: roomName,
+    appPack: appPackForRoom(input),
+    hostPack: input.room?.hostPack || (input.hostPack ? {
+      id: input.hostPack.id,
+      version: input.hostPack.version,
+      hash: input.hostPack.hash || manifestHash(input.hostPack),
+      pluginGraphHash: input.hostPack.compatibility?.pluginGraphHash
+    } : undefined)
+  };
+}
+
+function appPackChanged(current, next) {
+  return Boolean(current?.id && next?.id && current.id === next.id && current.hash !== next.hash);
+}
+
+function pluginsCanRun(plugins = []) {
+  return plugins.every((plugin) =>
+    plugin &&
+    typeof plugin.createInitialState === "function" &&
+    typeof plugin.authorize === "function" &&
+    typeof plugin.reduce === "function"
+  );
+}
+
+function pluginListForComposition(input) {
+  const plugins = input.plugins || input.installed?.plugins;
+  if (!Array.isArray(plugins) || plugins.length === 0) throw new Error("Relay room composition requires at least one plugin");
+  return plugins;
+}
+
+function pluginRuntimeDescriptor(plugin) {
+  if (!plugin?.id) return undefined;
+  return {
+    id: plugin.id,
+    version: plugin.version,
+    operations: Object.keys(plugin.schemas?.operations || {}).sort(),
+    operationSchemaDescriptor: clone(plugin.operationSchemaDescriptor)
+  };
+}
+
+function pluginDescriptorsForComposition(input, plugins) {
+  const declared = input.expectedPlugins || input.operationDescriptorPlugins || input.installed?.expectedPlugins;
+  const source = Array.isArray(declared) && declared.length > 0 ? declared : plugins;
+  return source
+    .map((plugin) => {
+      if (plugin?.operations && plugin.id) {
+        return {
+          id: plugin.id,
+          version: plugin.version,
+          operations: plugin.operations.slice().sort(),
+          operationSchemaDescriptor: clone(plugin.operationSchemaDescriptor)
+        };
+      }
+      return pluginRuntimeDescriptor(plugin);
+    })
+    .filter(Boolean);
+}
+
+function defaultLogger() {
+  return { debug() {}, info() {}, warn() {}, error() {} };
+}
+
+function operationRoleKeyGrantsForInput(input = {}, options = {}) {
+  return input.operationRoleKeyGrants || input.operationKeyGrants || input.installed?.operationRoleKeyGrants || options.operationRoleKeyGrants || options.operationKeyGrants || undefined;
+}
+
+function operationGrantAuthoritiesForInput(input = {}, options = {}) {
+  return input.operationGrantAuthorities || input.grantAuthorities || input.installed?.operationGrantAuthorities || options.operationGrantAuthorities || options.grantAuthorities || undefined;
+}
+
+function allowUnsignedOperationRoleKeyGrants(input = {}, options = {}) {
+  return input.allowUnsignedOperationRoleKeyGrants === true || input.allowUnsignedRoleKeyGrants === true || options.allowUnsignedOperationRoleKeyGrants === true || options.allowUnsignedRoleKeyGrants === true;
+}
+
+function allowHistoricalAppPackHashes(input = {}, options = {}) {
+  if (input.allowHistoricalAppPackHashes !== undefined) return input.allowHistoricalAppPackHashes === true;
+  return options.allowHistoricalAppPackHashes !== false;
+}
+
+function grantArray(grants) {
+  if (!grants) return [];
+  if (Array.isArray(grants)) return grants;
+  if (grants instanceof Map) return [...grants.values()];
+  if (grants.kind === "matterhorn.operation-role-key-grant") return [grants];
+  return Object.values(grants);
+}
+
+function initialMembersFromGrants(grants = []) {
+  const members = {};
+  for (const grant of grantArray(grants)) {
+    if (!grant?.memberId) continue;
+    members[grant.memberId] = {
+      ...(members[grant.memberId] || {}),
+      id: grant.memberId,
+      role: operationKeyRoleToActorRole(grant.role),
+      credentialId: grant.credentialId,
+      deviceId: grant.deviceId
+    };
+  }
+  return members;
+}
+
+function validateRelayOperationRoleKeyGrants(input = {}, options = {}) {
+  const grants = operationRoleKeyGrantsForInput(input, options);
+  if (!grants) return { grants: undefined, authorities: operationGrantAuthoritiesForInput(input, options), requireSignedGrants: false };
+  const authorities = operationGrantAuthoritiesForInput(input, options);
+  const allowUnsigned = allowUnsignedOperationRoleKeyGrants(input, options);
+  const requireSignedGrants = !allowUnsigned;
+  if (requireSignedGrants && (!authorities || grantArray(authorities).length === 0)) {
+    throw new Error("Relay operation role-key grants require at least one trusted grant authority. Set allowUnsignedOperationRoleKeyGrants only for local development fixtures.");
+  }
+  const currentAppPackHash = input.appPack?.hash || (input.appPack ? manifestHash(input.appPack) : undefined) || input.room?.appPack?.hash || input.installed?.roomAppPack?.hash || input.installed?.appPack?.hash;
+  const allowHistoricalHashes = allowHistoricalAppPackHashes(input, options);
+  for (const grant of grantArray(grants)) {
+    const verified = verifyOperationRoleKeyGrant(grant, authorities, {
+      roomId: input.roomName || input.room?.id || input.roomId,
+      appPackId: input.appPack?.id || input.room?.appPack?.id || input.installed?.roomAppPack?.id || input.installed?.appPack?.id,
+      appPackHash: allowHistoricalHashes && grant?.appPackHash ? grant.appPackHash : currentAppPackHash,
+      now: input.now || options.now,
+      requireSignedGrants
+    });
+    if (!verified.ok) throw new Error(`Relay operation role-key grant is not trusted: ${verified.error}`);
+  }
+  return { grants, authorities, requireSignedGrants };
+}
+
+function authenticatorForRoom(input = {}, room, options = {}) {
+  if (input.authenticateActor) return input.authenticateActor;
+  if (options.authenticateActor) return options.authenticateActor;
+  const grantTrust = validateRelayOperationRoleKeyGrants(input, options);
+  const grants = grantTrust.grants;
+  if (grants) {
+    return createRoleKeyAuthenticator({
+      roomId: room.id,
+      appPackId: room.appPack.id,
+      appPackHash: room.appPack.hash,
+      grants,
+      grantAuthorities: grantTrust.authorities,
+      requireSignedGrants: grantTrust.requireSignedGrants,
+      acceptOperationAppPackHash: allowHistoricalAppPackHashes(input, options),
+      now: input.now || options.now
+    });
+  }
+  return async () => {
+    throw new Error("Relay plugin runtime authenticateActor is required");
+  };
+}
+
+function runtimeForEntry({
+  input,
+  room,
+  plugins,
+  store,
+  operationLog,
+  authenticateActor,
+  capabilities,
+  grantTrust,
+  logger,
+  now,
+  options
+}) {
+  return new HostPluginRuntime({
+    room,
+    hostPack: input.hostPack || input.installed?.hostPack || null,
+    playerPacks: input.playerPacks || input.installed?.playerPacks || [],
+    store,
+    operationLog,
+    plugins,
+    capabilities,
+    authenticateActor,
+    now: input.now || now,
+    logger,
+    allowHistoricalAppPackHashes: allowHistoricalAppPackHashes(input, options),
+    initialMembers: input.initialMembers || initialMembersFromGrants(grantTrust?.grants),
+    relayExecuted: options.productionRuntime === true || input.productionRuntime === true,
+    devUnsafeTrustActorRole: input.devUnsafeTrustActorRole === true || options.devUnsafeTrustActorRole === true,
+    strictStanding: input.strictStanding === undefined ? options.strictStanding : input.strictStanding
+  });
+}
+
+function normalizeOperationMessage(message) {
+  const operation = message?.operation || message;
+  const result = safeValidate(validateRoomOperation, operation);
+  if (!result.ok) {
+    return {
+      ok: false,
+      error: result.message || "Operation is invalid"
+    };
+  }
+  if (operation?.auth?.scheme === "matterhorn.device-signing.v1") {
+    const signature = verifyRoomDeviceSignedOperation(operation, operation.auth.claim);
+    if (!signature.ok) return { ok: false, error: signature.error || "Operation room-device signature is invalid" };
+  }
+  return { ok: true, operation };
+}
+
+function createHostMessage(type, roomName, body = {}) {
+  return {
+    type,
+    protocol: 1,
+    roomName,
+    ...body
+  };
+}
+
+function logRuntimeDecision(logger, status, context = {}) {
+  const payload = {
+    roomName: context.roomName,
+    operationId: context.operationId,
+    pluginId: context.pluginId,
+    operationType: context.operationType,
+    reason: context.reason,
+    relayDirection: context.relayDirection
+  };
+  const message = `relay runtime ${status}: ${payload.roomName || "unknown-room"} ${payload.operationId || "unknown-operation"}`;
+  if (status === "accepted") logger.info?.(message, payload);
+  else logger.warn?.(message, payload);
+}
+
+function operationCapability(pluginId, operationType) {
+  return { pluginId, type: operationType };
+}
+
+function runtimeCapabilityDocument(value) {
+  if (!value) {
+    return {
+      mode: "unavailable",
+      availablePlugins: [],
+      unavailablePlugins: [],
+      availableOperations: [],
+      unavailableOperations: []
+    };
+  }
+  const availablePluginIds = new Set(value.plugins.map((plugin) => plugin.id));
+  const descriptors = Array.isArray(value.pluginDescriptors) ? value.pluginDescriptors : value.plugins.map(pluginRuntimeDescriptor).filter(Boolean);
+  const availablePlugins = value.plugins.map((plugin) => ({ id: plugin.id, version: plugin.version }));
+  const unavailablePlugins = descriptors
+    .filter((plugin) => !availablePluginIds.has(plugin.id))
+    .map((plugin) => ({ id: plugin.id, version: plugin.version }));
+  const availableOperations = [];
+  const unavailableOperations = [];
+  for (const descriptor of descriptors) {
+    const target = availablePluginIds.has(descriptor.id) ? availableOperations : unavailableOperations;
+    for (const type of descriptor.operations || []) target.push(operationCapability(descriptor.id, type));
+  }
+  return {
+    mode: unavailablePlugins.length > 0 ? "partial" : "full",
+    availablePlugins,
+    unavailablePlugins,
+    availableOperations,
+    unavailableOperations
+  };
+}
+
+function resultWithCapabilityFailure(value, operation, result) {
+  if (!result || result.ok !== false) return result;
+  const missingPlugin = result.code === "PLUGIN_NOT_INSTALLED";
+  const unavailable = runtimeCapabilityDocument(value).unavailableOperations
+    .some((item) => item.pluginId === operation?.pluginId && item.type === operation?.type);
+  if (!missingPlugin && !unavailable) return result;
+  return {
+    ...result,
+    code: "PLUGIN_UNAVAILABLE",
+    reason: `Operation ${operation.pluginId}.${operation.type} is not available on this relay.`,
+    retryableWhenCapabilityAvailable: true
+  };
+}
+
+
+function normalizeSnapshotInput(incoming) {
+  if (incoming && typeof incoming === "object" && incoming.state && typeof incoming.state === "object") {
+    return { state: incoming.state, operations: Array.isArray(incoming.operations) ? incoming.operations : undefined };
+  }
+  return { state: incoming, operations: undefined };
+}
+
+function comparableRoomState(state) {
+  if (!state || typeof state !== "object") return state;
+  return {
+    roomId: state.roomId,
+    appPack: state.appPack,
+    version: state.version,
+    members: state.members,
+    pluginVersions: state.pluginVersions,
+    plugins: state.plugins,
+    seenOperations: state.seenOperations
+  };
+}
+
+function sameRoomState(left, right) {
+  return canonicalJson(comparableRoomState(left)) === canonicalJson(comparableRoomState(right));
+}
+
+function plainObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function hasMeaningfulData(value) {
+  if (value === null || value === undefined) return false;
+  if (Array.isArray(value)) return value.some(hasMeaningfulData);
+  if (typeof value === "object") return Object.values(value).some(hasMeaningfulData);
+  if (typeof value === "string") return value.length > 0;
+  return true;
+}
+
+function dropsMeaningfulObjectEntries(candidate, current) {
+  const candidateObject = plainObject(candidate);
+  for (const [key, value] of Object.entries(plainObject(current))) {
+    if (!hasMeaningfulData(value)) continue;
+    if (!Object.prototype.hasOwnProperty.call(candidateObject, key)) return true;
+    if (!hasMeaningfulData(candidateObject[key])) return true;
+  }
+  return false;
+}
+
+function isDestructiveRoomState(candidate, current) {
+  if (!current || typeof current !== "object") return false;
+  if (dropsMeaningfulObjectEntries(candidate?.plugins, current.plugins)) return true;
+  if (dropsMeaningfulObjectEntries(candidate?.members, current.members)) return true;
+  const currentSeen = Array.isArray(current.seenOperations) ? current.seenOperations : [];
+  const candidateSeen = Array.isArray(candidate?.seenOperations) ? candidate.seenOperations : [];
+  return currentSeen.length > 0 && candidateSeen.length < currentSeen.length;
+}
+
+function createTransactionalRoomStore(targetStore, initialState) {
+  let committed = false;
+  let staged = clone(initialState);
+  return {
+    async load() {
+      return committed ? await targetStore.load() : clone(staged);
+    },
+    async save(nextState) {
+      if (committed) {
+        await targetStore.save(clone(nextState));
+        return;
+      }
+      staged = clone(nextState);
+    },
+    async commit() {
+      await targetStore.save(clone(staged));
+      committed = true;
+      return clone(staged);
+    }
+  };
+}
+
+
+function operationForEnvelopeCompare(operation) {
+  const next = clone(operation);
+  delete next.ledgerId;
+  delete next.snowflakeId;
+  delete next.committedRoomVersion;
+  delete next.committedAt;
+  delete next.receivedAt;
+  delete next.relayId;
+  return next;
+}
+
+function operationsContainEnvelopeOperation(operations, operation) {
+  if (!Array.isArray(operations)) return false;
+  const expected = canonicalJson(operationForEnvelopeCompare(operation));
+  return operations.some((candidate) => canonicalJson(operationForEnvelopeCompare(candidate)) === expected);
+}
+
+async function verifySnapshotWithOperations(value, incomingState, operations = []) {
+  if (!Array.isArray(operations) || operations.length === 0) {
+    return { ok: false, reason: "snapshot-operation-proof-required" };
+  }
+  const baselineState = await value.runtime.getState();
+  const replayRuntime = new HostPluginRuntime({
+    room: value.room,
+    hostPack: value.hostPack,
+    playerPacks: [],
+    store: createMemoryRoomStore(baselineState),
+    operationLog: createMemoryOperationLog(),
+    plugins: value.plugins,
+    capabilities: [...value.runtime.capabilities],
+    authenticateActor: value.runtime.authenticateActor,
+    initialMembers: baselineState.members || {},
+    initialRevokedCredentialIds: baselineState.revokedCredentialIds || [],
+    strictStanding: value.runtime.strictStanding,
+    allowHistoricalAppPackHashes: true,
+    now: () => incomingState.createdAt || incomingState.updatedAt || Date.now(),
+    logger: value.runtime.logger
+  });
+  await replayRuntime.start();
+  for (const operation of operations) {
+    const result = await replayRuntime.handleOperation(operation);
+    if (!result.ok) return { ok: false, reason: `snapshot-operation-proof-invalid: ${result.reason || result.code || "operation rejected"}` };
+  }
+  const replayed = await replayRuntime.getState();
+  if (!sameRoomState(replayed, incomingState)) return { ok: false, reason: "snapshot-operation-proof-mismatch" };
+  return { ok: true, state: replayed };
+}
+
+function createRelayPluginRuntimeManager(options = {}) {
+  const rooms = new Map();
+  const logger = options.logger || defaultLogger();
+  const relayAddress = options.relayAddress || "relay-local";
+  const sendRelayEnvelope = options.sendRelayEnvelope || (() => 0);
+  const now = options.now || (() => Date.now());
+  let messageSeq = 0;
+
+  function nextMessageId(type = "relay.matterhorn") {
+    messageSeq += 1;
+    return `${relayAddress}:${type}:${now()}:${messageSeq}`;
+  }
+
+  function entry(roomName) {
+    return rooms.get(roomName);
+  }
+
+  async function startEntry(entryValue) {
+    await entryValue.runtime.start();
+    return entryValue;
+  }
+
+  async function replaceEntryRuntime(existing, input, room, plugins, grantTrust) {
+    const previousState = await existing.store.load();
+    const stagedStore = createTransactionalRoomStore(existing.store, previousState);
+    const authenticateActor = (input.authenticateActor || options.authenticateActor || operationRoleKeyGrantsForInput(input, options))
+      ? authenticatorForRoom(input, room, options)
+      : existing.runtime.authenticateActor;
+    const runtime = runtimeForEntry({
+      input,
+      room,
+      plugins,
+      store: stagedStore,
+      operationLog: existing.operationLog,
+      authenticateActor,
+      capabilities: input.capabilities || input.hostPack?.capabilities?.required || input.installed?.hostPack?.capabilities?.required || [...existing.runtime.capabilities],
+      grantTrust,
+      logger,
+      now,
+      options
+    });
+    await runtime.start();
+    await stagedStore.commit();
+    existing.room = room;
+    existing.hostPack = input.hostPack || input.installed?.hostPack || null;
+    existing.plugins = plugins;
+    existing.pluginDescriptors = pluginDescriptorsForComposition(input, plugins);
+    existing.operationRoleKeyGrants = publicOperationRoleKeyGrants(grantTrust.grants || []);
+    existing.operationGrantAuthorities = publicOperationGrantAuthorities(grantTrust.authorities || []);
+    existing.requireSignedOperationRoleKeyGrants = grantTrust.requireSignedGrants;
+    existing.runtime = runtime;
+    return existing;
+  }
+
+  async function enableRoomComposition(input = {}) {
+    const room = roomForComposition(input);
+    const roomName = room.id;
+    const plugins = pluginListForComposition(input);
+    const existing = rooms.get(roomName);
+    if (existing) {
+      if (input.roomApp) existing.roomApp = clone(input.roomApp);
+      existing.pluginDescriptors = pluginDescriptorsForComposition(input, plugins);
+      if (appPackChanged(existing.room.appPack, room.appPack) || !pluginsCanRun(existing.plugins)) {
+        const grantTrust = validateRelayOperationRoleKeyGrants(input, options);
+        await replaceEntryRuntime(existing, input, room, plugins, grantTrust);
+      }
+      const incomingState = input.state || input.snapshot;
+      if (incomingState) await syncSnapshot(roomName, incomingState, { trusted: true });
+      return existing;
+    }
+
+    const grantTrust = validateRelayOperationRoleKeyGrants(input, options);
+    const store = input.store || createMemoryRoomStore(input.state || input.snapshot || null);
+    const operationLog = input.operationLog || createMemoryOperationLog(input.operations || []);
+    const runtime = runtimeForEntry({
+      input,
+      room,
+      store,
+      operationLog,
+      plugins,
+      authenticateActor: authenticatorForRoom(input, room, options),
+      capabilities: input.capabilities || input.hostPack?.capabilities?.required || input.installed?.hostPack?.capabilities?.required || [],
+      grantTrust,
+      logger,
+      now,
+      options
+    });
+    const created = {
+      roomName,
+      room,
+      hostPack: input.hostPack || input.installed?.hostPack || null,
+      plugins,
+      pluginDescriptors: pluginDescriptorsForComposition(input, plugins),
+      runtime,
+      store,
+      operationLog,
+      roomApp: clone(input.roomApp || {}),
+      operationRoleKeyGrants: publicOperationRoleKeyGrants(grantTrust.grants || []),
+      operationGrantAuthorities: publicOperationGrantAuthorities(grantTrust.authorities || []),
+      requireSignedOperationRoleKeyGrants: grantTrust.requireSignedGrants,
+      relayAddress,
+      enabledAt: now()
+    };
+    await startEntry(created);
+    rooms.set(roomName, created);
+    return created;
+  }
+
+  function hasRoom(roomName) {
+    return rooms.has(roomName);
+  }
+
+  function enabledPlugins(roomName) {
+    const value = entry(roomName);
+    return value ? value.plugins.map((plugin) => ({ id: plugin.id, version: plugin.version, meta: clone(plugin.meta) })) : [];
+  }
+
+  function roomApp(roomName) {
+    const value = entry(roomName);
+    if (!value) return undefined;
+    const appPack = {
+      id: value.room.appPack.id,
+      version: value.room.appPack.version,
+      hash: value.room.appPack.hash,
+      protocolHash: value.room.appPack.protocolHash,
+      ...(value.room.appPack.matterhorn ? { matterhorn: clone(value.room.appPack.matterhorn) } : {}),
+      ...(value.room.appPack.metadata ? { metadata: clone(value.room.appPack.metadata) } : {})
+    };
+    const extras = clone(value.roomApp || {});
+    const roomAppPack = extras.appPack ? { ...extras.appPack, ...appPack } : appPack;
+    return {
+      ...extras,
+      id: value.room.appPack.id,
+      version: value.room.appPack.version,
+      hash: value.room.appPack.hash,
+      protocolHash: value.room.appPack.protocolHash,
+      appPack: roomAppPack,
+      hostPack: value.room.hostPack || extras.hostPack,
+      plugins: enabledPlugins(roomName),
+      operationAuth: {
+        kind: "matterhorn.operation-role-keyring",
+        version: 1,
+        grants: publicOperationRoleKeyGrants(value.operationRoleKeyGrants || []),
+        authorities: publicOperationGrantAuthorities(value.operationGrantAuthorities || []),
+        requireSignedGrants: value.requireSignedOperationRoleKeyGrants === true
+      },
+      runtimeCapabilities: runtimeCapabilityDocument(value)
+    };
+  }
+
+  function runtimeCapabilities(roomName) {
+    return runtimeCapabilityDocument(entry(roomName));
+  }
+
+  function updateRoomApp(roomName, nextRoomApp) {
+    const value = entry(roomName);
+    if (!value) return false;
+    value.roomApp = clone(nextRoomApp || {});
+    return true;
+  }
+
+  async function snapshot(roomName, actor) {
+    const value = entry(roomName);
+    if (!value) return undefined;
+    const state = actor ? await value.runtime.publicView(actor) : await value.runtime.getState();
+    return {
+      roomName,
+      room: clone(value.room),
+      roomApp: roomApp(roomName),
+      state,
+      operations: typeof value.operationLog.list === "function" ? await value.operationLog.list() : clone(value.operationLog.entries || [])
+    };
+  }
+
+  async function syncSnapshot(roomName, incomingSnapshot, options = {}) {
+    const value = entry(roomName);
+    if (!value) return { ok: false, updated: false, reason: "room-not-enabled" };
+    const { state: rawIncomingState, operations } = normalizeSnapshotInput(incomingSnapshot);
+    let incomingState = rawIncomingState;
+    if (!incomingState || typeof incomingState !== "object") return { ok: false, updated: false, reason: "snapshot-required" };
+    if (incomingState.roomId !== value.room.id) return { ok: false, updated: false, reason: "room-mismatch" };
+    if (incomingState.appPack?.id !== value.room.appPack.id) return { ok: false, updated: false, reason: "app-mismatch" };
+    if (incomingState.appPack?.hash !== value.room.appPack.hash) incomingState = { ...clone(incomingState), appPack: clone(value.room.appPack) };
+    try {
+      incomingState = await value.runtime.migrateExistingState(incomingState);
+    } catch (error) {
+      return { ok: false, updated: false, reason: error?.message || "snapshot-invalid" };
+    }
+    const current = await value.runtime.getState();
+    if (!isNewerRoomState(incomingState, current)) return { ok: true, updated: false, state: current };
+    const destructive = isDestructiveRoomState(incomingState, current);
+    const requiresProof = destructive || options.requireOperationProof === true || (value.requireSignedOperationRoleKeyGrants === true && options.trusted !== true);
+    if (requiresProof) {
+      const verified = await verifySnapshotWithOperations(value, incomingState, operations);
+      if (!verified.ok) return { ok: false, updated: false, reason: verified.reason };
+    }
+    await value.store.save(clone(incomingState));
+    if (Array.isArray(operations) && Array.isArray(value.operationLog?.entries)) {
+      value.operationLog.entries.splice(0, value.operationLog.entries.length, ...operations.map(clone));
+      await value.operationLog.persist?.();
+    }
+    return { ok: true, updated: true, state: await value.runtime.getState() };
+  }
+
+  async function handleClientOperation({ roomName, peerId, message, sendToClient, broadcastToRoom, broadcastToMesh = sendRelayEnvelope } = {}) {
+    const value = entry(roomName || message?.roomName);
+    if (!value) {
+      sendToClient?.(peerId, createHostMessage("host/error", roomName || message?.roomName, {
+        code: "room-runtime-unavailable",
+        message: "The relay has not enabled this room composition."
+      }));
+      logRuntimeDecision(logger, "rejected", {
+        roomName: roomName || message?.roomName,
+        operationId: message?.operation?.id,
+        reason: "room-runtime-unavailable",
+        relayDirection: "client"
+      });
+      return { ok: false, reason: "room-runtime-unavailable" };
+    }
+    const parsed = normalizeOperationMessage(message);
+    if (!parsed.ok) {
+      sendToClient?.(peerId, createHostMessage("host/error", value.roomName, {
+        code: "bad-operation",
+        message: parsed.error
+      }));
+      logRuntimeDecision(logger, "rejected", {
+        roomName: value.roomName,
+        operationId: message?.operation?.id,
+        reason: parsed.error,
+        relayDirection: "client"
+      });
+      return { ok: false, reason: parsed.error };
+    }
+    const result = resultWithCapabilityFailure(value, parsed.operation, await value.runtime.handleOperation(parsed.operation));
+    logRuntimeDecision(logger, result.ok ? "accepted" : "rejected", {
+      roomName: value.roomName,
+      operationId: parsed.operation.id,
+      pluginId: parsed.operation.pluginId,
+      operationType: parsed.operation.type,
+      reason: result.reason || result.code,
+      relayDirection: "client"
+    });
+    const state = await value.runtime.getState();
+    const actorState = await value.runtime.publicView(parsed.operation.actor);
+    const resultMessage = createHostMessage("host/operation-result", value.roomName, {
+      operationId: parsed.operation.id,
+      result,
+      state: actorState
+    });
+    sendToClient?.(peerId, resultMessage);
+    if (result.ok) {
+      const operations = typeof value.operationLog.list === "function" ? await value.operationLog.list() : [];
+      await broadcastToRoom?.(value.roomName, async (actor) => createHostMessage("host/matterhorn-state", value.roomName, {
+        acceptedOperationId: parsed.operation.id,
+        state: actor ? await value.runtime.publicView(actor) : state
+      }));
+      broadcastToMesh?.({
+        type: "relay.matterhorn-operation",
+        id: nextMessageId("relay.matterhorn-operation"),
+        roomName: value.roomName,
+        operation: parsed.operation,
+        state,
+        operations,
+        originRelay: relayAddress
+      });
+    }
+    return { ...result, state };
+  }
+
+  async function handleRelayOperation(message = {}) {
+    const value = entry(message.roomName);
+    if (!value) {
+      logRuntimeDecision(logger, "rejected", {
+        roomName: message.roomName,
+        operationId: message.operation?.id,
+        reason: "room-runtime-unavailable",
+        relayDirection: "relay"
+      });
+      return { ok: false, reason: "room-runtime-unavailable" };
+    }
+    const parsed = normalizeOperationMessage(message.operation);
+    if (!parsed.ok) {
+      logRuntimeDecision(logger, "rejected", {
+        roomName: message.roomName,
+        operationId: message.operation?.id,
+        reason: parsed.error,
+        relayDirection: "relay"
+      });
+      return { ok: false, reason: parsed.error };
+    }
+    if (parsed.operation.appPackId !== value.room.appPack.id) {
+      logRuntimeDecision(logger, "rejected", {
+        roomName: message.roomName,
+        operationId: parsed.operation.id,
+        pluginId: parsed.operation.pluginId,
+        operationType: parsed.operation.type,
+        reason: "app-mismatch",
+        relayDirection: "relay"
+      });
+      return { ok: false, ignored: true, code: "APP_PACK_MISMATCH", reason: "app-mismatch", state: await value.runtime.getState() };
+    }
+    const result = resultWithCapabilityFailure(value, parsed.operation, await value.runtime.handleOperation(parsed.operation));
+    logRuntimeDecision(logger, result.ok ? "accepted" : "rejected", {
+      roomName: message.roomName,
+      operationId: parsed.operation.id,
+      pluginId: parsed.operation.pluginId,
+      operationType: parsed.operation.type,
+      reason: result.reason || result.code,
+      relayDirection: "relay"
+    });
+    if (result.ok) return { ...result, state: await value.runtime.getState() };
+    if (message.state && Array.isArray(message.operations) && operationsContainEnvelopeOperation(message.operations, parsed.operation)) {
+      const synced = await syncSnapshot(message.roomName, { state: message.state, operations: message.operations });
+      if (synced.ok && synced.updated) return { ok: true, synced: true, acceptedOperationId: parsed.operation.id, state: await value.runtime.getState() };
+    }
+    return { ...result, state: await value.runtime.getState() };
+  }
+
+  return {
+    enableRoomComposition,
+    enabledPlugins,
+    get: entry,
+    handleClientOperation,
+    handleRelayOperation,
+    hasRoom,
+    roomApp,
+    rooms,
+    runtimeCapabilities,
+    snapshot,
+    syncSnapshot,
+    updateRoomApp
+  };
+}
+
+module.exports = {
+  createRelayPluginRuntimeManager,
+  isNewerRoomState
+};