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

package/src/builder/matterhornApp/plugins.cjs

@@ -0,0 +1,95 @@
+const { hashCanonical } = require('@mh-gg/base');
+
+function assertCanonicalOperationDescriptor(plugin, descriptor) {
+  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor) || !descriptor.operations || typeof descriptor.operations !== 'object' || Array.isArray(descriptor.operations)) {
+    throw new Error(`${plugin.id} must expose canonical operationSchemaDescriptor.operations`);
+  }
+  return descriptor;
+}
+
+function pluginSchemaDescriptor(plugin, fallbackStateDescriptor, fallbackOperationDescriptor) {
+  return {
+    state: plugin.stateSchemaDescriptor || fallbackStateDescriptor || { plugin: plugin.id, version: plugin.version },
+    operations: assertCanonicalOperationDescriptor(plugin, plugin.operationSchemaDescriptor || fallbackOperationDescriptor)
+  };
+}
+
+function collectHostPluginEntries(items) {
+  const out = [];
+  function collect(item) {
+    if (!item) return;
+    if (Array.isArray(item)) {
+      for (const child of item) collect(child);
+      return;
+    }
+    if (item.kind === 'matterhorn.example-plugin-suite' && Array.isArray(item.entries)) {
+      for (const child of item.entries) collect(child);
+      return;
+    }
+    if (Array.isArray(item.entries)) {
+      for (const child of item.entries) collect(child);
+      return;
+    }
+    out.push(item);
+  }
+  collect(items);
+  return out;
+}
+
+function normalizeHostPluginEntries(config, version) {
+  const entries = [];
+  if (config.hostPlugin) {
+    entries.push({
+      plugin: config.hostPlugin,
+      packageName: config.packageName,
+      exportName: config.hostPluginExport || 'hostPlugin',
+      source: config.hostPluginSource,
+      dependsOn: config.hostPluginDependsOn || [],
+      conflictsWith: config.hostPluginConflictsWith || []
+    });
+  }
+  for (const entry of collectHostPluginEntries(config.hostPlugins)) {
+    const normalized = entry.plugin ? { ...entry } : { plugin: entry };
+    if (!normalized.plugin) throw new Error('hostPlugins entries must include plugin');
+    const plugin = normalized.config === undefined ? normalized.plugin : { ...normalized.plugin, config: JSON.parse(JSON.stringify(normalized.config)) };
+    entries.push({
+      plugin,
+      packageName: normalized.packageName || config.packageName,
+      exportName: normalized.exportName || normalized.hostPluginExport || normalized.plugin.exportName || 'hostPlugin',
+      source: normalized.source,
+      dependsOn: normalized.dependsOn || normalized.plugin.dependsOn || [],
+      conflictsWith: normalized.conflictsWith || normalized.plugin.conflictsWith || [],
+      stateSchemaDescriptor: normalized.stateSchemaDescriptor,
+      operationSchemaDescriptor: normalized.operationSchemaDescriptor
+    });
+  }
+  if (entries.length === 0) throw new Error('At least one host plugin is required');
+  const seen = new Set();
+  for (const entry of entries) {
+    if (seen.has(entry.plugin.id)) throw new Error(`Duplicate host plugin ${entry.plugin.id}`);
+    seen.add(entry.plugin.id);
+    const descriptors = pluginSchemaDescriptor(entry.plugin, entry.stateSchemaDescriptor, entry.operationSchemaDescriptor);
+    entry.stateSchemaDescriptor = descriptors.state;
+    entry.operationSchemaDescriptor = descriptors.operations;
+    entry.plugin.stateSchemaHash = hashCanonical(entry.stateSchemaDescriptor);
+    entry.plugin.operationSchemaHash = hashCanonical(entry.operationSchemaDescriptor);
+    entry.version = entry.plugin.version || version;
+  }
+  return entries;
+}
+
+function primaryHostPluginForBuilt(built) {
+  const primaryId = built.config.hostPlugin?.id || built.compositionSchema.primaryPlugin.id;
+  return built.hostPlugins.find((plugin) => plugin.id === primaryId) || built.hostPlugins[0];
+}
+
+function primaryHostPluginDescriptorForBuilt(built) {
+  const primaryId = primaryHostPluginForBuilt(built).id;
+  return built.hostPluginDescriptors.find((descriptor) => descriptor.id === primaryId) || built.hostPluginDescriptors[0];
+}
+
+module.exports = {
+  normalizeHostPluginEntries,
+  primaryHostPluginDescriptorForBuilt,
+  primaryHostPluginForBuilt
+};

package/src/builder/matterhornApp/shared.cjs

@@ -0,0 +1,105 @@
+const { cloneJson } = require('../../json.cjs');
+const { namespaceNameForApp } = require('../../types/index.cjs');
+
+const APP_MATTERHORN_META = Symbol.for('matterhorn.schema.builder.app.matterhorn');
+
+const DEFAULT_PUBLISHER = Object.freeze({
+  id: 'com.matterhorn.schema',
+  name: 'Matterhorn Schema Builder',
+  publicKey: 'rk_pub_schema_builder'
+});
+
+const DEFAULT_TRUST = Object.freeze({
+  signatures: Object.freeze([{ publicKey: DEFAULT_PUBLISHER.publicKey, signature: 'sig_schema_builder' }])
+});
+
+function maybeClone(value) {
+  return value === undefined ? undefined : cloneJson(value);
+}
+
+function pascalCase(value) {
+  return String(value).replace(/(^|[^a-zA-Z0-9]+)([a-zA-Z0-9])/g, (_match, _sep, char) => char.toUpperCase()).replace(/[^a-zA-Z0-9]/g, '');
+}
+
+function slugFromAppId(appId) {
+  return String(appId).split('.').filter(Boolean).pop() || 'matterhorn-app';
+}
+
+function optionValue(options, key, fallback) {
+  return Object.prototype.hasOwnProperty.call(options, key) ? options[key] : fallback;
+}
+
+function matterhornMetadataForSpec(spec = {}, registry) {
+  return Object.freeze({
+    registry,
+    slug: spec.slug,
+    packageName: spec.packageName,
+    packageRoot: spec.packageRoot,
+    exportPrefix: spec.exportPrefix,
+    constantPrefix: spec.constantPrefix,
+    typeNamespace: spec.typeNamespace,
+    frontend: maybeClone(spec.frontend),
+    matterhorn: maybeClone(spec.matterhorn),
+    matterhornApp: maybeClone(spec.matterhornApp),
+    deployment: maybeClone(spec.deployment),
+    example: maybeClone(spec.example),
+    demo: maybeClone(spec.demo),
+    exportAliases: maybeClone(spec.exportAliases),
+    publisher: maybeClone(spec.publisher),
+    trust: maybeClone(spec.trust),
+    createdAt: spec.createdAt,
+    summary: spec.summary,
+    appCapabilities: maybeClone(spec.appCapabilities),
+    hostCapabilities: maybeClone(spec.hostCapabilities),
+    entrypoints: maybeClone(spec.entrypoints),
+    recommendedFor: maybeClone(spec.recommendedFor),
+    routes: maybeClone(spec.playerRoutes),
+    actions: spec.playerActions,
+    optimisticReducers: spec.optimisticReducers,
+    navigation: maybeClone(spec.navigation),
+    deviceHints: maybeClone(spec.deviceHints),
+    hostPlugin: spec.hostPlugin,
+    hostPlugins: spec.hostPlugins,
+    hostPluginExport: spec.hostPluginExport,
+    hostPluginSource: spec.hostPluginSource,
+    hostPluginDependsOn: maybeClone(spec.hostPluginDependsOn || spec.dependsOn),
+    hostPluginConflictsWith: maybeClone(spec.hostPluginConflictsWith),
+    hostPackExport: spec.hostPackExport,
+    playerPackId: spec.playerPackId,
+    playerPackExport: spec.playerPackExport,
+    playerPluginId: spec.playerPluginId,
+    playerPluginExport: spec.playerPluginExport
+  });
+}
+
+function mergedOptions(app, options = {}) {
+  const meta = app?.[APP_MATTERHORN_META] || {};
+  const merged = { ...meta, ...options };
+  for (const key of ['frontend', 'matterhorn', 'matterhornApp', 'deployment', 'example', 'demo', 'exportAliases', 'publisher', 'trust', 'appCapabilities', 'hostCapabilities']) {
+    merged[key] = optionValue(options, key, meta[key]);
+  }
+  if (Object.prototype.hasOwnProperty.call(options, 'playerRoutes')) merged.routes = maybeClone(options.playerRoutes);
+  if (Object.prototype.hasOwnProperty.call(options, 'playerActions')) merged.actions = options.playerActions;
+  if (!Object.prototype.hasOwnProperty.call(options, 'hostPluginDependsOn') && Object.prototype.hasOwnProperty.call(options, 'dependsOn')) {
+    merged.hostPluginDependsOn = maybeClone(options.dependsOn);
+  }
+  merged.registry = options.registry || meta.registry;
+  return merged;
+}
+
+function typeNamespaceForBuilt(built) {
+  const config = built.config;
+  return pascalCase(config.typeNamespace || config.exportPrefix || config.slug || namespaceNameForApp(built.compositionSchema));
+}
+
+module.exports = {
+  APP_MATTERHORN_META,
+  DEFAULT_PUBLISHER,
+  DEFAULT_TRUST,
+  maybeClone,
+  mergedOptions,
+  pascalCase,
+  matterhornMetadataForSpec,
+  slugFromAppId,
+  typeNamespaceForBuilt
+};

package/src/builder/matterhornApp.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  ...require('./matterhornApp/shared.cjs'),
+  ...require('./matterhornApp/build.cjs'),
+  ...require('./matterhornApp/bundle.cjs'),
+  ...require('./matterhornApp/demo.cjs'),
+  ...require('./matterhornApp/exports.cjs')
+};

package/src/builder/model.cjs

@@ -0,0 +1,172 @@
+const { cloneJson, freezeJson, nonEmptyString } = require('../json.cjs');
+const { cleanObject, normalizePayloadShape, own } = require('./schema.cjs');
+const { collectionHandle, isCollection, normalizeCollection, fx } = require('./effects.cjs');
+const { normalizeReadClass, normalizeIntegrityClass, streamKey } = require('./streamKey.cjs');
+const { guard } = require('./guards.cjs');
+const { refForPayload, ref } = require('./refs.cjs');
+
+const QUERY_DEF = Symbol.for('matterhorn.schema.builder.query');
+const MODEL_DEF = Symbol.for('matterhorn.schema.builder.model');
+const SCOPE_DEF = Symbol.for('matterhorn.schema.builder.scope');
+
+function operationDefinition(spec = {}, build) {
+  const payload = normalizePayloadShape(spec.payload || {});
+  const body = typeof build === 'function' ? build({ ref: refForPayload(payload), fx, guard }) : (build || {});
+  const definition = cleanObject({
+    authorize: spec.authorize || {},
+    payload,
+    guards: body.guards || body.guard ? (body.guards || [body.guard]) : undefined,
+    effects: body.effects || []
+  });
+  if (!Array.isArray(definition.effects)) throw new Error('operation effects must be an array');
+  if (definition.guards && !Array.isArray(definition.guards)) throw new Error('operation guards must be an array');
+  return freezeJson(definition);
+}
+
+function op(spec, build) {
+  return operationDefinition(spec, build);
+}
+
+function roleDefinitionsFromSpec(roles = {}) {
+  const out = {};
+  for (const [id, role] of Object.entries(roles || {})) {
+    out[id] = cleanObject({
+      id,
+      name: role.name || id,
+      description: role.description,
+      color: role.color,
+      rank: Number.isFinite(Number(role.rank)) ? Number(role.rank) : 0,
+      systemRole: role.system ?? role.systemRole ?? true,
+      archivedAt: role.archivedAt === undefined ? null : role.archivedAt
+    });
+  }
+  return out;
+}
+
+function initialStateFromModelSpec(spec = {}) {
+  const state = spec.state && own(spec.state, 'initial') ? spec.state.initial : (spec.state || {});
+  const initial = cloneJson(state || {});
+  if (spec.roles && !initial.roleDefinitions) initial.roleDefinitions = roleDefinitionsFromSpec(spec.roles);
+  if (!initial.activity) initial.activity = [];
+  return initial;
+}
+
+function shapesFromCollections(collections = {}) {
+  const shapes = {};
+  for (const [name, handle] of Object.entries(collections)) {
+    shapes[name] = cleanObject({
+      readClass: handle.readClass,
+      integrityClass: handle.integrityClass,
+      storage: handle.storage,
+      partition: name
+    });
+  }
+  return shapes;
+}
+
+function makeModel(spec = {}, operations = {}) {
+  const initial = initialStateFromModelSpec(spec);
+  const collections = {};
+  for (const [name, sample] of Object.entries(initial)) {
+    const options = spec.shapes?.[name] || {};
+    collections[name] = collectionHandle(name, sample, options);
+  }
+  const shapes = shapesFromCollections(collections);
+  const model = {
+    [MODEL_DEF]: true,
+    roles: freezeJson(spec.roles || {}),
+    collections: Object.freeze(collections),
+    withOperations(nextOperations = {}) { return makeModel(spec, nextOperations); },
+    operation(name, definition) { return makeModel(spec, { ...operations, [name]: definition }); },
+    toJSON() {
+      return freezeJson({
+        kind: 'matterhorn.primary-model.schema',
+        schemaVersion: 1,
+        state: cleanObject({ initial, ...(spec.state?.roomIdPath ? { roomIdPath: spec.state.roomIdPath } : {}) }),
+        operations: cloneJson(operations),
+        views: cloneJson(spec.views || {}),
+        shapes: cloneJson(shapes),
+        ...(spec.publicView ? { publicView: cloneJson(spec.publicView) } : {}),
+        ...(spec.capabilities ? { capabilities: cloneJson(spec.capabilities) } : {})
+      });
+    }
+  };
+  return Object.freeze(model);
+}
+
+function defineModel(spec = {}) {
+  return makeModel(spec);
+}
+
+const q = Object.freeze({
+  state() { return Object.freeze({ [QUERY_DEF]: true, kind: 'state', toJSON() { return { kind: 'state' }; } }); },
+  collection(collection, options = {}) {
+    const c = normalizeCollection(collection);
+    const query = { [QUERY_DEF]: true, kind: 'collection', collection: c.name, path: options.path, includeArchived: options.includeArchived };
+    query.toJSON = () => cleanObject({ kind: 'collection', collection: c.name, path: options.path, includeArchived: options.includeArchived });
+    return Object.freeze(query);
+  },
+  count(collection, options = {}) {
+    const c = normalizeCollection(collection);
+    const query = { [QUERY_DEF]: true, kind: 'count', collection: c.name, path: options.path };
+    query.toJSON = () => cleanObject({ kind: 'count', collection: c.name, path: options.path });
+    return Object.freeze(query);
+  }
+});
+
+function queryToJson(value) {
+  if (value?.[QUERY_DEF] && typeof value.toJSON === 'function') return value.toJSON();
+  if (value && typeof value === 'object' && !Array.isArray(value)) return cloneJson(value);
+  throw new Error('view must be a query definition object');
+}
+
+function defineScope(spec = {}) {
+  const key = spec.key || spec.name || spec.type;
+  const scope = {
+    [SCOPE_DEF]: true,
+    key: nonEmptyString(key, 'scope key'),
+    scopeType: nonEmptyString(spec.type || spec.scopeType, 'scope type'),
+    scopeId: nonEmptyString(spec.id || spec.scopeId, 'scope id'),
+    identity: spec.identity,
+    participants: spec.participants,
+    collections: (spec.collections || []).map((item) => isCollection(item) ? item.name : String(item)),
+    description: spec.description,
+    readClass: normalizeReadClass(spec.readClass),
+    integrityClass: normalizeIntegrityClass(spec.integrityClass),
+    view: { action: 'view', scopeType: spec.type || spec.scopeType, scopeId: spec.id || spec.scopeId },
+    edit: { action: 'edit', scopeType: spec.type || spec.scopeType, scopeId: spec.id || spec.scopeId }
+  };
+  scope.toJSON = () => cleanObject({
+    scopeType: scope.scopeType,
+    scopeId: scope.scopeId,
+    identity: scope.identity,
+    participants: scope.participants,
+    collections: scope.collections,
+    description: scope.description,
+    readClass: scope.readClass,
+    integrityClass: scope.integrityClass
+  });
+  return Object.freeze(scope);
+}
+
+function modelToJson(model) {
+  if (model?.[MODEL_DEF] && typeof model.toJSON === 'function') return model.toJSON();
+  if (model && typeof model === 'object') return cloneJson(model);
+  throw new Error('defineApp requires a model');
+}
+
+module.exports = {
+  MODEL_DEF,
+  QUERY_DEF,
+  SCOPE_DEF,
+  defineModel,
+  defineScope,
+  modelToJson,
+  normalizeReadClass,
+  normalizeIntegrityClass,
+  op,
+  q,
+  queryToJson,
+  ref,
+  streamKey
+};

package/src/builder/notifications.cjs

@@ -0,0 +1,51 @@
+const { cloneJson } = require("../json.cjs");
+
+function defineNotification(spec = {}) {
+  if (!spec.on?.action) throw new Error("defineNotification requires on.action");
+  if (!spec.audience?.userIds) throw new Error("defineNotification requires audience.userIds");
+  if (!spec.scope) throw new Error("defineNotification requires scope");
+  if (!spec.presentation) throw new Error("defineNotification requires presentation");
+  if (!spec.read) throw new Error("defineNotification requires read");
+
+  return cleanObject({
+    on: cleanObject({
+      action: spec.on.action,
+      ...(spec.on.plugin ? { plugin: spec.on.plugin } : {}),
+      ...(spec.on.type ? { type: spec.on.type } : {})
+    }),
+    kind: spec.kind || spec.on.action,
+    ...(spec.privacy ? { privacy: spec.privacy } : {}),
+    audience: cleanObject({
+      userIds: spec.audience.userIds,
+      ...(spec.audience.excludeActor ? { excludeActor: true } : {})
+    }),
+    scope: cloneJson(spec.scope),
+    ...(spec.entity ? { entity: cloneJson(spec.entity) } : {}),
+    presentation: cloneJson(spec.presentation),
+    ...(spec.link ? { link: cloneJson(spec.link) } : {}),
+    read: cloneJson(spec.read),
+    ...(spec.delivery ? { delivery: cloneJson(spec.delivery) } : {})
+  });
+}
+
+function defineNotificationsBlock(spec = {}) {
+  const definitions = {};
+  for (const [name, def] of Object.entries(spec.definitions || {})) {
+    definitions[name] = typeof def === "function" ? def() : def;
+  }
+  return {
+    schemaVersion: spec.schemaVersion || 1,
+    definitions
+  };
+}
+
+function cleanObject(obj) {
+  if (!obj || typeof obj !== "object") return obj;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+module.exports = { defineNotification, defineNotificationsBlock };

package/src/builder/refs.cjs

@@ -0,0 +1,33 @@
+const { cloneJson, nonEmptyString } = require('../json.cjs');
+
+function knownPayloadKeys(payloadSchema) {
+  return new Set([...Object.keys(payloadSchema.required || {}), ...Object.keys(payloadSchema.optional || {})]);
+}
+
+function refForPayload(payloadSchema = {}) {
+  const keys = knownPayloadKeys(payloadSchema);
+  function assertPayloadKey(key) {
+    if (keys.size > 0 && !keys.has(key)) throw new Error(`Unknown payload key ${key}`);
+    return key;
+  }
+  return Object.freeze({
+    payload(key, fallback) {
+      const expr = `$payload.${assertPayloadKey(String(key))}`;
+      if (arguments.length < 2) return expr;
+      return { $expr: expr, fallback: cloneJson(fallback) };
+    },
+    actor(field = 'memberId') { return `$actor.${String(field)}`; },
+    app(field = 'id') { return `$app.${String(field)}`; },
+    room(field = 'id') { return `$room.${String(field)}`; },
+    profile(field = 'id') { return `$profile.${String(field)}`; },
+    now() { return '$createdAt'; },
+    operation(field = 'id') { return `$operation.${String(field)}`; },
+    newId(prefix) { return `$id:${nonEmptyString(prefix, 'id prefix')}`; },
+    literal(value) { return { $literal: cloneJson(value) }; },
+    expr(value) { return { $expr: nonEmptyString(value, 'expression') }; }
+  });
+}
+
+const ref = refForPayload({});
+
+module.exports = { knownPayloadKeys, ref, refForPayload };

package/src/builder/schema.cjs

@@ -0,0 +1,101 @@
+const { cloneJson, freezeJson } = require('../json.cjs');
+
+const SCHEMA_BUILDER = Symbol.for('matterhorn.schema.builder.schema');
+
+function own(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function cleanObject(value) {
+  const out = {};
+  for (const [key, entry] of Object.entries(value || {})) if (entry !== undefined) out[key] = entry;
+  return out;
+}
+
+function ensurePlainObject(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${name} must be an object`);
+  return value;
+}
+
+function makeSchema(spec, options = {}) {
+  const normalized = freezeJson(spec || { type: 'any' });
+  const state = Object.freeze({ optional: options.optional === true });
+  const api = {
+    [SCHEMA_BUILDER]: true,
+    optional() { return makeSchema(normalized, { ...state, optional: true }); },
+    nullable() { return makeSchema({ ...normalized, nullable: true }, state); },
+    default(value) { return makeSchema({ ...normalized, default: cloneJson(value) }, state); },
+    clearable() { return makeSchema({ ...normalized, clearable: true, nullable: true }, state); },
+    toJSON() { return cloneJson(normalized); }
+  };
+  Object.defineProperty(api, '__matterhornSchema', { value: state, enumerable: false });
+  return Object.freeze(api);
+}
+
+function isSchemaBuilder(value) {
+  return Boolean(value && typeof value === 'object' && value[SCHEMA_BUILDER]);
+}
+
+function schemaOptional(value) {
+  return Boolean(value?.__matterhornSchema?.optional);
+}
+
+function schemaJson(value, name = 'schema') {
+  if (isSchemaBuilder(value)) return value.toJSON();
+  if (typeof value === 'string') return { type: value };
+  if (value && typeof value === 'object' && !Array.isArray(value)) return cloneJson(value);
+  if (value === undefined) return { type: 'any' };
+  throw new Error(`${name} must be a Matterhorn payload schema`);
+}
+
+function payloadShapeFromSchemas(shape = {}, options = {}) {
+  ensurePlainObject(shape, 'payload shape');
+  const required = {};
+  const optional = {};
+  for (const [key, schema] of Object.entries(shape)) {
+    const target = schemaOptional(schema) ? optional : required;
+    target[key] = schemaJson(schema, `payload.${key}`);
+  }
+  return cleanObject({
+    ...(Object.keys(required).length ? { required } : {}),
+    ...(Object.keys(optional).length ? { optional } : {}),
+    ...(options.additional === undefined ? {} : { additional: options.additional })
+  });
+}
+
+function normalizePayloadShape(payload = {}) {
+  if (payload.required || payload.optional || payload.additional !== undefined) return cloneJson(payload);
+  return payloadShapeFromSchemas(payload);
+}
+
+function structuredObjectSchema(shape = {}, options = {}) {
+  return makeSchema({ type: 'object', ...payloadShapeFromSchemas(shape, { additional: options.additional ?? false }) });
+}
+
+const p = Object.freeze({
+  any() { return makeSchema({ type: 'any' }); },
+  string(opts = {}) { return makeSchema(cleanObject({ type: 'string', ...opts })); },
+  number(opts = {}) { return makeSchema(cleanObject({ type: 'number', ...opts })); },
+  boolean() { return makeSchema({ type: 'boolean' }); },
+  enum(values, opts = {}) {
+    if (!Array.isArray(values) || values.length === 0) throw new Error('p.enum requires a non-empty values array');
+    return makeSchema(cleanObject({ type: 'enum', values: values.map(String), ...opts }));
+  },
+  array(items, opts = {}) { return makeSchema(cleanObject({ type: 'array', items: items ? schemaJson(items, 'array item schema') : undefined, ...opts })); },
+  object(shape = {}, opts = {}) { return structuredObjectSchema(shape, opts); },
+  record(values = p.any(), opts = {}) { return makeSchema(cleanObject({ type: 'record', values: schemaJson(values, 'record value schema'), ...opts })); },
+  literal(value) { return makeSchema({ type: 'literal', value: cloneJson(value) }); }
+});
+
+module.exports = {
+  SCHEMA_BUILDER,
+  cleanObject,
+  ensurePlainObject,
+  isSchemaBuilder,
+  normalizePayloadShape,
+  own,
+  p,
+  payloadShapeFromSchemas,
+  schemaJson,
+  schemaOptional
+};

package/src/builder/streamKey.cjs

@@ -0,0 +1,27 @@
+const { nonEmptyString } = require('../json.cjs');
+
+const READ_CLASSES = Object.freeze(new Set(['window', 'head', 'full-fold']));
+const INTEGRITY_CLASSES = Object.freeze(new Set(['signature', 'seq', 'checkpoint']));
+
+function normalizeReadClass(value) {
+  if (!value) return 'full-fold';
+  if (READ_CLASSES.has(value)) return value;
+  throw new Error(`Invalid readClass "${value}". Must be one of: window, head, full-fold.`);
+}
+
+function normalizeIntegrityClass(value) {
+  if (!value) return 'signature';
+  if (INTEGRITY_CLASSES.has(value)) return value;
+  throw new Error(`Invalid integrityClass "${value}". Must be one of: signature, seq, checkpoint.`);
+}
+
+function streamKey({ pluginId, collection, scopeType, scopeId, recordId } = {}) {
+  const col = nonEmptyString(collection, 'collection');
+  if (scopeType && scopeId) {
+    return recordId ? `${scopeType}:${scopeId}:${col}:${recordId}` : `${scopeType}:${scopeId}:${col}`;
+  }
+  const plugin = nonEmptyString(pluginId, 'pluginId');
+  return recordId ? `${plugin}:${col}:${recordId}` : `${plugin}:${col}`;
+}
+
+module.exports = { normalizeReadClass, normalizeIntegrityClass, streamKey };