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

package/src/runtime/memberProfiles.cjs

@@ -0,0 +1,74 @@
+const { clone } = require("../shared.cjs");
+
+function cleanText(value, max = 160) {
+  if (typeof value !== "string") return undefined;
+  const text = value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+  return text ? text.slice(0, max) : undefined;
+}
+
+function actorDisplayName(actor) {
+  return cleanText(actor?.displayName, 120)
+    || cleanText(actor?.name, 120)
+    || cleanText(actor?.nickname, 120);
+}
+
+function actorMemberRecord(existing, actor, now) {
+  const memberId = cleanText(actor?.memberId, 160);
+  if (!memberId) return undefined;
+  const displayName = actorDisplayName(actor);
+  const next = {
+    ...(existing || {}),
+    id: existing?.id || memberId,
+    memberId,
+    profileOnly: existing ? existing.profileOnly : true,
+    role: existing?.role || cleanText(actor?.role, 80) || "member",
+    updatedAt: now,
+    lastSeenAt: now
+  };
+  const deviceId = cleanText(actor?.deviceId, 160);
+  const avatar = cleanText(actor?.avatar, 64);
+  const avatarUrl = cleanText(actor?.avatarUrl, 500);
+  const profileImageUrl = cleanText(actor?.profileImageUrl, 500);
+  const keyId = cleanText(actor?.keyId, 160);
+  const publicKey = cleanText(actor?.publicKey, 500);
+  if (!existing && !displayName && !avatar && !avatarUrl && !profileImageUrl) return undefined;
+  if (deviceId) next.deviceId = deviceId;
+  if (displayName) {
+    next.name = displayName;
+    next.displayName = displayName;
+  }
+  if (avatar) next.avatar = avatar;
+  if (avatarUrl) next.avatarUrl = avatarUrl;
+  if (profileImageUrl) next.profileImageUrl = profileImageUrl;
+  if (keyId) next.keyId = keyId;
+  if (publicKey) next.publicKey = publicKey;
+  return next;
+}
+
+function stateWithActorMember(state, actor, now) {
+  const member = actorMemberRecord(state?.members?.[actor?.memberId], actor, now);
+  if (!member) return state;
+  return {
+    ...state,
+    members: {
+      ...(state.members || {}),
+      [member.memberId]: member
+    }
+  };
+}
+
+async function stateWithOperationLogMembers(runtime, state) {
+  const entries = typeof runtime.operationLog?.list === "function"
+    ? await runtime.operationLog.list()
+    : runtime.operationLog?.entries || [];
+  let next = state;
+  for (const operation of entries || []) {
+    next = stateWithActorMember(next, operation?.actor, operation?.createdAt || operation?.committedAt || runtime.now());
+  }
+  return next === state ? state : clone(next);
+}
+
+module.exports = {
+  stateWithActorMember,
+  stateWithOperationLogMembers
+};

package/src/runtime/methods.cjs

@@ -0,0 +1,10 @@
+const lifecycle = require("./lifecycle.cjs");
+const { createContext } = require("./context.cjs");
+const operations = require("./operations.cjs");
+const queries = require("./queries.cjs");
+
+function attachRuntimeMethods(RuntimeClass) {
+  Object.assign(RuntimeClass.prototype, lifecycle, { createContext }, operations, queries);
+}
+
+module.exports = { attachRuntimeMethods };

package/src/runtime/operations.cjs

@@ -0,0 +1,166 @@
+const { validateRoomOperation } = require("@mh-gg/protocol");
+const { normalizeRuntimeFailure, runtimeError } = require("../errors.cjs");
+const { parseWithSchema } = require("../state.cjs");
+const { clone, pruneMap, rememberBounded } = require("../shared.cjs");
+const { stateWithActorMember } = require("./memberProfiles.cjs");
+const { assignOperationLedgerId } = require("./snowflake.cjs");
+const {
+  CORE_AUTHORITY_GRANT_TYPE,
+  CORE_AUTHORITY_REVOKE_TYPE,
+  CORE_PLUGIN_ID,
+  CORE_REVOKE_CREDENTIAL_TYPE,
+  authenticateAndGateOperation,
+  commitAccessRoleAssignment,
+  commitAccessRoleDefine,
+  commitAuthorityCoreOperation,
+  commitCoreOperation,
+  commitScopeRoleSet,
+  commitCredentialRevocation,
+  commitDirectCoreOperation,
+  commitReadTagCoreOperation,
+  isCoreOperation
+} = require("./coreOperations.cjs");
+
+function assertOperationRoom(op) {
+  if (op.roomId !== this.room.id) throw runtimeError("ROOM_MISMATCH", "Operation room does not match runtime room");
+  if (op.appPackId !== this.room.appPack.id) throw runtimeError("APP_PACK_MISMATCH", "Operation app pack id does not match runtime app");
+  if (op.appPackHash !== this.room.appPack.hash && this.allowHistoricalAppPackHashes !== true) throw runtimeError("APP_PACK_HASH_MISMATCH", "Operation app pack hash does not match runtime app");
+}
+
+async function findLoggedOperation(operationId) {
+  if (typeof this.operationLog.findById === "function") return await this.operationLog.findById(operationId);
+  const entries = typeof this.operationLog.list === "function" ? await this.operationLog.list() : (this.operationLog.entries || []);
+  return entries.find((entry) => entry.id === operationId) || null;
+}
+
+async function handleOperation(operation) {
+  try {
+    return await this.handleOperationOrThrow(operation);
+  } catch (error) {
+    this.logger.warn?.("Operation rejected", error);
+    return normalizeRuntimeFailure(error, operation?.id);
+  }
+}
+
+async function commitPluginOperation(runtime, operation, state, plugin, signedOperationForLog) {
+  const actor = await authenticateAndGateOperation(runtime, { operation, state, plugin });
+  const parsedPayload = parseWithSchema(plugin.schemas.operations[operation.type], operation.payload, `${plugin.id}.${operation.type}`);
+  const parsedOperation = { ...operation, payload: parsedPayload, actor };
+  const pluginState = state.plugins[plugin.id];
+  const authz = await plugin.authorize(runtime.createContext({ plugin, roomState: state, pluginState, actor, operation: parsedOperation }), parsedOperation);
+  if (!authz?.ok) throw runtimeError("FORBIDDEN", authz?.reason || "Forbidden");
+
+  let nextPluginState;
+  try {
+    nextPluginState = await plugin.reduce(runtime.createContext({ plugin, roomState: state, pluginState, actor, operation: parsedOperation }), clone(pluginState), parsedOperation);
+  } catch (error) {
+    throw runtimeError("PLUGIN_REDUCE_FAILED", `${plugin.id}: ${error?.message || error}`);
+  }
+  const parsedNextPluginState = parseWithSchema(plugin.schemas.state, nextPluginState, `${plugin.id} state`);
+  const updatedAt = parsedOperation.createdAt || runtime.now();
+  const memberRoomState = stateWithActorMember(state, actor, updatedAt);
+  const nextRoomState = runtime.validateRoomState({
+    ...memberRoomState,
+    plugins: { ...memberRoomState.plugins, [plugin.id]: parsedNextPluginState },
+    pluginVersions: { ...memberRoomState.pluginVersions, [plugin.id]: plugin.version },
+    version: state.version + 1,
+    updatedAt,
+    seenOperations: rememberBounded(state.seenOperations, parsedOperation.id, runtime.maxSeenOperations)
+  });
+  await runtime.commitStateAndOperation({
+    logEntry: { ...signedOperationForLog, committedRoomVersion: nextRoomState.version, committedAt: nextRoomState.updatedAt },
+    nextState: nextRoomState,
+    expectedPreviousVersion: state.version
+  });
+  await runAfterCommit(runtime, plugin, nextRoomState, parsedNextPluginState, actor, parsedOperation);
+  return ackOperation(runtime, parsedOperation.id, nextRoomState.version, parsedOperation);
+}
+
+async function commitStateAndOperation({ logEntry, nextState, expectedPreviousVersion }) {
+  logEntry = assignOperationLedgerId(this, logEntry);
+  if (!logEntry?.id) throw runtimeError("INVALID_OPERATION", "Operation log entry id is required");
+  if (Number.isInteger(expectedPreviousVersion) && nextState?.version !== expectedPreviousVersion + 1) {
+    throw runtimeError("VERSION_CONFLICT", "Committed room state version must advance by one");
+  }
+  const existing = await this.findLoggedOperation(logEntry.id);
+  if (existing) throw runtimeError("DUPLICATE_OPERATION", `Operation ${logEntry.id} is already committed`);
+  if (typeof this.store.commitStateAndOperation === "function") {
+    await this.store.commitStateAndOperation({ operation: logEntry, nextState, expectedPreviousVersion, operationLog: this.operationLog });
+    return;
+  }
+  if (this.productionRuntime || this.relayExecuted) {
+    throw runtimeError("ATOMIC_COMMIT_REQUIRED", "Production and relay-executed runtimes require store.commitStateAndOperation");
+  }
+  await this.operationLog.append(logEntry);
+  try {
+    await this.store.save(nextState);
+  } catch (error) {
+    if (typeof this.operationLog.removeById === "function") await this.operationLog.removeById(logEntry.id);
+    throw error;
+  }
+}
+
+async function runAfterCommit(runtime, plugin, nextRoomState, parsedNextPluginState, actor, parsedOperation) {
+  if (typeof plugin.afterCommit !== "function") return;
+  try {
+    await plugin.afterCommit(runtime.createContext({ plugin, roomState: nextRoomState, pluginState: parsedNextPluginState, actor, operation: parsedOperation }), { op: parsedOperation, state: parsedNextPluginState });
+  } catch (error) {
+    runtime.logger.error?.(`Plugin ${plugin.id} afterCommit failed`, error);
+  }
+}
+
+function ackOperation(runtime, operationId, roomVersion, operation = {}) {
+  const ack = { ok: true, acceptedOperationId: operationId, roomVersion, ...(operation.ledgerId ? { acceptedLedgerId: operation.ledgerId, acceptedSnowflakeId: operation.ledgerId } : {}) };
+  runtime.acks.set(operationId, ack);
+  pruneMap(runtime.acks, Math.min(runtime.maxAcks, runtime.maxAckCache));
+  return clone(ack);
+}
+
+async function handleOperationOrThrow(operation) {
+  await this.start();
+  validateRoomOperation(operation);
+  this.assertOperationRoom(operation);
+
+  const state = this.validateRoomState(await this.store.load());
+  if (this.acks.has(operation.id)) return clone(this.acks.get(operation.id));
+  const logged = await this.findLoggedOperation(operation.id);
+  if (logged || state.seenOperations.includes(operation.id)) {
+    return { ok: true, acceptedOperationId: operation.id, roomVersion: logged?.committedRoomVersion || state.version, duplicate: true, ...(logged?.ledgerId ? { acceptedLedgerId: logged.ledgerId, acceptedSnowflakeId: logged.ledgerId } : {}) };
+  }
+
+  const operationForCommit = assignOperationLedgerId(this, {
+    ...operation,
+    ledgerId: undefined,
+    snowflakeId: undefined
+  });
+  const signedOperationForLog = clone(operationForCommit);
+  if (isCoreOperation(operationForCommit)) {
+    const actor = await authenticateAndGateOperation(this, { operation: operationForCommit, state });
+    return this.commitCoreOperation(operationForCommit, actor, state, signedOperationForLog);
+  }
+
+  const plugin = this.pluginMap.get(operationForCommit.pluginId);
+  if (!plugin) throw runtimeError("PLUGIN_NOT_INSTALLED", `Plugin ${operationForCommit.pluginId} is not installed`);
+  if (!plugin.schemas.operations[operationForCommit.type]) throw runtimeError("UNKNOWN_OPERATION_TYPE", `Unknown operation type ${operationForCommit.type}`);
+  return commitPluginOperation(this, operationForCommit, state, plugin, signedOperationForLog);
+}
+
+module.exports = {
+  CORE_AUTHORITY_GRANT_TYPE,
+  CORE_AUTHORITY_REVOKE_TYPE,
+  CORE_PLUGIN_ID,
+  CORE_REVOKE_CREDENTIAL_TYPE,
+  assertOperationRoom,
+  commitAuthorityCoreOperation,
+  commitAccessRoleAssignment,
+  commitAccessRoleDefine,
+  commitCoreOperation,
+  commitStateAndOperation,
+  commitCredentialRevocation,
+  commitDirectCoreOperation,
+  commitReadTagCoreOperation,
+  commitScopeRoleSet,
+  findLoggedOperation,
+  handleOperation,
+  handleOperationOrThrow
+};

package/src/runtime/queries.cjs

@@ -0,0 +1,146 @@
+const { manifestHash } = require("@mh-gg/base");
+const { runtimeError } = require("../errors.cjs");
+const { pluginArtifactIntegrity } = require("../plugins/install.cjs");
+const { parseWithSchema } = require("../state.cjs");
+const { clone } = require("../shared.cjs");
+const { effectiveActorForRoom, publicScopedRolesView } = require("../security/scopedRoles.cjs");
+const { publicDirectView } = require("./directMessages.cjs");
+
+async function handleQuery(pluginId, queryName, input, actor) {
+  await this.start();
+  const plugin = this.pluginMap.get(pluginId);
+  if (!plugin) throw runtimeError("PLUGIN_NOT_INSTALLED", `Plugin ${pluginId} is not installed`);
+  const query = plugin.queries?.[queryName];
+  if (typeof query !== "function") throw runtimeError("PLUGIN_QUERY_NOT_FOUND", `Plugin query ${pluginId}.${queryName} is not available`);
+  const state = this.validateRoomState(await this.store.load());
+  const queryActor = await effectiveActorForRoom(this, { actor, state });
+  const pluginState = clone(state.plugins[pluginId]);
+  const result = await query(this.createContext({ plugin, roomState: clone(state), pluginState, actor: queryActor }), pluginState, clone(input), queryActor);
+  const querySchema = plugin.schemas.queries?.[queryName];
+  return clone(querySchema ? parseWithSchema(querySchema, result, `${plugin.id}.${queryName} query`) : result);
+}
+
+async function query(pluginId, queryName, input, actor) {
+  return await this.handleQuery(pluginId, queryName, input, actor);
+}
+
+async function operationBatchSince(baseVersion = 0, options = {}) {
+  await this.start();
+  const state = this.validateRoomState(await this.store.load());
+  const entries = typeof this.operationLog.list === "function" ? await this.operationLog.list() : (this.operationLog.entries || []).map(clone);
+  const operations = entries.filter((entry) => Number(entry.committedRoomVersion || 0) > baseVersion);
+  return {
+    kind: "matterhorn.host-operation-batch",
+    version: "0.1",
+    roomId: this.room.id,
+    appPackId: this.room.appPack.id,
+    appPackHash: this.room.appPack.hash,
+    baseVersion,
+    headVersion: state.version,
+    operations: operations.slice(0, options.limit || operations.length).map(clone)
+  };
+}
+
+async function createSnapshot() {
+  await this.start();
+  const state = this.validateRoomState(await this.store.load());
+  return {
+    kind: "matterhorn.host-snapshot",
+    version: state.version,
+    roomId: this.room.id,
+    appPackId: this.room.appPack.id,
+    appPackHash: this.room.appPack.hash,
+    appPack: clone(this.room.appPack),
+    createdAt: this.now(),
+    state: clone(state)
+  };
+}
+
+async function operations(options = {}) {
+  if (typeof this.operationLog.list === "function") return await this.operationLog.list(options);
+  return (this.operationLog.entries || []).map(clone);
+}
+
+function publicMembersView(members = {}, actor = {}) {
+  const view = {};
+  for (const [key, member] of Object.entries(members || {})) {
+    const id = member?.memberId || member?.id || key;
+    if (!id) continue;
+    const item = {
+      id,
+      memberId: id,
+      name: member.name,
+      displayName: member.displayName,
+      role: member.role,
+      status: member.status,
+      revokedAt: member.revokedAt,
+      bannedAt: member.bannedAt
+    };
+    if (member.avatar !== undefined) item.avatar = member.avatar;
+    if (member.avatarUrl !== undefined) item.avatarUrl = member.avatarUrl;
+    if (member.profileImageUrl !== undefined) item.profileImageUrl = member.profileImageUrl;
+    if (actor.memberId === id && member.readTags && typeof member.readTags === "object" && !Array.isArray(member.readTags)) item.readTags = clone(member.readTags);
+    view[id] = item;
+  }
+  return view;
+}
+
+async function publicView(actor) {
+  await this.start();
+  const state = this.validateRoomState(await this.store.load());
+  const viewActor = await effectiveActorForRoom(this, { actor, state });
+  const plugins = {};
+  for (const [pluginId, plugin] of this.pluginMap.entries()) {
+    const pluginState = clone(state.plugins[pluginId]);
+    const view = typeof plugin.getPublicView === "function"
+      ? await plugin.getPublicView(this.createContext({ plugin, roomState: clone(state), pluginState, actor: viewActor }), pluginState, viewActor)
+      : pluginState;
+    plugins[pluginId] = plugin.schemas.publicView ? parseWithSchema(plugin.schemas.publicView, view, `${pluginId} publicView`) : view;
+  }
+  return { roomId: state.roomId, appPack: clone(state.appPack), version: state.version, updatedAt: state.updatedAt, members: publicMembersView(state.members, viewActor), access: publicScopedRolesView(state, viewActor), direct: publicDirectView(state, viewActor), plugins };
+}
+
+async function roomInfo(extra = {}) {
+  await this.start();
+  const state = this.validateRoomState(await this.store.load());
+  return {
+    kind: "matterhorn.host-info",
+    type: "room/info",
+    version: "0.1",
+    roomId: this.room.id,
+    roomVersion: state.version,
+    appPack: clone(this.room.appPack),
+    hostPack: this.hostPack ? {
+      id: this.hostPack.id,
+      version: this.hostPack.version,
+      hash: manifestHash(this.hostPack),
+      pluginGraphHash: this.hostPack.compatibility.pluginGraphHash
+    } : undefined,
+    plugins: [...this.pluginMap.values()].map((plugin) => ({
+      id: plugin.id,
+      version: plugin.version,
+      capabilities: clone(plugin.capabilities || {}),
+      integrity: plugin.integrity || pluginArtifactIntegrity(plugin)
+    })),
+    capabilities: [...this.capabilities].sort(),
+    playerRecommendations: this.playerPacks.map((pack) => ({
+      id: pack.id,
+      name: pack.name,
+      version: pack.version,
+      mode: pack.mode,
+      recommendedFor: clone(pack.recommendedFor || {})
+    })),
+    operationPublicKey: this.operationPublicKey,
+    ...clone(extra)
+  };
+}
+
+module.exports = {
+  createSnapshot,
+  handleQuery,
+  operationBatchSince,
+  operations,
+  publicView,
+  query,
+  roomInfo
+};

package/src/runtime/readTags.cjs

@@ -0,0 +1,171 @@
+const { isSnowflakeId, compareSnowflakeIds } = require("@mh-gg/protocol");
+const { CORE_PLUGIN_ID } = require("@mh-gg/authority");
+const { runtimeError } = require("../errors.cjs");
+const { authorizeCoreOperation } = require("../security/authorization/coreGate.cjs");
+const { clone } = require("../shared.cjs");
+const { commitVersion, tombstone } = require("./authorityReplay/state.cjs");
+const { stateWithActorMember } = require("./memberProfiles.cjs");
+
+const CORE_READ_TAG_SET_TYPE = "read.tag.set";
+const READ_TAG_VERSION = 1;
+const MAX_MEMBER_READ_TAGS = 1000;
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function requiredString(value, name, max = 240) {
+  if (typeof value !== "string") throw runtimeError("SCHEMA_INVALID", `${name} must be a string`);
+  const text = value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+  if (!text) throw runtimeError("SCHEMA_INVALID", `${name} must be a non-empty string`);
+  if (text.length > max) throw runtimeError("SCHEMA_INVALID", `${name} is too long`);
+  return text;
+}
+
+function optionalString(value, name, max = 240) {
+  if (value === undefined || value === null || value === "") return undefined;
+  return requiredString(String(value), name, max);
+}
+
+function optionalTimestamp(value, name) {
+  if (value === undefined || value === null) return undefined;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0) throw runtimeError("SCHEMA_INVALID", `${name} must be a non-negative finite number`);
+  return Math.trunc(number);
+}
+
+function assertOnlyPayloadKeys(payload, allowed, operationType) {
+  if (!isPlainObject(payload)) throw runtimeError("SCHEMA_INVALID", `${operationType} payload must be an object`);
+  const allow = new Set(allowed);
+  for (const key of Object.keys(payload)) {
+    if (!allow.has(key)) throw runtimeError("SCHEMA_INVALID", `${operationType} payload has unknown field ${key}`);
+  }
+}
+
+function readTagScopeKey(scopeType, scopeId) {
+  return `${scopeType}:${scopeId}`;
+}
+
+function parseReadTagPayload(operation) {
+  assertOnlyPayloadKeys(operation.payload || {}, ["scopeType", "scopeId", "ledgerId", "operationId", "messageId", "readAt", "label"], operation.type);
+  const scopeType = requiredString(operation.payload?.scopeType, `${operation.type} scopeType`, 120);
+  const scopeId = requiredString(operation.payload?.scopeId, `${operation.type} scopeId`, 500);
+  const ledgerId = optionalString(operation.payload?.ledgerId, `${operation.type} ledgerId`, 32);
+  if (ledgerId && !isSnowflakeId(ledgerId)) throw runtimeError("SCHEMA_INVALID", `${operation.type} ledgerId must be a Snowflake ID`);
+  const operationId = optionalString(operation.payload?.operationId, `${operation.type} operationId`, 240);
+  const messageId = optionalString(operation.payload?.messageId, `${operation.type} messageId`, 240);
+  const readAt = optionalTimestamp(operation.payload?.readAt, `${operation.type} readAt`);
+  const label = optionalString(operation.payload?.label, `${operation.type} label`, 120);
+  return {
+    scopeType,
+    scopeId,
+    ...(ledgerId ? { ledgerId } : {}),
+    ...(operationId ? { operationId } : {}),
+    ...(messageId ? { messageId } : {}),
+    ...(readAt !== undefined ? { readAt } : {}),
+    ...(label ? { label } : {})
+  };
+}
+
+function readTagCursorValue(tag) {
+  if (tag?.ledgerId && isSnowflakeId(tag.ledgerId)) return { kind: "ledger", value: tag.ledgerId };
+  if (Number.isFinite(Number(tag?.readAt))) return { kind: "time", value: Number(tag.readAt) };
+  return { kind: "time", value: 0 };
+}
+
+function shouldReplaceReadTag(existing, next) {
+  if (!existing) return true;
+  const left = readTagCursorValue(existing);
+  const right = readTagCursorValue(next);
+  if (left.kind === "ledger" && right.kind === "ledger") return compareSnowflakeIds(right.value, left.value) >= 0;
+  if (left.kind === "ledger" && right.kind !== "ledger") return false;
+  if (left.kind !== "ledger" && right.kind === "ledger") return true;
+  return right.value >= left.value;
+}
+
+function pruneReadTags(readTags) {
+  const entries = Object.entries(readTags || {});
+  if (entries.length <= MAX_MEMBER_READ_TAGS) return readTags;
+  entries.sort((left, right) => Number(right[1]?.updatedAt || right[1]?.readAt || 0) - Number(left[1]?.updatedAt || left[1]?.readAt || 0));
+  return Object.fromEntries(entries.slice(0, MAX_MEMBER_READ_TAGS));
+}
+
+function applyReadTagToRoomState(state, payload, actor, operation, now) {
+  const memberId = requiredString(actor?.memberId, `${operation.type} actor.memberId`, 240);
+  const key = readTagScopeKey(payload.scopeType, payload.scopeId);
+  const readAt = payload.readAt ?? now;
+  const nextTag = {
+    kind: "matterhorn.read-tag",
+    version: READ_TAG_VERSION,
+    key,
+    scopeType: payload.scopeType,
+    scopeId: payload.scopeId,
+    readAt,
+    updatedAt: now,
+    updatedBy: memberId,
+    updateOperationId: operation.id,
+    ...(operation.ledgerId && isSnowflakeId(operation.ledgerId) ? { updateLedgerId: operation.ledgerId } : {}),
+    ...(payload.ledgerId ? { ledgerId: payload.ledgerId } : operation.ledgerId && isSnowflakeId(operation.ledgerId) ? { ledgerId: operation.ledgerId } : {}),
+    ...(payload.operationId ? { operationId: payload.operationId } : {}),
+    ...(payload.messageId ? { messageId: payload.messageId } : {}),
+    ...(payload.label ? { label: payload.label } : {})
+  };
+  const members = isPlainObject(state.members) ? state.members : {};
+  const existingMember = members[memberId] || {};
+  const existingReadTags = isPlainObject(existingMember.readTags) ? existingMember.readTags : {};
+  const existingTag = existingReadTags[key];
+  if (!shouldReplaceReadTag(existingTag, nextTag)) return state;
+  const member = {
+    ...existingMember,
+    id: existingMember.id || memberId,
+    memberId,
+    role: existingMember.role || actor.role || "member",
+    readTags: pruneReadTags({ ...existingReadTags, [key]: nextTag }),
+    updatedAt: now,
+    lastSeenAt: now
+  };
+  return {
+    ...state,
+    members: {
+      ...members,
+      [memberId]: member
+    }
+  };
+}
+
+async function applyReadTagCoreEnvelope(runtime, state, operation) {
+  try {
+    const rawActor = await runtime.authenticateActor(operation.auth, operation.actor, operation);
+    const actor = await authorizeCoreOperation(runtime, { operation, actor: rawActor, state, plugin: { id: CORE_PLUGIN_ID }, roles: ["member"], operationLabel: `${CORE_PLUGIN_ID}.${operation.type}` });
+    const payload = parseReadTagPayload(operation);
+    const updatedAt = operation.createdAt || runtime.now();
+    const memberState = stateWithActorMember(state, actor, updatedAt);
+    Object.assign(state, applyReadTagToRoomState(memberState, payload, actor, { ...operation, payload, actor }, updatedAt));
+    commitVersion(state, operation, runtime);
+    return true;
+  } catch (error) {
+    tombstone(state, operation, "invalid-read-tag-operation", { code: error?.code, message: error?.message || String(error) });
+    return false;
+  }
+}
+
+function readTagsForMember(state, memberId) {
+  const member = state?.members?.[memberId];
+  return isPlainObject(member?.readTags) ? clone(member.readTags) : {};
+}
+
+function readTagForScope(state, memberId, scopeType, scopeId) {
+  return readTagsForMember(state, memberId)[readTagScopeKey(scopeType, scopeId)];
+}
+
+module.exports = {
+  CORE_READ_TAG_SET_TYPE,
+  MAX_MEMBER_READ_TAGS,
+  READ_TAG_VERSION,
+  applyReadTagCoreEnvelope,
+  applyReadTagToRoomState,
+  parseReadTagPayload,
+  readTagForScope,
+  readTagScopeKey,
+  readTagsForMember
+};

package/src/runtime/scopedRoleOperations.cjs

@@ -0,0 +1,97 @@
+const { runtimeError } = require("../errors.cjs");
+const { clone, pruneMap, rememberBounded } = require("../shared.cjs");
+const { stateWithActorMember } = require("./memberProfiles.cjs");
+const {
+  CORE_ACCESS_ROLE_ASSIGN_TYPE,
+  CORE_ACCESS_ROLE_DEFINE_TYPE,
+  CORE_SCOPE_ROLE_SET_TYPE,
+  applyAccessRoleAssignmentToRoomState,
+  applyAccessRoleDefineToRoomState,
+  applyScopeRoleSetToRoomState,
+  assertScopedRoleManagerCanApply,
+  normalizeScopedRolesState,
+  parseAccessRoleAssignmentPayload,
+  parseAccessRoleDefinePayload,
+  parseScopeRoleSetPayload
+} = require("../security/scopedRoles.cjs");
+
+function parseScopedCorePayload(operation) {
+  if (operation.type === CORE_SCOPE_ROLE_SET_TYPE) return parseScopeRoleSetPayload(operation);
+  if (operation.type === CORE_ACCESS_ROLE_DEFINE_TYPE) return parseAccessRoleDefinePayload(operation);
+  return parseAccessRoleAssignmentPayload(operation);
+}
+
+function ackOperation(runtime, operationId, roomVersion) {
+  const ack = { ok: true, acceptedOperationId: operationId, roomVersion };
+  runtime.acks.set(operationId, ack);
+  pruneMap(runtime.acks, Math.min(runtime.maxAcks, runtime.maxAckCache));
+  return clone(ack);
+}
+
+async function commitScopedRoleState(runtime, operation, state, actor, signedOperationForLog, payload, nextScopedState) {
+  const createdAt = operation.createdAt || runtime.now();
+  const memberState = stateWithActorMember(nextScopedState, actor, createdAt);
+  const nextRoomState = runtime.validateRoomState({
+    ...memberState,
+    version: state.version + 1,
+    updatedAt: createdAt,
+    seenOperations: rememberBounded(state.seenOperations, operation.id, runtime.maxSeenOperations)
+  });
+  await runtime.commitStateAndOperation({
+    logEntry: { ...signedOperationForLog, payload, committedRoomVersion: nextRoomState.version, committedAt: nextRoomState.updatedAt },
+    nextState: nextRoomState,
+    expectedPreviousVersion: state.version
+  });
+  return ackOperation(runtime, operation.id, nextRoomState.version);
+}
+
+async function commitScopeRoleSet(operation, actor, state, signedOperationForLog) {
+  const payload = parseScopedCorePayload(operation);
+  assertScopedRoleManagerCanApply(actor, { grants: [{ role: payload.role || payload.defaultRole || "none" }] });
+  return commitScopedRoleState(
+    this,
+    operation,
+    state,
+    actor,
+    signedOperationForLog,
+    payload,
+    applyScopeRoleSetToRoomState(state, payload, actor, operation.createdAt || this.now(), operation)
+  );
+}
+
+async function commitAccessRoleDefine(operation, actor, state, signedOperationForLog) {
+  const payload = parseScopedCorePayload(operation);
+  assertScopedRoleManagerCanApply(actor, payload);
+  return commitScopedRoleState(
+    this,
+    operation,
+    state,
+    actor,
+    signedOperationForLog,
+    payload,
+    applyAccessRoleDefineToRoomState(state, payload, actor, operation.createdAt || this.now(), operation)
+  );
+}
+
+async function commitAccessRoleAssignment(operation, actor, state, signedOperationForLog) {
+  const payload = parseScopedCorePayload(operation);
+  const compoundRole = normalizeScopedRolesState(state.scopedRoles).roles[payload.roleId];
+  if (!compoundRole) throw runtimeError("SCHEMA_INVALID", `Compound role ${payload.roleId} is not defined`);
+  assertScopedRoleManagerCanApply(actor, { grants: compoundRole.grants });
+  return commitScopedRoleState(
+    this,
+    operation,
+    state,
+    actor,
+    signedOperationForLog,
+    payload,
+    applyAccessRoleAssignmentToRoomState(state, payload, operation.type === CORE_ACCESS_ROLE_ASSIGN_TYPE, actor, operation.createdAt || this.now(), operation)
+  );
+}
+
+module.exports = {
+  commitAccessRoleAssignment,
+  commitAccessRoleDefine,
+  commitScopeRoleSet,
+  parseScopedCorePayload
+};