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

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@mh-gg/host-runtime",
+  "version": "0.1.1-alpha.20260613T085325975Z",
+  "description": "Authoritative Matterhorn host plugin runtime.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "dependencies": {
+    "@mh-gg/event": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/authority": "^0.1.1-alpha.20260603T124500153Z",
+    "@mh-gg/base": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/protocol": "^0.1.1-alpha.20260613T085325975Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=75 --test-coverage-include=src/**/*.cjs test/*.test.cjs"
+  }
+}

package/src/constants.cjs

@@ -0,0 +1,9 @@
+const ROOM_STATE_SCHEMA_VERSION = 1;
+const DEFAULT_MAX_SEEN_OPERATIONS = 500;
+const DEFAULT_MAX_ACKS = 500;
+
+module.exports = {
+  DEFAULT_MAX_ACKS,
+  DEFAULT_MAX_SEEN_OPERATIONS,
+  ROOM_STATE_SCHEMA_VERSION
+};

package/src/errors.cjs

@@ -0,0 +1,39 @@
+class MatterhornRuntimeError extends Error {
+  constructor(code, message) {
+    super(message || code);
+    this.name = "MatterhornRuntimeError";
+    this.code = code;
+  }
+}
+
+function runtimeError(code, message) {
+  return new MatterhornRuntimeError(code, message);
+}
+
+function allow(details = {}) {
+  return { ok: true, ...details };
+}
+
+function deny(reason = "Forbidden") {
+  return { ok: false, reason };
+}
+
+function normalizeRuntimeFailure(error, operationId) {
+  if (error instanceof MatterhornRuntimeError) {
+    return { ok: false, code: error.code, reason: error.message, ...(operationId ? { operationId } : {}) };
+  }
+  return {
+    ok: false,
+    code: "PLUGIN_FAILURE",
+    reason: error?.message || String(error || "Plugin failed"),
+    ...(operationId ? { operationId } : {})
+  };
+}
+
+module.exports = {
+  MatterhornRuntimeError,
+  allow,
+  deny,
+  normalizeRuntimeFailure,
+  runtimeError
+};

package/src/host/installAppPack.cjs

@@ -0,0 +1,35 @@
+const {
+  assertProductionPluginGates,
+  assertTrustedManifest,
+  loadPackReference,
+  resolvePluginGraph,
+  validateAppPackManifest,
+  validateHostPackManifest
+} = require("@mh-gg/base");
+const { runtimeError } = require("../errors.cjs");
+const { installHostPack } = require("../plugins/install.cjs");
+
+async function installAppPack(appPackRef, options = {}) {
+  const appPack = validateAppPackManifest(await loadPackReference(appPackRef, options));
+  if (options.trustStore) assertTrustedManifest(appPack, options.trustStore, { requireSignature: options.requireSignature });
+  const hostPack = validateHostPackManifest(await loadPackReference(appPack.hostPack, options));
+  const installed = installHostPack({ appPack, hostPack, pluginRegistry: options.pluginRegistry });
+  const graph = resolvePluginGraph(installed.plugins);
+  if (hostPack.compatibility.pluginGraphHash !== graph.pluginGraphHash && options.skipPluginGraphHash !== true) {
+    throw runtimeError("PLUGIN_GRAPH_HASH_MISMATCH", `Host pack plugin graph hash mismatch: expected ${hostPack.compatibility.pluginGraphHash}, got ${graph.pluginGraphHash}`);
+  }
+  if (options.production) {
+    assertProductionPluginGates({
+      hostPack,
+      publisher: appPack.publisher,
+      trustStore: options.trustStore,
+      requireSignature: options.requireSignature,
+      availableCapabilities: options.availableCapabilities || hostPack.capabilities.required,
+      allowUnsafeSandbox: options.allowUnsafeSandbox,
+      allowMissingCapabilities: options.allowMissingCapabilities
+    });
+  }
+  return { ...installed, plugins: graph.plugins, pluginGraph: graph };
+}
+
+module.exports = { installAppPack };

package/src/host/migrations.cjs

@@ -0,0 +1,21 @@
+const { createMemoryOperationLog } = require("../memory.cjs");
+const { HostPluginRuntime } = require("../runtime/HostPluginRuntime.cjs");
+
+async function runMigrations(store, installed, options = {}) {
+  const state = await store.load();
+  if (!state) return { ok: true, migrated: [] };
+  const runtime = new HostPluginRuntime({
+    room: options.room || { id: state.roomId || "room", appPack: installed.roomAppPack },
+    store,
+    plugins: installed.plugins,
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor,
+    capabilities: options.capabilities || installed.hostPack?.capabilities?.required || []
+  });
+  const migratedState = await runtime.migrateExistingState(state);
+  const changed = JSON.stringify(migratedState) !== JSON.stringify(state);
+  if (changed) await store.save(migratedState);
+  return { ok: true, migrated: changed ? Object.keys(migratedState.pluginVersions || {}) : [], state: migratedState };
+}
+
+module.exports = { runMigrations };

package/src/host/runtimeFromPack.cjs

@@ -0,0 +1,25 @@
+const { installHostPack } = require("../plugins/install.cjs");
+const { HostPluginRuntime } = require("../runtime/HostPluginRuntime.cjs");
+
+function pluginRegistryFromPlugins(plugins = []) {
+  return Object.fromEntries(plugins.flatMap((plugin) => [[plugin.id, plugin], [plugin.source, plugin]].filter((entry) => entry[0])));
+}
+
+function createHostPluginRuntimeFromPack(options = {}) {
+  const installed = installHostPack({
+    appPack: options.appPack,
+    hostPack: options.hostPack,
+    pluginRegistry: pluginRegistryFromPlugins(options.plugins)
+  });
+  return new HostPluginRuntime({
+    ...options,
+    room: {
+      ...(options.room || {}),
+      id: options.room?.id,
+      appPack: installed.roomAppPack
+    },
+    plugins: installed.plugins
+  });
+}
+
+module.exports = { createHostPluginRuntimeFromPack, pluginRegistryFromPlugins };

package/src/host/startRoomHost.cjs

@@ -0,0 +1,95 @@
+const { manifestHash } = require("@mh-gg/base");
+const { runtimeError } = require("../errors.cjs");
+const { createMemoryRoomStore } = require("../memory.cjs");
+const { HostPluginRuntime } = require("../runtime/HostPluginRuntime.cjs");
+const { createRoleKeyAuthenticator, grantArray, operationKeyRoleToActorRole } = require("../security/roleKeys/index.cjs");
+const { installAppPack } = require("./installAppPack.cjs");
+const { runMigrations } = require("./migrations.cjs");
+
+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;
+}
+
+async function startRoomHost(options = {}) {
+  const installed = options.installed || await installAppPack(options.appPackRef, options);
+  const roomId = options.room?.id || options.roomName;
+  if (!roomId) throw runtimeError("INVALID_ROOM", "roomName or room.id is required");
+  const room = {
+    ...(options.room || {}),
+    id: roomId,
+    appPack: installed.roomAppPack,
+    hostPack: {
+      id: installed.hostPack.id,
+      version: installed.hostPack.version,
+      hash: manifestHash(installed.hostPack),
+      pluginGraphHash: installed.hostPack.compatibility.pluginGraphHash
+    }
+  };
+  const store = options.store || createMemoryRoomStore();
+  const operationRoleKeyGrants = options.operationRoleKeyGrants || options.operationKeyGrants || installed.operationRoleKeyGrants;
+  const operationGrantAuthorities = options.operationGrantAuthorities || options.grantAuthorities || installed.operationGrantAuthorities;
+  const authenticateActor = options.authenticateActor || (operationRoleKeyGrants ? createRoleKeyAuthenticator({
+    roomId: room.id,
+    appPackId: room.appPack.id,
+    appPackHash: room.appPack.hash,
+    grants: operationRoleKeyGrants,
+    grantAuthorities: operationGrantAuthorities,
+    requireSignedGrants: options.requireSignedOperationRoleKeyGrants || options.requireSignedGrants,
+    allowUnsignedOperationRoleKeyGrants: options.allowUnsignedOperationRoleKeyGrants,
+    devUnsafeUnsignedOperationRoleKeyGrants: options.devUnsafeUnsignedOperationRoleKeyGrants,
+    productionRuntime: options.productionRuntime,
+    relayExecuted: options.relayExecuted,
+    now: options.now
+  }) : undefined);
+  await runMigrations(store, installed, { ...options, room });
+  const runtime = new HostPluginRuntime({
+    ...options,
+    authenticateActor,
+    room,
+    store,
+    plugins: installed.plugins,
+    capabilities: options.capabilities || installed.hostPack.capabilities.required,
+    playerPacks: options.playerPacks || [],
+    initialMembers: options.initialMembers || initialMembersFromGrants(operationRoleKeyGrants),
+    strictStanding: options.strictStanding
+  });
+  await runtime.start();
+  if (options.relay?.registerRoom) {
+    try {
+      await options.relay.registerRoom({
+        room,
+        runtime,
+        installed,
+        appPack: installed.roomAppPack,
+        hostPack: installed.hostPack,
+        plugins: installed.plugins,
+        operationRoleKeyGrants,
+        operationGrantAuthorities,
+        allowUnsignedOperationRoleKeyGrants: options.allowUnsignedOperationRoleKeyGrants,
+        state: await runtime.getState(),
+        operations: typeof runtime.operationLog?.list === "function" ? await runtime.operationLog.list() : []
+      });
+    } catch (error) {
+      throw runtimeError("RELAY_REGISTRATION_FAILED", error?.message || "Relay registration failed");
+    }
+  }
+  return {
+    room,
+    runtime,
+    installed,
+    inviteUrl: options.createInviteUrl ? options.createInviteUrl({ room, installed }) : `matterhorn://room/${encodeURIComponent(room.id)}?app=${encodeURIComponent(room.appPack.id)}&appHash=${encodeURIComponent(room.appPack.hash)}`
+  };
+}
+
+module.exports = { startRoomHost };

package/src/index.cjs

@@ -0,0 +1,23 @@
+module.exports = {
+  ...require("./constants.cjs"),
+  ...require("./errors.cjs"),
+  ...require("./memory.cjs"),
+  ...require("./state.cjs"),
+  ...require("./plugins/definition.cjs"),
+  ...require("./plugins/operationDescriptors.cjs"),
+  ...require("./plugins/install.cjs"),
+  ...require("./runtime/HostPluginRuntime.cjs"),
+  ...require("./host/installAppPack.cjs"),
+  ...require("./host/migrations.cjs"),
+  ...require("./host/runtimeFromPack.cjs"),
+  ...require("./host/startRoomHost.cjs"),
+  ...require("./security/roleKeys/index.cjs"),
+  ...require("./security/roles.cjs"),
+  ...require("./security/scopedRoles.cjs"),
+  ...require("@mh-gg/authority"),
+  ...require("./security/standingAuthority.cjs"),
+  ...require("./security/roomDeviceKeys.cjs"),
+  ...require("./security/authorization/coreGate.cjs"),
+  ...require("./runtime/directMessages.cjs"),
+  ...require("./runtime/readTags.cjs")
+};

package/src/memory.cjs

@@ -0,0 +1,81 @@
+const { clone } = require("./shared.cjs");
+
+function createMemoryRoomStore(initialState = null) {
+  let state = clone(initialState);
+  return {
+    async load() {
+      return clone(state);
+    },
+    async save(nextState) {
+      state = clone(nextState);
+    }
+  };
+}
+
+function createMemoryOperationLog(initialEntries = []) {
+  const entries = initialEntries.map(clone);
+  const operationIds = new Set();
+  for (const entry of entries) {
+    if (!entry?.id) continue;
+    if (operationIds.has(entry.id)) throw new Error(`Duplicate operation id ${entry.id}`);
+    operationIds.add(entry.id);
+  }
+  return {
+    entries,
+    async append(operation) {
+      if (operation?.id && operationIds.has(operation.id)) throw new Error(`Duplicate operation id ${operation.id}`);
+      if (operation?.id) operationIds.add(operation.id);
+      entries.push(clone(operation));
+    },
+    async removeById(operationId) {
+      const index = entries.findIndex((entry) => entry?.id === operationId);
+      if (index < 0) return false;
+      const [removed] = entries.splice(index, 1);
+      if (removed?.id) operationIds.delete(removed.id);
+      return true;
+    },
+    async list() {
+      return entries.map(clone);
+    },
+    async findById(operationId) {
+      const found = entries.find((entry) => entry.id === operationId);
+      return found ? clone(found) : null;
+    }
+  };
+}
+
+function createMemoryPluginStorage() {
+  const values = new Map();
+  return {
+    async get(key) {
+      return values.has(key) ? clone(values.get(key)) : null;
+    },
+    async put(key, value) {
+      values.set(key, clone(value));
+    },
+    async delete(key) {
+      values.delete(key);
+    }
+  };
+}
+
+function createMemoryPluginEvents() {
+  const events = [];
+  return {
+    async append(event) {
+      events.push(clone(event));
+    },
+    async query(filter = {}) {
+      return events
+        .filter((event) => Object.entries(filter).every(([key, value]) => value === undefined || event[key] === value))
+        .map(clone);
+    }
+  };
+}
+
+module.exports = {
+  createMemoryOperationLog,
+  createMemoryPluginEvents,
+  createMemoryPluginStorage,
+  createMemoryRoomStore
+};

package/src/plugins/definition.cjs

@@ -0,0 +1,19 @@
+const { runtimeError } = require("../errors.cjs");
+const { validatePluginOperationDescriptors } = require("./operationDescriptors.cjs");
+
+function validatePlugin(plugin) {
+  if (!plugin || typeof plugin !== "object") throw runtimeError("INVALID_PLUGIN", "Plugin must be an object");
+  if (!plugin.id || !plugin.version) throw runtimeError("INVALID_PLUGIN", "Plugin id and version are required");
+  if (typeof plugin.createInitialState !== "function") throw runtimeError("INVALID_PLUGIN", `${plugin.id} createInitialState is required`);
+  if (typeof plugin.authorize !== "function") throw runtimeError("INVALID_PLUGIN", `${plugin.id} authorize is required`);
+  if (typeof plugin.reduce !== "function") throw runtimeError("INVALID_PLUGIN", `${plugin.id} reduce is required`);
+  if (!plugin.schemas?.state || !plugin.schemas?.operations) throw runtimeError("INVALID_PLUGIN", `${plugin.id} schemas are required`);
+  validatePluginOperationDescriptors(plugin);
+}
+
+function defineHostPlugin(plugin) {
+  validatePlugin(plugin);
+  return plugin;
+}
+
+module.exports = { defineHostPlugin, validatePlugin };

package/src/plugins/install.cjs

@@ -0,0 +1,90 @@
+const {
+  hashCanonical,
+  manifestHash,
+  validateAppPackManifest,
+  validateHostPackManifest
+} = require("@mh-gg/base");
+const { runtimeError } = require("../errors.cjs");
+const { validatePlugin } = require("./definition.cjs");
+
+function pluginArtifactIntegrity(plugin) {
+  return hashCanonical({ id: plugin.id, version: plugin.version, schema: plugin.schemaDescriptor || null });
+}
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function compositionPluginConfigs(hostPack) {
+  const configs = new Map();
+  for (const ref of hostPack.composition?.plugins || []) {
+    if (ref?.id && ref.config !== undefined) configs.set(ref.id, clone(ref.config));
+  }
+  return configs;
+}
+
+function resolveHostPlugins(hostPack, pluginRegistry) {
+  const pack = validateHostPackManifest(hostPack);
+  const registry = pluginRegistry || {};
+  const resolved = [];
+  const byId = new Map(pack.plugins.map((ref) => [ref.id, ref]));
+  const configs = compositionPluginConfigs(pack);
+
+  for (const ref of pack.plugins) {
+    for (const dependency of ref.dependsOn || []) {
+      const target = byId.get(dependency.id);
+      if (!target && !dependency.optional) throw runtimeError("PLUGIN_DEPENDENCY_MISSING", `Plugin ${ref.id} depends on ${dependency.id}`);
+      if (target && dependency.version && target.version !== dependency.version) throw runtimeError("PLUGIN_DEPENDENCY_VERSION", `Plugin ${ref.id} depends on ${dependency.id}@${dependency.version}`);
+    }
+    for (const conflictId of ref.conflictsWith || []) {
+      if (byId.has(conflictId)) throw runtimeError("PLUGIN_CONFLICT", `Plugin ${ref.id} conflicts with ${conflictId}`);
+    }
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(ref) {
+    if (visited.has(ref.id)) return;
+    if (visiting.has(ref.id)) throw runtimeError("PLUGIN_DEPENDENCY_CYCLE", `Plugin dependency cycle at ${ref.id}`);
+    visiting.add(ref.id);
+    for (const dependency of ref.dependsOn || []) {
+      const target = byId.get(dependency.id);
+      if (target) visit(target);
+    }
+    visiting.delete(ref.id);
+    visited.add(ref.id);
+    const plugin = registry[ref.id] || registry[ref.source];
+    if (!plugin) throw runtimeError("PLUGIN_NOT_INSTALLED", `Host plugin ${ref.id} is not available`);
+    validatePlugin(plugin);
+    if (plugin.id !== ref.id) throw runtimeError("PLUGIN_ID_MISMATCH", `Plugin ${ref.id} resolved to ${plugin.id}`);
+    if (plugin.version !== ref.version) throw runtimeError("PLUGIN_VERSION_MISMATCH", `Plugin ${ref.id} version mismatch`);
+    if (ref.integrity && plugin.integrity && ref.integrity !== plugin.integrity) throw runtimeError("PLUGIN_INTEGRITY_MISMATCH", `Plugin ${ref.id} integrity mismatch`);
+    resolved.push(configs.has(ref.id) ? { ...plugin, config: configs.get(ref.id) } : plugin);
+  }
+  for (const ref of pack.plugins) visit(ref);
+  return resolved;
+}
+
+function installHostPack(input) {
+  const appPack = validateAppPackManifest(input.appPack);
+  const hostPack = validateHostPackManifest(input.hostPack);
+  if (hostPack.appPackId !== appPack.id) throw runtimeError("APP_PACK_MISMATCH", "Host pack appPackId does not match app pack");
+  if (appPack.hostPack.integrity !== manifestHash(hostPack)) throw runtimeError("HOST_PACK_INTEGRITY_MISMATCH", "Host pack hash does not match app pack pin");
+  if (hostPack.compatibility.appProtocolHash !== appPack.compatibility.appProtocolHash) {
+    throw runtimeError("APP_PROTOCOL_MISMATCH", "Host pack protocol hash does not match app pack");
+  }
+  const plugins = resolveHostPlugins(hostPack, input.pluginRegistry);
+  return {
+    appPack,
+    hostPack,
+    plugins,
+    roomAppPack: {
+      id: appPack.id,
+      version: appPack.version,
+      hash: manifestHash(appPack),
+      protocolHash: appPack.compatibility.appProtocolHash
+    }
+  };
+}
+
+module.exports = { installHostPack, pluginArtifactIntegrity, resolveHostPlugins };

package/src/plugins/migrations.cjs

@@ -0,0 +1,27 @@
+const { runtimeError, MatterhornRuntimeError } = require("../errors.cjs");
+const { clone } = require("../shared.cjs");
+const { parseWithSchema } = require("../state.cjs");
+
+function migrationKey(from, to) {
+  return `${from}->${to}`;
+}
+
+async function migratePluginState(plugin, roomState, ctx) {
+  const currentVersion = roomState.pluginVersions?.[plugin.id];
+  if (!currentVersion || currentVersion === plugin.version) {
+    return parseWithSchema(plugin.schemas.state, roomState.plugins[plugin.id], `${plugin.id} state`);
+  }
+  const migrations = plugin.migrations || {};
+  let migration = migrations[migrationKey(currentVersion, plugin.version)] || migrations[plugin.version];
+  if (!migration && Array.isArray(migrations)) migration = migrations.find((candidate) => candidate.from === currentVersion && candidate.to === plugin.version)?.migrate;
+  if (typeof migration !== "function") throw runtimeError("MIGRATION_MISSING", `No migration for ${plugin.id} ${currentVersion} -> ${plugin.version}`);
+  try {
+    const migrated = await migration(ctx, clone(roomState.plugins[plugin.id]), { from: currentVersion, to: plugin.version });
+    return parseWithSchema(plugin.schemas.state, migrated, `${plugin.id} migrated state`);
+  } catch (error) {
+    if (error instanceof MatterhornRuntimeError) throw error;
+    throw runtimeError("MIGRATION_FAILED", `${plugin.id} migration failed: ${error?.message || error}`);
+  }
+}
+
+module.exports = { migratePluginState, migrationKey };

package/src/plugins/operationDescriptors.cjs

@@ -0,0 +1,138 @@
+const { runtimeError } = require('../errors.cjs');
+const { normalizeRoomRole } = require('../security/roles.cjs');
+const { clone } = require('../shared.cjs');
+
+const OPERATION_SCHEMA_DESCRIPTOR_KIND = 'matterhorn.operation-schema-descriptor';
+const FORBIDDEN_DESCRIPTOR_SHAPES = Object.freeze([
+  'operationPolicyDescriptor',
+  'operationDescriptors',
+  'operationSchemaDescriptors',
+  'operationSchemas'
+]);
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeOperationsObject(operations, label = 'operationSchemaDescriptor.operations') {
+  if (!isPlainObject(operations)) {
+    throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${label} must be a canonical operation descriptor map`);
+  }
+  return Object.fromEntries(Object.entries(operations).map(([type, descriptor]) => [type, clone(descriptor)]));
+}
+
+function createOperationSchemaDescriptor(input, version, operations) {
+  if (isPlainObject(input) && arguments.length === 1) {
+    const plugin = input.plugin || input.pluginId;
+    if (typeof plugin !== 'string' || plugin.length === 0) throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', 'operation descriptor plugin is required');
+    if (typeof input.version !== 'string' || input.version.length === 0) throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', 'operation descriptor version is required');
+    return {
+      kind: input.kind || OPERATION_SCHEMA_DESCRIPTOR_KIND,
+      plugin,
+      version: input.version,
+      ...(input.source ? { source: input.source } : {}),
+      operations: normalizeOperationsObject(input.operations)
+    };
+  }
+  if (typeof input !== 'string' || input.length === 0) throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', 'operation descriptor plugin is required');
+  if (typeof version !== 'string' || version.length === 0) throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', 'operation descriptor version is required');
+  return {
+    kind: OPERATION_SCHEMA_DESCRIPTOR_KIND,
+    plugin: input,
+    version,
+    operations: normalizeOperationsObject(operations)
+  };
+}
+
+function canonicalOperationDescriptor(plugin) {
+  return plugin?.operationSchemaDescriptor;
+}
+
+function operationDescriptor(plugin, type) {
+  const descriptor = canonicalOperationDescriptor(plugin);
+  if (!isPlainObject(descriptor?.operations)) return undefined;
+  return descriptor.operations[type];
+}
+
+function declaredRolesForOperation(plugin, type) {
+  const descriptor = operationDescriptor(plugin, type);
+  const roles = descriptor?.authorize?.roles;
+  return Array.isArray(roles) ? roles.slice() : undefined;
+}
+
+function assertNoLegacyDescriptorShapes(plugin) {
+  for (const property of FORBIDDEN_DESCRIPTOR_SHAPES) {
+    if (Object.prototype.hasOwnProperty.call(plugin, property)) {
+      throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${plugin.id} must use canonical operationSchemaDescriptor.operations; legacy ${property} is not supported`);
+    }
+  }
+  if (plugin.schemas?.operationsDescriptor) {
+    throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${plugin.id} must use canonical operationSchemaDescriptor.operations; schemas.operationsDescriptor is not supported`);
+  }
+  for (const [type, schema] of Object.entries(plugin.schemas?.operations || {})) {
+    if (schema?.descriptor) {
+      throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${plugin.id}.${type} must declare policy in operationSchemaDescriptor.operations, not schemas.operations.${type}.descriptor`);
+    }
+  }
+}
+
+function assertRoleArray(plugin, type, roles) {
+  if (!Array.isArray(roles) || roles.length === 0) {
+    throw runtimeError('OPERATION_ROLE_POLICY_MISSING', `${plugin.id}.${type} must declare authorize.roles in operationSchemaDescriptor.operations`);
+  }
+  for (const role of roles) {
+    if (typeof role !== 'string' || role.length === 0 || normalizeRoomRole(role, undefined) === undefined) {
+      throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${plugin.id}.${type} has invalid authorize.roles entry ${JSON.stringify(role)}`);
+    }
+  }
+}
+
+function validatePluginOperationDescriptors(plugin) {
+  assertNoLegacyDescriptorShapes(plugin);
+  const descriptor = canonicalOperationDescriptor(plugin);
+  if (!isPlainObject(descriptor) || !isPlainObject(descriptor.operations)) {
+    throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${plugin.id} must declare canonical operationSchemaDescriptor.operations`);
+  }
+  if (descriptor.kind !== undefined && descriptor.kind !== OPERATION_SCHEMA_DESCRIPTOR_KIND) {
+    throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${plugin.id} operationSchemaDescriptor.kind is invalid`);
+  }
+  if (descriptor.plugin !== plugin.id) {
+    throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${plugin.id} operationSchemaDescriptor.plugin must match plugin id`);
+  }
+  if (descriptor.version !== plugin.version) {
+    throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${plugin.id} operationSchemaDescriptor.version must match plugin version`);
+  }
+
+  const schemaOperationTypes = Object.keys(plugin.schemas?.operations || {}).sort();
+  const descriptorOperationTypes = Object.keys(descriptor.operations).sort();
+  for (const type of schemaOperationTypes) {
+    if (!Object.prototype.hasOwnProperty.call(descriptor.operations, type)) {
+      throw runtimeError('OPERATION_ROLE_POLICY_MISSING', `${plugin.id}.${type} must declare authorize.roles in operationSchemaDescriptor.operations`);
+    }
+    assertRoleArray(plugin, type, descriptor.operations[type]?.authorize?.roles);
+  }
+  for (const type of descriptorOperationTypes) {
+    if (!Object.prototype.hasOwnProperty.call(plugin.schemas.operations, type)) {
+      throw runtimeError('INVALID_PLUGIN_OPERATION_DESCRIPTOR', `${plugin.id}.${type} has an operation descriptor but no schemas.operations entry`);
+    }
+  }
+  return true;
+}
+
+function requireDeclaredRolePolicy(plugin, type) {
+  const roles = declaredRolesForOperation(plugin, type);
+  if (!Array.isArray(roles) || roles.length === 0) {
+    throw runtimeError('RUNTIME_CONFIGURATION_INVALID', `${plugin.id}.${type} has no validated canonical authorize.roles policy`);
+  }
+  return roles;
+}
+
+module.exports = {
+  OPERATION_SCHEMA_DESCRIPTOR_KIND,
+  canonicalOperationDescriptor,
+  createOperationSchemaDescriptor,
+  declaredRolesForOperation,
+  operationDescriptor,
+  requireDeclaredRolePolicy,
+  validatePluginOperationDescriptors
+};