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

package/src/microPlugin.cjs

@@ -0,0 +1,112 @@
+const { hashCanonical } = require("@mh-gg/base");
+const { assertJsonSerializable, assertPlainObject, freezeJson, nonEmptyString, optionalString } = require("./json.cjs");
+
+const MICRO_PLUGIN_SCHEMA_KIND = "matterhorn.micro-plugin.schema";
+const MICRO_PLUGIN_SCHEMA_VERSION = 1;
+
+function normalizeCapabilitySet(capabilities = {}) {
+  return {
+    requires: Object.freeze([...(capabilities.requires || capabilities.required || [])].map(String).sort()),
+    provides: Object.freeze([...(capabilities.provides || [])].map(String).sort())
+  };
+}
+
+function operationDescriptorsFromPlugin(plugin) {
+  const source = plugin.operationSchemaDescriptor?.operations || {};
+  const operations = {};
+  for (const [type, descriptor] of Object.entries(source)) {
+    if (descriptor && typeof descriptor === "object" && typeof descriptor.parse === "function") {
+      operations[type] = { type: "object", description: `${type} payload` };
+    } else {
+      operations[type] = descriptor && typeof descriptor === "object" ? descriptor : { type: "object" };
+    }
+  }
+  return operations;
+}
+
+function viewDescriptorsFromPlugin(plugin) {
+  const views = [];
+  if (plugin.schemas?.publicView) views.push({ name: "publicView", kind: "public-view", plugin: plugin.id });
+  for (const queryName of Object.keys(plugin.schemas?.queries || plugin.queries || {}).sort()) {
+    views.push({ name: queryName, kind: "query", plugin: plugin.id, query: queryName });
+  }
+  return views;
+}
+
+function actionNameFromOperation(type) {
+  return String(type).replace(/(^|\.)([a-z])/g, (_match, _prefix, letter) => letter.toUpperCase()).replace(/^[A-Z]/, (letter) => letter.toLowerCase());
+}
+
+function actionDescriptorsFromOperations(plugin, operationSchemas) {
+  return Object.keys(operationSchemas).sort().map((type) => ({
+    name: actionNameFromOperation(type),
+    plugin: plugin.id,
+    type,
+    payloadSchema: operationSchemas[type]
+  }));
+}
+
+function createMicroPluginSchema(input = {}) {
+  const value = assertPlainObject(input, "micro plugin schema");
+  const plugin = value.plugin;
+  const id = nonEmptyString(value.id || plugin?.id, "micro plugin id");
+  const version = nonEmptyString(value.version || plugin?.version, "micro plugin version");
+  const key = nonEmptyString(value.key || id, "micro plugin key");
+  const source = value.source || (value.packageName && value.exportName ? {
+    packageName: value.packageName,
+    exportName: value.exportName,
+    ref: `workspace:${value.packageName}#${value.exportName}`
+  } : undefined);
+  const stateSchema = value.stateSchema || plugin?.stateSchemaDescriptor || plugin?.schemas?.state?.descriptor || plugin?.schemas?.state || { type: "object" };
+  const operationSchemas = value.operationSchemas || (plugin ? operationDescriptorsFromPlugin(plugin) : {});
+  const schema = {
+    kind: MICRO_PLUGIN_SCHEMA_KIND,
+    schemaVersion: MICRO_PLUGIN_SCHEMA_VERSION,
+    key,
+    id,
+    version,
+    name: optionalString(value.name || plugin?.meta?.name, "micro plugin name") || id,
+    source,
+    capabilities: normalizeCapabilitySet(value.capabilities || plugin?.capabilities),
+    schemas: {
+      state: stateSchema,
+      operations: operationSchemas
+    },
+    views: value.views || (plugin ? viewDescriptorsFromPlugin(plugin) : []),
+    actions: value.actions || (plugin ? actionDescriptorsFromOperations(plugin, operationSchemas) : [])
+  };
+  assertJsonSerializable(schema, "micro plugin schema");
+  return freezeJson({ ...schema, schemaHash: hashCanonical(schema) });
+}
+
+function validateMicroPluginSchema(schema) {
+  const value = assertPlainObject(schema, "micro plugin schema");
+  if (value.kind !== MICRO_PLUGIN_SCHEMA_KIND) throw new Error("Invalid micro plugin schema kind");
+  if (value.schemaVersion !== MICRO_PLUGIN_SCHEMA_VERSION) throw new Error("Invalid micro plugin schema version");
+  nonEmptyString(value.key, "micro plugin key");
+  nonEmptyString(value.id, "micro plugin id");
+  nonEmptyString(value.version, "micro plugin version");
+  assertPlainObject(value.schemas, "micro plugin schemas");
+  assertPlainObject(value.schemas.state, "micro plugin state schema");
+  assertPlainObject(value.schemas.operations, "micro plugin operation schemas");
+  assertJsonSerializable(value, "micro plugin schema");
+  return value;
+}
+
+function microPluginSchemaHash(schema) {
+  const copy = { ...validateMicroPluginSchema(schema) };
+  delete copy.schemaHash;
+  return hashCanonical(copy);
+}
+
+module.exports = {
+  MICRO_PLUGIN_SCHEMA_KIND,
+  MICRO_PLUGIN_SCHEMA_VERSION,
+  actionDescriptorsFromOperations,
+  actionNameFromOperation,
+  createMicroPluginSchema,
+  microPluginSchemaHash,
+  operationDescriptorsFromPlugin,
+  validateMicroPluginSchema,
+  viewDescriptorsFromPlugin
+};

package/src/model/collections.cjs

@@ -0,0 +1,57 @@
+const { assignedOperationLedgerId, evaluate, getPath, setPath } = require('./expressions.cjs');
+
+function asArrayCollection(state, path) {
+  const current = getPath(state, path);
+  return Array.isArray(current) ? current : [];
+}
+
+function asMapCollection(state, path) {
+  const current = getPath(state, path);
+  return current && typeof current === 'object' && !Array.isArray(current) ? current : {};
+}
+
+function recordIdFrom(effect, ctx) {
+  if (effect.id) return evaluate(effect.id, ctx);
+  if (effect.idField && ctx.payload[effect.idField]) return ctx.payload[effect.idField];
+  if (effect.idPath) return getPath(ctx.payload, effect.idPath);
+  if (effect.idPrefix) return evaluate(`$id:${effect.idPrefix}`, ctx);
+  return assignedOperationLedgerId(ctx.operation) || evaluate('$operation.id', ctx);
+}
+
+function findRecordInArray(items, id) {
+  return items.find((item) => item && item.id === id);
+}
+
+function ensureRecord(record, id, label = 'Record') {
+  if (!record) throw new Error(`${label} ${id} not found`);
+  return record;
+}
+
+function recordFromCollection(state, effect, ctx) {
+  const id = recordIdFrom(effect, ctx);
+  if (effect.storage === 'map') {
+    const map = asMapCollection(state, effect.collection);
+    return { id, record: ensureRecord(map[id], id, effect.recordLabel || 'Record') };
+  }
+  const items = asArrayCollection(state, effect.collection);
+  return { id, record: ensureRecord(findRecordInArray(items, id), id, effect.recordLabel || 'Record') };
+}
+
+function writeRecordToCollection(state, effect, id, record) {
+  if (effect.storage === 'map') {
+    const map = asMapCollection(state, effect.collection);
+    return setPath(state, effect.collection, { ...map, [id]: record });
+  }
+  const items = asArrayCollection(state, effect.collection);
+  return setPath(state, effect.collection, items.map((item) => item && item.id === id ? record : item));
+}
+
+module.exports = {
+  asArrayCollection,
+  asMapCollection,
+  ensureRecord,
+  findRecordInArray,
+  recordFromCollection,
+  recordIdFrom,
+  writeRecordToCollection
+};

package/src/model/effects.cjs

@@ -0,0 +1,149 @@
+const { cloneJson } = require('../json.cjs');
+const { evaluate, getPath, prefixedOperationId, setPath } = require('./expressions.cjs');
+const { asArrayCollection, asMapCollection, ensureRecord, findRecordInArray, recordFromCollection, recordIdFrom, writeRecordToCollection } = require('./collections.cjs');
+
+const SUPPORTED_SCHEMA_EFFECT_KINDS = Object.freeze([
+  'noop',
+  'createRecord',
+  'upsertActorRecord',
+  'updateRecord',
+  'markRecord',
+  'mergePath',
+  'appendToArray',
+  'toggleReaction',
+  'insertIdIntoRecordArray',
+  'removeIdFromRecordArray'
+]);
+
+function withActivity(state, ctx, message) {
+  if (!message) return state;
+  const activity = Array.isArray(state.activity) ? state.activity.slice() : [];
+  activity.push({ id: prefixedOperationId('activity', ctx.operation), operationId: ctx.operation.id, ledgerId: ctx.operation.ledgerId, actorId: ctx.actor.memberId, actorName: ctx.actor.displayName || ctx.actor.memberId, message, createdAt: ctx.operation.createdAt });
+  return { ...state, activity };
+}
+
+function applyCreateRecord(state, effect, ctx) {
+  const id = recordIdFrom(effect, ctx);
+  const record = { id, ...evaluate(effect.fields || {}, { ...ctx, recordId: id }) };
+  if (effect.storage === 'array') {
+    const items = asArrayCollection(state, effect.collection);
+    return setPath(state, effect.collection, [...items, record]);
+  }
+  const map = asMapCollection(state, effect.collection);
+  return setPath(state, effect.collection, { ...map, [id]: record });
+}
+
+function applyUpsertActorRecord(state, effect, ctx) {
+  const id = ctx.actor.memberId;
+  const map = asMapCollection(state, effect.collection);
+  const existing = map[id] || { id, joinedAt: ctx.operation.createdAt };
+  const record = { ...existing, ...evaluate(effect.fields || {}, ctx), id };
+  return setPath(state, effect.collection, { ...map, [id]: record });
+}
+
+function applyUpdateRecord(state, effect, ctx) {
+  const id = recordIdFrom(effect, ctx);
+  if (effect.storage === 'array') {
+    const items = asArrayCollection(state, effect.collection);
+    const record = ensureRecord(findRecordInArray(items, id), id, effect.recordLabel || 'Record');
+    const updated = { ...record, ...evaluate(effect.fields || {}, { ...ctx, record }) };
+    return setPath(state, effect.collection, items.map((item) => item.id === id ? updated : item));
+  }
+  const map = asMapCollection(state, effect.collection);
+  const record = ensureRecord(map[id], id, effect.recordLabel || 'Record');
+  const updated = { ...record, ...evaluate(effect.fields || {}, { ...ctx, record }) };
+  return setPath(state, effect.collection, { ...map, [id]: updated });
+}
+
+function applyMergePath(state, effect, ctx) {
+  const current = getPath(state, effect.path) || {};
+  const merged = { ...current, ...evaluate(effect.fields || '$payload', ctx) };
+  if (effect.deleteNullFields === true) {
+    for (const [key, value] of Object.entries(merged)) {
+      if (value === null) delete merged[key];
+    }
+  }
+  return setPath(state, effect.path, merged);
+}
+
+function applyAppendToArray(state, effect, ctx) {
+  const items = asArrayCollection(state, effect.path);
+  return setPath(state, effect.path, [...items, evaluate(effect.item || '$payload', ctx)]);
+}
+
+function applyToggleReaction(state, effect, ctx) {
+  const id = recordIdFrom(effect, ctx);
+  const map = asMapCollection(state, effect.collection);
+  const record = ensureRecord(map[id], id, effect.recordLabel || 'Record');
+  const emoji = ctx.payload[effect.emojiField || 'emoji'];
+  const reactions = { ...(record.reactions || {}) };
+  const current = new Set(reactions[emoji] || []);
+  if (current.has(ctx.actor.memberId)) current.delete(ctx.actor.memberId);
+  else current.add(ctx.actor.memberId);
+  reactions[emoji] = [...current];
+  return setPath(state, effect.collection, { ...map, [id]: { ...record, reactions } });
+}
+
+function recordAndIdForArrayEffect(state, effect, ctx) {
+  if (typeof effect.collection !== 'string' || effect.collection.length === 0) throw new Error('Array record effect collection is required');
+  if (typeof effect.arrayField !== 'string' || effect.arrayField.length === 0) throw new Error('Array record effect arrayField is required');
+  if (!Object.prototype.hasOwnProperty.call(effect, 'value')) throw new Error('Array record effect value is required');
+  return recordFromCollection(state, effect, ctx);
+}
+
+function finitePosition(position) {
+  return typeof position === 'number' && Number.isFinite(position);
+}
+
+function applyInsertIdIntoRecordArray(state, effect, ctx) {
+  const { id, record } = recordAndIdForArrayEffect(state, effect, ctx);
+  const arrayField = effect.arrayField;
+  const nextId = evaluate(effect.value, ctx);
+  const rawPosition = effect.position === undefined ? undefined : evaluate(effect.position, ctx);
+  const positioned = finitePosition(rawPosition);
+  const values = Array.isArray(record[arrayField]) ? record[arrayField].slice() : [];
+
+  if (positioned) {
+    const withoutExisting = values.filter((value) => value !== nextId);
+    const index = Math.max(0, Math.min(Math.trunc(rawPosition), withoutExisting.length));
+    withoutExisting.splice(index, 0, nextId);
+    return writeRecordToCollection(state, effect, id, { ...record, [arrayField]: withoutExisting });
+  }
+
+  if (values.includes(nextId)) return state;
+  values.push(nextId);
+  return writeRecordToCollection(state, effect, id, { ...record, [arrayField]: values });
+}
+
+function applyRemoveIdFromRecordArray(state, effect, ctx) {
+  const { id, record } = recordAndIdForArrayEffect(state, effect, ctx);
+  const arrayField = effect.arrayField;
+  const removeId = evaluate(effect.value, ctx);
+  const values = Array.isArray(record[arrayField]) ? record[arrayField].filter((value) => value !== removeId) : [];
+  return writeRecordToCollection(state, effect, id, { ...record, [arrayField]: values });
+}
+
+function applyEffect(state, effect, ctx) {
+  if (!effect || effect.kind === 'noop') return state;
+  let next;
+  if (effect.kind === 'createRecord') next = applyCreateRecord(state, effect, ctx);
+  else if (effect.kind === 'upsertActorRecord') next = applyUpsertActorRecord(state, effect, ctx);
+  else if (effect.kind === 'updateRecord' || effect.kind === 'markRecord') next = applyUpdateRecord(state, effect, ctx);
+  else if (effect.kind === 'mergePath') next = applyMergePath(state, effect, ctx);
+  else if (effect.kind === 'appendToArray') next = applyAppendToArray(state, effect, ctx);
+  else if (effect.kind === 'toggleReaction') next = applyToggleReaction(state, effect, ctx);
+  else if (effect.kind === 'insertIdIntoRecordArray') next = applyInsertIdIntoRecordArray(state, effect, ctx);
+  else if (effect.kind === 'removeIdFromRecordArray') next = applyRemoveIdFromRecordArray(state, effect, ctx);
+  else throw new Error(`Unsupported schema effect ${effect.kind}`);
+  return withActivity(next, ctx, effect.activity);
+}
+
+function applyEffects(state, effects = [], ctx) {
+  return effects.reduce((current, effect) => applyEffect(current, effect, ctx), cloneJson(state));
+}
+
+module.exports = {
+  SUPPORTED_SCHEMA_EFFECT_KINDS,
+  applyEffect,
+  applyEffects
+};

package/src/model/expressions.cjs

@@ -0,0 +1,85 @@
+const { cloneJson } = require('../json.cjs');
+const { isSnowflakeId, prefixedSnowflakeId, snowflakeIdForOperation } = require('@mh-gg/protocol');
+
+function sanitizeId(value) {
+  return String(value || '').replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+
+function assignedOperationLedgerId(operation = {}) {
+  const id = operation.ledgerId || operation.snowflakeId;
+  return id && isSnowflakeId(id) ? String(id) : undefined;
+}
+
+function operationLedgerId(operation = {}, options = {}) {
+  const assigned = assignedOperationLedgerId(operation);
+  if (assigned) return assigned;
+  return options.synthetic === false ? undefined : snowflakeIdForOperation(operation);
+}
+
+function prefixedOperationId(prefix, operation = {}) {
+  const ledgerId = assignedOperationLedgerId(operation);
+  if (ledgerId) return prefixedSnowflakeId(prefix, ledgerId);
+  return `${prefix}_${sanitizeId(operation.clientOperationId || operation.id)}`;
+}
+
+function getPath(root, path) {
+  if (!path) return root;
+  return String(path).split('.').reduce((value, part) => (value == null ? undefined : value[part]), root);
+}
+
+function setPath(root, path, nextValue) {
+  const parts = String(path).split('.').filter(Boolean);
+  if (parts.length === 0) return nextValue;
+  const copy = Array.isArray(root) ? root.slice() : { ...(root || {}) };
+  let cursor = copy;
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    const part = parts[index];
+    const current = cursor[part];
+    cursor[part] = Array.isArray(current) ? current.slice() : { ...(current || {}) };
+    cursor = cursor[part];
+  }
+  cursor[parts.at(-1)] = nextValue;
+  return copy;
+}
+
+function evaluateStringExpression(expr, ctx) {
+  if (expr.startsWith('$payload.')) return getPath(ctx.payload, expr.slice('$payload.'.length));
+  if (expr === '$payload') return ctx.payload;
+  if (expr.startsWith('$actor.')) return getPath(ctx.actor, expr.slice('$actor.'.length));
+  if (expr === '$actor') return ctx.actor;
+  if (expr.startsWith('$app.')) return getPath(ctx.app, expr.slice('$app.'.length));
+  if (expr === '$app') return ctx.app;
+  if (expr.startsWith('$room.')) return getPath(ctx.room, expr.slice('$room.'.length));
+  if (expr === '$room') return ctx.room;
+  if (expr === '$createdAt') return ctx.operation.createdAt;
+  if (expr === '$operation.id') return ctx.operation.id;
+  if (expr === '$operation.ledgerId' || expr === '$operation.snowflakeId') return operationLedgerId(ctx.operation);
+  if (expr === '$operation.type') return ctx.operation.type;
+  if (expr.startsWith('$id:')) return prefixedOperationId(expr.slice('$id:'.length), ctx.operation);
+  if (expr.startsWith('$const:')) return expr.slice('$const:'.length);
+  return expr;
+}
+
+function evaluate(value, ctx) {
+  if (typeof value === 'string') return value.startsWith('$') ? evaluateStringExpression(value, ctx) : value;
+  if (Array.isArray(value)) return value.map((item) => evaluate(item, ctx));
+  if (!value || typeof value !== 'object') return value;
+  if (Object.prototype.hasOwnProperty.call(value, '$expr')) {
+    const evaluated = evaluateStringExpression(value.$expr, ctx);
+    if (evaluated === undefined && Object.prototype.hasOwnProperty.call(value, 'fallback')) return cloneJson(value.fallback);
+    return evaluated;
+  }
+  if (Object.prototype.hasOwnProperty.call(value, '$literal')) return cloneJson(value.$literal);
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const evaluated = evaluate(entry, ctx);
+    if (evaluated !== undefined) out[key] = evaluated;
+  }
+  return out;
+}
+
+function collectionValue(state, path) {
+  return getPath(state, path) || (path.endsWith('s') ? [] : {});
+}
+
+module.exports = { assignedOperationLedgerId, collectionValue, evaluate, getPath, operationLedgerId, prefixedOperationId, sanitizeId, setPath };

package/src/model/guards.cjs

@@ -0,0 +1,139 @@
+const { asArrayCollection, asMapCollection, findRecordInArray, recordIdFrom } = require('./collections.cjs');
+const { evaluate } = require('./expressions.cjs');
+
+const ROLE_RANKS = Object.freeze({
+  guest: 0,
+  member: 1,
+  user: 1,
+  moderator: 2,
+  admin: 3,
+  owner: 4
+});
+
+function roleRank(role) {
+  return ROLE_RANKS[role === 'user' ? 'member' : role] ?? ROLE_RANKS.guest;
+}
+
+function roleMeetsAny(actor, roles = []) {
+  return roles.some((role) => roleRank(actor?.role) >= roleRank(role));
+}
+
+function recordForGuard(state, guard, ctx) {
+  const id = recordIdFrom(guard, ctx);
+  if (guard.storage === 'map') return asMapCollection(state, guard.collection)[id];
+  return findRecordInArray(asArrayCollection(state, guard.collection), id);
+}
+
+function assertRecordOwnerOrRole(state, guard, ctx) {
+  if (roleMeetsAny(ctx.actor, guard.roles || [])) return;
+  const record = recordForGuard(state, guard, ctx);
+  if (!record || record[guard.ownerField || 'authorId'] !== ctx.actor.memberId) {
+    throw new Error(guard.message || 'Only the owner or an allowed role can perform this operation');
+  }
+}
+
+function assertRecordFlagClear(state, guard, ctx) {
+  const record = recordForGuard(state, guard, ctx);
+  if (record?.[guard.flag]) throw new Error(guard.message || `${guard.flag} blocks this operation`);
+}
+
+function pathSegments(path, ctx) {
+  const parts = [];
+  const text = String(path || '').replace(/\[([^\]]+)\]/g, (_m, inner) => {
+    let key = inner.trim();
+    if ((key.startsWith('"') && key.endsWith('"')) || (key.startsWith("'") && key.endsWith("'"))) key = key.slice(1, -1);
+    else if (key.startsWith('$')) key = evaluate(key, ctx);
+    return `.${String(key).replace(/\./g, '\\.')}`;
+  });
+  for (const raw of text.split('.')) {
+    if (!raw) continue;
+    parts.push(raw.replace(/\\\./g, '.'));
+  }
+  return parts;
+}
+
+function getPathWithRuntimeKeys(root, path, ctx) {
+  const parts = pathSegments(path, ctx);
+  return parts.reduce((value, part) => (value == null ? undefined : value[part]), root);
+}
+
+function statePathValue(state, path, ctx) {
+  if (typeof path !== 'string') return path;
+  if (path.startsWith('$state.')) return getPathWithRuntimeKeys(state, path.slice('$state.'.length), ctx);
+  if (path === '$state') return state;
+  if (path.startsWith('state.')) return getPathWithRuntimeKeys(state, path.slice('state.'.length), ctx);
+  if (path.startsWith('$')) return evaluate(path, ctx);
+  return getPathWithRuntimeKeys(state, path, ctx);
+}
+
+function operandValue(state, operand, ctx) {
+  if (!operand || typeof operand !== 'object' || Array.isArray(operand)) {
+    if (typeof operand === 'string' && operand.startsWith('$')) return evaluate(operand, ctx);
+    return operand;
+  }
+  if (operand.kind === 'value.literal') return operand.value;
+  if (operand.kind === 'value.expr') return evaluate(operand.expr, ctx);
+  if (operand.kind === 'value.path') return statePathValue(state, operand.path, ctx);
+  if (operand.kind === 'value.length') {
+    const value = statePathValue(state, operand.path, ctx);
+    if (Array.isArray(value) || typeof value === 'string') return value.length;
+    if (value && typeof value === 'object') return Object.keys(value).length;
+    return 0;
+  }
+  if (operand.kind === 'length') {
+    const value = statePathValue(state, operand.path, ctx);
+    if (Array.isArray(value) || typeof value === 'string') return value.length;
+    if (value && typeof value === 'object') return Object.keys(value).length;
+    return 0;
+  }
+  if (Object.prototype.hasOwnProperty.call(operand, 'value')) return operand.value;
+  if (operand.path) return statePathValue(state, operand.path, ctx);
+  return operand;
+}
+
+function compareValues(kind, left, right) {
+  if (kind === 'eq') return left === right;
+  if (kind === 'ne') return left !== right;
+  if (kind === 'lt') return Number(left) < Number(right);
+  if (kind === 'lte') return Number(left) <= Number(right);
+  if (kind === 'gt') return Number(left) > Number(right);
+  if (kind === 'gte') return Number(left) >= Number(right);
+  return false;
+}
+
+function guardPasses(state, guard, ctx) {
+  if (!guard || guard.kind === 'noop') return true;
+  if (guard.kind === 'recordOwnerOrRole') {
+    assertRecordOwnerOrRole(state, guard, ctx);
+    return true;
+  }
+  if (guard.kind === 'recordFlagClear') {
+    assertRecordFlagClear(state, guard, ctx);
+    return true;
+  }
+  if (['eq', 'ne', 'lt', 'lte', 'gt', 'gte'].includes(guard.kind)) return compareValues(guard.kind, operandValue(state, guard.left, ctx), operandValue(state, guard.right, ctx));
+  if (guard.kind === 'exists') return statePathValue(state, guard.path, ctx) !== undefined;
+  if (guard.kind === 'and') return (guard.guards || []).every((item) => guardPasses(state, item, ctx));
+  if (guard.kind === 'or') return (guard.guards || []).some((item) => guardPasses(state, item, ctx));
+  if (guard.kind === 'not') return !guardPasses(state, guard.guard, ctx);
+  throw new Error(`Unsupported schema guard ${guard.kind}`);
+}
+
+function applyGuard(state, guard, ctx) {
+  if (!guard || guard.kind === 'noop') return;
+  const ok = guardPasses(state, guard, ctx);
+  if (!ok) throw new Error(guard.message || 'Schema guard rejected this operation');
+}
+
+function applyGuards(state, guards = [], ctx) {
+  for (const guard of guards) applyGuard(state, guard, ctx);
+}
+
+module.exports = {
+  applyGuard,
+  applyGuards,
+  guardPasses,
+  roleMeetsAny,
+  roleRank,
+  statePathValue
+};

package/src/model/index.cjs

@@ -0,0 +1,9 @@
+module.exports = {
+  ...require('./expressions.cjs'),
+  ...require('./collections.cjs'),
+  ...require('./payload.cjs'),
+  ...require('./effects.cjs'),
+  ...require('./guards.cjs'),
+  ...require('./plugin.cjs'),
+  ...require('./partitionValidator.cjs')
+};

package/src/model/partitionOperands.cjs

@@ -0,0 +1,89 @@
+const { SUPPORTED_SCHEMA_EFFECT_KINDS } = require('./effects.cjs');
+
+const READ_CLASSES_CHUNKABLE = Object.freeze(new Set(['window', 'head']));
+
+function topLevelPath(path) {
+  if (typeof path !== 'string' || path.length === 0) return undefined;
+  let normalized = path;
+  if (normalized.startsWith('$state.')) normalized = normalized.slice(7);
+  else if (normalized === '$state') return undefined;
+  else if (normalized.startsWith('state.')) normalized = normalized.slice(6);
+  else if (normalized.startsWith('$payload.')) return undefined;
+  else if (normalized.startsWith('$')) return undefined;
+  const first = normalized.split('.')[0];
+  return first || undefined;
+}
+
+function partitionsFromOperand(operand) {
+  const parts = new Set();
+  if (!operand || typeof operand !== 'object') return parts;
+  if (operand.path) {
+    const p = topLevelPath(operand.path);
+    if (p) parts.add(p);
+  }
+  if (operand.kind === 'value.path' && operand.path) {
+    const p = topLevelPath(operand.path);
+    if (p) parts.add(p);
+  }
+  if (operand.kind === 'value.length' && operand.path) {
+    const p = topLevelPath(operand.path);
+    if (p) parts.add(p);
+  }
+  if (operand.kind === 'length' && operand.path) {
+    const p = topLevelPath(operand.path);
+    if (p) parts.add(p);
+  }
+  return parts;
+}
+
+function partitionsFromGuard(guard) {
+  const parts = new Set();
+  if (!guard || guard.kind === 'noop') return parts;
+  if (guard.kind === 'recordOwnerOrRole' || guard.kind === 'recordFlagClear') {
+    if (guard.collection) parts.add(guard.collection);
+    return parts;
+  }
+  if (['eq', 'ne', 'lt', 'lte', 'gt', 'gte'].includes(guard.kind)) {
+    for (const p of partitionsFromOperand(guard.left)) parts.add(p);
+    for (const p of partitionsFromOperand(guard.right)) parts.add(p);
+    return parts;
+  }
+  if (guard.kind === 'exists') {
+    const p = topLevelPath(guard.path);
+    if (p) parts.add(p);
+    return parts;
+  }
+  if (guard.kind === 'and' || guard.kind === 'or') {
+    for (const child of guard.guards || []) {
+      for (const p of partitionsFromGuard(child)) parts.add(p);
+    }
+    return parts;
+  }
+  if (guard.kind === 'not') {
+    return partitionsFromGuard(guard.guard);
+  }
+  return parts;
+}
+
+function partitionsFromEffect(effect) {
+  const parts = new Set();
+  if (!effect || effect.kind === 'noop') return parts;
+  if (effect.partition) parts.add(effect.partition);
+  if (effect.kind === 'mergePath' && effect.path) {
+    const p = topLevelPath(effect.path);
+    if (p) parts.add(p);
+  }
+  if (effect.kind === 'appendToArray' && effect.path) {
+    const p = topLevelPath(effect.path);
+    if (p) parts.add(p);
+  }
+  return parts;
+}
+
+module.exports = {
+  READ_CLASSES_CHUNKABLE,
+  partitionsFromEffect,
+  partitionsFromGuard,
+  partitionsFromOperand,
+  topLevelPath
+};