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

package/src/runtime/corePayloads.cjs

@@ -0,0 +1,66 @@
+const {
+  CORE_AUTHORITY_GRANT_TYPE,
+  CORE_AUTHORITY_REVOKE_TYPE,
+  CORE_REVOKE_CREDENTIAL_TYPE
+} = require("@mh-gg/authority");
+const { runtimeError } = require("../errors.cjs");
+const { normalizeRoomRole } = require("../security/roles.cjs");
+const {
+  CORE_ACCESS_ROLE_ASSIGN_TYPE,
+  CORE_ACCESS_ROLE_DEFINE_TYPE,
+  CORE_ACCESS_ROLE_UNASSIGN_TYPE,
+  CORE_SCOPE_ROLE_SET_TYPE,
+  parseAccessRoleAssignmentPayload,
+  parseAccessRoleDefinePayload,
+  parseScopeRoleSetPayload
+} = require("../security/scopedRoles.cjs");
+const { parseDirectPayload, isDirectCoreOperation } = require("./directMessages.cjs");
+const { CORE_READ_TAG_SET_TYPE, parseReadTagPayload } = require("./readTags.cjs");
+
+function parseCredentialRevokePayload(operation) {
+  const credentialId = operation.payload?.credentialId;
+  if (typeof credentialId !== "string" || credentialId.length === 0 || credentialId.length > 240) throw runtimeError("SCHEMA_INVALID", "credential.revoke credentialId must be a non-empty string");
+  return { credentialId, ...(typeof operation.payload.reason === "string" && operation.payload.reason.length > 0 ? { reason: operation.payload.reason.slice(0, 500) } : {}) };
+}
+
+function parseAuthorityGrantPayload(operation) {
+  const target = operation.payload?.target;
+  const role = normalizeRoomRole(operation.payload?.role, undefined);
+  if (typeof target !== "string" || target.length === 0 || target.length > 240) throw runtimeError("SCHEMA_INVALID", "authority.grant target must be a non-empty string");
+  if (!role) throw runtimeError("SCHEMA_INVALID", "authority.grant role is invalid");
+  return { target, role, ...(typeof operation.payload.reason === "string" && operation.payload.reason.length > 0 ? { reason: operation.payload.reason.slice(0, 500) } : {}) };
+}
+
+function parseAuthorityRevokePayload(operation) {
+  const voidGrantIds = Array.isArray(operation.payload?.voidGrantIds) ? operation.payload.voidGrantIds.filter((id) => typeof id === "string" && id.length > 0).slice(0, 500) : [];
+  const scope = operation.payload?.scope || (voidGrantIds.length ? "all-by-target" : "future");
+  if (!["future", "from-point", "all-by-target"].includes(scope)) throw runtimeError("SCHEMA_INVALID", "authority.revoke scope is invalid");
+  if (voidGrantIds.length === 0 && typeof operation.payload?.target !== "string") throw runtimeError("SCHEMA_INVALID", "authority.revoke requires target or voidGrantIds");
+  return {
+    ...(typeof operation.payload.target === "string" && operation.payload.target.length > 0 ? { target: operation.payload.target } : {}),
+    voidGrantIds,
+    ...(operation.payload.voidFrom !== undefined ? { voidFrom: operation.payload.voidFrom } : {}),
+    scope,
+    cascade: operation.payload.cascade !== false,
+    ...(typeof operation.payload.reason === "string" && operation.payload.reason.length > 0 ? { reason: operation.payload.reason.slice(0, 500) } : {})
+  };
+}
+
+function parseCorePayload(operation) {
+  if (operation.type === CORE_REVOKE_CREDENTIAL_TYPE) return parseCredentialRevokePayload(operation);
+  if (operation.type === CORE_AUTHORITY_GRANT_TYPE) return parseAuthorityGrantPayload(operation);
+  if (operation.type === CORE_AUTHORITY_REVOKE_TYPE) return parseAuthorityRevokePayload(operation);
+  if (operation.type === CORE_SCOPE_ROLE_SET_TYPE) return parseScopeRoleSetPayload(operation);
+  if (operation.type === CORE_ACCESS_ROLE_DEFINE_TYPE) return parseAccessRoleDefinePayload(operation);
+  if (operation.type === CORE_ACCESS_ROLE_ASSIGN_TYPE || operation.type === CORE_ACCESS_ROLE_UNASSIGN_TYPE) return parseAccessRoleAssignmentPayload(operation);
+  if (isDirectCoreOperation(operation)) return parseDirectPayload(operation);
+  if (operation.type === CORE_READ_TAG_SET_TYPE) return parseReadTagPayload(operation);
+  throw runtimeError("UNKNOWN_CORE_OPERATION", `Unknown core operation ${operation.type}`);
+}
+
+module.exports = {
+  parseAuthorityGrantPayload,
+  parseAuthorityRevokePayload,
+  parseCorePayload,
+  parseCredentialRevokePayload
+};

package/src/runtime/directMessages/commit.cjs

@@ -0,0 +1,50 @@
+const { clone, pruneMap, rememberBounded } = require("../../shared.cjs");
+const { authorizeCoreOperation } = require("../../security/authorization/coreGate.cjs");
+const { CORE_PLUGIN_ID } = require("@mh-gg/authority");
+const { commitVersion, tombstone } = require("../authorityReplay/state.cjs");
+const { stateWithActorMember } = require("../memberProfiles.cjs");
+const { parseDirectPayload } = require("./payloads.cjs");
+const { applyDirectOperationToRoomState } = require("./state.cjs");
+
+async function commitDirectCoreOperation(operation, actor, state, signedOperationForLog) {
+  const payload = parseDirectPayload(operation);
+  const parsedOperation = { ...operation, payload, actor };
+  const updatedAt = parsedOperation.createdAt || this.now();
+  const directState = applyDirectOperationToRoomState(state, parsedOperation, actor, updatedAt);
+  const memberState = stateWithActorMember(directState, actor, updatedAt);
+  const nextRoomState = this.validateRoomState({
+    ...memberState,
+    version: state.version + 1,
+    updatedAt,
+    seenOperations: rememberBounded(state.seenOperations, parsedOperation.id, this.maxSeenOperations)
+  });
+  await this.commitStateAndOperation({
+    logEntry: { ...signedOperationForLog, payload, committedRoomVersion: nextRoomState.version, committedAt: nextRoomState.updatedAt },
+    nextState: nextRoomState,
+    expectedPreviousVersion: state.version
+  });
+  const ack = { ok: true, acceptedOperationId: parsedOperation.id, roomVersion: nextRoomState.version, ...(parsedOperation.ledgerId ? { acceptedLedgerId: parsedOperation.ledgerId, acceptedSnowflakeId: parsedOperation.ledgerId } : {}) };
+  this.acks.set(parsedOperation.id, ack);
+  pruneMap(this.acks, Math.min(this.maxAcks, this.maxAckCache));
+  return clone(ack);
+}
+
+async function applyDirectCoreEnvelope(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 = parseDirectPayload(operation);
+    const updatedAt = operation.createdAt || runtime.now();
+    Object.assign(state, stateWithActorMember(applyDirectOperationToRoomState(state, { ...operation, payload }, actor, updatedAt), actor, updatedAt));
+    commitVersion(state, operation, runtime);
+    return true;
+  } catch (error) {
+    tombstone(state, operation, "invalid-direct-operation", { code: error?.code, message: error?.message || String(error) });
+    return false;
+  }
+}
+
+module.exports = {
+  applyDirectCoreEnvelope,
+  commitDirectCoreOperation
+};

package/src/runtime/directMessages/constants.cjs

@@ -0,0 +1,20 @@
+const CORE_DIRECT_MESSAGE_PUBLISH_TYPE = "direct.message.publish";
+const CORE_DIRECT_MESSAGE_SEND_TYPE = "direct.message.send";
+const CORE_DM_MESSAGE_TYPE = "dm.message";
+const CORE_MEMBER_KEY_PUBLISH_TYPE = "member.key.publish";
+const CORE_DIRECT_OPERATION_TYPES = Object.freeze([
+  CORE_MEMBER_KEY_PUBLISH_TYPE,
+  CORE_DIRECT_MESSAGE_PUBLISH_TYPE,
+  CORE_DIRECT_MESSAGE_SEND_TYPE,
+  CORE_DM_MESSAGE_TYPE
+]);
+const NIP17_PROTOCOL = "nostr.nip17";
+
+module.exports = {
+  CORE_DIRECT_MESSAGE_SEND_TYPE,
+  CORE_DIRECT_MESSAGE_PUBLISH_TYPE,
+  CORE_DIRECT_OPERATION_TYPES,
+  CORE_DM_MESSAGE_TYPE,
+  CORE_MEMBER_KEY_PUBLISH_TYPE,
+  NIP17_PROTOCOL
+};

package/src/runtime/directMessages/helpers.cjs

@@ -0,0 +1,59 @@
+const { hashCanonical } = require("@mh-gg/base");
+const { runtimeError } = require("../../errors.cjs");
+const { NIP17_PROTOCOL } = require("./constants.cjs");
+
+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 trimmed = value.trim();
+  if (!trimmed) throw runtimeError("SCHEMA_INVALID", `${name} must be a non-empty string`);
+  if (trimmed.length > max) throw runtimeError("SCHEMA_INVALID", `${name} is too long`);
+  return trimmed;
+}
+
+function optionalString(value, name, max = 240) {
+  if (value === undefined || value === null || value === "") return undefined;
+  return requiredString(value, name, max);
+}
+
+function assertOnlyPayloadKeys(payload, allowed, operationType) {
+  if (!isPlainObject(payload)) throw runtimeError("SCHEMA_INVALID", `${operationType} payload must be an object`);
+  const allowedKeys = new Set(allowed);
+  for (const key of Object.keys(payload)) {
+    if (!allowedKeys.has(key)) throw runtimeError("SCHEMA_INVALID", `${operationType} payload has unknown field ${key}`);
+  }
+}
+
+function normalizeDirectUserIds(value) {
+  if (!Array.isArray(value)) throw runtimeError("SCHEMA_INVALID", "direct userIds must be an array");
+  const userIds = [...new Set(value.map((item) => requiredString(item, "direct userId", 240)))].sort();
+  if (userIds.length < 2) throw runtimeError("SCHEMA_INVALID", "direct userIds must include at least two users");
+  if (userIds.length > 100) throw runtimeError("SCHEMA_INVALID", "direct userIds supports at most 100 users");
+  return userIds;
+}
+
+function directThreadIdFor({ roomId, userIds, topicKey }) {
+  const digest = hashCanonical({ kind: "matterhorn.direct.thread.v1", protocol: NIP17_PROTOCOL, roomId, userIds, topicKey: topicKey || null }).slice("sha256-".length, "sha256-".length + 32);
+  return `direct_${digest}`;
+}
+
+function directState(state) {
+  return {
+    directThreads: isPlainObject(state.directThreads) ? state.directThreads : {},
+    directMessages: isPlainObject(state.directMessages) ? state.directMessages : {},
+    memberKeys: isPlainObject(state.memberKeys) ? state.memberKeys : {}
+  };
+}
+
+module.exports = {
+  assertOnlyPayloadKeys,
+  directState,
+  directThreadIdFor,
+  isPlainObject,
+  normalizeDirectUserIds,
+  optionalString,
+  requiredString
+};

package/src/runtime/directMessages/payloads.cjs

@@ -0,0 +1,74 @@
+const { verifyRoomMemberKeyClaim } = require("@mh-gg/protocol");
+const { runtimeError } = require("../../errors.cjs");
+const { clone } = require("../../shared.cjs");
+const { CORE_DIRECT_OPERATION_TYPES, CORE_MEMBER_KEY_PUBLISH_TYPE } = require("./constants.cjs");
+const {
+  assertOnlyPayloadKeys,
+  directThreadIdFor,
+  isPlainObject,
+  normalizeDirectUserIds,
+  optionalString,
+  requiredString
+} = require("./helpers.cjs");
+const { CORE_PLUGIN_ID } = require("@mh-gg/authority");
+
+function parseOpaqueGiftWrap(value, name) {
+  if (!isPlainObject(value)) throw runtimeError("SCHEMA_INVALID", `${name} must be an object`);
+  const serialized = JSON.stringify(value);
+  if (serialized.length > 256000) throw runtimeError("SCHEMA_INVALID", `${name} is too large`);
+  return clone(value);
+}
+
+function parseGiftWraps(value, userIds, operationType) {
+  if (!isPlainObject(value)) throw runtimeError("SCHEMA_INVALID", `${operationType} giftWraps must be an object keyed by userId`);
+  const userSet = new Set(userIds);
+  const wraps = {};
+  for (const [recipientId, rawWrap] of Object.entries(value)) {
+    requiredString(recipientId, `${operationType} giftWraps recipientId`, 240);
+    if (!userSet.has(recipientId)) throw runtimeError("SCHEMA_INVALID", `${operationType} giftWraps recipientId must be in userIds`);
+    wraps[recipientId] = parseOpaqueGiftWrap(rawWrap, `${operationType} giftWraps.${recipientId}`);
+  }
+  for (const userId of userIds) {
+    if (!wraps[userId]) throw runtimeError("SCHEMA_INVALID", `${operationType} giftWraps must include ${userId}`);
+  }
+  return wraps;
+}
+
+function parseMemberKeyPublishPayload(operation) {
+  assertOnlyPayloadKeys(operation.payload || {}, [], operation.type);
+  const verification = verifyRoomMemberKeyClaim(operation.auth?.claim);
+  if (!verification.ok) throw runtimeError("SCHEMA_INVALID", verification.error || "member key claim is invalid");
+  const claim = verification.claim;
+  const claimRoomId = claim.roomName || claim.roomId;
+  if (claimRoomId !== operation.roomId) throw runtimeError("ROOM_MISMATCH", "member key claim room must match operation room");
+  return { claim: clone(claim) };
+}
+
+function parseDirectMessagePublishPayload(operation) {
+  assertOnlyPayloadKeys(operation.payload, ["userIds", "topicKey", "giftWraps"], operation.type);
+  const roomId = operation.roomId;
+  const userIds = normalizeDirectUserIds(operation.payload?.userIds);
+  const topicKey = optionalString(operation.payload?.topicKey, `${operation.type} topicKey`, 240);
+  const threadId = directThreadIdFor({ roomId, userIds, topicKey });
+  return {
+    userIds,
+    topicKey,
+    threadId,
+    giftWraps: parseGiftWraps(operation.payload?.giftWraps, userIds, operation.type)
+  };
+}
+
+function parseDirectPayload(operation) {
+  if (operation.type === CORE_MEMBER_KEY_PUBLISH_TYPE) return parseMemberKeyPublishPayload(operation);
+  if (CORE_DIRECT_OPERATION_TYPES.includes(operation.type)) return parseDirectMessagePublishPayload(operation);
+  throw runtimeError("UNKNOWN_CORE_OPERATION", `Unknown core direct operation ${operation.type}`);
+}
+
+function isDirectCoreOperation(operation) {
+  return operation?.pluginId === CORE_PLUGIN_ID && CORE_DIRECT_OPERATION_TYPES.includes(operation.type);
+}
+
+module.exports = {
+  isDirectCoreOperation,
+  parseDirectPayload
+};

package/src/runtime/directMessages/state.cjs

@@ -0,0 +1,168 @@
+const { hashCanonical } = require("@mh-gg/base");
+const { isSnowflakeId } = require("@mh-gg/protocol");
+const { runtimeError } = require("../../errors.cjs");
+const { clone } = require("../../shared.cjs");
+const { CORE_DIRECT_OPERATION_TYPES, CORE_MEMBER_KEY_PUBLISH_TYPE, NIP17_PROTOCOL } = require("./constants.cjs");
+const { directState, isPlainObject } = require("./helpers.cjs");
+const { readTagForScope } = require("../readTags.cjs");
+
+function assertActorInThread(actor, userIds, operationType) {
+  if (!actor?.memberId || !userIds.includes(actor.memberId)) throw runtimeError("FORBIDDEN", `${operationType} actor must be in userIds`);
+}
+
+function assertKnownRoomMembers(state, userIds, operationType) {
+  const members = isPlainObject(state.members) ? state.members : {};
+  if (Object.keys(members).length === 0) return;
+  for (const userId of userIds) {
+    if (!members[userId]) throw runtimeError("NOT_FOUND", `${operationType} user ${userId} is not a room member`);
+  }
+}
+
+function publicMemberKeyClaim(claim) {
+  return {
+    memberId: claim.memberId,
+    deviceId: claim.deviceId,
+    keyId: claim.keyId,
+    publicKey: claim.publicKey,
+    publicKeyFingerprint: claim.publicKeyFingerprint,
+    ...(claim.notificationPublicKey ? {
+      notificationAlg: claim.notificationAlg,
+      notificationKeyEpoch: claim.notificationKeyEpoch,
+      notificationPublicKey: claim.notificationPublicKey
+    } : {}),
+    createdAt: claim.createdAt
+  };
+}
+
+function applyMemberKeyPublish(state, payload, actor, now) {
+  const claim = payload.claim;
+  if (claim.memberId !== actor.memberId || claim.deviceId !== actor.deviceId || claim.keyId !== actor.keyId) {
+    throw runtimeError("FORBIDDEN", "member.key.publish claim must match the operation signer");
+  }
+  const current = directState(state);
+  const member = current.memberKeys[claim.memberId] || { memberId: claim.memberId, devices: {} };
+  return {
+    ...state,
+    memberKeys: {
+      ...current.memberKeys,
+      [claim.memberId]: {
+        ...member,
+        memberId: claim.memberId,
+        devices: {
+          ...(isPlainObject(member.devices) ? member.devices : {}),
+          [claim.deviceId]: publicMemberKeyClaim(claim)
+        },
+        updatedAt: now
+      }
+    }
+  };
+}
+
+function upsertDirectThread(state, payload, actor, operation, messageId, now) {
+  const current = directState(state);
+  const existing = current.directThreads[payload.threadId];
+  const ledgerId = operation?.ledgerId && isSnowflakeId(operation.ledgerId) ? operation.ledgerId : undefined;
+  const thread = existing || {
+    id: payload.threadId,
+    protocol: NIP17_PROTOCOL,
+    userIds: payload.userIds,
+    topicKey: payload.topicKey,
+    createdBy: actor.memberId,
+    createdAt: now
+  };
+  return {
+    ...state,
+    directThreads: {
+      ...current.directThreads,
+      [payload.threadId]: {
+        ...thread,
+        protocol: NIP17_PROTOCOL,
+        userIds: payload.userIds,
+        topicKey: payload.topicKey,
+        updatedAt: now,
+        ...(ledgerId ? { lastLedgerId: ledgerId } : {}),
+        ...(messageId ? { lastMessageId: messageId } : {})
+      }
+    }
+  };
+}
+
+function directMessageIdFor(operation) {
+  if (operation?.ledgerId && isSnowflakeId(operation.ledgerId)) return `direct_message_${operation.ledgerId}`;
+  if (operation?.snowflakeId && isSnowflakeId(operation.snowflakeId)) return `direct_message_${operation.snowflakeId}`;
+  const digest = hashCanonical({ kind: "matterhorn.direct.message.v1", operationId: operation.id }).slice("sha256-".length, "sha256-".length + 32);
+  return `direct_message_${digest}`;
+}
+
+function applyDirectMessagePublish(state, payload, actor, operation, now) {
+  assertActorInThread(actor, payload.userIds, operation.type);
+  assertKnownRoomMembers(state, payload.userIds, operation.type);
+  const id = directMessageIdFor(operation);
+  const ledgerId = operation?.ledgerId && isSnowflakeId(operation.ledgerId) ? operation.ledgerId : undefined;
+  const withThread = upsertDirectThread(state, payload, actor, operation, id, now);
+  const current = directState(withThread);
+  return {
+    ...withThread,
+    directMessages: {
+      ...current.directMessages,
+      [id]: {
+        id,
+        protocol: NIP17_PROTOCOL,
+        threadId: payload.threadId,
+        userIds: payload.userIds,
+        topicKey: payload.topicKey,
+        authorId: actor.memberId,
+        authorDeviceId: actor.deviceId,
+        authorKeyId: actor.keyId,
+        authorPublicKey: actor.publicKey,
+        operationId: operation.id,
+        ...(ledgerId ? { ledgerId, snowflakeId: ledgerId } : {}),
+        createdAt: now,
+        giftWraps: payload.giftWraps
+      }
+    }
+  };
+}
+
+function applyDirectOperationToRoomState(state, operation, actor, now) {
+  const payload = operation.payload;
+  if (operation.type === CORE_MEMBER_KEY_PUBLISH_TYPE) return applyMemberKeyPublish(state, payload, actor, now);
+  if (CORE_DIRECT_OPERATION_TYPES.includes(operation.type)) return applyDirectMessagePublish(state, payload, actor, operation, now);
+  throw runtimeError("UNKNOWN_CORE_OPERATION", `Unknown core direct operation ${operation.type}`);
+}
+
+function publicMessageForActor(message, memberId) {
+  const wrap = message.giftWraps?.[memberId];
+  if (!wrap) return undefined;
+  return {
+    ...clone(message),
+    giftWraps: { [memberId]: clone(wrap) }
+  };
+}
+
+function publicDirectView(state, actor = {}) {
+  const current = directState(state);
+  const memberId = actor.memberId;
+  const visibleThreads = {};
+  for (const [id, thread] of Object.entries(current.directThreads)) {
+    if (!Array.isArray(thread.userIds) || !thread.userIds.includes(memberId)) continue;
+    const item = clone(thread);
+    const readTag = readTagForScope(state, memberId, "direct.thread", id);
+    if (readTag) item.readTag = readTag;
+    visibleThreads[id] = item;
+  }
+  const visibleThreadIds = new Set(Object.keys(visibleThreads));
+  const visibleMessages = {};
+  for (const [id, message] of Object.entries(current.directMessages)) {
+    if (!visibleThreadIds.has(message.threadId)) continue;
+    const view = publicMessageForActor(message, memberId);
+    if (view) visibleMessages[id] = view;
+  }
+  return { threads: visibleThreads, messages: visibleMessages, keys: clone(current.memberKeys) };
+}
+
+module.exports = {
+  applyDirectOperationToRoomState,
+  directMessageIdFor,
+  publicDirectView
+};

package/src/runtime/directMessages.cjs

@@ -0,0 +1,6 @@
+module.exports = {
+  ...require("./directMessages/constants.cjs"),
+  ...require("./directMessages/payloads.cjs"),
+  ...require("./directMessages/state.cjs"),
+  ...require("./directMessages/commit.cjs")
+};

package/src/runtime/lifecycle.cjs

@@ -0,0 +1,166 @@
+const { ROOM_STATE_SCHEMA_VERSION } = require("../constants.cjs");
+const { runtimeError, MatterhornRuntimeError } = require("../errors.cjs");
+const { migratePluginState } = require("../plugins/migrations.cjs");
+const { parseWithSchema } = require("../state.cjs");
+const { clone } = require("../shared.cjs");
+const { applyAuthorityProjection, normalizeAuthorityState } = require("@mh-gg/authority");
+const { stateWithOperationLogMembers } = require("./memberProfiles.cjs");
+
+function appPackForCurrentRuntime(stateAppPack, roomAppPack) {
+  if (!stateAppPack) return clone(roomAppPack);
+  if (stateAppPack.id === roomAppPack.id && stateAppPack.hash !== roomAppPack.hash) return clone(roomAppPack);
+  return clone(stateAppPack);
+}
+
+async function start() {
+  let state = await this.store.load();
+  if (state) {
+    state = await this.migrateExistingState(state);
+    if (this.initialAuthority && !state.authority) {
+      const projected = applyAuthorityProjection(this.initialAuthority, state.members);
+      state = { ...state, authority: projected.authority, members: projected.members, adminIds: projected.adminIds };
+    } else if (state.authority) {
+      const projected = applyAuthorityProjection(normalizeAuthorityState(state.authority), state.members);
+      state = { ...state, authority: projected.authority, members: projected.members, adminIds: projected.adminIds };
+    }
+    state = await stateWithOperationLogMembers(this, state);
+    state = this.validateRoomState(state);
+    if (!this.replayBaseState && state.authority && (!this.operationLog?.entries || this.operationLog.entries.length === 0)) this.replayBaseState = clone(state);
+    await this.store.save(state);
+    if (!this.started) await this.runLifecycleHook("onRoomStart", state);
+    if (!this.started) await this.runLifecycleHook("afterStart", state);
+    this.started = true;
+    return clone(state);
+  }
+
+  if ((this.productionRuntime || this.relayExecuted) && !this.initialAuthority) {
+    throw runtimeError("BOOTSTRAP_AUTHORITY_REQUIRED", "Production and relay-executed empty rooms require initial owner/admin authority");
+  }
+
+  const createdAt = this.now();
+  state = {
+    schemaVersion: ROOM_STATE_SCHEMA_VERSION,
+    roomId: this.room.id,
+    appPack: clone(this.room.appPack),
+    version: 0,
+    createdAt,
+    updatedAt: createdAt,
+    members: clone(this.initialMembers || {}),
+    revokedCredentialIds: Array.isArray(this.initialRevokedCredentialIds) ? this.initialRevokedCredentialIds.slice(-this.maxRevokedCredentialIds) : [],
+    pluginVersions: {},
+    plugins: {},
+    seenOperations: []
+  };
+
+  for (const plugin of this.pluginList()) {
+    const context = this.createContext({ plugin, roomState: state, pluginState: undefined });
+    await this.runPluginHook(plugin, "onInstall", state, undefined);
+    let pluginState;
+    try {
+      pluginState = await plugin.createInitialState(context);
+    } catch (error) {
+      throw runtimeError("PLUGIN_INITIAL_STATE_FAILED", `${plugin.id}: ${error?.message || error}`);
+    }
+    state.plugins[plugin.id] = parseWithSchema(plugin.schemas.state, pluginState, `${plugin.id} state`);
+    state.pluginVersions[plugin.id] = plugin.version;
+  }
+
+  if (this.initialAuthority) {
+    const projected = applyAuthorityProjection(this.initialAuthority, state.members);
+    state = { ...state, authority: projected.authority, members: projected.members, adminIds: projected.adminIds };
+  }
+  state = this.validateRoomState(state);
+  if (!this.replayBaseState) this.replayBaseState = clone(state);
+  await this.store.save(state);
+  await this.runLifecycleHook("onRoomStart", state);
+  await this.runLifecycleHook("afterStart", state);
+  this.started = true;
+  return clone(state);
+}
+
+async function migrateExistingState(state) {
+  const timestamp = this.now();
+  const previous = clone(state);
+  const next = {
+    schemaVersion: ROOM_STATE_SCHEMA_VERSION,
+    seenOperations: [],
+    pluginVersions: {},
+    plugins: {},
+    revokedCredentialIds: [],
+    ...previous,
+    appPack: appPackForCurrentRuntime(previous.appPack, this.room.appPack),
+    createdAt: previous.createdAt ?? timestamp,
+    updatedAt: previous.updatedAt ?? previous.createdAt ?? timestamp
+  };
+  for (const plugin of this.pluginList()) {
+    const pluginState = next.plugins[plugin.id];
+    if (pluginState === undefined) {
+      const created = await plugin.createInitialState(this.createContext({ plugin, roomState: next, pluginState: undefined }));
+      next.plugins[plugin.id] = parseWithSchema(plugin.schemas.state, created, `${plugin.id} state`);
+    } else {
+      next.plugins[plugin.id] = await migratePluginState(plugin, next, this.createContext({ plugin, roomState: next, pluginState }));
+    }
+    next.pluginVersions[plugin.id] = plugin.version;
+  }
+  next.seenOperations = (Array.isArray(next.seenOperations) ? next.seenOperations : []).slice(-this.maxSeenOperations);
+  if (this.initialAuthority && !next.authority) {
+    const projected = applyAuthorityProjection(this.initialAuthority, next.members);
+    next.authority = projected.authority;
+    next.members = projected.members;
+    next.adminIds = projected.adminIds;
+  } else if (next.authority) {
+    const projected = applyAuthorityProjection(normalizeAuthorityState(next.authority), next.members);
+    next.authority = projected.authority;
+    next.members = projected.members;
+    next.adminIds = projected.adminIds;
+  }
+  return this.validateRoomState(next);
+}
+
+async function runPluginHook(plugin, name, state, pluginState) {
+  const hook = plugin[name];
+  if (typeof hook !== "function") return;
+  try {
+    await hook(this.createContext({ plugin, roomState: state, pluginState }), { roomState: state, pluginState });
+  } catch (error) {
+    if (error instanceof MatterhornRuntimeError) throw error;
+    throw runtimeError("LIFECYCLE_HOOK_FAILED", `${plugin.id}.${name} failed: ${error?.message || error}`);
+  }
+}
+
+async function runLifecycleHook(name, state, options = {}) {
+  for (const plugin of this.pluginList(options)) await this.runPluginHook(plugin, name, state, state.plugins?.[plugin.id]);
+}
+
+async function stop() {
+  const state = await this.store.load();
+  try {
+    if (state) await this.runLifecycleHook("onRoomStop", this.validateRoomState(state), { reverse: true });
+  } finally {
+    this.started = false;
+  }
+}
+
+async function uninstall() {
+  const state = await this.store.load();
+  try {
+    if (state) await this.runLifecycleHook("onUninstall", this.validateRoomState(state), { reverse: true });
+  } finally {
+    this.started = false;
+  }
+}
+
+async function getState() {
+  await this.start();
+  return clone(this.validateRoomState(await this.store.load()));
+}
+
+module.exports = {
+  getState,
+  migrateExistingState,
+  runLifecycleHook,
+  runPluginHook,
+  start,
+  stop,
+  uninstall
+};