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

package/test/schema-configured-builders.test.cjs

@@ -0,0 +1,286 @@
+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 {
+  COMMENTS_PLUGIN_ID,
+  MEDIA_ROOMS_PLUGIN_ID,
+  PRESENCE_PLUGIN_ID
+} = require("@mh-gg/base-plugins");
+
+const schema = createConfiguredSchemaApi(schemaModule, registryRecords());
+
+function boardModel() {
+  const model = schema.defineModel({
+    roles: {
+      member: { name: "Member", rank: "1", systemRole: false },
+      admin: { name: "Admin", rank: 10, color: "red", archivedAt: null }
+    },
+    state: {
+      initial: {
+        cards: {
+          seed: { id: "seed", title: "Seed", ownerId: "ada", reactions: {} }
+        },
+        lists: {},
+        participants: [],
+        settings: {},
+        activity: []
+      },
+      roomIdPath: "room.id"
+    },
+    views: {
+      cards: schema.q.collection("cards", { includeArchived: true }),
+      cardCount: schema.q.count("cards")
+    },
+    publicView: { kind: "state" },
+    capabilities: { required: ["room.state"] }
+  });
+  const { cards, lists, participants } = model.collections;
+  return model.withOperations({
+    "card.create": schema.op({
+      authorize: { roles: ["member"] },
+      payload: {
+        cardId: schema.p.string(),
+        title: schema.p.string().nullable(),
+        listId: schema.p.string().optional()
+      }
+    }, ({ ref, fx, guard }) => ({
+      guard: guard.ne(guard.path("cards[$payload.cardId]"), null, "Card already exists"),
+      effects: [
+        fx.create(cards, {
+          id: ref.payload("cardId"),
+          fields: {
+            id: ref.payload("cardId"),
+            title: ref.payload("title"),
+            ownerId: ref.actor("memberId"),
+            createdAt: ref.now()
+          },
+          activity: "created",
+          recordLabel: "card"
+        }),
+        fx.insertIntoArray(lists, { matchId: ref.payload("listId"), field: "cardIds", value: ref.payload("cardId"), at: 0 }),
+        fx.noop()
+      ]
+    })),
+    "card.update": schema.op({
+      payload: {
+        cardId: schema.p.string(),
+        title: schema.p.string().optional(),
+        archivedAt: schema.p.number().optional()
+      }
+    }, ({ ref, fx, guard }) => ({
+      guards: [
+        guard.ownerOrRole(cards, { id: ref.payload("cardId"), ownerField: "ownerId", roles: ["admin"] }),
+        guard.flagClear(cards, { id: ref.payload("cardId"), flag: "archivedAt" })
+      ],
+      effects: [
+        fx.update(cards, { id: ref.payload("cardId"), set: { title: ref.payload("title") } }),
+        fx.mark(cards, { id: ref.payload("cardId"), set: { archivedAt: ref.payload("archivedAt") } })
+      ]
+    })),
+    "reaction.toggle": schema.op({
+      payload: {
+        cardId: schema.p.string(),
+        emoji: schema.p.string()
+      }
+    }, ({ ref, fx }) => ({
+      effects: [fx.toggleReaction(cards, { id: ref.payload("cardId"), emoji: ref.payload("emoji") })]
+    })),
+    "list.removeCard": schema.op({
+      payload: {
+        listId: schema.p.string(),
+        cardId: schema.p.string()
+      }
+    }, ({ ref, fx }) => ({
+      effects: [fx.removeFromArray(lists, { matchId: ref.payload("listId"), field: "cardIds", value: ref.payload("cardId") })]
+    })),
+    "settings.merge": schema.op({
+      payload: { theme: schema.p.enum(["light", "dark"]).optional() }
+    }, {
+      effects: [schema.fx.merge({ path: "settings" })]
+    }),
+    "participant.upsert": schema.op({
+      payload: { memberId: schema.p.string(), name: schema.p.string().optional() }
+    }, ({ fx }) => ({
+      effects: [fx.upsertActor(participants, { fields: { memberId: "$actor.memberId", name: "$actor.displayName" } })]
+    }))
+  });
+}
+
+test("configured schema API builds app compositions with base plugin registry defaults", () => {
+  assert.equal(schema.getMicroPluginSchema("comments").id, COMMENTS_PLUGIN_ID);
+  assert.equal(schema.listMicroPluginSchemas().some((item) => item.id === MEDIA_ROOMS_PLUGIN_ID), true);
+
+  const model = boardModel();
+  const cardScope = schema.defineScope({
+    key: "cardDetail",
+    type: "card",
+    id: "$payload.cardId",
+    identity: "$payload.cardId",
+    collections: [model.collections.cards, "activity"]
+  });
+  const app = schema.defineApp({
+    id: "com.matterhorn.tests.configured-board",
+    name: "Configured Board",
+    version: "1.2.3",
+    namespace: "ConfiguredBoard",
+    model,
+    plugins: ["comments", "presence", { id: MEDIA_ROOMS_PLUGIN_ID, config: { defaultRooms: [{ id: "standup", name: "Standup" }] } }],
+    scopes: [cardScope, schema.defineScope({ key: "workspace", type: "workspace", id: "$app.id", collections: ["cards"] })],
+    views: {
+      cards: schema.q.collection(model.collections.cards),
+      online: { plugin: "presence", kind: "query", query: "onlineMembers" }
+    },
+    actions: {
+      commentOnCard: { plugin: "comments", type: "comments.add", payloadDefaults: { scopeType: "card" } },
+      directMessageSend: { plugin: "core", type: "dm.message", requiredRole: "member" }
+    },
+    routes: [
+      { path: "/", component: "BoardPage", requiredPlugins: ["comments", model, { id: MEDIA_ROOMS_PLUGIN_ID }] }
+    ]
+  });
+
+  const composition = app.toJSON();
+  assert.deepEqual(composition.plugins.map((plugin) => plugin.id), [COMMENTS_PLUGIN_ID, PRESENCE_PLUGIN_ID, MEDIA_ROOMS_PLUGIN_ID]);
+  assert.equal(composition.sharedScopes.cardDetail.scopeId, "$payload.cardId");
+  assert.deepEqual(composition.routes[0].requiredPlugins, ["comments", MEDIA_ROOMS_PLUGIN_ID]);
+  assert.equal(schema.validateAppCompositionSchema(composition).schemaHash, composition.schemaHash);
+  assert.equal(schema.resolveCompositionHostPluginEntries(composition)[2].config.defaultRooms[0].id, "standup");
+  assert.deepEqual(
+    composition.actions.find((action) => action.name === "directMessageSend"),
+    { name: "directMessageSend", plugin: "core", type: "dm.message", requiredRole: "member" }
+  );
+  assert.equal(composition.actions.some((action) => action.plugin === "comments" && action.type === "comments.add" && action.name !== "commentOnCard"), true);
+
+  const descriptor = composition.actions.find((action) => action.plugin === "comments" && action.type === "comments.add");
+  const dispatched = [];
+  schema.createActionDispatchersFromComposition(composition)[descriptor.name]({ dispatch: (op) => dispatched.push(op) }, {
+    scopeType: "card",
+    scopeId: "seed",
+    body: "Looks good"
+  });
+  assert.deepEqual(dispatched, [{
+    schemaAction: descriptor.name,
+    pluginId: COMMENTS_PLUGIN_ID,
+    type: "comments.add",
+    payload: { scopeType: "card", scopeId: "seed", body: "Looks good" }
+  }]);
+  schema.createActionDispatchersFromComposition(composition).commentOnCard({ dispatch: (op) => dispatched.push(op) }, {
+    scopeId: "card_1",
+    body: "Explicit alias"
+  });
+  assert.deepEqual(dispatched[1], {
+    schemaAction: "commentOnCard",
+    pluginId: COMMENTS_PLUGIN_ID,
+    type: "comments.add",
+    payload: { scopeType: "card", scopeId: "card_1", body: "Explicit alias" }
+  });
+  assert.equal(schema.pluginIdForAction({ plugin: "primary" }, composition), composition.primaryPlugin.id);
+  assert.equal(schema.pluginIdForAction({ plugin: "matterhorn.core" }, composition), "matterhorn.core");
+  assert.equal(schema.pluginIdForAction(descriptor, composition), COMMENTS_PLUGIN_ID);
+
+  const fragments = app.toJSONFragments({ modelPath: "./board-model.json", actionsPath: "./board-actions.json" });
+  assert.deepEqual(fragments.composition.$imports.map((item) => item.path), ["./board-model.json", "./board-actions.json"]);
+  const types = schema.generateAppTypeDeclaration(composition, { namespace: "ConfiguredBoard" });
+  assert.doesNotMatch(types, /ScopedRole/);
+  assert.doesNotMatch(types, /PluginState/);
+  assert.doesNotMatch(types, /comments: CommentsPluginState/);
+  assert.match(types, /export type ThreadId = string & \{ readonly __brand: "ThreadId" \};/);
+  assert.match(types, /export type ScopeType = "card" \| "channel" \| "workspace" \| \(string & \{\}\);/);
+  assert.match(types, /From the comments plugin\./);
+  assert.match(types, /Requires `member` role\./);
+  assert.match(types, /commentThreads: Record<ThreadId, CommentThread>;/);
+  assert.match(types, /comments: Record<CommentId, Comment>;/);
+  assert.match(types, /commentOnCard: \{ body: string; threadId\?: ThreadId; parentId\?: CommentId \} & Partial<ScopeRef>/);
+  assert.match(types, /directMessageSend: \{ userIds: MemberId\[\]; body: string; topicKey\?: string \}/);
+  assert.match(types, /directMessageSend: "dm\.message"/);
+  assert.doesNotMatch(types, /getDMs\(topicPattern\?: RegExp\): DirectMessageThread\[\]/);
+  assert.doesNotMatch(types, /subscribeDMs/);
+  assert.doesNotMatch(types, /sendDirectMessage\(input:/);
+  assert.doesNotMatch(types, /ActionHelpers|DispatchResult|ConnectionStatus|export interface Client/);
+  assert.doesNotMatch(types, /dispatch<K extends ActionName>/);
+  assert.doesNotMatch(types, /plugins: Plugins/);
+  assert.doesNotMatch(types, /"comments\.add":/);
+  assert.doesNotMatch(types, /MarkdownDocument|GitRepo|ApprovalRequest/);
+
+  assert.equal(typeof app.toClientHelpers, "undefined");
+});
+
+test("schema builder primitives reject malformed input and keep JSON output explicit", () => {
+  const arrayCollection = schema.collectionHandle("items", []);
+  assert.equal(arrayCollection.storage, "array");
+  assert.deepEqual(schema.fx.create("cards", { id: "$id:card", fields: { title: "New" } }).idPrefix, "card");
+  assert.deepEqual(schema.fx.update("cards", { id: "seed", fields: { title: "Done" } }).id, "seed");
+  assert.deepEqual(schema.fx.append(arrayCollection, { id: "item_1" }).path, "items");
+  assert.deepEqual(schema.guard.eq("$payload.status", schema.guard.value("done"), "Done only").left, { kind: "value.expr", expr: "$payload.status" });
+  assert.deepEqual(schema.guard.and([schema.guard.noop()], schema.guard.not(schema.guard.exists("cards.seed"))).guards[0], { kind: "noop" });
+  assert.throws(() => schema.normalizeCollection({}), /collection handle or collection name/);
+  assert.throws(() => schema.op({}, () => ({ effects: {} })), /effects must be an array/);
+  assert.throws(() => schema.op({}, () => ({ guards: {} })), /guards must be an array/);
+  assert.throws(() => schema.queryToJson("bad"), /view must be a query definition object/);
+  assert.throws(() => schema.modelToJson(null), /defineApp requires a model/);
+  assert.throws(() => schema.emitAppArtifacts({}, {}), /requires a defineApp/);
+});
+
+test("generated app types use stored create shapes and selected plugin entities", () => {
+  const model = schema.defineModel({
+    roles: { member: { name: "Member", rank: 1 } },
+    state: { initial: { items: [] } }
+  });
+  const { items } = model.collections;
+  const app = schema.defineApp({
+    id: "com.matterhorn.tests.typed-items",
+    name: "Typed Items",
+    namespace: "TypedItems",
+    model: model.withOperations({
+      "item.create": schema.op({
+        payload: {
+          name: schema.p.string(),
+          note: schema.p.string().nullable().optional()
+        }
+      }, ({ ref, fx }) => ({
+        effects: [fx.create(items, {
+          id: ref.newId("item"),
+          fields: { name: ref.payload("name"), note: ref.payload("note", null), createdAt: ref.now() }
+        })]
+      }))
+    }),
+    plugins: ["presence"]
+  });
+
+  const types = app.toTypes({ namespace: "TypedItems" });
+  assert.match(types, /export interface Item \{\n    createdAt: number;\n    id: string;\n    name: string;\n    note: null \| string;\n  \}/);
+  assert.match(types, /export interface PresenceMember/);
+  assert.doesNotMatch(types, /PluginState|ScopedRole|MarkdownDocument|GitRepo|ApprovalRequest|MediaRoom \{/);
+});
+
+test("generated app types emit ScopedRole only for scoped role entities", () => {
+  const model = schema.defineModel({ state: { initial: {} } });
+  const approvalTypes = schema.defineApp({
+    id: "com.matterhorn.tests.approval-types",
+    name: "Approval Types",
+    namespace: "ApprovalTypes",
+    model,
+    plugins: ["approvals"]
+  }).toTypes({ namespace: "ApprovalTypes" });
+
+  assert.match(approvalTypes, /export type ScopedRole = "none" \| "viewer" \| "editor" \| "moderator" \| "admin" \| "owner";/);
+  assert.match(approvalTypes, /export interface ApprovalRequest/);
+  assert.match(approvalTypes, /approvals: Record<string, ApprovalRequest>;/);
+
+  const coreAccessTypes = schema.defineApp({
+    id: "com.matterhorn.tests.core-access-types",
+    name: "Core Access Types",
+    namespace: "CoreAccessTypes",
+    model,
+    actions: {
+      grantScopeRole: { plugin: "core", type: "scope.role.set" }
+    }
+  }).toTypes({ namespace: "CoreAccessTypes" });
+
+  assert.match(coreAccessTypes, /export type ScopedRole = "none" \| "viewer" \| "editor" \| "moderator" \| "admin" \| "owner";/);
+  assert.match(coreAccessTypes, /export interface CoreScopeAccess/);
+  assert.match(coreAccessTypes, /access: CoreAccessState;/);
+  assert.doesNotMatch(coreAccessTypes, /ApprovalRequest|PluginState/);
+});

package/test/schema-imports.test.cjs

@@ -0,0 +1,66 @@
+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 { loadJsonWithImports, assertValidJsonSchema, readSchema } = require('../src/index.cjs');
+
+function tmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'matterhorn-schema-imports-'));
+}
+
+test('JSON schema files are published as draft 2020-12 contracts', () => {
+  for (const name of [
+    'app-composition.schema.json',
+    'example-app.schema.json',
+    'example-demo.schema.json',
+    'micro-plugin.schema.json'
+  ]) {
+    const schema = readSchema(name);
+    assert.equal(schema.$schema, 'https://json-schema.org/draft/2020-12/schema', `${name} should declare JSON Schema draft 2020-12`);
+    assert.equal(schema.type, 'object', `${name} should validate an object`);
+  }
+});
+
+test('schema imports merge decomposed action and model JSON into composition documents', () => {
+  const root = tmpDir();
+  fs.writeFileSync(path.join(root, 'model.json'), JSON.stringify({ kind: 'matterhorn.primary-model.schema', schemaVersion: 1, state: { initial: {} }, operations: {}, views: {} }));
+  fs.writeFileSync(path.join(root, 'actions.json'), JSON.stringify({ createThing: { plugin: 'primary', type: 'thing.create' } }));
+  fs.writeFileSync(path.join(root, 'composition.json'), JSON.stringify({
+    $schema: 'https://matterhorn.gg/schemas/app-composition.schema.json',
+    $imports: [
+      { path: './model.json', into: 'primaryPlugin.model' },
+      { path: './actions.json', into: 'actions' }
+    ],
+    kind: 'matterhorn.app-composition.schema',
+    schemaVersion: 1,
+    app: { id: 'app.import-test', version: '1.0.0', name: 'Import Test' },
+    primaryPlugin: { id: 'app.import-test.primary', version: '1.0.0' },
+    plugins: ['comments'],
+    views: [],
+    routes: []
+  }));
+
+  const resolved = loadJsonWithImports(path.join(root, 'composition.json'), { baseDir: root });
+  assert.equal(resolved.primaryPlugin.model.kind, 'matterhorn.primary-model.schema');
+  assert.equal(resolved.actions.createThing.type, 'thing.create');
+  assert.doesNotThrow(() => assertValidJsonSchema('app-composition.schema.json', resolved));
+});
+
+test('schema imports reject remote, non-json, path escape, and circular references', () => {
+  const root = tmpDir();
+  fs.writeFileSync(path.join(root, 'a.json'), JSON.stringify({ $imports: [{ path: './b.json' }] }));
+  fs.writeFileSync(path.join(root, 'b.json'), JSON.stringify({ $imports: [{ path: './a.json' }] }));
+  fs.writeFileSync(path.join(root, 'remote.json'), JSON.stringify({ $imports: [{ path: 'https://example.com/model.json' }] }));
+  fs.writeFileSync(path.join(root, 'bad-ext.json'), JSON.stringify({ $imports: [{ path: './model.js' }] }));
+  fs.writeFileSync(path.join(root, 'escape.json'), JSON.stringify({ $imports: [{ path: '../outside.json' }] }));
+  fs.writeFileSync(path.join(root, 'missing-select.json'), JSON.stringify({ $imports: [{ path: './fragment.json', select: 'missing.path' }] }));
+  fs.writeFileSync(path.join(root, 'fragment.json'), JSON.stringify({ ok: true }));
+  fs.writeFileSync(path.join(path.dirname(root), 'outside.json'), JSON.stringify({ escaped: true }));
+
+  assert.throws(() => loadJsonWithImports(path.join(root, 'a.json'), { baseDir: root }), /Circular schema import/);
+  assert.throws(() => loadJsonWithImports(path.join(root, 'remote.json'), { baseDir: root }), /must be a relative JSON file/);
+  assert.throws(() => loadJsonWithImports(path.join(root, 'bad-ext.json'), { baseDir: root }), /must point to a \.json file/);
+  assert.throws(() => loadJsonWithImports(path.join(root, 'escape.json'), { baseDir: root }), /escapes/);
+  assert.throws(() => loadJsonWithImports(path.join(root, 'missing-select.json'), { baseDir: root }), /did not contain/);
+});

package/test/schema-model-interpreter.test.cjs

@@ -0,0 +1,273 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const { manifestHash } = require('@mh-gg/base');
+const { HostPluginRuntime, createMemoryOperationLog, createMemoryRoomStore } = require('@mh-gg/host-runtime');
+const { ensureOperationIdentity } = require('@mh-gg/protocol');
+const { createSchemaDefinedHostPlugin, schemaDefinedHostPluginEntry, SCHEMA_DEFINED_PLUGIN_SOURCE } = require('../src/index.cjs');
+
+const APP_PACK = { id: 'com.matterhorn.schema-model-test', version: '1.0.0' };
+const APP_HASH = manifestHash(APP_PACK);
+const PLUGIN_ID = 'com.matterhorn.schema-model-test.plugin';
+
+function composition(overrides = {}) {
+  return {
+    kind: 'matterhorn.app-composition.schema',
+    schemaVersion: 1,
+    app: { id: APP_PACK.id, version: APP_PACK.version, name: 'Schema Model Test' },
+    primaryPlugin: {
+      id: PLUGIN_ID,
+      version: '1.0.0',
+      model: {
+        kind: 'matterhorn.primary-model.schema',
+        schemaVersion: 1,
+        state: { initial: { lists: [], cards: {}, guests: {}, details: {}, notes: [], posts: {}, activity: [] }, roomIdPath: 'roomId' },
+        operations: {
+          'list.create': {
+            authorize: { roles: ['admin'] },
+            payload: { required: { title: { type: 'string', max: 80 } }, optional: { wipLimit: { type: 'number', min: 0 } } },
+            effects: [{ kind: 'createRecord', collection: 'lists', storage: 'array', idPrefix: 'list', fields: { title: '$payload.title', wipLimit: '$payload.wipLimit', cardIds: [], createdAt: '$createdAt' }, activity: 'created list' }]
+          },
+          'card.create': {
+            authorize: { roles: ['member'] },
+            payload: { required: { listId: { type: 'string' }, title: { type: 'string' } }, optional: { body: { type: 'string', nonEmpty: false, nullable: true } } },
+            effects: [
+              { kind: 'createRecord', collection: 'cards', storage: 'map', idPrefix: 'card', fields: { listId: '$payload.listId', title: '$payload.title', body: '$payload.body', createdBy: '$actor.memberId', createdAt: '$createdAt', reactions: {}, archivedAt: null } },
+              { kind: 'insertIdIntoRecordArray', collection: 'lists', storage: 'array', idField: 'listId', arrayField: 'cardIds', value: '$id:card' }
+            ]
+          },
+          'card.move': {
+            authorize: { roles: ['member'] },
+            payload: { required: { cardId: { type: 'string' }, fromListId: { type: 'string' }, toListId: { type: 'string' } }, optional: { position: { type: 'number', min: 0 } } },
+            effects: [
+              { 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' }
+            ]
+          },
+          'card.react': {
+            authorize: { roles: ['member'] },
+            payload: { required: { cardId: { type: 'string' }, emoji: { type: 'string' } } },
+            effects: [{ kind: 'toggleReaction', collection: 'cards', storage: 'map', idField: 'cardId', emojiField: 'emoji' }]
+          },
+          'card.archive': {
+            authorize: { roles: ['admin'] },
+            payload: { required: { cardId: { type: 'string' } } },
+            effects: [{ kind: 'markRecord', collection: 'cards', storage: 'map', idField: 'cardId', fields: { archivedAt: '$createdAt' } }]
+          },
+          'guest.upsert': {
+            authorize: { roles: ['guest'] },
+            payload: { additional: true },
+            effects: [{ kind: 'upsertActorRecord', collection: 'guests', fields: { displayName: '$actor.displayName', rsvp: '$payload.rsvp', lastSeenAt: '$createdAt' } }]
+          },
+          'details.merge': {
+            authorize: { roles: ['admin'] },
+            payload: { additional: true },
+            effects: [{ kind: 'mergePath', path: 'details', fields: '$payload' }]
+          },
+          'note.add': {
+            authorize: { roles: ['member'] },
+            payload: { required: { body: { type: 'string' } } },
+            effects: [{ kind: 'appendToArray', path: 'notes', item: { id: '$operation.id', body: '$payload.body', by: '$actor.memberId', createdAt: '$createdAt' } }]
+          }
+        },
+        views: { board: { kind: 'state' }, activeCards: { kind: 'collection', collection: 'cards' }, activeCardCount: { kind: 'count', collection: 'cards' }, rsvpCounts: { kind: 'rsvpCounts' } }
+      }
+    },
+    plugins: [],
+    actions: { createList: { plugin: 'primary', type: 'list.create' } },
+    ...overrides
+  };
+}
+
+function op(type, payload = {}, overrides = {}) {
+  const operation = {
+    clientOperationId: overrides.id || `op_${type.replace(/[^a-z0-9]+/gi, '_')}`,
+    roomId: 'room_schema',
+    appPackId: APP_PACK.id,
+    appPackHash: APP_HASH,
+    pluginId: PLUGIN_ID,
+    type,
+    actor: overrides.actor || { memberId: 'admin', deviceId: 'dev_admin', role: 'admin', displayName: 'Ada' },
+    seq: overrides.seq || 1,
+    createdAt: overrides.createdAt || 1000,
+    payload,
+    auth: { credentialId: 'cred', signature: 'sig' }
+  };
+  return ensureOperationIdentity(operation, { now: operation.createdAt, nodeId: operation.actor?.deviceId || 'dev_admin' });
+}
+
+async function runtimeFor(schema = composition()) {
+  const plugin = createSchemaDefinedHostPlugin(schema);
+  const runtime = new HostPluginRuntime({
+    room: { id: 'room_schema', appPack: { id: APP_PACK.id, version: APP_PACK.version, hash: APP_HASH, protocolHash: schema.app?.id || APP_PACK.id } },
+    plugins: [plugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+  await runtime.start();
+  return { runtime, plugin };
+}
+
+test('schema-defined host plugin exposes deterministic descriptors without app backend JS', () => {
+  const schema = composition();
+  const plugin = createSchemaDefinedHostPlugin(schema);
+  const entry = schemaDefinedHostPluginEntry(schema, { packageName: '@mh-gg/base-plugins' });
+
+  assert.equal(plugin.schemaDefined, true);
+  assert.equal(plugin.schemaSource, SCHEMA_DEFINED_PLUGIN_SOURCE);
+  assert.equal(plugin.stateSchemaDescriptor.source, SCHEMA_DEFINED_PLUGIN_SOURCE);
+  assert.equal(plugin.operationSchemaDescriptor.operations['card.create'].required.title.type, 'string');
+  assert.equal(entry.source, SCHEMA_DEFINED_PLUGIN_SOURCE);
+  assert.equal(entry.plugin.id, PLUGIN_ID);
+});
+
+test('schema-defined model applies common reducer effects through the trusted interpreter', async () => {
+  const { runtime, plugin } = await runtimeFor();
+  await runtime.handleOperation(op('details.merge', { title: 'Schema Room' }, { id: 'op_1', seq: 1 }));
+  await runtime.handleOperation(op('list.create', { title: 'Todo' }, { id: 'op_2', seq: 2 }));
+  let state = await runtime.getState();
+  const todoId = state.plugins[PLUGIN_ID].lists[0].id;
+  await runtime.handleOperation(op('list.create', { title: 'Done' }, { id: 'op_3', seq: 3 }));
+  state = await runtime.getState();
+  const doneId = state.plugins[PLUGIN_ID].lists[1].id;
+  await runtime.handleOperation(op('card.create', { listId: todoId, title: 'Ship schema backends', body: null }, { id: 'op_4', seq: 4, actor: { memberId: 'mira', deviceId: 'dev_mira', role: 'member', displayName: 'Mira' } }));
+  state = await runtime.getState();
+  const cardId = state.plugins[PLUGIN_ID].lists[0].cardIds[0];
+  await runtime.handleOperation(op('card.react', { cardId, emoji: '🚀' }, { id: 'op_5', seq: 5, actor: { memberId: 'mira', deviceId: 'dev_mira', role: 'member', displayName: 'Mira' } }));
+  await runtime.handleOperation(op('card.move', { cardId, fromListId: todoId, toListId: doneId, position: 0 }, { id: 'op_6', seq: 6, actor: { memberId: 'mira', deviceId: 'dev_mira', role: 'member', displayName: 'Mira' } }));
+  await runtime.handleOperation(op('guest.upsert', { rsvp: 'yes' }, { id: 'op_7', seq: 7, actor: { memberId: 'guest', deviceId: 'dev_guest', role: 'guest', displayName: 'Gus' } }));
+  await runtime.handleOperation(op('note.add', { body: 'No app reducer ran here' }, { id: 'op_8', seq: 8, actor: { memberId: 'mira', deviceId: 'dev_mira', role: 'member', displayName: 'Mira' } }));
+  await runtime.handleOperation(op('card.archive', { cardId }, { id: 'op_9', seq: 9 }));
+
+  state = await runtime.getState();
+  const primary = state.plugins[PLUGIN_ID];
+  assert.equal(primary.roomId, 'room_schema');
+  assert.equal(primary.details.title, 'Schema Room');
+  assert.equal(primary.cards[cardId].listId, doneId);
+  assert.deepEqual(primary.cards[cardId].reactions['🚀'], ['mira']);
+  assert.equal(primary.guests.guest.rsvp, 'yes');
+  assert.equal(primary.notes[0].body, 'No app reducer ran here');
+  assert.equal(primary.activity.some((item) => item.message === 'created list'), true);
+
+  const activeCards = await runtime.handleQuery(plugin.id, 'activeCards', {}, { role: 'member' });
+  const activeCardCount = await runtime.handleQuery(plugin.id, 'activeCardCount', {}, { role: 'member' });
+  const rsvpCounts = await runtime.handleQuery(plugin.id, 'rsvpCounts', {}, { role: 'member' });
+  assert.deepEqual(activeCards, []);
+  assert.equal(activeCardCount, 0);
+  assert.deepEqual(rsvpCounts, { yes: 1, no: 0, maybe: 0, unset: 0 });
+});
+
+test('schema-defined model enforces owner guard rules and enum payload fallbacks', async () => {
+  const schema = composition();
+  Object.assign(schema.primaryPlugin.model.operations, {
+    'post.add': {
+      authorize: { roles: ['member'] },
+      payload: { required: { body: { type: 'string' } } },
+      effects: [{ kind: 'createRecord', collection: 'posts', storage: 'map', idPrefix: 'post', fields: { body: '$payload.body', authorId: '$actor.memberId' } }]
+    },
+    'post.delete': {
+      authorize: { roles: ['member'] },
+      payload: { required: { id: { type: 'string' } } },
+      guards: [{ kind: 'recordOwnerOrRole', collection: 'posts', storage: 'map', idField: 'id', ownerField: 'authorId', roles: ['admin'], message: 'Only owners or admins.' }],
+      effects: [{ kind: 'updateRecord', collection: 'posts', storage: 'map', idField: 'id', fields: { deletedAt: '$createdAt' } }]
+    },
+    'details.theme': {
+      authorize: { roles: ['admin'] },
+      payload: { optional: { theme: { type: 'enum', values: ['sunset', 'mint'], fallback: 'sunset' } }, additional: false },
+      effects: [{ kind: 'mergePath', path: 'details', fields: '$payload', deleteNullFields: true }]
+    }
+  });
+
+  const { runtime } = await runtimeFor(schema);
+  const member = { memberId: 'mira', deviceId: 'dev_mira', role: 'member', displayName: 'Mira' };
+  assert.equal((await runtime.handleOperation(op('post.add', { body: 'Owned' }, { id: 'guard_post', seq: 1, actor: member }))).ok, true);
+
+  let state = await runtime.getState();
+  const postId = Object.values(state.plugins[PLUGIN_ID].posts)[0].id;
+  const deniedDelete = await runtime.handleOperation(op('post.delete', { id: postId }, { id: 'guard_other_delete', seq: 2, actor: { memberId: 'omar', deviceId: 'dev_omar', role: 'member' } }));
+  assert.equal(deniedDelete.ok, false);
+  assert.match(deniedDelete.reason, /Only owners or admins/);
+  assert.equal((await runtime.handleOperation(op('post.delete', { id: postId }, { id: 'guard_admin_delete', seq: 3 }))).ok, true);
+
+  await runtime.handleOperation(op('details.theme', { theme: 'invalid' }, { id: 'guard_theme', seq: 4 }));
+  state = await runtime.getState();
+  assert.equal(state.plugins[PLUGIN_ID].details.theme, 'sunset');
+});
+
+test('schema-defined model validates payloads, roles, bad schemas, and unsupported effects', async () => {
+  const { runtime } = await runtimeFor();
+
+  const guestAdminOp = await runtime.handleOperation(op('list.create', { title: 'Nope' }, { actor: { memberId: 'g', deviceId: 'd', role: 'guest' } }));
+  assert.equal(guestAdminOp.ok, false);
+  assert.match(guestAdminOp.reason, /Operation is not allowed|requires admin|requires member/);
+
+  const badPayload = await runtime.handleOperation(op('list.create', { title: '' }, { id: 'bad_payload' }));
+  assert.equal(badPayload.ok, false);
+  assert.match(badPayload.reason, /title is required/);
+
+  const badOptionalPayload = await runtime.handleOperation(op('list.create', { title: 'Todo', wipLimit: -1 }, { id: 'bad_optional_payload' }));
+  assert.equal(badOptionalPayload.ok, false);
+  assert.match(badOptionalPayload.reason, /wipLimit must be >= 0/);
+
+  const badEffectSchema = composition();
+  badEffectSchema.primaryPlugin.model.operations['bad.effect'] = {
+    authorize: { roles: ['admin'] },
+    payload: { additional: true },
+    effects: [{ kind: 'doesNotExist' }]
+  };
+  assert.throws(() => createSchemaDefinedHostPlugin(badEffectSchema), /JSON schema validation|kind/);
+
+  assert.throws(() => createSchemaDefinedHostPlugin({ ...composition(), primaryPlugin: { id: PLUGIN_ID, version: '1.0.0', model: { state: { initial: { forbidden: BigInt(1) } } } } }), /JSON|serialize a BigInt/);
+});
+
+const { evaluate, collectionValue, getPath, sanitizeId, setPath } = require('../src/model/expressions.cjs');
+const { createPayloadParser, parseValue } = require('../src/model/payload.cjs');
+
+test('schema model primitive parsers and expression helpers cover edge cases', () => {
+  assert.equal(sanitizeId('a/b c'), 'a_b_c');
+  assert.deepEqual(setPath({ a: { b: 1 } }, 'a.c', 2), { a: { b: 1, c: 2 } });
+  assert.deepEqual(setPath(null, '', { root: true }), { root: true });
+  assert.equal(getPath({ a: { b: 2 } }, 'a.b'), 2);
+  assert.deepEqual(collectionValue({ things: [] }, 'things'), []);
+  assert.deepEqual(collectionValue({}, 'metadata'), {});
+
+  const ctx = { payload: { nested: { value: 'payload' } }, actor: { memberId: 'alice' }, operation: { id: 'op/a b', type: 'thing.create', createdAt: 123 } };
+  assert.equal(evaluate('$payload.nested.value', ctx), 'payload');
+  assert.deepEqual(evaluate('$payload', ctx), ctx.payload);
+  assert.equal(evaluate('$actor.memberId', ctx), 'alice');
+  assert.deepEqual(evaluate('$actor', ctx), ctx.actor);
+  assert.equal(evaluate('$createdAt', ctx), 123);
+  assert.equal(evaluate('$operation.id', ctx), 'op/a b');
+  assert.equal(evaluate('$operation.type', ctx), 'thing.create');
+  assert.equal(evaluate('$id:item', ctx), 'item_op_a_b');
+  assert.equal(evaluate('$const:fixed', ctx), 'fixed');
+  assert.deepEqual(evaluate(['$const:a', '$const:b'], ctx), ['a', 'b']);
+  assert.deepEqual(evaluate({ keep: { $literal: { raw: '$payload.nested.value' } }, expr: { $expr: '$payload.nested.value' }, fallback: { $expr: '$payload.nope', fallback: null }, missing: '$payload.nope' }, ctx), { keep: { raw: '$payload.nested.value' }, expr: 'payload', fallback: null });
+
+  assert.equal(parseValue(undefined, { type: 'string', default: 'fallback' }, 'name'), 'fallback');
+  assert.equal(parseValue('', { type: 'string', nullable: true }, 'name'), null);
+  assert.equal(parseValue(' hi ', { type: 'string' }, 'name'), 'hi');
+  assert.equal(parseValue(' hi ', { type: 'string', trim: false }, 'name'), ' hi ');
+  assert.equal(parseValue('abcd', { type: 'string', max: 3, truncate: true }, 'name'), 'abc');
+  assert.equal(parseValue('2', { type: 'number', min: 1, max: 3 }, 'count'), 2);
+  assert.equal(parseValue(1, { type: 'boolean' }, 'flag'), true);
+  assert.equal(parseValue('yes', { type: 'enum', values: ['yes', 'no'] }, 'choice'), 'yes');
+  assert.equal(parseValue('bad', { type: 'enum', values: ['ok'], fallback: 'ok' }, 'choice'), 'ok');
+  assert.deepEqual(parseValue(['1', '2'], { type: 'array', items: { type: 'number' } }, 'items'), [1, 2]);
+  assert.deepEqual(parseValue({ a: 1 }, { type: 'object' }, 'obj'), { a: 1 });
+  assert.deepEqual(parseValue({ media: { video: true }, access: { team: 'editor' } }, {
+    type: 'object',
+    required: { media: { type: 'object', optional: { audio: { type: 'boolean', default: true }, video: { type: 'boolean' } }, additional: false } },
+    optional: { access: { type: 'record', values: { type: 'enum', values: ['editor', 'readonly'] } } },
+    additional: false
+  }, 'settings'), { media: { audio: true, video: true }, access: { team: 'editor' } });
+  assert.throws(() => parseValue('bad', { type: 'enum', values: ['ok'] }, 'choice'), /must be one of/);
+  assert.throws(() => parseValue('x', { type: 'array' }, 'items'), /must be an array/);
+  assert.throws(() => parseValue([], { type: 'object' }, 'obj'), /must be an object/);
+  assert.throws(() => parseValue('x', { type: 'mystery' }, 'field'), /not supported/);
+
+  const parse = createPayloadParser({ required: ['title'], optional: { count: { type: 'number', default: 1 }, hidden: { type: 'string' } }, additional: false });
+  assert.deepEqual(parse({ title: 'Task', extra: 'ignored' }), { title: 'Task', count: 1 });
+  assert.throws(() => parse(null), /payload must be an object/);
+});