@mh-gg/schema 0.1.1-alpha.20260613T085325975Z

package/schemas/example-app.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://matterhorn.gg/schemas/example-app.schema.json",
+  "title": "Matterhorn example app definition",
+  "type": "object",
+  "required": ["kind", "schemaVersion", "slug", "packageName", "appId", "pluginId", "version", "name", "composition"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "$imports": { "type": ["array", "object"] },
+    "kind": { "const": "matterhorn.example-app.schema" },
+    "schemaVersion": { "const": 1 },
+    "slug": { "type": "string", "minLength": 1 },
+    "packageName": { "type": "string", "minLength": 1 },
+    "appId": { "type": "string", "minLength": 1 },
+    "pluginId": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "minLength": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "exportPrefix": { "type": "string", "minLength": 1 },
+    "constantPrefix": { "type": "string", "minLength": 1 },
+    "composition": { "type": "string", "minLength": 1 },
+    "demo": { "type": "string", "minLength": 1 },
+    "frontend": {
+      "oneOf": [
+        { "const": false },
+        {
+          "type": "object",
+          "properties": {
+            "port": { "type": "integer", "minimum": 1 },
+            "defaultPort": { "type": "integer", "minimum": 1 },
+            "bundlePort": { "type": "integer", "minimum": 1 },
+            "devEntry": { "type": "string" },
+            "builtEntry": { "type": "string" },
+            "backgroundColor": { "type": "string", "minLength": 1, "maxLength": 128 },
+            "icon": {
+              "oneOf": [
+                { "type": "string", "minLength": 1, "maxLength": 512 },
+                {
+                  "type": "object",
+                  "properties": {
+                    "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+                    "svg": { "type": "string", "minLength": 1, "maxLength": 65536 },
+                    "label": { "type": "string", "minLength": 1, "maxLength": 120 }
+                  },
+                  "additionalProperties": false,
+                  "anyOf": [
+                    { "required": ["path"] },
+                    { "required": ["svg"] }
+                  ]
+                }
+              ]
+            },
+            "label": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "matterhornApp": { "type": "object" },
+    "exportAliases": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 } },
+    "example": { "type": "object" },
+    "typeNamespace": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/schemas/example-demo.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://matterhorn.gg/schemas/example-demo.schema.json",
+  "title": "Matterhorn example demo replay schema",
+  "type": "object",
+  "required": ["kind", "schemaVersion", "roomId", "operations"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "$imports": { "type": ["array", "object"] },
+    "kind": { "const": "matterhorn.example-demo.schema" },
+    "schemaVersion": { "const": 1 },
+    "roomId": { "type": "string", "minLength": 1 },
+    "startTime": { "type": "number" },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "actor", "payload"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "pluginId": { "type": "string", "minLength": 1 },
+          "plugin": { "type": "string", "minLength": 1 },
+          "type": { "type": "string", "minLength": 1 },
+          "actor": {
+            "type": "object",
+            "required": ["memberId", "deviceId", "role"],
+            "properties": {
+              "memberId": { "type": "string", "minLength": 1 },
+              "deviceId": { "type": "string", "minLength": 1 },
+              "role": { "type": "string", "minLength": 1 },
+              "displayName": { "type": "string" }
+            },
+            "additionalProperties": true
+          },
+          "seq": { "type": "integer", "minimum": 1 },
+          "createdAt": { "type": "number" },
+          "payload": { "type": "object" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "summary": { "type": "object" }
+  },
+  "additionalProperties": false
+}

package/schemas/micro-plugin.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://matterhorn.gg/schemas/micro-plugin.schema.json",
+  "title": "Matterhorn reusable micro-plugin schema",
+  "type": "object",
+  "required": ["kind", "schemaVersion", "key", "id", "version", "source"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "kind": { "const": "matterhorn.micro-plugin.schema" },
+    "schemaVersion": { "const": 1 },
+    "key": { "type": "string", "minLength": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "minLength": 1 },
+    "source": { "type": "object" },
+    "plugin": { "type": "object" },
+    "packageName": { "type": "string" },
+    "exportName": { "type": "string" }
+  },
+  "additionalProperties": true
+}

package/src/actions.cjs

@@ -0,0 +1,31 @@
+const { builtinMicroPluginRegistry } = require("./registry.cjs");
+const { validateAppCompositionSchema } = require("./composition.cjs");
+
+function pluginIdForAction(descriptor, schema, registry = builtinMicroPluginRegistry) {
+  if (descriptor.plugin === "primary" || descriptor.plugin === "$primary") return schema.primaryPlugin.id;
+  if (descriptor.plugin === "core" || descriptor.plugin === "matterhorn.core") return "matterhorn.core";
+  return registry.get(descriptor.plugin).schema.id;
+}
+
+function createActionDispatchersFromComposition(schema, options = {}) {
+  const registry = options.registry || builtinMicroPluginRegistry;
+  const composition = validateAppCompositionSchema(schema, { registry });
+  const dispatchers = {};
+  for (const descriptor of composition.actions) {
+    dispatchers[descriptor.name] = (client, input = {}) => {
+      const payload = {
+        ...(descriptor.payloadDefaults || {}),
+        ...(input || {})
+      };
+      return client.dispatch({ schemaAction: descriptor.name, pluginId: pluginIdForAction(descriptor, composition, registry), type: descriptor.type, payload });
+    };
+  }
+  return Object.freeze(dispatchers);
+}
+
+function actionDescriptorsForPlugin(schema, pluginSelection) {
+  const composition = validateAppCompositionSchema(schema);
+  return Object.freeze(composition.actions.filter((action) => action.plugin === pluginSelection || action.plugin === pluginSelection?.key || action.plugin === pluginSelection?.id));
+}
+
+module.exports = { actionDescriptorsForPlugin, createActionDispatchersFromComposition, pluginIdForAction };

package/src/app.d.ts

@@ -0,0 +1,119 @@
+import type { Json, Model, QueryDef, ScopeDef } from "./index";
+export type { NotificationsBlock } from "./notifications";
+
+export type MatterhornFrontendCommand = { command: string; args?: string[]; env?: Record<string, string> };
+export type MatterhornFrontendIcon = string | {
+  path?: string;
+  svg?: string;
+  label?: string;
+};
+export type MatterhornFrontendOptions = false | {
+  kind?: string;
+  root?: string;
+  label?: string;
+  port?: number;
+  defaultPort?: number;
+  bundlePort?: number;
+  devEntry?: string;
+  builtEntry?: string;
+  backgroundColor?: string;
+  icon?: MatterhornFrontendIcon;
+  mountPath?: string;
+  healthPath?: string;
+  dev?: MatterhornFrontendCommand;
+  build?: MatterhornFrontendCommand;
+  dist?: string;
+  bundle?: Record<string, unknown>;
+  locations?: object[];
+};
+
+export type MatterhornAppOptions = {
+  slug?: string;
+  packageName?: string;
+  packageRoot?: string;
+  exportPrefix?: string;
+  constantPrefix?: string;
+  typeNamespace?: string;
+  frontend?: MatterhornFrontendOptions;
+  matterhorn?: object;
+  matterhornApp?: object;
+  deployment?: object;
+  example?: object;
+  demo?: object;
+  exportAliases?: Record<string, string>;
+  publisher?: object;
+  trust?: object;
+  appCapabilities?: object;
+  hostCapabilities?: object;
+  entrypoints?: object;
+  recommendedFor?: object;
+  playerRoutes?: object[];
+  playerActions?: object;
+  optimisticReducers?: object;
+  navigation?: object;
+  deviceHints?: object;
+  hostPlugin?: object;
+  hostPlugins?: Array<object | { plugin: object; config?: Json }>;
+  hostPluginExport?: string;
+  hostPluginSource?: string;
+  hostPluginDependsOn?: string[];
+  hostPluginConflictsWith?: string[];
+  hostPackExport?: string;
+  playerPackId?: string;
+  playerPackExport?: string;
+  playerPluginId?: string;
+  playerPluginExport?: string;
+  createdAt?: string;
+  summary?: (state: unknown) => object;
+  registry?: unknown;
+  compositionSchema?: object;
+};
+
+export type AppSpec = MatterhornAppOptions & {
+  id: string;
+  name?: string;
+  namespace?: string;
+  version?: string;
+  pluginId?: string;
+  model: Model | object;
+  plugins?: Array<string | { key?: string; id?: string; config?: Json }>;
+  scopes?: ScopeDef[];
+  views?: Record<string, QueryDef | object> | object[];
+  queries?: Record<string, QueryDef | object>;
+  actions?: object;
+  routes?: Array<{ path: string; component: string; requires?: unknown[]; requiredPlugins?: string[] }>;
+  notifications?: NotificationsBlock;
+};
+
+export interface AppDef {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly namespace: string;
+  toJSON(): object;
+  toJSONFragments(options?: object): { composition: object; model: object; actions: object };
+  toTypes(options?: { namespace?: string }): string;
+  emit(options?: EmitOptions): EmitResult;
+  toMatterhornApp(options?: MatterhornAppOptions): object;
+  toMatterhornExports(options?: MatterhornAppOptions): Record<string, unknown>;
+  toMatterhornBundle(options?: MatterhornAppOptions): Record<string, unknown>;
+  emitMatterhornBundle(options?: MatterhornAppOptions & { outDir?: string; fileName?: string }): { bundlePath: string; bundle: Record<string, unknown> };
+}
+
+export type EmitOptions = {
+  outDir?: string;
+  modelFile?: string;
+  actionsFile?: string;
+  compositionFile?: string;
+  typesFile?: string;
+  namespace?: string;
+  schemaPath?: string | false;
+};
+
+export type EmitResult = {
+  modelPath: string;
+  actionsPath: string;
+  compositionPath: string;
+  typesPath: string;
+  composition: object;
+};

package/src/builder/app.cjs

@@ -0,0 +1,157 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { createAppCompositionSchema } = require('../composition.cjs');
+const { actionNameFromOperation } = require('../microPlugin.cjs');
+const { builtinMicroPluginRegistry } = require('../registry.cjs');
+const { cloneJson } = require('../json.cjs');
+const { generateAppTypeDeclaration, namespaceNameForApp } = require('../types/index.cjs');
+const { cleanObject } = require('./schema.cjs');
+const { modelToJson, queryToJson, SCOPE_DEF, MODEL_DEF } = require('./model.cjs');
+const {
+  APP_MATTERHORN_META,
+  createMatterhornAppBundle,
+  createMatterhornAppDescriptor,
+  createMatterhornAppExports,
+  emitMatterhornAppBundle,
+  matterhornMetadataForSpec
+} = require('./matterhornApp.cjs');
+
+const APP_DEF = Symbol.for('matterhorn.schema.builder.app');
+
+function pluginSelectionForComposition(plugin) {
+  if (typeof plugin === 'string') return plugin;
+  if (plugin?.key) return cleanObject({ key: plugin.key, config: plugin.config });
+  if (plugin?.id) return cleanObject({ id: plugin.id, config: plugin.config });
+  throw new Error('plugins must be registry keys, ids, or plugin refs');
+}
+
+function pluginKeyForAction(plugin, registry) {
+  if (typeof plugin === 'string') return registry.get(plugin).schema.key;
+  return registry.get(plugin.key || plugin.id).schema.key;
+}
+
+function defaultActionsForApp(modelJson, plugins = [], registry = builtinMicroPluginRegistry) {
+  const actions = {};
+  for (const type of Object.keys(modelJson.operations || {}).sort()) actions[actionNameFromOperation(type)] = { plugin: 'primary', type };
+  for (const plugin of plugins) {
+    const key = pluginKeyForAction(plugin, registry);
+    const record = registry.get(key);
+    for (const action of record.schema.actions || []) {
+      const name = actions[action.name] ? `${key}.${action.name}` : action.name;
+      actions[name] = cleanObject({ plugin: key, type: action.type, payloadDefaults: action.payloadDefaults, payloadSchema: action.payloadSchema, requiredRole: action.requiredRole });
+    }
+  }
+  return actions;
+}
+
+function viewDescriptors(views = {}) {
+  if (Array.isArray(views)) return cloneJson(views);
+  const out = [];
+  for (const [name, view] of Object.entries(views || {})) {
+    if (view?.plugin || view?.query) out.push({ name, ...cloneJson(view) });
+    else out.push({ name, plugin: 'primary', kind: 'query', query: name, ...queryToJson(view) });
+  }
+  return out;
+}
+
+function normalizeRoute(route) {
+  const out = { path: route.path, component: route.component };
+  const required = route.requiredPlugins || route.requires;
+  if (required) {
+    out.requiredPlugins = required.map((item) => {
+      if (typeof item === 'string') return item;
+      if (item?.[MODEL_DEF]) return undefined;
+      if (item?.id) return item.id;
+      return item;
+    }).filter(Boolean);
+  }
+  return cleanObject(out);
+}
+
+function actionsArrayToObject(actions = []) {
+  const out = {};
+  for (const action of actions) out[action.name] = cleanObject({ plugin: action.plugin, type: action.type, payloadDefaults: action.payloadDefaults, payloadSchema: action.payloadSchema, requiredRole: action.requiredRole, label: action.label });
+  return out;
+}
+
+function appActionsForSpec(modelJson, plugins, specActions, registry) {
+  const defaults = defaultActionsForApp(modelJson, plugins, registry);
+  if (!specActions) return defaults;
+  const configured = Array.isArray(specActions) ? actionsArrayToObject(specActions) : specActions;
+  return { ...defaults, ...configured };
+}
+
+function splitCompositionForFiles(composition, options = {}) {
+  const modelPath = options.modelPath || './model.json';
+  const actionsPath = options.actionsPath || './actions.json';
+  const schemaPath = options.schemaPath === false ? undefined : (options.schemaPath || 'matterhorn-sdk/schemas/app-composition.schema.json');
+  const model = cloneJson(composition.primaryPlugin.model || {});
+  const actions = actionsArrayToObject(composition.actions || []);
+  const split = cleanObject({
+    ...(schemaPath ? { $schema: schemaPath } : {}),
+    $imports: [{ path: modelPath, into: 'primaryPlugin.model' }, { path: actionsPath, into: 'actions' }],
+    ...cloneJson(composition)
+  });
+  delete split.primaryPlugin.model;
+  delete split.actions;
+  delete split.schemaHash;
+  return { composition: split, model, actions };
+}
+
+function defineApp(spec = {}) {
+  const registry = spec.registry || builtinMicroPluginRegistry;
+  const modelJson = modelToJson(spec.model);
+  const plugins = (spec.plugins || []).map(pluginSelectionForComposition);
+  const sharedScopes = {};
+  for (const scope of spec.scopes || []) {
+    if (scope?.[SCOPE_DEF]) sharedScopes[scope.key] = scope.toJSON();
+    else if (scope?.key) sharedScopes[scope.key] = cloneJson(scope);
+  }
+  const appSpec = {
+    app: { id: spec.id, version: spec.version || '1.0.0', name: spec.name || spec.id },
+    primaryPlugin: { id: spec.pluginId || `${spec.id}.plugin`, version: spec.version || '1.0.0', model: modelJson },
+    plugins,
+    ...(Object.keys(sharedScopes).length ? { sharedScopes } : {}),
+    views: viewDescriptors(spec.views || spec.queries || modelJson.views || {}),
+    actions: appActionsForSpec(modelJson, plugins, spec.actions, registry),
+    routes: (spec.routes || []).map(normalizeRoute),
+    ...(spec.notifications ? { notifications: spec.notifications } : {})
+  };
+  const composition = createAppCompositionSchema(appSpec, registry);
+  const matterhornMetadata = matterhornMetadataForSpec(spec, registry);
+  const app = {
+    [APP_DEF]: true,
+    [APP_MATTERHORN_META]: matterhornMetadata,
+    id: composition.app.id,
+    name: composition.app.name,
+    version: composition.app.version,
+    namespace: spec.namespace || namespaceNameForApp(composition),
+    toJSON() { return cloneJson(composition); },
+    toJSONFragments(options = {}) { return splitCompositionForFiles(composition, options); },
+    toTypes(options = {}) { return generateAppTypeDeclaration(composition, { ...options, namespace: options.namespace || app.namespace, registry: options.registry || registry }); },
+    emit(options = {}) { return emitAppArtifacts(app, options); },
+    toMatterhornApp(options = {}) { return createMatterhornAppDescriptor(app, options); },
+    toMatterhornExports(options = {}) { return createMatterhornAppExports(app, options); },
+    toMatterhornBundle(options = {}) { return createMatterhornAppBundle(app, options); },
+    emitMatterhornBundle(options = {}) { return emitMatterhornAppBundle(app, options); }
+  };
+  return Object.freeze(app);
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function emitAppArtifacts(app, options = {}) {
+  if (!app?.[APP_DEF]) throw new Error('emitAppArtifacts requires a defineApp() result');
+  const outDir = path.resolve(options.outDir || '.');
+  const schemaFile = options.schemaFile || options.compositionFile || 'matterhorn.schema.json';
+  const typesFile = options.typesFile || 'matterhorn.types.d.ts';
+  writeJson(path.join(outDir, schemaFile), app.toJSON());
+  fs.mkdirSync(path.dirname(path.join(outDir, typesFile)), { recursive: true });
+  fs.writeFileSync(path.join(outDir, typesFile), app.toTypes({ namespace: options.namespace || app.namespace }));
+  return Object.freeze({ schemaPath: path.join(outDir, schemaFile), typesPath: path.join(outDir, typesFile), composition: app.toJSON() });
+}
+
+module.exports = { APP_DEF, defineApp, emitAppArtifacts, splitCompositionForFiles };

package/src/builder/effects.cjs

@@ -0,0 +1,116 @@
+const { cloneJson, nonEmptyString } = require('../json.cjs');
+const { cleanObject, ensurePlainObject } = require('./schema.cjs');
+
+const COLLECTION_HANDLE = Symbol.for('matterhorn.schema.builder.collection');
+
+const READ_CLASSES = Object.freeze(['window', 'head', 'full-fold']);
+const INTEGRITY_CLASSES = Object.freeze(['signature', 'seq', 'checkpoint']);
+
+function normalizeReadClass(value) {
+  if (!value) return 'full-fold';
+  const v = String(value);
+  return READ_CLASSES.includes(v) ? v : 'full-fold';
+}
+
+function normalizeIntegrityClass(value) {
+  if (!value) return 'checkpoint';
+  const v = String(value);
+  return INTEGRITY_CLASSES.includes(v) ? v : 'checkpoint';
+}
+
+function collectionHandle(name, sample, options = {}) {
+  const storage = options.storage || (Array.isArray(sample) ? 'array' : 'map');
+  const readClass = normalizeReadClass(options.readClass);
+  const integrityClass = normalizeIntegrityClass(options.integrityClass);
+  const handle = {
+    [COLLECTION_HANDLE]: true,
+    name: nonEmptyString(name, 'collection name'),
+    storage,
+    readClass,
+    integrityClass
+  };
+  return Object.freeze(handle);
+}
+
+function isCollection(value) {
+  return Boolean(value && typeof value === 'object' && value[COLLECTION_HANDLE]);
+}
+
+function normalizeCollection(collection, name = 'collection') {
+  if (isCollection(collection)) return collection;
+  if (typeof collection === 'string') return collectionHandle(collection, {}, { storage: 'map' });
+  throw new Error(`${name} must be a collection handle or collection name`);
+}
+
+function idRefParts(value, fallbackPrefix) {
+  if (typeof value !== 'string') return {};
+  const match = /^\$payload\.([A-Za-z0-9_-]+)$/.exec(value);
+  if (match) return { idField: match[1] };
+  const idPrefix = /^\$id:([A-Za-z0-9_-]+)$/.exec(value);
+  if (idPrefix && fallbackPrefix !== false) return { idPrefix: idPrefix[1] };
+  return { id: value };
+}
+
+function fieldNameFromPayloadRef(value) {
+  if (typeof value !== 'string') return undefined;
+  const match = /^\$payload\.([A-Za-z0-9_-]+)$/.exec(value);
+  return match ? match[1] : undefined;
+}
+
+function collectionEffectBase(kind, collection) {
+  const c = normalizeCollection(collection);
+  return { kind, collection: c.name, storage: c.storage, partition: c.name };
+}
+
+function normalizeFields(fields = {}) {
+  ensurePlainObject(fields, 'fields');
+  return cloneJson(fields);
+}
+
+const fx = Object.freeze({
+  noop() { return { kind: 'noop' }; },
+  create(collection, spec = {}) {
+    const base = collectionEffectBase('createRecord', collection);
+    const idParts = spec.id !== undefined ? idRefParts(spec.id) : (spec.idPrefix ? { idPrefix: spec.idPrefix } : {});
+    return cleanObject({ ...base, ...idParts, fields: normalizeFields(spec.fields || {}), activity: spec.activity, recordLabel: spec.recordLabel });
+  },
+  update(collection, spec = {}) {
+    return cleanObject({ ...collectionEffectBase('updateRecord', collection), ...idRefParts(spec.id, false), fields: normalizeFields(spec.set || spec.fields || {}), activity: spec.activity, recordLabel: spec.recordLabel });
+  },
+  mark(collection, spec = {}) {
+    return cleanObject({ ...collectionEffectBase('markRecord', collection), ...idRefParts(spec.id, false), fields: normalizeFields(spec.set || spec.fields || {}), activity: spec.activity, recordLabel: spec.recordLabel });
+  },
+  merge(spec = {}) {
+    return cleanObject({ kind: 'mergePath', path: nonEmptyString(spec.path, 'merge path'), fields: spec.fields === undefined ? '$payload' : cloneJson(spec.fields), deleteNullFields: spec.deleteNullFields, activity: spec.activity });
+  },
+  append(pathOrCollection, item = '$payload') {
+    const pathValue = isCollection(pathOrCollection) ? pathOrCollection.name : pathOrCollection;
+    return { kind: 'appendToArray', path: nonEmptyString(pathValue, 'append path'), item: cloneJson(item) };
+  },
+  toggleReaction(collection, spec = {}) {
+    const idField = fieldNameFromPayloadRef(spec.id);
+    const emojiField = fieldNameFromPayloadRef(spec.emoji);
+    return cleanObject({ ...collectionEffectBase('toggleReaction', collection), ...(idField ? { idField } : idRefParts(spec.id, false)), ...(emojiField ? { emojiField } : { emoji: spec.emoji }), activity: spec.activity, recordLabel: spec.recordLabel });
+  },
+  insertIntoArray(collection, spec = {}) {
+    return cleanObject({ ...collectionEffectBase('insertIdIntoRecordArray', collection), ...idRefParts(spec.matchId || spec.id, false), arrayField: nonEmptyString(spec.field || spec.arrayField, 'array field'), value: cloneJson(spec.value), position: spec.at || spec.position, activity: spec.activity, recordLabel: spec.recordLabel });
+  },
+  removeFromArray(collection, spec = {}) {
+    return cleanObject({ ...collectionEffectBase('removeIdFromRecordArray', collection), ...idRefParts(spec.matchId || spec.id, false), arrayField: nonEmptyString(spec.field || spec.arrayField, 'array field'), value: cloneJson(spec.value), activity: spec.activity, recordLabel: spec.recordLabel });
+  },
+  upsertActor(collection, spec = {}) {
+    return cleanObject({ ...collectionEffectBase('upsertActorRecord', collection), fields: normalizeFields(spec.fields || {}), activity: spec.activity, recordLabel: spec.recordLabel });
+  }
+});
+
+module.exports = {
+  COLLECTION_HANDLE,
+  collectionEffectBase,
+  collectionHandle,
+  fx,
+  idRefParts,
+  isCollection,
+  normalizeCollection,
+  normalizeReadClass,
+  normalizeIntegrityClass
+};

package/src/builder/guards.cjs

@@ -0,0 +1,35 @@
+const { cloneJson, nonEmptyString } = require('../json.cjs');
+const { cleanObject } = require('./schema.cjs');
+const { collectionEffectBase, idRefParts } = require('./effects.cjs');
+
+function guardOperand(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value) && typeof value.kind === 'string' && value.kind.startsWith('value.')) return cloneJson(value);
+  if (typeof value === 'string' && value.startsWith('$')) return { kind: 'value.expr', expr: value };
+  return { kind: 'value.literal', value: cloneJson(value) };
+}
+
+const guard = Object.freeze({
+  path(pathValue) { return { kind: 'value.path', path: nonEmptyString(pathValue, 'guard path') }; },
+  length(pathValue) { return { kind: 'value.length', path: nonEmptyString(pathValue, 'guard length path') }; },
+  value(value) { return { kind: 'value.literal', value: cloneJson(value) }; },
+  expr(expr) { return { kind: 'value.expr', expr: nonEmptyString(expr, 'guard expression') }; },
+  ownerOrRole(collection, spec = {}) {
+    return cleanObject({ ...collectionEffectBase('recordOwnerOrRole', collection), ...idRefParts(spec.id || spec.match, false), ownerField: spec.ownerField, roles: spec.roles || [], message: spec.message, recordLabel: spec.recordLabel });
+  },
+  flagClear(collection, spec = {}) {
+    return cleanObject({ ...collectionEffectBase('recordFlagClear', collection), ...idRefParts(spec.id || spec.match, false), flag: nonEmptyString(spec.flag, 'guard flag'), message: spec.message, recordLabel: spec.recordLabel });
+  },
+  eq(left, right, message) { return cleanObject({ kind: 'eq', left: guardOperand(left), right: guardOperand(right), message }); },
+  ne(left, right, message) { return cleanObject({ kind: 'ne', left: guardOperand(left), right: guardOperand(right), message }); },
+  lt(left, right, message) { return cleanObject({ kind: 'lt', left: guardOperand(left), right: guardOperand(right), message }); },
+  lte(left, right, message) { return cleanObject({ kind: 'lte', left: guardOperand(left), right: guardOperand(right), message }); },
+  gt(left, right, message) { return cleanObject({ kind: 'gt', left: guardOperand(left), right: guardOperand(right), message }); },
+  gte(left, right, message) { return cleanObject({ kind: 'gte', left: guardOperand(left), right: guardOperand(right), message }); },
+  exists(pathValue, message) { return cleanObject({ kind: 'exists', path: nonEmptyString(pathValue, 'guard path'), message }); },
+  and(...guards) { return { kind: 'and', guards: cloneJson(guards.flat()) }; },
+  or(...guards) { return { kind: 'or', guards: cloneJson(guards.flat()) }; },
+  not(item) { return { kind: 'not', guard: cloneJson(item) }; },
+  noop() { return { kind: 'noop' }; }
+});
+
+module.exports = { guard, guardOperand };

package/src/builder/index.cjs

@@ -0,0 +1,11 @@
+module.exports = {
+  ...require('./schema.cjs'),
+  ...require('./effects.cjs'),
+  ...require('./refs.cjs'),
+  ...require('./guards.cjs'),
+  ...require('./model.cjs'),
+  ...require('./app.cjs'),
+  ...require('./notifications.cjs'),
+  ...require('./matterhornApp.cjs'),
+  ...require('./matterhornApp/demoAliases.cjs')
+};