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

package/test/schema-array-effects.test.cjs

@@ -0,0 +1,116 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const { applyEffect, applyEffects, SUPPORTED_SCHEMA_EFFECT_KINDS } = require('../src/model/index.cjs');
+
+function ctx(overrides = {}) {
+  return {
+    operation: { id: 'op_1', createdAt: 1000, type: 'card.move', ...(overrides.operation || {}) },
+    actor: { memberId: 'alice', deviceId: 'dev_alice', role: 'member', ...(overrides.actor || {}) },
+    payload: { ...(overrides.payload || {}) }
+  };
+}
+
+function legacyMoveCard(state, payload, createdAt = 1000) {
+  const cards = state.cards || {};
+  const card = cards[payload.cardId];
+  if (!card) throw new Error(`Card ${payload.cardId} not found`);
+  const lists = Array.isArray(state.lists) ? state.lists : [];
+  const toList = lists.find((list) => list.id === payload.toListId);
+  if (!toList) throw new Error(`List ${payload.toListId} not found`);
+  const nextLists = lists.map((list) => {
+    const without = (list.cardIds || []).filter((id) => id !== payload.cardId);
+    if (list.id !== toList.id) return { ...list, cardIds: without };
+    const cardIds = without.slice();
+    cardIds.splice(Math.min(payload.position ?? cardIds.length, cardIds.length), 0, payload.cardId);
+    return { ...list, cardIds };
+  });
+  return {
+    ...state,
+    lists: nextLists,
+    cards: { ...cards, [card.id]: { ...card, listId: toList.id, updatedAt: createdAt } }
+  };
+}
+
+const moveEffects = [
+  { kind: 'removeIdFromRecordArray', collection: 'lists', storage: 'array', idField: 'fromListId', arrayField: 'cardIds', value: '$payload.cardId', recordLabel: 'List' },
+  { kind: 'insertIdIntoRecordArray', collection: 'lists', storage: 'array', idField: 'toListId', arrayField: 'cardIds', value: '$payload.cardId', position: '$payload.position', recordLabel: 'List' },
+  { kind: 'updateRecord', collection: 'cards', storage: 'map', idField: 'cardId', fields: { listId: '$payload.toListId', updatedAt: '$createdAt' }, recordLabel: 'Card' }
+];
+
+test('schema array primitives expose a domain-neutral allowlist', () => {
+  assert.ok(SUPPORTED_SCHEMA_EFFECT_KINDS.includes('insertIdIntoRecordArray'));
+  assert.ok(SUPPORTED_SCHEMA_EFFECT_KINDS.includes('removeIdFromRecordArray'));
+  assert.equal(SUPPORTED_SCHEMA_EFFECT_KINDS.includes('moveCard'), false);
+  assert.equal(SUPPORTED_SCHEMA_EFFECT_KINDS.includes('appendIdToArrayInRecord'), false);
+});
+
+test('insertIdIntoRecordArray appends with de-dupe and repositions when a finite position is supplied', () => {
+  const state = { lists: [{ id: 'todo', cardIds: ['a', 'b'] }] };
+  const appendDuplicate = applyEffect(state, {
+    kind: 'insertIdIntoRecordArray', collection: 'lists', storage: 'array', idField: 'listId', arrayField: 'cardIds', value: '$payload.cardId'
+  }, ctx({ payload: { listId: 'todo', cardId: 'b' } }));
+  assert.deepEqual(appendDuplicate.lists[0].cardIds, ['a', 'b']);
+
+  const appendNew = applyEffect(state, {
+    kind: 'insertIdIntoRecordArray', collection: 'lists', storage: 'array', idField: 'listId', arrayField: 'cardIds', value: '$payload.cardId'
+  }, ctx({ payload: { listId: 'todo', cardId: 'c' } }));
+  assert.deepEqual(appendNew.lists[0].cardIds, ['a', 'b', 'c']);
+
+  const repositioned = applyEffect(state, {
+    kind: 'insertIdIntoRecordArray', collection: 'lists', storage: 'array', idField: 'listId', arrayField: 'cardIds', value: '$payload.cardId', position: '$payload.position'
+  }, ctx({ payload: { listId: 'todo', cardId: 'b', position: 0 } }));
+  assert.deepEqual(repositioned.lists[0].cardIds, ['b', 'a']);
+});
+
+test('insertIdIntoRecordArray clamps positioned inserts and works with map storage', () => {
+  const state = { columns: { todo: { id: 'todo', itemIds: ['a'] } } };
+  const next = applyEffect(state, {
+    kind: 'insertIdIntoRecordArray', collection: 'columns', storage: 'map', idField: 'columnId', arrayField: 'itemIds', value: '$payload.itemId', position: '$payload.position'
+  }, ctx({ payload: { columnId: 'todo', itemId: 'b', position: 99 } }));
+  assert.deepEqual(next.columns.todo.itemIds, ['a', 'b']);
+});
+
+test('removeIdFromRecordArray removes all matching ids and throws on missing records', () => {
+  const state = { lists: [{ id: 'todo', cardIds: ['a', 'b', 'a'] }] };
+  const next = applyEffect(state, {
+    kind: 'removeIdFromRecordArray', collection: 'lists', storage: 'array', idField: 'listId', arrayField: 'cardIds', value: '$payload.cardId'
+  }, ctx({ payload: { listId: 'todo', cardId: 'a' } }));
+  assert.deepEqual(next.lists[0].cardIds, ['b']);
+
+  assert.throws(() => applyEffect(state, {
+    kind: 'removeIdFromRecordArray', collection: 'lists', storage: 'array', idField: 'listId', arrayField: 'cardIds', value: '$payload.cardId'
+  }, ctx({ payload: { listId: 'missing', cardId: 'a' } })), /Record missing not found/);
+});
+
+test('composed card.move effects match the legacy moveCard behavior under the single-list invariant', () => {
+  const fixtures = [
+    {
+      name: 'move to empty list',
+      state: { lists: [{ id: 'todo', cardIds: ['card_1'] }, { id: 'done', cardIds: [] }], cards: { card_1: { id: 'card_1', listId: 'todo', title: 'One' } } },
+      payload: { cardId: 'card_1', fromListId: 'todo', toListId: 'done' }
+    },
+    {
+      name: 'move with explicit position',
+      state: { lists: [{ id: 'todo', cardIds: ['card_1'] }, { id: 'done', cardIds: ['card_2'] }], cards: { card_1: { id: 'card_1', listId: 'todo', title: 'One' }, card_2: { id: 'card_2', listId: 'done', title: 'Two' } } },
+      payload: { cardId: 'card_1', fromListId: 'todo', toListId: 'done', position: 0 }
+    },
+    {
+      name: 'position clamps past end',
+      state: { lists: [{ id: 'todo', cardIds: ['card_1'] }, { id: 'done', cardIds: ['card_2'] }], cards: { card_1: { id: 'card_1', listId: 'todo', title: 'One' }, card_2: { id: 'card_2', listId: 'done', title: 'Two' } } },
+      payload: { cardId: 'card_1', fromListId: 'todo', toListId: 'done', position: 99 }
+    },
+    {
+      name: 'same-list reorder',
+      state: { lists: [{ id: 'todo', cardIds: ['card_1', 'card_2', 'card_3'] }], cards: { card_1: { id: 'card_1', listId: 'todo', title: 'One' }, card_2: { id: 'card_2', listId: 'todo', title: 'Two' }, card_3: { id: 'card_3', listId: 'todo', title: 'Three' } } },
+      payload: { cardId: 'card_3', fromListId: 'todo', toListId: 'todo', position: 0 }
+    }
+  ];
+
+  for (const fixture of fixtures) {
+    const context = ctx({ payload: fixture.payload, operation: { createdAt: 2000 } });
+    const rewritten = applyEffects(fixture.state, moveEffects, context);
+    const legacy = legacyMoveCard(fixture.state, fixture.payload, 2000);
+    assert.deepEqual(rewritten, legacy, fixture.name);
+    assert.deepEqual(JSON.parse(JSON.stringify(rewritten)), JSON.parse(JSON.stringify(legacy)), `${fixture.name} JSON shape`);
+  }
+});

package/test/schema-builder-types.test.cjs

@@ -0,0 +1,383 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+const {
+  manifestHash,
+  playerSupportsApp,
+  validateAppPackManifest,
+  validateHostPackManifest,
+  validatePlayerPackManifest
+} = require('@mh-gg/base');
+const { HostPluginRuntime, createMemoryOperationLog, createMemoryRoomStore } = require('@mh-gg/host-runtime');
+const { ensureOperationIdentity } = require('@mh-gg/protocol');
+const { createSignedPartyEvent, nostrEventToPartyEvent, partyEventToNostrEvent } = require('@mh-gg/event');
+const {
+  defineApp,
+  defineModel,
+  fx,
+  guard,
+  op,
+  p,
+  q,
+  ref,
+  createSchemaDefinedHostPlugin,
+  genericSummary
+} = require('../src/index.cjs');
+
+function inertPlugin(id) {
+  return {
+    id,
+    version: '1.0.0',
+    operationSchemaDescriptor: { operations: {} }
+  };
+}
+
+function dynamicBoardApp() {
+  const model = defineModel({
+    roles: {
+      member: { name: 'Member', rank: 1, system: true },
+      admin: { name: 'Admin', rank: 3, system: true }
+    },
+    state: { lists: {}, cards: {}, settings: {}, activity: [] }
+  });
+  const { lists, cards } = model.collections;
+  const board = model.withOperations({
+    'list.create': op({
+      authorize: { roles: ['member'] },
+      payload: {
+        listId: p.string({ max: 80 }),
+        title: p.string({ max: 80 }),
+        wipLimit: p.number({ min: 0 })
+      }
+    }, ({ ref, fx }) => ({
+      effects: [fx.create(lists, {
+        id: ref.payload('listId'),
+        fields: { title: ref.payload('title'), cardIds: [], wipLimit: ref.payload('wipLimit'), createdAt: ref.now() }
+      })]
+    })),
+    'card.create': op({
+      authorize: { roles: ['member'] },
+      payload: { cardId: p.string({ max: 80 }), listId: p.string({ max: 80 }), title: p.string({ max: 160 }) }
+    }, ({ ref, fx, guard }) => ({
+      guards: [
+        guard.lt(
+          guard.length('lists[$payload.listId].cardIds'),
+          guard.path('lists[$payload.listId].wipLimit'),
+          'List is at its WIP limit'
+        )
+      ],
+      effects: [
+        fx.create(cards, { id: ref.payload('cardId'), fields: { listId: ref.payload('listId'), title: ref.payload('title'), createdAt: ref.now() } }),
+        fx.insertIntoArray(lists, { matchId: ref.payload('listId'), field: 'cardIds', value: ref.payload('cardId') })
+      ]
+    })),
+    'settings.update': op({
+      authorize: { roles: ['member'] },
+      payload: {
+        media: p.object({
+          audio: p.boolean().default(true),
+          video: p.boolean().optional(),
+          screen: p.boolean().optional()
+        }),
+        roleAccess: p.record(p.enum(['editor', 'readonly'])).optional()
+      }
+    }, () => ({ effects: [fx.merge({ path: 'settings', fields: '$payload' })] }))
+  });
+
+  return defineApp({
+    id: 'com.matterhorn.tests.dynamic-board',
+    name: 'Dynamic Board',
+    version: '1.0.0',
+    model: board,
+    views: { board: q.state() },
+    routes: [{ path: '/', component: 'BoardPage' }]
+  });
+}
+
+function operation(app, type, payload, overrides = {}) {
+  const composition = app.toJSON();
+  const actor = overrides.actor || { memberId: 'ada', deviceId: 'dev_ada', role: 'member', displayName: 'Ada' };
+  const createdAt = overrides.createdAt || 1000;
+  return ensureOperationIdentity({
+    clientOperationId: overrides.id || `op_${type.replace(/[^a-z0-9]+/gi, '_')}`,
+    roomId: 'room_dynamic_board',
+    appPackId: composition.app.id,
+    appPackHash: manifestHash({ id: composition.app.id, version: composition.app.version }),
+    pluginId: composition.primaryPlugin.id,
+    type,
+    actor,
+    seq: overrides.seq || 1,
+    createdAt,
+    payload,
+    auth: { credentialId: 'cred', signature: 'sig' }
+  }, { now: createdAt, nodeId: actor.deviceId || actor.memberId });
+}
+
+test('defineApp emits JSON fragments and a concrete frontend type namespace', () => {
+  const app = dynamicBoardApp();
+  const composition = app.toJSON();
+  assert.equal(composition.primaryPlugin.model.operations['settings.update'].payload.required.media.type, 'object');
+  assert.equal(composition.primaryPlugin.model.operations['settings.update'].payload.optional.roleAccess.type, 'record');
+  assert.doesNotThrow(() => JSON.stringify(composition));
+
+  const types = app.toTypes({ namespace: 'DynamicBoard' });
+  assert.match(types, /export namespace DynamicBoard/);
+  assert.match(types, /cardCreate: \{ cardId: string; listId: string; title: string \}/);
+  assert.match(types, /cardIds: string\[\]/);
+  assert.match(types, /settingsUpdate: \{ media: \{ audio: boolean; video\?: boolean; screen\?: boolean \}; roleAccess\?: Record<string, "editor" \| "readonly"> \}/);
+  assert.match(types, /export type ActionName = keyof Actions/);
+  assert.match(types, /Requires `member` role\./);
+  assert.match(types, /title: string, <= 80/);
+  assert.match(types, /wipLimit: number, >= 0/);
+  assert.doesNotMatch(types, /ActionHelpers|DispatchResult|ConnectionStatus|export interface Client/);
+  assert.doesNotMatch(types, /dispatch<K extends ActionName>|query<K extends QueryName>/);
+
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'matterhorn-builder-'));
+  const emitted = app.emit({ outDir, namespace: 'DynamicBoard' });
+  assert.equal(fs.existsSync(emitted.schemaPath), true);
+  assert.equal(fs.existsSync(emitted.typesPath), true);
+  assert.equal(path.basename(emitted.schemaPath), 'matterhorn.schema.json');
+  assert.equal(path.basename(emitted.typesPath), 'matterhorn.types.d.ts');
+  assert.equal("modelPath" in emitted, false);
+  assert.equal("actionsPath" in emitted, false);
+  assert.equal("compositionPath" in emitted, false);
+  assert.equal("clientPath" in emitted, false);
+  assert.equal(fs.existsSync(path.join(outDir, "client.ts")), false);
+  assert.equal(fs.existsSync(path.join(outDir, "actions.json")), false);
+  assert.equal(fs.existsSync(path.join(outDir, "model.json")), false);
+  assert.equal(fs.existsSync(path.join(outDir, "composition.json")), false);
+  const schema = JSON.parse(fs.readFileSync(emitted.schemaPath, 'utf8'));
+  assert.equal(schema.primaryPlugin.model.operations['card.create'].guards[0].kind, 'lt');
+});
+
+test('defineApp builds self-contained Matterhorn app exports without JSON sidecars', () => {
+  const app = dynamicBoardApp();
+  const matterhornOptions = {
+    slug: 'dynamic-board',
+    packageName: '@mh-gg/test-dynamic-board',
+    exportPrefix: 'dynamicBoard',
+    constantPrefix: 'DYNAMIC_BOARD',
+    frontend: false,
+    matterhorn: { bridgeGlobalName: 'MATTERHORN_DYNAMIC_BOARD_HOST', frontendProjection: 'board' },
+    demo: {
+      roomId: 'demo_board',
+      operations: [{
+        id: 'demo_list',
+        plugin: '$primary',
+        type: 'list.create',
+        actor: { memberId: 'ada', deviceId: 'dev_ada', role: 'member', displayName: 'Ada' },
+        payload: { listId: 'todo', title: 'Todo', wipLimit: 2 }
+      }]
+    }
+  };
+  const exported = app.toMatterhornExports(matterhornOptions);
+  const bundle = app.toMatterhornBundle(matterhornOptions);
+
+  assert.equal(validateAppPackManifest(exported.appPack).id, 'com.matterhorn.tests.dynamic-board');
+  assert.equal(validateHostPackManifest(exported.hostPack).appPackId, exported.appPack.id);
+  assert.equal(validatePlayerPackManifest(exported.playerPack).supports[0].appPackId, exported.appPack.id);
+  assert.equal(playerSupportsApp(exported.playerPack, exported.appPack), true);
+  assert.equal(exported.matterhornApp.matterhorn.bridgeGlobalName, 'MATTERHORN_DYNAMIC_BOARD_HOST');
+  assert.equal(exported.matterhornApp.frontend, undefined);
+  assert.match(exported.generatedTypes, /export namespace DynamicBoard/);
+  assert.equal(exported.DYNAMIC_BOARD_APP_ID, 'com.matterhorn.tests.dynamic-board');
+  assert.equal(exported.DYNAMIC_BOARD_PLUGIN_ID, 'com.matterhorn.tests.dynamic-board.plugin');
+  assert.equal(exported.dynamicBoardAppPack, exported.appPack);
+  assert.equal(exported.dynamicBoardHostPlugin, exported.hostPlugin);
+  assert.equal(exported.schemaArtifacts.types, exported.generatedTypes);
+  assert.equal(exported.schemaArtifacts.schema.app.id, exported.appPack.id);
+  assert.deepEqual(exported.schemaArtifacts.files, { schema: 'matterhorn.schema.json', types: 'matterhorn.types.d.ts' });
+
+  const operations = exported.createDemoOperations('room_override');
+  assert.equal(operations.length, 1);
+  assert.equal(operations[0].roomId, 'room_override');
+  assert.equal(operations[0].pluginId, exported.hostPlugin.id);
+  assert.equal(operations[0].type, 'list.create');
+
+  assert.equal(bundle.kind, 'matterhorn.app-bundle');
+  assert.equal(bundle.id, exported.appPack.id);
+  assert.equal(bundle.appPack.id, exported.appPack.id);
+  assert.equal(bundle.hostPack.appPackId, exported.appPack.id);
+  assert.equal(bundle.hostPlugins[0].kind, 'matterhorn.schema-model-host-plugin');
+  assert.equal(bundle.hostPlugins[0].composition.primaryPlugin.id, exported.hostPlugin.id);
+  assert.equal('types' in bundle, false);
+  assert.equal('types' in bundle.artifacts, false);
+  assert.equal(bundle.artifacts.composition.app.id, exported.appPack.id);
+  assert.doesNotThrow(() => JSON.stringify(bundle));
+
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'matterhorn-bundle-'));
+  const emitted = app.emitMatterhornBundle({ ...matterhornOptions, outDir });
+  assert.equal(emitted.bundlePath, path.join(outDir, 'com.matterhorn.tests.dynamic-board.json'));
+  const emittedBundle = JSON.parse(fs.readFileSync(emitted.bundlePath, 'utf8'));
+  assert.equal(emittedBundle.kind, 'matterhorn.app-bundle');
+  assert.equal('types' in emittedBundle, false);
+  assert.equal('types' in emittedBundle.artifacts, false);
+});
+
+test('defineApp matterhorn exports honor app-stack options and host plugin helpers', () => {
+  const app = dynamicBoardApp();
+  const explicitHostPlugin = createSchemaDefinedHostPlugin(app.toJSON());
+  const sidecarPlugin = inertPlugin('com.matterhorn.tests.sidecar');
+  const nestedPlugin = inertPlugin('com.matterhorn.tests.nested');
+  const suitePlugin = inertPlugin('com.matterhorn.tests.suite');
+  const exported = app.toMatterhornExports({
+    exportPrefix: 'dynamicBoard',
+    constantPrefix: 'DYNAMIC_BOARD',
+    packageName: '@mh-gg/test-dynamic-board',
+    hostPlugin: explicitHostPlugin,
+    hostPluginExport: 'explicitHostPlugin',
+    hostPluginSource: 'workspace:test#explicitHostPlugin',
+    hostPluginDependsOn: [{ id: 'matterhorn.core', optional: true }],
+    hostPluginConflictsWith: ['com.matterhorn.tests.conflict'],
+    hostPlugins: [
+      null,
+      [{ plugin: sidecarPlugin, config: { enabled: true }, packageName: '@mh-gg/sidecar', exportName: 'sidecarPlugin' }],
+      { entries: [nestedPlugin] },
+      { kind: 'matterhorn.example-plugin-suite', entries: [{ plugin: suitePlugin, source: 'workspace:test#suitePlugin' }] }
+    ],
+    frontend: {
+      root: __dirname,
+      port: 4555,
+      label: 'Dynamic Board test frontend',
+      backgroundColor: ' #102030 ',
+      icon: ' assets/board.svg ',
+      devEntry: 'src/main.ts',
+      bundle: {
+        builtEntry: 'dynamic-board.js',
+        prebuilt: true
+      }
+    },
+    matterhornApp: { matterhorn: { bridgeGlobalName: 'MATTERHORN_DYNAMIC_BOARD_HOST', frontendProjection: 'board' } },
+    deployment: { relay: { mode: 'embedded', autoStart: false } },
+    publisher: { id: 'com.matterhorn.tests', name: 'Matterhorn Tests', publicKey: 'rk_pub_tests' },
+    trust: { signatures: [{ publicKey: 'rk_pub_tests', signature: 'sig_tests' }] },
+    appCapabilities: { required: ['room.state'], optional: [] },
+    hostCapabilities: { required: ['room.state'], optional: [] },
+    entrypoints: { default: 'https://example.test/player/' },
+    recommendedFor: { devices: ['desktop'], roles: ['member'] },
+    playerRoutes: [{ path: '/', component: 'BoardShell', requiredPlugins: [explicitHostPlugin.id] }],
+    playerActions: { custom: async () => {} },
+    optimisticReducers: { custom: (state) => state },
+    navigation: { adminRoute: '/settings' },
+    deviceHints: { phone: true },
+    exportAliases: { primaryPack: 'dynamicBoardAppPack' },
+    createdAt: '2026-06-04T00:00:00Z'
+  });
+
+  const explicitRef = exported.hostPack.plugins.find((plugin) => plugin.id === explicitHostPlugin.id);
+  assert.equal(explicitRef.source, 'workspace:test#explicitHostPlugin');
+  assert.deepEqual(explicitRef.dependsOn, [{ id: 'matterhorn.core', optional: true }]);
+  assert.deepEqual(explicitRef.conflictsWith, ['com.matterhorn.tests.conflict']);
+  assert.equal(exported.hostPlugins.find((plugin) => plugin.id === sidecarPlugin.id).config.enabled, true);
+  assert.equal(exported.hostPack.plugins.some((plugin) => plugin.id === nestedPlugin.id), true);
+  assert.equal(exported.hostPack.plugins.some((plugin) => plugin.id === suitePlugin.id), true);
+  assert.equal(exported.matterhornApp.frontend.bundle.dev.command, 'npm');
+  assert.equal(exported.matterhornApp.frontend.bundle.build.command, 'npm');
+  assert.equal(exported.matterhornApp.frontend.bundle.prebuilt, true);
+  assert.equal(exported.matterhornApp.frontend.backgroundColor, '#102030');
+  assert.deepEqual(exported.matterhornApp.frontend.icon, { path: 'assets/board.svg' });
+  assert.equal(exported.matterhornApp.deployment.relay.autoStart, false);
+  assert.equal(exported.appPack.publisher.id, 'com.matterhorn.tests');
+  assert.equal(exported.appPack.trust.createdAt, '2026-06-04T00:00:00Z');
+  assert.equal(exported.playerPack.entrypoints.default, 'https://example.test/player/');
+  assert.deepEqual(exported.playerPack.recommendedFor.roles, ['member']);
+  assert.equal(exported.playerPlugin.routes[0].component, 'BoardShell');
+  assert.equal(typeof exported.playerPlugin.actions.custom, 'function');
+  assert.equal(exported.playerPlugin.navigation.adminRoute, '/settings');
+  assert.equal(exported.playerPlugin.deviceHints.phone, true);
+  assert.equal(exported.primaryPack, exported.dynamicBoardAppPack);
+
+  assert.throws(() => app.toMatterhornExports({ hostPlugins: [inertPlugin('com.matterhorn.tests.dup'), inertPlugin('com.matterhorn.tests.dup')] }), /Duplicate host plugin/);
+  assert.throws(() => app.toMatterhornExports({ exportAliases: { missingAlias: 'missingExport' } }), /missingExport/);
+  assert.throws(() => app.toMatterhornExports({ hostPlugin: { id: 'bad.plugin', version: '1.0.0', operationSchemaDescriptor: {} } }), /canonical operationSchemaDescriptor/);
+});
+
+test('defineApp demo helpers replay schema operations', async () => {
+  const app = dynamicBoardApp();
+  const exported = app.toMatterhornExports({
+    slug: 'dynamic-board',
+    packageName: '@mh-gg/test-dynamic-board',
+    exportPrefix: 'dynamicBoard',
+    demo: {
+      roomId: 'demo_board',
+      startTime: 1700000000000,
+      operations: [{
+        id: 'demo_list',
+        type: 'list.create',
+        payload: { listId: 'todo', title: 'Todo', wipLimit: 2 }
+      }]
+    },
+    summary(state) {
+      return { version: state.version, lists: Object.keys(state.plugins[exported.hostPlugin.id].lists).length };
+    }
+  });
+
+  const operations = exported.createDemoOperations();
+  assert.equal(operations[0].roomId, 'demo_board');
+  assert.equal(operations[0].actor.memberId, 'admin');
+  assert.equal(operations[0].pluginId, exported.hostPlugin.id);
+
+  const replay = await exported.createDemo({ roomId: 'demo_override' });
+  assert.equal(replay.operations[0].roomId, 'demo_override');
+  assert.equal(replay.state.version, 1);
+  assert.equal(replay.summary.lists, 1);
+  assert.equal(replay.guestView.version, 1);
+
+  const fileEvent = partyEventToNostrEvent(createSignedPartyEvent({
+    kind: 'file.upload',
+    partyId: 'demo_board',
+    identity: {
+      privateKey: '0000000000000000000000000000000000000000000000000000000000000002',
+      pubkey: 'c6047f9441ed7d6d3045406e95c07cd85a5c778e4b8cef3ca7abac09b95c709e'
+    },
+    payload: { fileName: 'demo.txt', mimeType: 'text/plain', sizeBytes: 4, sha256: '0'.repeat(64), dataBase64: 'ZGVtbw==' },
+    createdAt: 1700000000000
+  }));
+  const fileDemo = app.toMatterhornExports({
+    slug: 'dynamic-board',
+    packageName: '@mh-gg/test-dynamic-board',
+    exportPrefix: 'dynamicBoard',
+    demo: {
+      roomId: 'demo_board',
+      operations: [{ id: 'demo_file', type: 'file.upload', pluginId: 'com.matterhorn.examples.plugins.files', payload: { scopeType: 'list', scopeId: 'todo', event: fileEvent } }]
+    }
+  });
+  const fileOperation = fileDemo.createDemoOperations('demo_override')[0];
+  assert.equal(nostrEventToPartyEvent(fileOperation.payload.event).partyId, 'demo_override');
+  assert.notEqual(fileOperation.payload.event.id, fileEvent.id);
+
+  const summary = genericSummary({
+    version: 2,
+    plugins: {
+      [exported.hostPlugin.id]: {
+        lists: { todo: { id: 'todo' }, done: { id: 'done', archivedAt: 1 } },
+        cards: [{ id: 'card_1' }, { id: 'card_2', deletedAt: 1 }],
+        settings: { theme: 'dark' },
+        details: { title: 'Board' }
+      }
+    }
+  }, exported.hostPlugin.id);
+  assert.deepEqual(summary, { version: 2, lists: 1, cards: 1, title: 'Board' });
+});
+
+test('declarative comparison guards run in the schema interpreter', async () => {
+  const app = dynamicBoardApp();
+  const composition = app.toJSON();
+  const plugin = createSchemaDefinedHostPlugin(composition);
+  const runtime = new HostPluginRuntime({
+    room: { id: 'room_dynamic_board', appPack: { id: composition.app.id, version: composition.app.version, hash: manifestHash({ id: composition.app.id, version: composition.app.version }), protocolHash: composition.app.id } },
+    plugins: [plugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+  await runtime.start();
+
+  assert.equal((await runtime.handleOperation(operation(app, 'list.create', { listId: 'todo', title: 'Todo', wipLimit: 1 }, { id: 'op_1', seq: 1 }))).ok, true);
+  assert.equal((await runtime.handleOperation(operation(app, 'card.create', { cardId: 'card_1', listId: 'todo', title: 'First' }, { id: 'op_2', seq: 2 }))).ok, true);
+  const denied = await runtime.handleOperation(operation(app, 'card.create', { cardId: 'card_2', listId: 'todo', title: 'Second' }, { id: 'op_3', seq: 3 }));
+  assert.equal(denied.ok, false);
+  assert.match(denied.reason, /WIP limit/);
+});

package/test/schema-composition.test.cjs

@@ -0,0 +1,144 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const schemaModule = require("../src/index.cjs");
+const { createConfiguredSchemaApi } = require("../src/configured.cjs");
+const { registryRecords } = require("@mh-gg/base-plugins/composer/registry");
+const {
+  APP_COMPOSITION_SCHEMA_KIND,
+  actionDescriptorsForPlugin,
+  builtinMicroPluginRegistry,
+  createActionDispatchersFromComposition,
+  createAppCompositionSchema,
+  createMicroPluginSchema,
+  listMicroPluginSchemas,
+  resolveCompositionHostPluginEntries,
+  validateAppCompositionSchema,
+  loadAppCompositionSchemaFile,
+  assertValidJsonSchema
+} = createConfiguredSchemaApi(schemaModule, registryRecords());
+const { COMMENTS_PLUGIN_ID, MEDIA_ROOMS_PLUGIN_ID, PRESENCE_PLUGIN_ID } = require("@mh-gg/base-plugins");
+
+test("micro plugin schemas are JSON-only and describe operations, views, and actions", () => {
+  const comments = builtinMicroPluginRegistry.get("comments");
+  assert.equal(comments.schema.kind, "matterhorn.micro-plugin.schema");
+  assert.equal(comments.schema.id, COMMENTS_PLUGIN_ID);
+  assert.equal(typeof comments.schema.schemaHash, "string");
+  assert.equal([...comments.schema.schemas.operations["comments.add"].required, ...comments.schema.schemas.operations["comments.add"].optional].includes("scopeType"), true);
+  assert.equal(comments.schema.views.some((view) => view.name === "commentsForScope"), true);
+  assert.equal(comments.schema.actions.some((action) => action.type === "comments.add"), true);
+  assert.doesNotThrow(() => JSON.stringify(comments.schema));
+});
+
+test("micro plugin schemas reject function-bearing glue", () => {
+  assert.throws(() => createMicroPluginSchema({
+    key: "bad",
+    id: "bad.plugin",
+    version: "1.0.0",
+    stateSchema: { type: "object" },
+    operationSchemas: { "bad.run": { parse() {} } }
+  }), /JSON serializable/);
+});
+
+test("app composition schemas resolve reusable micro plugins without passing plugin JS through app code", () => {
+  const schema = createAppCompositionSchema({
+    app: { id: "app.test", version: "1.0.0", name: "Schema App" },
+    primaryPlugin: { id: "app.test.primary", version: "1.0.0" },
+    plugins: ["comments", "presence", { key: "mediaRooms", config: { defaultRooms: [{ id: "event_room", name: "Event room" }] } }, "comments"],
+    sharedScopes: {
+      directMessages: {
+        scopeType: "chat.direct",
+        scopeId: "$app.id",
+        identity: "$profile.id",
+        participants: "userIds",
+        collections: ["directThreads", "directMessages"]
+      }
+    },
+    views: [{ name: "onlineMembers", plugin: "presence", kind: "query", query: "onlineMembers" }],
+    actions: {
+      comment: { plugin: "comments", type: "comments.add", payloadDefaults: { scopeType: "task" } },
+      updatePresence: { plugin: "presence", type: "presence.update" },
+      createRoom: { plugin: "mediaRooms", type: "media.room.create" }
+    }
+  });
+
+  assert.equal(schema.kind, APP_COMPOSITION_SCHEMA_KIND);
+  assert.deepEqual(schema.plugins.map((plugin) => plugin.id), [COMMENTS_PLUGIN_ID, PRESENCE_PLUGIN_ID, MEDIA_ROOMS_PLUGIN_ID]);
+  assert.equal(validateAppCompositionSchema(schema).schemaHash, schema.schemaHash);
+  assert.deepEqual(schema.sharedScopes.directMessages.collections, ["directThreads", "directMessages"]);
+
+  const entries = resolveCompositionHostPluginEntries(schema);
+  assert.deepEqual(entries.map((entry) => entry.plugin.id), [COMMENTS_PLUGIN_ID, PRESENCE_PLUGIN_ID, MEDIA_ROOMS_PLUGIN_ID]);
+  assert.deepEqual(entries[2].config.defaultRooms[0], { id: "event_room", name: "Event room" });
+
+  const dispatched = [];
+  const actions = createActionDispatchersFromComposition(schema);
+  actions.comment({ dispatch: (op) => dispatched.push(op) }, { scopeId: "card_1", body: "Ship it" });
+  actions.createRoom({ dispatch: (op) => dispatched.push(op) }, { name: "Standup", allowsVideo: true });
+  assert.deepEqual(dispatched, [
+    { schemaAction: "comment", pluginId: COMMENTS_PLUGIN_ID, type: "comments.add", payload: { scopeType: "task", scopeId: "card_1", body: "Ship it" } },
+    { schemaAction: "createRoom", pluginId: MEDIA_ROOMS_PLUGIN_ID, type: "media.room.create", payload: { name: "Standup", allowsVideo: true } }
+  ]);
+  assert.deepEqual(actionDescriptorsForPlugin(schema, "comments").map((action) => action.name), ["comment"]);
+  assert.deepEqual(actionDescriptorsForPlugin(schema, { key: "mediaRooms" }).map((action) => action.name), ["createRoom"]);
+  assert.deepEqual(actionDescriptorsForPlugin({
+    ...schema,
+    actions: [...schema.actions, { name: "idBasedPresence", plugin: PRESENCE_PLUGIN_ID, type: "presence.update" }]
+  }, { id: PRESENCE_PLUGIN_ID }).map((action) => action.name), ["idBasedPresence"]);
+});
+
+test("raw JSON composition files are normalized and validated", () => {
+  const eventsSchema = loadAppCompositionSchemaFile(require("node:path").join(__dirname, "../../../examples/events/src/composition.json"));
+  const normalized = validateAppCompositionSchema(eventsSchema);
+  assert.equal(normalized.kind, APP_COMPOSITION_SCHEMA_KIND);
+  assert.equal(normalized.actions.find((action) => action.name === "updateEvent").plugin, "primary");
+  assert.equal(normalized.plugins.some((plugin) => plugin.id === MEDIA_ROOMS_PLUGIN_ID), true);
+  assert.equal(JSON.parse(JSON.stringify(normalized)).schemaHash, normalized.schemaHash);
+});
+
+test("first-party reusable registry exposes every micro plugin schema", () => {
+  const schemas = listMicroPluginSchemas();
+  assert.equal(schemas.length >= 12, true);
+  assert.equal(new Set(schemas.map((schema) => schema.id)).size, schemas.length);
+  assert.equal(schemas.every((schema) => schema.kind === "matterhorn.micro-plugin.schema"), true);
+});
+
+
+test("composition JSON Schema rejects arbitrary app glue", () => {
+  assert.throws(() => assertValidJsonSchema("app-composition.schema.json", {
+    kind: "matterhorn.app-composition.schema",
+    schemaVersion: 1,
+    app: { id: "bad", version: "1", name: "Bad" },
+    primaryPlugin: { id: "bad.plugin", version: "1" },
+    plugins: [],
+    views: [],
+    actions: [],
+    routes: [],
+    run() {}
+  }, { label: "composition" }), /failed: .*not allowed/);
+});
+
+test("composition shared scopes require an explicit scope id", () => {
+  assert.throws(() => assertValidJsonSchema("app-composition.schema.json", {
+    kind: "matterhorn.app-composition.schema",
+    schemaVersion: 1,
+    app: { id: "app.test", version: "1", name: "App" },
+    primaryPlugin: { id: "app.test.primary", version: "1" },
+    plugins: [],
+    sharedScopes: {
+      directMessages: {
+        scopeType: "chat.direct",
+        collections: ["directThreads", "directMessages"]
+      }
+    },
+    views: [],
+    actions: [],
+    routes: []
+  }, { label: "composition" }), /scopeId/);
+});
+
+test("composition imports let actions and models live in separate files", () => {
+  const schema = loadAppCompositionSchemaFile(require("node:path").join(__dirname, "../../../examples/events/src/composition.json"));
+  assert.equal(schema.primaryPlugin.model.kind, "matterhorn.primary-model.schema");
+  assert.equal(schema.actions.some((action) => action.name === "updateEvent"), true);
+  assert.equal(schema.schemaHash, validateAppCompositionSchema(schema).schemaHash);
+});