@mh-gg/reducer-runtime 0.1.1-alpha.20260813T095547173Z

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matterhorn contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,6 @@
+# @mh-gg/reducer-runtime
+
+Pure deterministic reducer execution for Matterhorn clients and isolated tests.
+
+This package has no network transport, persistent store, operation log, migration,
+host startup, relay execution, or application-state authority.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mh-gg/reducer-runtime",
+  "version": "0.1.1-alpha.20260813T095547173Z",
+  "description": "Deterministic client-side and test-only reducer engine for Matterhorn apps.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "dependencies": {
+    "@mh-gg/authority": "^0.1.1-alpha.20260813T095547173Z",
+    "@mh-gg/base": "^0.1.1-alpha.20260813T095547173Z",
+    "@mh-gg/protocol": "^0.1.1-alpha.20260813T095547173Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-include=src/**/*.cjs test/*.test.cjs"
+  }
+}

package/src/errors.cjs

@@ -0,0 +1,21 @@
+class ReducerRuntimeError extends Error {
+  constructor(code, message) {
+    super(message || code);
+    this.name = "ReducerRuntimeError";
+    this.code = code;
+  }
+}
+
+function reducerError(code, message) {
+  return new ReducerRuntimeError(code, message);
+}
+
+function allow(details = {}) {
+  return { ok: true, ...details };
+}
+
+function deny(reason = "Forbidden") {
+  return { ok: false, reason };
+}
+
+module.exports = { ReducerRuntimeError, allow, deny, reducerError };

package/src/index.cjs

@@ -0,0 +1,6 @@
+module.exports = {
+  ...require("./errors.cjs"),
+  ...require("./plugin.cjs"),
+  ...require("./runtime.cjs"),
+  ...require("./schema.cjs")
+};

package/src/plugin.cjs

@@ -0,0 +1,38 @@
+const { reducerError } = require("./errors.cjs");
+const { clone } = require("./shared.cjs");
+
+const OPERATION_SCHEMA_DESCRIPTOR_KIND = "matterhorn.operation-schema-descriptor";
+
+function operationMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw reducerError("INVALID_PLUGIN_OPERATION_DESCRIPTOR", "operations must be an object");
+  return Object.fromEntries(Object.entries(value).map(([type, descriptor]) => [type, clone(descriptor)]));
+}
+
+function validatePlugin(plugin) {
+  if (!plugin || typeof plugin !== "object" || Array.isArray(plugin)) throw reducerError("INVALID_PLUGIN", "Plugin must be an object");
+  if (!plugin.id || !plugin.version) throw reducerError("INVALID_PLUGIN", "Plugin id and version are required");
+  if (typeof plugin.createInitialState !== "function") throw reducerError("INVALID_PLUGIN", `${plugin.id} createInitialState is required`);
+  if (typeof plugin.authorize !== "function") throw reducerError("INVALID_PLUGIN", `${plugin.id} authorize is required`);
+  if (typeof plugin.reduce !== "function") throw reducerError("INVALID_PLUGIN", `${plugin.id} reduce is required`);
+  if (!plugin.schemas?.state || !plugin.schemas?.operations) throw reducerError("INVALID_PLUGIN", `${plugin.id} schemas are required`);
+  for (const hook of ["afterCommit", "onInstall", "onRoomStart", "afterStart", "onRoomStop", "onUninstall", "migrations"]) {
+    if (plugin[hook] !== undefined) throw reducerError("NONDETERMINISTIC_PLUGIN", `${plugin.id} ${hook} is not available in the reducer runtime`);
+  }
+  return plugin;
+}
+
+function definePlugin(plugin) {
+  return validatePlugin(plugin);
+}
+
+function createOperationSchemaDescriptor(input, version, operations) {
+  if (input && typeof input === "object" && !Array.isArray(input) && arguments.length === 1) {
+    const plugin = input.plugin || input.pluginId;
+    if (!plugin || !input.version) throw reducerError("INVALID_PLUGIN_OPERATION_DESCRIPTOR", "plugin and version are required");
+    return { kind: input.kind || OPERATION_SCHEMA_DESCRIPTOR_KIND, plugin, version: input.version, ...(input.source ? { source: input.source } : {}), operations: operationMap(input.operations) };
+  }
+  if (typeof input !== "string" || !input || typeof version !== "string" || !version) throw reducerError("INVALID_PLUGIN_OPERATION_DESCRIPTOR", "plugin and version are required");
+  return { kind: OPERATION_SCHEMA_DESCRIPTOR_KIND, plugin: input, version, operations: operationMap(operations) };
+}
+
+module.exports = { OPERATION_SCHEMA_DESCRIPTOR_KIND, createOperationSchemaDescriptor, definePlugin, validatePlugin };

package/src/runtime.cjs

@@ -0,0 +1,181 @@
+const { hashCanonical } = require("@mh-gg/base");
+const { sortOperations } = require("@mh-gg/authority");
+const { snowflakeIdForOperation } = require("@mh-gg/protocol");
+const { reducerError } = require("./errors.cjs");
+const { validatePlugin } = require("./plugin.cjs");
+const { parseWithSchema } = require("./schema.cjs");
+const { clone } = require("./shared.cjs");
+const { canEditScope, canViewScope, evaluateScopedAction, scopedRoleForActor } = require("./scopedRoles/access.cjs");
+
+function requireRoom(room) {
+  if (!room?.id) throw reducerError("INVALID_ROOM", "room.id is required");
+  if (!room.appPack?.id || !room.appPack?.hash) throw reducerError("INVALID_ROOM", "room.appPack id and hash are required");
+  return clone(room);
+}
+
+function operationTime(operation) {
+  if (Number.isFinite(operation.createdAt)) return operation.createdAt;
+  throw reducerError("INVALID_OPERATION", "operation.createdAt is required for deterministic folding");
+}
+
+class ReducerRuntime {
+  constructor(options = {}) {
+    this.room = requireRoom(options.room);
+    this.plugins = new Map();
+    this.capabilities = new Set(options.capabilities || []);
+    this.initialState = clone(options.initialState);
+    this.state = undefined;
+    for (const plugin of options.plugins || []) {
+      validatePlugin(plugin);
+      if (this.plugins.has(plugin.id)) throw reducerError("DUPLICATE_PLUGIN", `Duplicate plugin ${plugin.id}`);
+      this.plugins.set(plugin.id, plugin);
+    }
+    if (this.plugins.size === 0) throw reducerError("NO_PLUGINS", "At least one plugin is required");
+  }
+
+  context(plugin, roomState, pluginState, actor, operation) {
+    const runtime = this;
+    let randomIndex = 0;
+    return {
+      room: { id: this.room.id, appPackId: this.room.appPack.id, appPackHash: this.room.appPack.hash },
+      plugin: { id: plugin.id, version: plugin.version, ...(plugin.config === undefined ? {} : { config: clone(plugin.config) }) },
+      actor: clone(actor),
+      roomState: clone(roomState),
+      pluginState: clone(pluginState),
+      now: operation ? operationTime(operation) : roomState.createdAt,
+      crypto: {
+        hash: hashCanonical,
+        verifySignature() { return false; },
+        randomId(prefix = "id") {
+          randomIndex += 1;
+          const digest = hashCanonical({ operationId: operation?.id || "initial", pluginId: plugin.id, prefix, randomIndex }).slice(7, 23);
+          return `${prefix}_${digest}`;
+        }
+      },
+      access: {
+        roleForScope(scopeType, scopeId, inputActor = actor) {
+          return scopedRoleForActor(roomState, inputActor, scopeType, scopeId);
+        },
+        canView(scopeType, scopeId, inputActor = actor) {
+          return canViewScope(roomState, inputActor, scopeType, scopeId);
+        },
+        canEdit(scopeType, scopeId, inputActor = actor) {
+          return canEditScope(roomState, inputActor, scopeType, scopeId);
+        },
+        canPerform(operationType, scopeType, scopeId, options = {}, inputActor = actor) {
+          return evaluateScopedAction({ state: roomState, actor: inputActor, operationType, scopeType, scopeId, at: operation?.createdAt, ...options }).allowed;
+        },
+        explain(operationType, scopeType, scopeId, options = {}, inputActor = actor) {
+          return evaluateScopedAction({ state: roomState, actor: inputActor, operationType, scopeType, scopeId, at: operation?.createdAt, ...options });
+        }
+      },
+      plugins: {
+        has(pluginId) { return runtime.plugins.has(pluginId); },
+        async call(pluginId, method, input) {
+          const target = runtime.plugins.get(pluginId);
+          const fn = target?.methods?.[method];
+          if (typeof fn !== "function") throw reducerError("PLUGIN_METHOD_NOT_FOUND", `Plugin method ${pluginId}.${method} is not available`);
+          return clone(await fn({ actor: clone(actor), roomState: clone(roomState), state: clone(roomState.plugins[pluginId]), capabilities: runtime.capabilities }, clone(input)));
+        }
+      },
+      capabilities: {
+        has: (capability) => runtime.capabilities.has(capability),
+        require: (capability) => {
+          if (!runtime.capabilities.has(capability)) throw reducerError("CAPABILITY_MISSING", `Missing capability ${capability}`);
+        }
+      }
+    };
+  }
+
+  async initialize() {
+    if (this.state) return this.getState();
+    const createdAt = Number.isFinite(this.initialState?.createdAt) ? this.initialState.createdAt : 0;
+    const state = this.initialState || {
+      roomId: this.room.id,
+      appPack: clone(this.room.appPack),
+      version: 0,
+      createdAt,
+      updatedAt: createdAt,
+      plugins: {},
+      pluginVersions: {}
+    };
+    state.plugins ||= {};
+    state.pluginVersions ||= {};
+    for (const plugin of this.plugins.values()) {
+      if (state.plugins[plugin.id] === undefined) {
+        const initial = await plugin.createInitialState(this.context(plugin, state, undefined, undefined, undefined));
+        state.plugins[plugin.id] = parseWithSchema(plugin.schemas.state, initial, `${plugin.id} state`);
+      } else {
+        state.plugins[plugin.id] = parseWithSchema(plugin.schemas.state, state.plugins[plugin.id], `${plugin.id} state`);
+      }
+      state.pluginVersions[plugin.id] = plugin.version;
+    }
+    this.state = clone(state);
+    return this.getState();
+  }
+
+  async fold(operation) {
+    await this.initialize();
+    if (!operation || typeof operation !== "object" || Array.isArray(operation)) throw reducerError("INVALID_OPERATION", "Operation must be an object");
+    if (operation.roomId !== this.room.id) throw reducerError("ROOM_MISMATCH", "Operation room does not match reducer room");
+    if (operation.appPackId !== this.room.appPack.id || operation.appPackHash !== this.room.appPack.hash) throw reducerError("APP_PACK_MISMATCH", "Operation app pack does not match reducer app");
+    const plugin = this.plugins.get(operation.pluginId);
+    if (!plugin) throw reducerError("PLUGIN_NOT_INSTALLED", `Plugin ${operation.pluginId} is not installed`);
+    const schema = plugin.schemas.operations[operation.type];
+    if (!schema) throw reducerError("UNKNOWN_OPERATION_TYPE", `Unknown operation type ${operation.type}`);
+    const ledgerId = snowflakeIdForOperation(operation);
+    const parsed = {
+      ...clone(operation),
+      ledgerId,
+      snowflakeId: ledgerId,
+      payload: parseWithSchema(schema, operation.payload, `${plugin.id}.${operation.type}`)
+    };
+    const pluginState = clone(this.state.plugins[plugin.id]);
+    const context = this.context(plugin, this.state, pluginState, parsed.actor, parsed);
+    const authorized = await plugin.authorize(context, parsed);
+    if (!authorized?.ok) throw reducerError("FORBIDDEN", authorized?.reason || "Forbidden");
+    const next = await plugin.reduce(context, pluginState, parsed);
+    this.state.plugins[plugin.id] = parseWithSchema(plugin.schemas.state, next, `${plugin.id} state`);
+    this.state.pluginVersions[plugin.id] = plugin.version;
+    this.state.version += 1;
+    this.state.updatedAt = operationTime(parsed);
+    return this.getState();
+  }
+
+  async foldBatch(operations) {
+    if (!Array.isArray(operations)) throw reducerError("INVALID_OPERATION_BATCH", "Operations must be an array");
+    for (const operation of sortOperations(operations)) await this.fold(operation);
+    return this.getState();
+  }
+
+  async query(pluginId, queryName, input, actor) {
+    await this.initialize();
+    const plugin = this.plugins.get(pluginId);
+    const query = plugin?.queries?.[queryName];
+    if (typeof query !== "function") throw reducerError("PLUGIN_QUERY_NOT_FOUND", `Plugin query ${pluginId}.${queryName} is not available`);
+    const pluginState = clone(this.state.plugins[pluginId]);
+    const result = await query(this.context(plugin, this.state, pluginState, actor), pluginState, clone(input), clone(actor));
+    const schema = plugin.schemas.queries?.[queryName];
+    return clone(schema ? parseWithSchema(schema, result, `${pluginId}.${queryName} query`) : result);
+  }
+
+  async project(actor) {
+    await this.initialize();
+    const plugins = {};
+    for (const [pluginId, plugin] of this.plugins) {
+      const pluginState = clone(this.state.plugins[pluginId]);
+      const value = typeof plugin.getPublicView === "function"
+        ? await plugin.getPublicView(this.context(plugin, this.state, pluginState, actor), pluginState, clone(actor))
+        : pluginState;
+      plugins[pluginId] = clone(plugin.schemas.publicView ? parseWithSchema(plugin.schemas.publicView, value, `${pluginId} public view`) : value);
+    }
+    return { roomId: this.state.roomId, appPack: clone(this.state.appPack), version: this.state.version, updatedAt: this.state.updatedAt, plugins };
+  }
+
+  getState() {
+    if (!this.state) throw reducerError("NOT_INITIALIZED", "Reducer runtime is not initialized");
+    return clone(this.state);
+  }
+}
+
+module.exports = { ReducerRuntime };

package/src/schema.cjs

@@ -0,0 +1,13 @@
+const { ReducerRuntimeError, reducerError } = require("./errors.cjs");
+
+function parseWithSchema(schema, value, name) {
+  if (!schema || typeof schema.parse !== "function") throw reducerError("SCHEMA_MISSING", `${name} schema is missing`);
+  try {
+    return schema.parse(value);
+  } catch (error) {
+    if (error instanceof ReducerRuntimeError) throw error;
+    throw reducerError("SCHEMA_INVALID", `${name} did not validate: ${error?.message || error}`);
+  }
+}
+
+module.exports = { parseWithSchema };

package/src/scopedRoles/access.cjs

@@ -0,0 +1,19 @@
+const { canEditScoped, canViewScoped, evaluateScopedAction, resolveScopedRole } = require("@mh-gg/authority");
+
+function scopedRoleForActor(roomState, actor, scopeType, scopeId) {
+  return resolveScopedRole(roomState, actor, scopeType, scopeId);
+}
+
+function canAccessScope(roomState, actor, scopeType, scopeId, requiredRole) {
+  return evaluateScopedAction({ state: roomState, actor, scopeType, scopeId, operationType: "matterhorn.scope.access", minimumLevel: requiredRole }).allowed;
+}
+
+function canViewScope(roomState, actor, scopeType, scopeId) {
+  return canViewScoped(roomState, actor, scopeType, scopeId);
+}
+
+function canEditScope(roomState, actor, scopeType, scopeId) {
+  return canEditScoped(roomState, actor, scopeType, scopeId);
+}
+
+module.exports = { canAccessScope, canEditScope, canViewScope, evaluateScopedAction, scopedRoleForActor };

package/src/shared.cjs

@@ -0,0 +1,5 @@
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+module.exports = { clone };