@human-synthesis/norns 0.0.16 → 0.2.0

package/src/kernel/emit-units.js

@@ -0,0 +1,855 @@
+/**
+ * Unit templates (K-12): Query, Action, Policy, Page, Trigger.
+ *
+ * Guard-first by construction: emitted actions check the entity's write
+ * policy (and any per-action run rule) before touching the database;
+ * emitted queries AND the read policy's row rule into every select. All
+ * iteration is over sorted keys so output is independent of spec key
+ * order. Level-2 (`impl: custom`) actions and pages emit shells (K-13):
+ * the generated code keeps the guards and the contract, then delegates to
+ * the hand-written body imported via the `$custom` alias (→ `src/`).
+ */
+
+import { isAddress, parseAddress } from './address.js';
+import { VALIBOT, normalizeField } from './emit-schema.js';
+import { compileGuard } from './expr-compile.js';
+import { parseExpr } from './expr.js';
+
+const header = (moduleName) =>
+	`// GENERATED by \`norns generate\` from specs/${moduleName}.tron — do not edit.`;
+
+const pascal = (name) => name[0].toUpperCase() + name.slice(1);
+
+/** `Order` (in-module) or `catalog.Entity.Product` → { module, entity }. */
+function resolveEntityRef(moduleName, ref) {
+	if (isAddress(ref)) {
+		const parsed = parseAddress(ref);
+		return { module: parsed.module, entity: parsed.name };
+	}
+	return { module: moduleName, entity: ref };
+}
+
+function policyFor(specs, module, entity) {
+	return specs.modules[module]?.policies?.[entity];
+}
+
+function ownerFieldOf(specs, module, entity) {
+	return specs.modules[module]?.entities?.[entity]?.owner;
+}
+
+/** Relative import prefix from a file at `depth` dirs below the generated root. */
+const up = (depth) => '../'.repeat(depth);
+
+/**
+ * In specs, `status == draft` compares against the state *name* — the
+ * canonical form is unquoted (PLAN §5.2). The parser reads `draft` as a
+ * path, so rewrite single-segment paths that name a state of the target
+ * entity into literals when compared with `status`.
+ */
+function withStateLiterals(node, states) {
+	if (!node || typeof node !== 'object' || !node.op) return node;
+	if (node.op === 'and' || node.op === 'or' || node.op === 'not') {
+		return { op: node.op, args: node.args.map((a) => withStateLiterals(a, states)) };
+	}
+	const isStatus = (n) => n.path?.length === 1 && n.path[0] === 'status';
+	const asState = (n) =>
+		n.path?.length === 1 && states.has(n.path[0]) ? { lit: n.path[0] } : n;
+	let [a, b] = node.args;
+	if (isStatus(a)) b = asState(b);
+	else if (isStatus(b)) a = asState(a);
+	return { op: node.op, args: [a, b] };
+}
+
+function statesOf(specs, module, entity) {
+	return new Set(Object.keys(specs.modules[module]?.entities?.[entity]?.status ?? {}));
+}
+
+function parseUnitExpr(exprSrc, states) {
+	return withStateLiterals(parseExpr(exprSrc), states ?? new Set());
+}
+
+function whereCall(exprSrc, { entity, ownerField, states }) {
+	const ast = JSON.stringify(parseUnitExpr(exprSrc, states));
+	const owner = ownerField ? `, ownerField: ${JSON.stringify(ownerField)}` : '';
+	return `compileWhere(${ast}, { table: ${entity}, ops, user: ctx.user${owner} })`;
+}
+
+function guardExpr(exprSrc, ownerField, states) {
+	return compileGuard(parseUnitExpr(exprSrc, states), { ownerField });
+}
+
+/* ------------------------------------------------------------------ */
+/* Policies → lib/<module>/policies.c                                  */
+/* ------------------------------------------------------------------ */
+
+export function emitModulePolicies(moduleName, moduleSpec, specs) {
+	const policies = moduleSpec.policies ?? {};
+	const names = Object.keys(policies).sort();
+	if (names.length === 0) return null;
+
+	const lines = [header(moduleName), '', `import { compileWhere } from '@human-synthesis/norns/server'`, '', `import { ${names.join(', ')} } from './schema.c'`, ''];
+
+	for (const entity of names) {
+		const policy = policies[entity];
+		const ownerField = ownerFieldOf(specs, moduleName, entity);
+		const states = statesOf(specs, moduleName, entity);
+		const owner = ownerField ? `, ownerField: ${JSON.stringify(ownerField)}` : '';
+		const body = [`\tentity: ${entity}`];
+		if (ownerField) body.push(`\townerField: ${JSON.stringify(ownerField)}`);
+		for (const rule of ['read', 'write']) {
+			if (policy[rule] === undefined) continue;
+			const ast = JSON.stringify(parseUnitExpr(policy[rule], states));
+			body.push(
+				[
+					`\t${rule}: {`,
+					`\t\tcheck: (row, user) => ${guardExpr(policy[rule], ownerField, states)},`,
+					`\t\twhere: (ops, user) => compileWhere(${ast}, { table: ${entity}, ops, user${owner} })`,
+					`\t}`
+				].join('\n')
+			);
+		}
+		const runs = Object.keys(policy.run ?? {}).sort();
+		if (runs.length > 0) {
+			body.push(
+				[
+					`\trun: {`,
+					runs
+						.map((a) => `\t\t${a}: (row, user) => ${guardExpr(policy.run[a], ownerField, states)}`)
+						.join(',\n'),
+					`\t}`
+				].join('\n')
+			);
+		}
+		lines.push(`export ${entity}Policy := {`, body.join(',\n'), `}`, '');
+	}
+	return { path: `lib/${moduleName}/policies.c`, text: lines.join('\n') };
+}
+
+/* ------------------------------------------------------------------ */
+/* Queries → lib/<module>/queries.c                                    */
+/* ------------------------------------------------------------------ */
+
+const OPS_CONST = `ops := { 'and': dz.and, 'or': dz.or, 'not': dz.not, eq: dz.eq, ne: dz.ne, lt: dz.lt, lte: dz.lte, gt: dz.gt, gte: dz.gte, inArray: dz.inArray, bool: (b) => b ? dz.sql\`1 = 1\` : dz.sql\`1 = 0\` }`;
+
+const GROUP_ROWS = [
+	`groupRows := (rows, key) => {`,
+	`\tconst out = {}`,
+	`\tfor (const row of rows) (out[row[key]] ??= []).push(row)`,
+	`\treturn out`,
+	`}`
+].join('\n');
+
+export function emitModuleQueries(moduleName, moduleSpec, specs) {
+	const queries = moduleSpec.queries ?? {};
+	const names = Object.keys(queries).sort();
+	if (names.length === 0) return null;
+
+	const entityImports = new Map();
+	const policyImports = new Map();
+	const fns = [];
+	let needsGroup = false;
+	let needsWhere = false;
+
+	for (const name of names) {
+		const q = queries[name];
+		const { module, entity } = resolveEntityRef(moduleName, q.from);
+		const local = module === moduleName ? './' : `../${module}/`;
+		entityImports.set(entity, `${local}schema.c`);
+
+		const policy = policyFor(specs, module, entity);
+		const ownerField = ownerFieldOf(specs, module, entity);
+		const wheres = [];
+		if (policy?.read !== undefined) {
+			policyImports.set(`${entity}Policy`, `${local}policies.c`);
+			wheres.push(`${entity}Policy.read.where(ops, ctx.user)`);
+		}
+		if (q.filter !== undefined) {
+			needsWhere = true;
+			wheres.push(whereCall(q.filter, { entity, ownerField, states: statesOf(specs, module, entity) }));
+		}
+
+		const chain = [`db.select().from(${entity})`];
+		if (wheres.length === 1) chain.push(`.where(${wheres[0]})`);
+		else if (wheres.length > 1) chain.push(`.where(dz.and(${wheres.join(', ')}))`);
+		for (const sort of [q.sort ?? []].flat()) {
+			const desc = sort.startsWith('-');
+			chain.push(`.orderBy(dz.${desc ? 'desc' : 'asc'}(${entity}.${desc ? sort.slice(1) : sort}))`);
+		}
+		if (q.limit !== undefined) chain.push(`.limit(${q.limit})`);
+
+		const body = [
+			`export ${name} := async (ctx) => {`,
+			`\tconst db = ctx.container.resolve('db')`,
+			`\tconst rows = await ${chain.join('')}`
+		];
+		if (q.groupBy) {
+			needsGroup = true;
+			body.push(`\treturn groupRows(rows, ${JSON.stringify(q.groupBy)})`);
+		} else {
+			body.push(`\treturn rows`);
+		}
+		body.push(`}`);
+		fns.push(body.join('\n'));
+	}
+
+	const lines = [header(moduleName), '', `import * as dz from 'drizzle-orm'`];
+	if (needsWhere) lines.push(`import { compileWhere } from '@human-synthesis/norns/server'`);
+	lines.push('');
+	for (const [file, names_] of groupImports(entityImports)) {
+		lines.push(`import { ${names_.join(', ')} } from '${file}'`);
+	}
+	for (const [file, names_] of groupImports(policyImports)) {
+		lines.push(`import { ${names_.join(', ')} } from '${file}'`);
+	}
+	lines.push('', OPS_CONST, '');
+	if (needsGroup) lines.push(GROUP_ROWS, '');
+	lines.push(fns.join('\n\n'), '');
+	return { path: `lib/${moduleName}/queries.c`, text: lines.join('\n') };
+}
+
+function groupImports(map) {
+	const byFile = new Map();
+	for (const [name, file] of [...map.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+		if (!byFile.has(file)) byFile.set(file, []);
+		byFile.get(file).push(name);
+	}
+	return [...byFile.entries()].sort(([a], [b]) => a.localeCompare(b));
+}
+
+/* ------------------------------------------------------------------ */
+/* Actions → lib/<module>/actions.c                                    */
+/* ------------------------------------------------------------------ */
+
+/** The entity an action operates on: first `set` step, else its input refs. */
+export function actionEntity(moduleName, action, specs) {
+	for (const step of action.steps ?? []) {
+		if (step.set?.entity) return resolveEntityRef(moduleName, step.set.entity);
+	}
+	for (const key of Object.keys(action.input ?? {}).sort()) {
+		const ref = action.input[key];
+		if (typeof ref !== 'string') continue;
+		const entity = ref.replace(/\?$/, '').split('.')[0];
+		if (specs.modules[moduleName]?.entities?.[entity]) return { module: moduleName, entity };
+	}
+	return null;
+}
+
+function inputSchema(moduleName, action, specs) {
+	const input = action.input ?? {};
+	const keys = Object.keys(input).sort();
+	if (keys.length === 0) return null;
+	const fields = keys.map((key) => {
+		const ref = input[key];
+		let schema = 'v.unknown()';
+		if (typeof ref === 'string') {
+			const optional = ref.endsWith('?');
+			const [entity, field] = ref.replace(/\?$/, '').split('.');
+			const def =
+				field === 'id'
+					? { type: 'text' }
+					: normalizeField(specs.modules[moduleName]?.entities?.[entity]?.fields?.[field] ?? 'text');
+			schema = VALIBOT[def.type] ?? 'v.string()';
+			if (optional) schema = `v.optional(${schema})`;
+		}
+		return `${key}: ${schema}`;
+	});
+	return `v.strictObject({ ${fields.join(', ')} })`;
+}
+
+const SERVICE_CALL_RE = /^([a-z][a-z0-9_]*)\.Service\.([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/;
+const SCOPE_PATH_RE = /^(row|input|user)(\.[A-Za-z_$][A-Za-z0-9_$]*)*$/;
+
+/** `with:` values are scope paths (`input.id`) or JSON literals; no `with` passes the action input through. */
+function withArg(withMap) {
+	if (!withMap || typeof withMap !== 'object') return 'input';
+	const entries = Object.keys(withMap)
+		.sort()
+		.map((k) => {
+			const val = withMap[k];
+			const isPath = typeof val === 'string' && SCOPE_PATH_RE.test(val);
+			return `${k}: ${isPath ? val : JSON.stringify(val)}`;
+		});
+	return `{ ${entries.join(', ')} }`;
+}
+
+/** A `call` step: service operations go through the generated typed client; anything else resolves a container token. */
+function callStep(step, moduleName, serviceImports, ctx) {
+	const m = SERVICE_CALL_RE.exec(step.call);
+	if (m) {
+		const [, module, service, op] = m;
+		const local = module === moduleName ? './' : `../${module}/`;
+		serviceImports.set(service, `${local}services.c`);
+		return `\t\tawait ${service}.${op}(${withArg(step.with)}, container)`;
+	}
+	return `\t\tawait container.resolve(${JSON.stringify(step.call)})(${ctx})`;
+}
+
+const JOB_ADDR_RE = /^[a-z][a-z0-9_]*\.Job\.[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** An `enqueue` step hands the input to the `jobs` facade (R-14): Queues in prod, inline in dev. */
+function enqueueStep(step, moduleName) {
+	const addr = JOB_ADDR_RE.test(step.enqueue) ? step.enqueue : `${moduleName}.Job.${step.enqueue}`;
+	return `\t\tawait container.resolve('jobs').enqueue(${JSON.stringify(addr)}, ${withArg(step.with)}, user)`;
+}
+
+export function emitModuleActions(moduleName, moduleSpec, specs) {
+	const actions = moduleSpec.actions ?? {};
+	const names = Object.keys(actions).sort();
+	if (names.length === 0) return null;
+
+	const entityImports = new Map();
+	const policyImports = new Map();
+	const serviceImports = new Map();
+	const customImports = [];
+	const fns = [];
+
+	for (const name of names) {
+		const action = actions[name];
+		const custom = action.impl === 'custom';
+		const target = actionEntity(moduleName, action, specs);
+		const address = `${moduleName}.Action.${name}`;
+		const body = [];
+
+		if (target) {
+			const { module, entity } = target;
+			const local = module === moduleName ? './' : `../${module}/`;
+			entityImports.set(entity, `${local}schema.c`);
+			const policy = policyFor(specs, module, entity);
+			const ownerField = ownerFieldOf(specs, module, entity);
+			const idKey =
+				Object.keys(action.input ?? {})
+					.sort()
+					.find((k) => action.input[k] === `${entity}.id`) ?? 'id';
+
+			body.push(
+				`\t\tconst db = container.resolve('db')`,
+				`\t\tconst row = (await db.select().from(${entity}).where(eq(${entity}.id, input.${idKey})).limit(1))[0]`,
+				`\t\tif (!row) throw error(404, ${JSON.stringify(`${entity} not found`)})`
+			);
+			if (policy?.write !== undefined) {
+				policyImports.set(`${entity}Policy`, `${local}policies.c`);
+				body.push(`\t\tif (!${entity}Policy.write.check(row, user)) throw error(403, 'forbidden')`);
+			}
+			if (policy?.run?.[name] !== undefined) {
+				policyImports.set(`${entity}Policy`, `${local}policies.c`);
+				body.push(`\t\tif (!${entity}Policy.run.${name}(row, user)) throw error(403, 'forbidden')`);
+			}
+			if (action.requires !== undefined) {
+				body.push(
+					`\t\tif (!(${guardExpr(action.requires, ownerField, statesOf(specs, module, entity))})) throw error(409, ${JSON.stringify(`requires failed: ${action.requires}`)})`
+				);
+			}
+			if (custom) {
+				body.push(`\t\treturn ${name}Body({ row, input, container, user })`);
+			}
+			for (const step of custom ? [] : (action.steps ?? [])) {
+				if (step.set) {
+					const { entity: setEntity, ...fields } = step.set;
+					const sets = Object.keys(fields)
+						.sort()
+						.map((f) => `${f}: ${JSON.stringify(fields[f])}`);
+					// K-17: a status write must be a legal edge of the entity's
+					// machine, independent of any authored `requires` guard.
+					if ('status' in fields && statesOf(specs, module, entity).size > 0) {
+						entityImports.set(`${entity}Status`, `${local}schema.c`);
+						const to = JSON.stringify(fields.status);
+						body.push(
+							`\t\tif (!(${entity}Status[row.status] ?? []).includes(${to})) throw error(409, 'invalid transition ' + row.status + ' -> ' + ${to})`
+						);
+					}
+					body.push(
+						`\t\tawait db.update(${entity}).set({ ${sets.join(', ')} }).where(eq(${entity}.id, input.${idKey}))`
+					);
+				} else if (step.emit) {
+					body.push(
+						`\t\tawait container.resolve('events').emit(${JSON.stringify(step.emit)}, { row, input, user })`
+					);
+				} else if (step.call) {
+					body.push(callStep(step, moduleName, serviceImports, '{ row, input, user }'));
+				} else if (step.enqueue) {
+					body.push(enqueueStep(step, moduleName));
+				}
+			}
+			for (const evt of custom ? [] : (action.emits ?? [])) {
+				body.push(
+					`\t\tawait container.resolve('events').emit(${JSON.stringify(evt)}, { row, input, user })`
+				);
+			}
+		} else if (custom) {
+			body.push(`\t\treturn ${name}Body({ input, container, user })`);
+		} else {
+			// No entity target: pure flow actions (integrations, notifications)
+			// still run their emit/call steps.
+			for (const step of action.steps ?? []) {
+				if (step.emit) {
+					body.push(
+						`\t\tawait container.resolve('events').emit(${JSON.stringify(step.emit)}, { input, user })`
+					);
+				} else if (step.call) {
+					body.push(callStep(step, moduleName, serviceImports, '{ input, user }'));
+				} else if (step.enqueue) {
+					body.push(enqueueStep(step, moduleName));
+				}
+			}
+			for (const evt of action.emits ?? []) {
+				body.push(
+					`\t\tawait container.resolve('events').emit(${JSON.stringify(evt)}, { input, user })`
+				);
+			}
+		}
+		if (custom) {
+			customImports.push(`import ${name}Body from '$custom/${moduleName}/actions/${name}.c'`);
+		} else {
+			body.push(`\t\treturn { ok: true }`);
+		}
+
+		const schema = inputSchema(moduleName, action, specs);
+		const props = [`\taddress: ${JSON.stringify(address)}`];
+		if (schema) props.push(`\tinput: ${schema}`);
+		if (action.refresh) props.push(`\trefresh: ${JSON.stringify(action.refresh)}`);
+		props.push([`\trun: async ({ input, container, user }) => {`, ...body, `\t}`].join('\n'));
+		fns.push([`export ${name} := {`, props.join(',\n'), `}`].join('\n'));
+	}
+
+	const lines = [header(moduleName), '', `import { error } from '@sveltejs/kit'`, `import { eq } from 'drizzle-orm'`, `import * as v from 'valibot'`, ''];
+	for (const [file, names_] of groupImports(entityImports)) {
+		lines.push(`import { ${names_.join(', ')} } from '${file}'`);
+	}
+	for (const [file, names_] of groupImports(policyImports)) {
+		lines.push(`import { ${names_.join(', ')} } from '${file}'`);
+	}
+	for (const [file, names_] of groupImports(serviceImports)) {
+		lines.push(`import { ${names_.join(', ')} } from '${file}'`);
+	}
+	lines.push(...customImports);
+	lines.push('', fns.join('\n\n'), '');
+	return { path: `lib/${moduleName}/actions.c`, text: lines.join('\n') };
+}
+
+/* ------------------------------------------------------------------ */
+/* Services → lib/<module>/services.c                                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Service manifests (D15) become typed clients. Credentials resolve at call
+ * time from the env the container carries — never from the spec. `services`
+ * maps unit addresses to clients so boot can container-register them (R-14).
+ */
+export function emitModuleServices(moduleName, moduleSpec) {
+	const services = moduleSpec.services ?? {};
+	const names = Object.keys(services).sort();
+	if (names.length === 0) return null;
+
+	const lines = [header(moduleName), '', `import { serviceClient } from '@human-synthesis/norns/server'`, ''];
+	const entries = [];
+	for (const name of names) {
+		const svc = services[name];
+		const operations = {};
+		for (const op of Object.keys(svc.operations ?? {}).sort()) {
+			const o = svc.operations[op];
+			operations[op] = {
+				method: o.method ?? 'POST',
+				path: o.path ?? `/${op}`,
+				...(o.input !== undefined ? { input: o.input } : {}),
+				...(o.output !== undefined ? { output: o.output } : {})
+			};
+		}
+		const def = {
+			name: `${moduleName}.Service.${name}`,
+			base: svc.base,
+			auth: svc.auth,
+			operations
+		};
+		lines.push(`export ${name} := serviceClient(${JSON.stringify(def, null, '\t')})`, '');
+		entries.push(`\t${JSON.stringify(`${moduleName}.Service.${name}`)}: ${name}`);
+	}
+	lines.push(`export services := {`, entries.join(',\n'), `}`, '');
+	return { path: `lib/${moduleName}/services.c`, text: lines.join('\n') };
+}
+
+/* ------------------------------------------------------------------ */
+/* Jobs → lib/<module>/jobs.c                                          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Jobs (K-22) become `job({...})` units carrying their retry/dlq contract;
+ * `registerJobs` (R-14) wires them to `job:<address>` bus messages with
+ * retry/backoff/DLQ semantics — Cloudflare Queues in prod, inline in dev.
+ */
+export function emitModuleJobs(moduleName, moduleSpec) {
+	const jobs = moduleSpec.jobs ?? {};
+	const names = Object.keys(jobs).sort();
+	if (names.length === 0) return null;
+
+	const serviceImports = new Map();
+	const customImports = [];
+	const fns = [];
+	const entries = [];
+
+	for (const name of names) {
+		const j = jobs[name];
+		const custom = j.impl === 'custom';
+		const address = `${moduleName}.Job.${name}`;
+		const body = [];
+		if (custom) {
+			customImports.push(`import ${name}Body from '$custom/${moduleName}/jobs/${name}.c'`);
+			body.push(`\t\treturn ${name}Body({ input, container, user })`);
+		} else {
+			for (const step of j.steps ?? []) {
+				if (step.emit) {
+					body.push(
+						`\t\tawait container.resolve('events').emit(${JSON.stringify(step.emit)}, { input, user })`
+					);
+				} else if (step.call) {
+					body.push(callStep(step, moduleName, serviceImports, '{ input, user }'));
+				} else if (step.enqueue) {
+					body.push(enqueueStep(step, moduleName));
+				}
+			}
+			for (const evt of j.emits ?? []) {
+				body.push(
+					`\t\tawait container.resolve('events').emit(${JSON.stringify(evt)}, { input, user })`
+				);
+			}
+		}
+		const props = [`\taddress: ${JSON.stringify(address)}`, `\tretry: ${JSON.stringify(j.retry)}`];
+		if (j.dlq) props.push(`\tdlq: ${JSON.stringify(j.dlq)}`);
+		if (j.concurrency) props.push(`\tconcurrency: ${j.concurrency}`);
+		props.push([`\trun: async ({ input, container, user }) => {`, ...body, `\t}`].join('\n'));
+		fns.push([`export ${name} := job({`, props.join(',\n'), `})`].join('\n'));
+		entries.push(`\t${JSON.stringify(address)}: ${name}`);
+	}
+
+	const lines = [header(moduleName), '', `import { job } from '@human-synthesis/norns/server'`, ''];
+	for (const [file, names_] of groupImports(serviceImports)) {
+		lines.push(`import { ${names_.join(', ')} } from '${file}'`);
+	}
+	lines.push(...customImports);
+	lines.push('', fns.join('\n\n'), '');
+	lines.push(`export jobs := {`, entries.join(',\n'), `}`, '');
+	return { path: `lib/${moduleName}/jobs.c`, text: lines.join('\n') };
+}
+
+/* ------------------------------------------------------------------ */
+/* Triggers → lib/<module>/triggers.c                                  */
+/* ------------------------------------------------------------------ */
+
+export function emitModuleTriggers(moduleName, moduleSpec) {
+	const triggers = moduleSpec.triggers ?? {};
+	const names = Object.keys(triggers).sort();
+	if (names.length === 0) return null;
+
+	const actionImports = new Map();
+	const entries = [];
+	for (const name of names) {
+		const t = triggers[name];
+		const spec = typeof t === 'string' ? { action: t } : t;
+		const parsed = parseAddress(spec.action);
+		const local = parsed.module === moduleName ? './' : `../${parsed.module}/`;
+		actionImports.set(parsed.name, `${local}actions.c`);
+		const props = [`on: ${JSON.stringify(name)}`, `action: ${parsed.name}`];
+		if (spec.schedule) props.push(`schedule: ${JSON.stringify(spec.schedule)}`);
+		if (spec.source) props.push(`source: ${JSON.stringify(spec.source)}`);
+		entries.push(`\t{ ${props.join(', ')} }`);
+	}
+
+	const lines = [header(moduleName), ''];
+	for (const [file, names_] of groupImports(actionImports)) {
+		lines.push(`import { ${names_.join(', ')} } from '${file}'`);
+	}
+	lines.push('', `export triggers := [`, entries.join(',\n'), `]`, '');
+	return { path: `lib/${moduleName}/triggers.c`, text: lines.join('\n') };
+}
+
+/* ------------------------------------------------------------------ */
+/* Remote actions → routes/api/<module>/<action>/+server.c             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Actions with `transport: 'remote'` also get a POST endpoint wrapping the
+ * same generated unit (schema + guards + refresh publication ride along
+ * via `remoteAction`). Client side: `remoteCall` in `norns/live-client`.
+ */
+export function emitModuleRemotes(moduleName, moduleSpec) {
+	const actions = moduleSpec.actions ?? {};
+	const names = Object.keys(actions)
+		.filter((n) => actions[n]?.transport === 'remote')
+		.sort();
+	if (names.length === 0) return null;
+
+	return names.map((name) => ({
+		path: `routes/api/${moduleName}/${name}/+server.c`,
+		text: [
+			header(moduleName),
+			'',
+			`import { remoteAction } from '@human-synthesis/norns/server'`,
+			'',
+			`import { ${name} } from '${up(4)}lib/${moduleName}/actions.c'`,
+			'',
+			`export POST := remoteAction(${name})`,
+			''
+		].join('\n')
+	}));
+}
+
+/* ------------------------------------------------------------------ */
+/* Pages → routes<route>/+page.server.c + +page.n                      */
+/* ------------------------------------------------------------------ */
+
+/** '/orders/:id' → ['orders', '[id]'] */
+function routeSegments(route) {
+	return route
+		.split('/')
+		.filter(Boolean)
+		.map((seg) => (seg.startsWith(':') ? `[${seg.slice(1)}]` : seg));
+}
+
+/** '/api/chat' from a `stream:` Endpoint address (falls back to the address). */
+function endpointRoute(specs, address) {
+	const parsed = isAddress(address) ? parseAddress(address) : null;
+	return specs?.modules?.[parsed?.module]?.endpoints?.[parsed?.name]?.route ?? address;
+}
+
+/**
+ * The tag key of a page component entry. Authors write the tag first, but
+ * TRON canonicalization sorts record keys on write, so the primary must be
+ * recovered semantically: a realtime object binding ({stream}/{room}) wins,
+ * else a Query address, else an Action address (the form target), else the
+ * first key in record order.
+ */
+export function componentKey(entry) {
+	const keys = Object.keys(entry ?? {});
+	let query = null;
+	let action = null;
+	for (const key of keys) {
+		const value = entry[key];
+		if (value && typeof value === 'object' && !Array.isArray(value)) {
+			if (typeof value.stream === 'string' || typeof value.room === 'string') return key;
+			continue;
+		}
+		if (typeof value !== 'string' || !isAddress(value)) continue;
+		const { kind } = parseAddress(value);
+		if (kind === 'Query') query ??= key;
+		else if (kind === 'Action') action ??= key;
+	}
+	return query ?? action ?? keys[0] ?? null;
+}
+
+/** Collect { queries, actions, components } bound by a page spec. */
+function pageBindings(pageSpec, specs) {
+	const queries = new Map();
+	const actions = new Map();
+	const snippets = new Map();
+	const components = [];
+	for (const entry of pageSpec.components ?? []) {
+		const keys = Object.keys(entry);
+		if (keys.length === 0) continue;
+		const first = componentKey(entry);
+		const component = { tag: pascal(first), props: [] };
+		for (const key of keys) {
+			const value = entry[key];
+			if (key === first && value && typeof value === 'object' && !Array.isArray(value)) {
+				// realtime bindings (K-27): the component connects itself via
+				// streamSource(url) / roomChannel(name) from norns/live-client
+				if (typeof value.stream === 'string') {
+					component.props.push(`streamSource=${JSON.stringify(endpointRoute(specs, value.stream))}`);
+				}
+				if (typeof value.room === 'string') {
+					component.props.push(`roomChannel=${JSON.stringify(value.room)}`);
+				}
+				continue;
+			}
+			const parsed = typeof value === 'string' && isAddress(value) ? parseAddress(value) : null;
+			if (parsed?.kind === 'Snippet') {
+				// U-07: the page wraps the custom body in a `+snippet` forwarding
+				// the declared args as props, and binds that snippet to the slot
+				const unit = specs?.modules?.[parsed.module]?.snippets?.[parsed.name];
+				snippets.set(parsed.name, { module: parsed.module, args: unit?.args ?? [] });
+				component.props.push(`${key}!="{${parsed.name}}"`);
+			} else if (parsed?.kind === 'Query') {
+				queries.set(parsed.name, parsed.module);
+				component.props.push(
+					key === first
+						? `data!="{data.${parsed.name}}"`
+						: `${key}!="{data.${parsed.name}}"`
+				);
+			} else if (parsed?.kind === 'Action') {
+				actions.set(parsed.name, parsed.module);
+				// an Action in the component slot is the form target, so it binds
+				// the conventional `action` prop rather than the slot key
+				component.props.push(`${key === first ? 'action' : key}="?/${parsed.name}"`);
+			} else if (typeof value === 'string' && key !== first) {
+				component.props.push(`${key}=${JSON.stringify(value)}`);
+			} else if ((typeof value === 'number' || typeof value === 'boolean') && key !== first) {
+				component.props.push(`${key}!="{${JSON.stringify(value)}}"`);
+			}
+		}
+		components.push(component);
+	}
+	return { queries, actions, snippets, components };
+}
+
+export function emitModulePages(moduleName, moduleSpec, specs) {
+	const pages = moduleSpec.pages ?? {};
+	const names = Object.keys(pages).sort();
+	const files = [];
+
+	for (const name of names) {
+		const spec = pages[name];
+		const segments = routeSegments(spec.route);
+		const dir = ['routes', ...segments].join('/');
+		const lib = up(segments.length + 1) + 'lib';
+		const { queries, actions, snippets, components } = pageBindings(spec, specs);
+		// Queries marked `live: true` get a depends key in the load and an
+		// EventSource subscription in the page, so refresh signals from
+		// /_norns/live re-run the load (R-11).
+		const liveAddrs = [...queries]
+			.filter(([q, m]) => specs?.modules?.[m]?.queries?.[q]?.live === true)
+			.map(([q, m]) => `${m}.Query.${q}`)
+			.sort();
+
+		const lines = [header(moduleName), '', `import { page } from '@human-synthesis/norns/server'`, ''];
+		for (const [file, names_] of groupImports(
+			new Map([...queries].map(([q, m]) => [q, `${lib}/${m}/queries.c`]))
+		)) {
+			lines.push(`import { ${names_.join(', ')} } from '${file}'`);
+		}
+		for (const [file, names_] of groupImports(
+			new Map([...actions].map(([a, m]) => [a, `${lib}/${m}/actions.c`]))
+		)) {
+			lines.push(`import { ${names_.join(', ')} } from '${file}'`);
+		}
+		lines.push('');
+
+		const loads = [...queries.keys()].sort();
+		lines.push(
+			`export load := page.load({`,
+			`\thandler: async (ctx) => {`,
+			...liveAddrs.map((addr) => `\t\tctx.event.depends(${JSON.stringify(`norns:${addr}`)})`),
+			`\t\treturn { ${loads.map((q) => `${q}: await ${q}(ctx)`).join(', ')} }`,
+			`\t}`,
+			`})`
+		);
+		const acts = [...actions.keys()].sort();
+		if (acts.length > 0) {
+			lines.push('', `export actions := page.actions({`, acts.map((a) => `\t${a}: ${a}`).join(',\n'), `})`);
+		}
+		lines.push('');
+		files.push({ path: `${dir}/+page.server.c`, text: lines.join('\n') });
+
+		const liveScript = liveAddrs.length
+			? {
+					imports: [
+						`\timport { invalidate } from '$app/navigation'`,
+						`\timport { liveQueries } from '@human-synthesis/norns/live-client'`
+					],
+					effect: `\t$effect(() => liveQueries(${JSON.stringify(liveAddrs)}, invalidate))`
+				}
+			: null;
+
+		const pug = [header(moduleName), ''];
+		if (spec.impl === 'custom') {
+			// Level-2: the template body lives in src/, the generated shell
+			// stays the routing surface and passes the page contract through.
+			pug.push(
+				`Body(data!="{data}" form!="{form}")`,
+				'',
+				'<script>',
+				...(liveScript?.imports ?? []),
+				`\timport Body from '$custom/${moduleName}/pages/${name}.n'`,
+				`\t{ data, form } := $props()`,
+				...(liveScript ? [liveScript.effect] : []),
+				'</script>',
+				''
+			);
+		} else {
+			pug.push(`section.norns-page`);
+			for (const c of components) {
+				pug.push(`\t${c.tag}(${c.props.join(' ')})`);
+			}
+			for (const [sname, s] of [...snippets].sort(([a], [b]) => a.localeCompare(b))) {
+				pug.push('', `+snippet('${sname}'${s.args.length ? `, ${s.args.join(', ')}` : ''})`);
+				pug.push(
+					`\t${pascal(sname)}${s.args.length ? `(${s.args.map((a) => `${a}!="{${a}}"`).join(' ')})` : ''}`
+				);
+			}
+			const stateKeys = Object.keys(spec.state ?? {}).sort();
+			pug.push('', '<script>');
+			if (liveScript) pug.push(...liveScript.imports);
+			for (const [sname, s] of [...snippets].sort(([a], [b]) => a.localeCompare(b))) {
+				pug.push(`\timport ${pascal(sname)} from '$custom/${s.module}/snippets/${sname}.n'`);
+			}
+			pug.push(`\t{ data, form } := $props()`);
+			for (const key of stateKeys) pug.push(`\t${key} := $state(null)`);
+			if (liveScript) pug.push(liveScript.effect);
+			pug.push('</script>', '');
+		}
+		files.push({ path: `${dir}/+page.n`, text: pug.join('\n') });
+	}
+	return files;
+}
+
+/* ------------------------------------------------------------------ */
+/* Endpoints → routes<route>/+server.c (D14/K-23)                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Each Endpoint becomes a `+server.c` shell at its declared route: the
+ * `endpoint()` runtime verifies auth, validates input, runs the custom
+ * body from `src/<m>/endpoints/<name>.c`, then validates output — or, in
+ * `stream` mode, serves the body's yielded frames as typed SSE.
+ */
+export function emitModuleEndpoints(moduleName, moduleSpec) {
+	const endpoints = moduleSpec.endpoints ?? {};
+	const names = Object.keys(endpoints).sort();
+	if (names.length === 0) return null;
+
+	return names.map((name) => {
+		const spec = endpoints[name];
+		const def = { name: `${moduleName}.Endpoint.${name}`, auth: spec.auth };
+		if (spec.input !== undefined) def.input = spec.input;
+		if (spec.output !== undefined) def.output = spec.output;
+		if (spec.stream !== undefined) def.stream = spec.stream;
+		const defJson = JSON.stringify(def, null, '\t');
+		const withBody = defJson.slice(0, defJson.lastIndexOf('}')).trimEnd() + `,\n\tbody: ${name}Body\n}`;
+		return {
+			path: ['routes', ...routeSegments(spec.route), '+server.c'].join('/'),
+			text: [
+				header(moduleName),
+				'',
+				`import { endpoint } from '@human-synthesis/norns/server'`,
+				'',
+				`import ${name}Body from '$custom/${moduleName}/endpoints/${name}.c'`,
+				'',
+				`export ${spec.method ?? 'POST'} := endpoint(${withBody})`,
+				''
+			].join('\n')
+		};
+	});
+}
+
+/* ------------------------------------------------------------------ */
+
+const single = (fn) => ({ moduleName, moduleSpec, specs }) => {
+	const file = fn(moduleName, moduleSpec, specs);
+	return file ? [file] : [];
+};
+
+export const policiesEmitter = { name: 'policies', emit: single(emitModulePolicies) };
+export const queriesEmitter = { name: 'queries', emit: single(emitModuleQueries) };
+export const actionsEmitter = { name: 'actions', emit: single(emitModuleActions) };
+export const servicesEmitter = { name: 'services', emit: single(emitModuleServices) };
+export const jobsEmitter = { name: 'jobs', emit: single(emitModuleJobs) };
+export const triggersEmitter = { name: 'triggers', emit: single(emitModuleTriggers) };
+export const pagesEmitter = {
+	name: 'pages',
+	emit: ({ moduleName, moduleSpec, specs }) => emitModulePages(moduleName, moduleSpec, specs)
+};
+export const remotesEmitter = {
+	name: 'remotes',
+	emit: ({ moduleName, moduleSpec }) => emitModuleRemotes(moduleName, moduleSpec) ?? []
+};
+export const endpointsEmitter = {
+	name: 'endpoints',
+	emit: ({ moduleName, moduleSpec }) => emitModuleEndpoints(moduleName, moduleSpec) ?? []
+};