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

package/src/model/partitionValidator.cjs

@@ -0,0 +1,95 @@
+const { READ_CLASSES_CHUNKABLE, partitionsFromEffect, partitionsFromGuard } = require('./partitionOperands.cjs');
+
+function operationPartitions(operation) {
+  const parts = new Set();
+  for (const effect of operation.effects || []) {
+    for (const p of partitionsFromEffect(effect)) parts.add(p);
+  }
+  return parts;
+}
+
+function validateOperationShape(operationName, operation, shapes = {}) {
+  const issues = [];
+  const effectPartitions = operationPartitions(operation);
+  const affectedChunkableShapes = [];
+  for (const part of effectPartitions) {
+    const shape = shapes[part];
+    if (shape && READ_CLASSES_CHUNKABLE.has(shape.readClass)) {
+      affectedChunkableShapes.push(part);
+    }
+  }
+  if (affectedChunkableShapes.length === 0) return issues;
+
+  for (const guard of operation.guards || []) {
+    const guardParts = partitionsFromGuard(guard);
+    for (const gp of guardParts) {
+      if (!effectPartitions.has(gp)) {
+        issues.push({
+          operation: operationName,
+          type: 'cross-partition-guard',
+          guardKind: guard.kind,
+          partition: gp,
+          message: `Guard reads from partition "${gp}" but operation only writes to [${[...effectPartitions].join(', ')}]. ` +
+            `Chunkable shape "${affectedChunkableShapes.join(', ')}" cannot depend on another partition.`
+        });
+      }
+    }
+  }
+
+  for (const effect of operation.effects || []) {
+    const fxParts = partitionsFromEffect(effect);
+    for (const fp of fxParts) {
+      const shape = shapes[fp];
+      if (shape && READ_CLASSES_CHUNKABLE.has(shape.readClass)) {
+        for (const other of fxParts) {
+          if (other !== fp && !effectPartitions.has(other)) {
+            issues.push({
+              operation: operationName,
+              type: 'cross-partition-effect',
+              effectKind: effect.kind,
+              partition: other,
+              message: `Effect touches chunkable shape "${fp}" and also reads from "${other}".`
+            });
+          }
+        }
+      }
+    }
+  }
+
+  for (const effect of operation.effects || []) {
+    const part = effect.partition;
+    if (!part) continue;
+    const shape = shapes[part];
+    if (shape && shape.readClass === 'window') {
+      if (effect.kind === 'updateRecord' || effect.kind === 'markRecord' || effect.kind === 'removeIdFromRecordArray') {
+        issues.push({
+          operation: operationName,
+          type: 'non-crdt-window-effect',
+          effectKind: effect.kind,
+          partition: part,
+          message: `Window shape "${part}" does not support "${effect.kind}" because it is not append-only.`
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+function validateModelShapes(modelJson) {
+  const issues = [];
+  const shapes = modelJson?.shapes || {};
+  const operations = modelJson?.operations || {};
+  for (const [name, op] of Object.entries(operations)) {
+    issues.push(...validateOperationShape(name, op, shapes));
+  }
+  return issues;
+}
+
+module.exports = {
+  operationPartitions,
+  partitionsFromEffect,
+  partitionsFromGuard,
+  validateModelShapes,
+  validateOperationShape
+};

package/src/model/payload.cjs

@@ -0,0 +1,93 @@
+const { cloneJson } = require('../json.cjs');
+
+function schemaEntries(schemaPart) {
+  if (!schemaPart) return [];
+  if (Array.isArray(schemaPart)) return schemaPart.map((name) => [name, { type: 'string' }]);
+  return Object.entries(schemaPart).map(([name, spec]) => [name, typeof spec === 'string' ? { type: spec } : spec || { type: 'any' }]);
+}
+
+function parseValue(value, spec, name) {
+  const type = spec.type || 'any';
+  if (value === undefined || value === null || (value === '' && spec.nonEmpty !== false)) {
+    if (spec.default !== undefined) return cloneJson(spec.default);
+    if (spec.nullable) return null;
+    throw new Error(`${name} is required`);
+  }
+  if (type === 'any') return cloneJson(value);
+  if (type === 'string') {
+    if (typeof value !== 'string') throw new Error(`${name} must be a string`);
+    const trimmed = spec.trim === false ? value : value.trim();
+    if (!trimmed && spec.nonEmpty !== false) throw new Error(`${name} must be a non-empty string`);
+    if (spec.max && trimmed.length > spec.max) {
+      if (spec.truncate === true) return trimmed.slice(0, spec.max);
+      throw new Error(`${name} is too long`);
+    }
+    return trimmed;
+  }
+  if (type === 'number') {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) throw new Error(`${name} must be a finite number`);
+    if (spec.min !== undefined && parsed < spec.min) throw new Error(`${name} must be >= ${spec.min}`);
+    if (spec.max !== undefined && parsed > spec.max) throw new Error(`${name} must be <= ${spec.max}`);
+    return parsed;
+  }
+  if (type === 'boolean') return Boolean(value);
+  if (type === 'enum') {
+    if (!spec.values.includes(value) && spec.fallback !== undefined) return cloneJson(spec.fallback);
+    if (!spec.values.includes(value)) throw new Error(`${name} must be one of ${spec.values.join(', ')}`);
+    return value;
+  }
+  if (type === 'array') {
+    if (!Array.isArray(value)) throw new Error(`${name} must be an array`);
+    return value.map((item, index) => spec.items ? parseValue(item, spec.items, `${name}[${index}]`) : cloneJson(item));
+  }
+  if (type === 'object') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${name} must be an object`);
+    if (spec.required || spec.optional || spec.additional === false) {
+      return createPayloadParser({ required: spec.required, optional: spec.optional, additional: spec.additional })(value);
+    }
+    if (spec.properties && typeof spec.properties === 'object') {
+      const shaped = { required: {}, optional: {}, additional: spec.additional };
+      for (const [key, child] of Object.entries(spec.properties)) {
+        if (child?.optional) shaped.optional[key] = child;
+        else shaped.required[key] = child;
+      }
+      return createPayloadParser(shaped)(value);
+    }
+    return cloneJson(value);
+  }
+  if (type === 'record') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${name} must be an object`);
+    const out = {};
+    const child = spec.values || spec.items;
+    for (const [key, item] of Object.entries(value)) out[key] = child ? parseValue(item, child, `${name}.${key}`) : cloneJson(item);
+    return out;
+  }
+  if (type === 'literal') {
+    const expected = JSON.stringify(spec.value);
+    if (JSON.stringify(value) !== expected) throw new Error(`${name} must equal ${expected}`);
+    return cloneJson(value);
+  }
+  throw new Error(`${name} schema type ${type} is not supported`);
+}
+
+function createPayloadParser(payloadSchema = {}) {
+  const required = schemaEntries(payloadSchema.required);
+  const optional = schemaEntries(payloadSchema.optional);
+  return function parsePayload(payload = {}) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new Error('payload must be an object');
+    const out = {};
+    for (const [name, spec] of required) out[name] = parseValue(payload[name], spec, name);
+    for (const [name, spec] of optional) {
+      if (payload[name] !== undefined && payload[name] !== null && (payload[name] !== '' || spec.nonEmpty === false)) out[name] = parseValue(payload[name], spec, name);
+      else if (payload[name] === null && (spec.clearable || spec.nullable)) out[name] = null;
+      else if (spec.default !== undefined) out[name] = cloneJson(spec.default);
+    }
+    for (const [name, value] of Object.entries(payload)) {
+      if (!(name in out) && payloadSchema.additional !== false) out[name] = cloneJson(value);
+    }
+    return out;
+  };
+}
+
+module.exports = { createPayloadParser, parseValue };

package/src/model/plugin.cjs

@@ -0,0 +1,146 @@
+const { hashCanonical } = require('@mh-gg/base');
+const { allow, defineHostPlugin, deny } = require('@mh-gg/host-runtime');
+const { assertJsonSerializable, cloneJson, freezeJson } = require('../json.cjs');
+const { validateAppCompositionSchema } = require('../composition.cjs');
+const { createPayloadParser } = require('./payload.cjs');
+const { applyEffects } = require('./effects.cjs');
+const { applyGuards } = require('./guards.cjs');
+const { getPath } = require('./expressions.cjs');
+
+const SCHEMA_DEFINED_PLUGIN_SOURCE = 'schema:matterhorn.primary-model';
+
+function inferModelFromComposition(composition) {
+  const operations = {};
+  for (const action of composition.actions.filter((item) => item.plugin === 'primary' || item.plugin === '$primary')) {
+    const collection = action.type.split('.')[0] + 's';
+    const creates = /(^|\.)(create|add|send|open|log|record|request)$/.test(action.type);
+    operations[action.type] = {
+      payload: action.payloadSchema || { additional: true },
+      authorize: { roles: creates ? ['member'] : ['member'] },
+      effects: [creates
+        ? { kind: 'createRecord', collection, idPrefix: action.type.split('.')[0], fields: { ...action.payloadDefaults, ...{ createdAt: '$createdAt', actorId: '$actor.memberId' }, data: '$payload' } }
+        : { kind: 'noop' }]
+    };
+  }
+  return { kind: 'matterhorn.primary-model.schema', schemaVersion: 1, state: { initial: { activity: [] } }, operations, views: {} };
+}
+
+function normalizeModel(composition) {
+  const model = composition.primaryPlugin.model || inferModelFromComposition(composition);
+  if (!model || typeof model !== 'object' || Array.isArray(model)) throw new Error('primaryPlugin.model must be a JSON object');
+  assertJsonSerializable(model, 'primary plugin model');
+  return freezeJson({
+    kind: model.kind || 'matterhorn.primary-model.schema',
+    schemaVersion: model.schemaVersion || 1,
+    state: model.state || { initial: { activity: [] } },
+    operations: model.operations || {},
+    views: model.views || {},
+    publicView: model.publicView || { kind: 'state' }
+  });
+}
+
+function stateDescriptorForModel(composition, model) {
+  return { plugin: composition.primaryPlugin.id, version: composition.primaryPlugin.version, source: SCHEMA_DEFINED_PLUGIN_SOURCE, state: model.state };
+}
+
+function operationDescriptorForModel(composition, model) {
+  return {
+    plugin: composition.primaryPlugin.id,
+    version: composition.primaryPlugin.version,
+    source: SCHEMA_DEFINED_PLUGIN_SOURCE,
+    operations: Object.fromEntries(Object.entries(model.operations).map(([type, op]) => [type, { ...(op.payload || { additional: true }), authorize: op.authorize }]))
+  };
+}
+
+function createQueryHandler(view) {
+  if (!view || view.kind === 'state') return (_ctx, state) => cloneJson(state);
+  if (view.kind === 'collection') return (_ctx, state) => {
+    const value = getPath(state, view.path || view.collection);
+    const list = Array.isArray(value) ? value : Object.values(value || {});
+    return cloneJson(view.includeArchived === true ? list : list.filter((item) => !item.archivedAt && !item.deletedAt));
+  };
+  if (view.kind === 'count') return (_ctx, state) => {
+    const value = getPath(state, view.path || view.collection);
+    const list = Array.isArray(value) ? value : Object.values(value || {});
+    return list.filter((item) => !item.archivedAt && !item.deletedAt).length;
+  };
+  if (view.kind === 'rsvpCounts') return (_ctx, state) => {
+    const counts = { yes: 0, no: 0, maybe: 0, unset: 0 };
+    for (const guest of Object.values(state.guests || {})) counts[guest.rsvp || 'unset'] = (counts[guest.rsvp || 'unset'] || 0) + 1;
+    return counts;
+  };
+  return (_ctx, state) => cloneJson(state);
+}
+
+function parseModelState(model, state) {
+  const initial = cloneJson(model.state.initial || {});
+  if (!state || typeof state !== 'object' || Array.isArray(state)) return initial;
+  return { ...initial, ...cloneJson(state) };
+}
+
+function createSchemaDefinedHostPlugin(schema) {
+  const composition = validateAppCompositionSchema(schema);
+  const model = normalizeModel(composition);
+  const operationParsers = {};
+  for (const [type, descriptor] of Object.entries(model.operations)) operationParsers[type] = { parse: createPayloadParser(descriptor.payload || { additional: true }) };
+  const queries = {};
+  for (const [name, view] of Object.entries(model.views || {})) queries[name] = createQueryHandler(view);
+  const stateSchemaDescriptor = stateDescriptorForModel(composition, model);
+  const operationSchemaDescriptor = operationDescriptorForModel(composition, model);
+
+  const plugin = defineHostPlugin({
+    id: composition.primaryPlugin.id,
+    version: composition.primaryPlugin.version,
+    meta: { name: composition.app.name, source: SCHEMA_DEFINED_PLUGIN_SOURCE },
+    capabilities: model.capabilities || { requires: ['room.state', 'room.roles'], provides: ['schema.primary-model'] },
+    stateSchemaDescriptor,
+    operationSchemaDescriptor,
+    schemas: {
+      state: { parse: (state) => parseModelState(model, state) },
+      operations: operationParsers,
+      publicView: { parse: (view) => view }
+    },
+    createInitialState(ctx = {}) {
+      const initial = cloneJson(model.state.initial || { activity: [] });
+      if (model.state.roomIdPath) return { ...initial, [model.state.roomIdPath]: ctx.room?.id };
+      return initial;
+    },
+    authorize(_ctx, op) {
+      const descriptor = model.operations[op.type];
+      if (!descriptor) return deny(`Unsupported schema operation ${op.type}`);
+      return allow();
+    },
+    reduce(ctx, state, op) {
+      const descriptor = model.operations[op.type];
+      if (!descriptor) return state;
+      const effectContext = { operation: op, actor: ctx.actor || op.actor, payload: op.payload || {}, state, app: composition.app, room: ctx.room || { id: op.roomId } };
+      applyGuards(state, descriptor.guards || [], effectContext);
+      return applyEffects(state, descriptor.effects || [], effectContext);
+    },
+    getPublicView(_ctx, state) {
+      return cloneJson(state);
+    },
+    queries
+  });
+  plugin.schemaDefined = true;
+  plugin.schemaSource = SCHEMA_DEFINED_PLUGIN_SOURCE;
+  plugin.schemaModelHash = hashCanonical(model);
+  return plugin;
+}
+
+function schemaDefinedHostPluginEntry(schema, options = {}) {
+  const plugin = createSchemaDefinedHostPlugin(schema);
+  return Object.freeze({
+    plugin,
+    packageName: options.packageName || '@mh-gg/schema',
+    exportName: 'schemaDefinedHostPlugin',
+    source: SCHEMA_DEFINED_PLUGIN_SOURCE,
+    schemaDefined: true
+  });
+}
+
+module.exports = {
+  SCHEMA_DEFINED_PLUGIN_SOURCE,
+  createSchemaDefinedHostPlugin,
+  schemaDefinedHostPluginEntry
+};

package/src/notifications.cjs

@@ -0,0 +1,41 @@
+const { assertPlainObject, cloneJson, nonEmptyString } = require("./json.cjs");
+
+function normalizeNotificationDefinition(definition, name) {
+  const value = assertPlainObject(definition, `notification ${name}`);
+  const on = assertPlainObject(value.on, `notification ${name}.on`);
+  const audience = assertPlainObject(value.audience, `notification ${name}.audience`);
+  const scope = assertPlainObject(value.scope, `notification ${name}.scope`);
+  const presentation = assertPlainObject(value.presentation, `notification ${name}.presentation`);
+  const read = assertPlainObject(value.read, `notification ${name}.read`);
+  const normalized = {
+    kind: nonEmptyString(value.kind, `notification ${name}.kind`),
+    on: {
+      action: nonEmptyString(on.action, `notification ${name}.on.action`),
+      ...(on.plugin === undefined ? {} : { plugin: String(on.plugin) }),
+      ...(on.type === undefined ? {} : { type: String(on.type) })
+    },
+    ...(value.privacy === undefined ? {} : { privacy: String(value.privacy) }),
+    audience: {
+      userIds: audience.userIds,
+      ...(audience.excludeActor === undefined ? {} : { excludeActor: Boolean(audience.excludeActor) })
+    },
+    scope: cloneJson(scope),
+    ...(value.entity === undefined ? {} : { entity: cloneJson(value.entity) }),
+    presentation: cloneJson(presentation),
+    ...(value.link === undefined ? {} : { link: cloneJson(value.link) }),
+    read: cloneJson(read),
+    ...(value.delivery === undefined ? {} : { delivery: cloneJson(value.delivery) })
+  };
+  return Object.freeze(normalized);
+}
+
+function normalizeNotifications(notifications = {}) {
+  const value = assertPlainObject(notifications, "composition notifications");
+  const definitions = assertPlainObject(value.definitions, "composition notifications.definitions");
+  return Object.freeze({
+    schemaVersion: Number(value.schemaVersion) || 1,
+    definitions: Object.freeze(Object.fromEntries(Object.entries(definitions).map(([name, def]) => [name, normalizeNotificationDefinition(def, name)])))
+  });
+}
+
+module.exports = { normalizeNotifications };

package/src/notifications.d.ts

@@ -0,0 +1,63 @@
+export type NotificationExpression = string | { $expr: string; fallback?: string };
+
+export type NotificationAudience = {
+  userIds: string | string[];
+  excludeActor?: boolean;
+};
+
+export type NotificationScope = {
+  type: string;
+  id: string;
+};
+
+export type NotificationEntity = {
+  type: string;
+  id: string;
+};
+
+export type NotificationPresentation = {
+  title?: string | NotificationExpression;
+  body?: string;
+};
+
+export type NotificationLink = {
+  route: string;
+  params?: Record<string, string>;
+};
+
+export type NotificationReadPolicy = "player" | "click" | "route-visible" | "manual";
+
+export type NotificationRead = {
+  scopeKey: string;
+  cursor: { createdAt: string; operationId: string };
+  defaultPolicy: NotificationReadPolicy;
+};
+
+export type NotificationDelivery = {
+  collapse?: "scope" | "entity" | "none";
+  ttlSeconds?: number;
+};
+
+export type NotificationOn = {
+  action: string;
+  plugin?: string;
+  type?: string;
+};
+
+export type NotificationDef = {
+  on: NotificationOn;
+  kind: string;
+  privacy?: "encrypted" | "cleartext";
+  audience: NotificationAudience;
+  scope: NotificationScope;
+  entity?: NotificationEntity;
+  presentation: NotificationPresentation;
+  link?: NotificationLink;
+  read: NotificationRead;
+  delivery?: NotificationDelivery;
+};
+
+export type NotificationsBlock = {
+  schemaVersion?: number;
+  definitions: Record<string, NotificationDef>;
+};

package/src/registry.cjs

@@ -0,0 +1,63 @@
+const { createMicroPluginSchema, validateMicroPluginSchema } = require("./microPlugin.cjs");
+const { freezeJson, nonEmptyString } = require("./json.cjs");
+
+function createRegistryRecord(entry) {
+  const schema = createMicroPluginSchema({
+    key: entry.key,
+    id: entry.id,
+    plugin: entry.plugin,
+    packageName: entry.packageName,
+    exportName: entry.exportName,
+    source: { packageName: entry.packageName, exportName: entry.exportName, ref: `workspace:${entry.packageName}#${entry.exportName}` }
+  });
+  return Object.freeze({ ...entry, schema });
+}
+
+function createMicroPluginRegistry(entries = []) {
+  const byKey = new Map();
+  const byId = new Map();
+  const records = [];
+  for (const raw of entries) {
+    const record = raw.schema ? raw : createRegistryRecord(raw);
+    validateMicroPluginSchema(record.schema);
+    if (byKey.has(record.schema.key)) throw new Error(`Duplicate micro plugin key ${record.schema.key}`);
+    if (byId.has(record.schema.id)) throw new Error(`Duplicate micro plugin id ${record.schema.id}`);
+    const frozen = Object.freeze(record);
+    records.push(frozen);
+    byKey.set(record.schema.key, frozen);
+    byId.set(record.schema.id, frozen);
+    for (const alias of record.aliases || []) if (!byKey.has(alias)) byKey.set(alias, frozen);
+  }
+  return Object.freeze({
+    records: Object.freeze(records.slice()),
+    schemas: freezeJson(records.map((record) => record.schema)),
+    get(selection) {
+      const key = typeof selection === "string" ? selection : selection?.key || selection?.id;
+      nonEmptyString(key, "micro plugin selection");
+      const record = byKey.get(key) || byId.get(key);
+      if (!record) throw new Error(`Unknown micro plugin ${key}`);
+      return record;
+    },
+    has(selection) {
+      try { this.get(selection); return true; } catch { return false; }
+    }
+  });
+}
+
+const builtinMicroPluginRegistry = createMicroPluginRegistry();
+
+function getMicroPluginSchema(selection) {
+  return builtinMicroPluginRegistry.get(selection).schema;
+}
+
+function listMicroPluginSchemas() {
+  return builtinMicroPluginRegistry.schemas;
+}
+
+module.exports = {
+  builtinMicroPluginRegistry,
+  createMicroPluginRegistry,
+  getMicroPluginSchema,
+  listMicroPluginSchemas,
+  reusableMicroPluginSchemas: listMicroPluginSchemas()
+};

package/src/runtime-exports.d.ts

@@ -0,0 +1,65 @@
+export const APP_COMPOSITION_SCHEMA_KIND: any;
+export const APP_COMPOSITION_SCHEMA_VERSION: any;
+export const MICRO_PLUGIN_SCHEMA_KIND: any;
+export const MICRO_PLUGIN_SCHEMA_VERSION: any;
+export const SCHEMA_DEFINED_PLUGIN_SOURCE: any;
+export const SCHEMA_ROOT: any;
+export const SUPPORTED_SCHEMA_EFFECT_KINDS: any;
+export const actionDescriptorsForPlugin: any;
+export const actionDescriptorsFromOperations: any;
+export const actionNameFromOperation: any;
+export const appCompositionSchemaHash: any;
+export const applyEffect: any;
+export const applyEffects: any;
+export const applyGuard: any;
+export const applyGuards: any;
+export const asArrayCollection: any;
+export const asMapCollection: any;
+export const assertJsonSerializable: any;
+export const assertPlainObject: any;
+export const assertValidJsonSchema: any;
+export const builtinMicroPluginRegistry: any;
+export const cloneJson: any;
+export const collectionValue: any;
+export const compositionPluginIds: any;
+export const createActionDispatchersFromComposition: any;
+export const createAppCompositionSchema: any;
+export const createMicroPluginRegistry: any;
+export const createMicroPluginSchema: any;
+export const createPayloadParser: any;
+export const createSchemaDefinedHostPlugin: any;
+export const deepFreeze: any;
+export const ensureRecord: any;
+export const evaluate: any;
+export const findRecordInArray: any;
+export const freezeJson: any;
+export const getMicroPluginSchema: any;
+export const getPath: any;
+export const guardPasses: any;
+export const jsonArray: any;
+export const listMicroPluginSchemas: any;
+export const loadAppCompositionSchemaFile: any;
+export const loadJsonWithImports: any;
+export const microPluginSchemaHash: any;
+export const nonEmptyString: any;
+export const operationDescriptorsFromPlugin: any;
+export const operationsMap: any;
+export const optionalString: any;
+export const parseValue: any;
+export const pluginIdForAction: any;
+export const readSchema: any;
+export const recordFromCollection: any;
+export const recordIdFrom: any;
+export const resolveCompositionHostPluginEntries: any;
+export const reusableMicroPluginSchemas: any;
+export const roleMeetsAny: any;
+export const roleRank: any;
+export const sanitizeId: any;
+export const schemaDefinedHostPluginEntry: any;
+export const setPath: any;
+export const statePathValue: any;
+export const validateAppCompositionSchema: any;
+export const validateJsonSchema: any;
+export const validateMicroPluginSchema: any;
+export const viewDescriptorsFromPlugin: any;
+export const writeRecordToCollection: any;

package/src/streamKey.d.ts

@@ -0,0 +1,15 @@
+export type ReadClass = "window" | "head" | "full-fold";
+export type IntegrityClass = "signature" | "seq" | "checkpoint";
+
+export interface ShapeSpec {
+  readClass?: ReadClass;
+  integrityClass?: IntegrityClass;
+}
+
+export function streamKey(spec: {
+  pluginId?: string;
+  collection: string;
+  scopeType?: string;
+  scopeId?: string;
+  recordId?: string;
+}): string;