@human-synthesis/norns 0.0.16 → 0.1.0

package/bin/norns.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { watch, realpathSync, readFileSync, lstatSync, readdirSync, rmSync } from 'node:fs';
+import { watch, realpathSync, readFileSync, lstatSync, readdirSync, rmSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import {
@@ -100,7 +100,31 @@ function findViteBin(root) {
 	return join(dirname(pkgPath), binEntry);
 }
 
-function devCommand(passthrough) {
+/**
+ * Spec-first regeneration hook. Returns null when the app has no `specs/`
+ * dir; otherwise a closure that (re)generates `.norns/generated/` and
+ * reports refusals without throwing.
+ */
+async function makeSpecRegen(cwd) {
+	if (!existsSync(join(cwd, 'specs'))) return null;
+	const { generateApp } = await import('../src/kernel/index.js');
+	return () => {
+		try {
+			const result = generateApp(join(cwd, 'specs'));
+			if (result.written.length > 0) {
+				console.log(
+					`[norns] generated ${result.written.length} file(s) (spec ${result.version.slice(0, 12)})`
+				);
+			}
+			return true;
+		} catch (err) {
+			console.error(`[norns] generate refused:\n${err.message}`);
+			return false;
+		}
+	};
+}
+
+async function devCommand(passthrough) {
 	const cwd = process.cwd();
 	const cleaned = cleanShadowedFrameworkPkgs(cwd);
 	if (cleaned.length > 0) {
@@ -109,6 +133,25 @@ function devCommand(passthrough) {
 				`— the workspace symlinks at the parent will be used instead.`
 		);
 	}
+
+	const regen = await makeSpecRegen(cwd);
+	if (regen) {
+		regen();
+		const specsDir = join(cwd, 'specs');
+		let specDebounce = null;
+		try {
+			watch(specsDir, { recursive: true }, () => {
+				clearTimeout(specDebounce);
+				// Vite HMR picks up the rewritten files in .norns/generated/ itself;
+				// a failed regenerate keeps serving the last good tree.
+				specDebounce = setTimeout(() => regen(), 100);
+			});
+			console.log(`[norns] watching specs: ${specsDir}`);
+		} catch (err) {
+			console.warn(`[norns] could not watch ${specsDir}: ${err.message}`);
+		}
+	}
+
 	const viteBin = findViteBin(cwd);
 	const watchSrcs = resolveWorkspaceFrameworkSrcs(cwd);
 
@@ -177,8 +220,14 @@ function devCommand(passthrough) {
 	spawnVite();
 }
 
-function passthroughCommand(name, passthrough) {
+async function passthroughCommand(name, passthrough) {
 	const cwd = process.cwd();
+
+	if (name === 'build') {
+		const regen = await makeSpecRegen(cwd);
+		if (regen && !regen()) process.exit(1);
+	}
+
 	const cleaned = cleanShadowedFrameworkPkgs(cwd);
 	if (cleaned.length > 0) {
 		console.log(
@@ -205,6 +254,8 @@ function migrateCommand(rest) {
 	}
 	try {
 		switch (sub) {
+			case 'gen':
+				return runMigrateGen(rest.slice(1));
 			case 'status':
 				return runMigrateStatus(cwd);
 			case 'up':
@@ -216,7 +267,7 @@ function migrateCommand(rest) {
 			}
 			default:
 				console.error(`norns migrate: unknown subcommand "${sub}"`);
-				console.error('Usage: norns migrate <status|up|create <feature>/<name>>');
+				console.error('Usage: norns migrate <gen|status|up|create <feature>/<name>>');
 				process.exit(1);
 		}
 	} catch (err) {
@@ -273,6 +324,82 @@ function openTargetDb(cwd) {
 	return openSqliteDb(cwd, target.path);
 }
 
+async function validateCommand(rest) {
+	try {
+		const { validateSpecs } = await import('../src/kernel/index.js');
+		const result = validateSpecs(rest[0]);
+		for (const issue of result.issues) {
+			console.log(`[${issue.level}] ${issue.address}: ${issue.message}`);
+		}
+		if (result.ok) {
+			console.log(
+				`spec ok — ${result.modules.length} module(s), version ${result.version.slice(0, 12)}`
+			);
+		} else {
+			process.exit(1);
+		}
+	} catch (err) {
+		console.error(err.message);
+		process.exit(1);
+	}
+}
+
+async function runMigrateGen(rest) {
+	try {
+		const { migrateApp } = await import('../src/kernel/index.js');
+		const force = rest.includes('--force');
+		const dir = rest.find((a) => !a.startsWith('--'));
+		const result = await migrateApp(dir, { force });
+		const modules = Object.keys(result.created);
+		if (modules.length === 0) {
+			console.log('migrations up to date — no schema changes');
+			return;
+		}
+		for (const m of modules) {
+			for (const f of result.created[m]) console.log(`created migrations/${m}/${f}`);
+		}
+	} catch (err) {
+		console.error(err.message);
+		process.exit(1);
+	}
+}
+
+async function generateCommand(rest) {
+	try {
+		const { generateApp } = await import('../src/kernel/index.js');
+		const result = generateApp(rest[0]);
+		console.log(`generated ${result.written.length} file(s) at spec version ${result.version}`);
+	} catch (err) {
+		console.error(err.message);
+		process.exit(1);
+	}
+}
+
+async function traceCommand(rest) {
+	try {
+		const { traceApp } = await import('../src/kernel/index.js');
+		const report = await traceApp(rest[0]);
+		for (const c of report.cases) {
+			const mark = c.pass ? '✓' : '✗';
+			console.log(`${mark} ${c.address} #${c.index}`);
+			if (!c.pass) {
+				if (c.error) console.log(`    error: ${c.error}${c.status ? ` (${c.status})` : ''}`);
+				console.log(`    input:  ${JSON.stringify(c.input)}`);
+				console.log(`    expect: ${JSON.stringify(c.expect)}`);
+				if (c.row) console.log(`    row:    ${JSON.stringify(c.row)}`);
+				if (c.result !== undefined) console.log(`    result: ${JSON.stringify(c.result)}`);
+			}
+			for (const e of c.events) console.log(`    emit ${e.name}`);
+			for (const call of c.calls) console.log(`    call ${call.name}`);
+		}
+		console.log(`${report.pass} pass, ${report.fail} fail (spec ${report.version.slice(0, 12)})`);
+		process.exit(report.fail > 0 ? 1 : 0);
+	} catch (err) {
+		console.error(err.message);
+		process.exit(1);
+	}
+}
+
 function lintCommand() {
 	const findings = nornsLint(process.cwd());
 	const { errors } = printFindings(findings);
@@ -312,6 +439,15 @@ switch (cmd) {
 	case 'lint':
 		lintCommand();
 		break;
+	case 'validate':
+		validateCommand(rest);
+		break;
+	case 'generate':
+		generateCommand(rest);
+		break;
+	case 'trace':
+		traceCommand(rest);
+		break;
 	case 'diag':
 		diagCommand(rest);
 		break;
@@ -320,12 +456,16 @@ switch (cmd) {
 		console.log(`norns <command>
 
 Commands:
-  dev                                start vite dev with framework-source watching (default)
-  build                              run vite build
+  dev                                start vite dev; watches specs/ → regenerate (spec-first) and framework src (default)
+  build                              generate from specs/ (spec-first), then run vite build
   preview                            run vite preview
+  migrate gen [dir] [--force]        diff specs against migrations/ via drizzle-kit (additive-only)
   migrate status                     list applied + pending migrations
   migrate up                         apply pending migrations
   migrate create <feature>/<name>    scaffold a new SQL migration
+  validate [dir]                     validate specs/*.tron (default dir: ./specs)
+  generate [dir]                     validate specs and generate code into .norns/generated/
+  trace [dir]                        run Action examples against a sandboxed in-memory SQLite
   lint                               scan .c/.civet/.n + vite.config for known AI pitfalls
   diag <file>                        print the compiled JS for a .c/.civet/.n file
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@human-synthesis/norns",
-  "version": "0.0.16",
+  "version": "0.1.0",
   "description": "Norns — SvelteKit with Civet, Pug, and the .n / .civet / .c file extensions",
   "license": "MIT",
   "author": "Daniel Teodoroiu (https://humansynthesis.ai)",
@@ -27,6 +27,8 @@
     "./vite": "./src/vite.js",
     "./preprocess": "./src/preprocess.js",
     "./server": "./src/server/index.js",
+    "./live-client": "./src/live-client.js",
+    "./kernel": "./src/kernel/index.js",
     "./package.json": "./package.json"
   },
   "peerDependencies": {
@@ -35,8 +37,12 @@
     "vite": "^5.0.0 || ^6.0.0"
   },
   "dependencies": {
-    "@danielx/civet": "^0.11.0",
-    "@human-synthesis/norns-core": "^0.0.10"
+    "@danielx/civet": "^0.11.16",
+    "@human-synthesis/norns-core": "^0.0.10",
+    "@human-synthesis/norns-tron": "^0.1.0",
+    "drizzle-kit": "0.31.10",
+    "drizzle-orm": "0.45.2",
+    "valibot": "^1.4.0"
   },
   "engines": {
     "node": ">=18"

package/src/auto-import.js

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 
 // `match`: optional regex tested against the filename. When set, the helper
@@ -658,7 +658,10 @@ function renderImports(entries) {
  *   glob). Default `['.c', '.civet', '.js']` — `.ts` excluded because
  *   regex-scanned `.ts` can't reliably distinguish value vs type-only exports.
  * @param {string} [options.libRoot]   Default `'src/lib'`.
- * @param {string} [options.libAlias]  Default `'$lib'`.
+ * @param {string} [options.libAlias]  Default `'$lib'` — except in spec-first
+ *   projects (a `specs/` dir at the root), where `nornsConfig` points `$lib`
+ *   at `.norns/generated/lib`, so hand-written components under `src/lib`
+ *   default to the `$custom/lib` alias (`$custom` → `src`) instead.
  * @param {string} [options.root]      Default `process.cwd()`.
  * @param {(msg: string) => void} [options.log]
  *   Channel for conflict warnings. Default `console.warn`. Tests pass a
@@ -672,7 +675,8 @@ export function nornsAutoImport(options = {}) {
 	const componentExts = options.componentExtensions ?? DEFAULT_COMPONENT_EXTS;
 	const exportExts = options.exportExtensions ?? DEFAULT_EXPORT_EXTS;
 	const libRoot = options.libRoot ?? DEFAULT_LIB_ROOT;
-	const libAlias = options.libAlias ?? DEFAULT_LIB_ALIAS;
+	const specFirst = existsSync(join(root, 'specs'));
+	const libAlias = options.libAlias ?? (specFirst ? '$custom/lib' : DEFAULT_LIB_ALIAS);
 	const componentSpecs = options.components ?? null;
 	const log = options.log ?? console.warn;
 

package/src/config.js

@@ -15,6 +15,13 @@ import { nornsPreprocess } from '@human-synthesis/norns-core/preprocess';
  *   path is the non-invasive way to make `.c`/`.civet` hooks discoverable.
  *   Same for the client and universal counterparts.
  * - `preprocess: nornsPreprocess()`         — Pug + Civet
+ * - `kit.alias.$custom` → `src` — generated Level-2 shells import their
+ *   hand-written bodies through this alias
+ * - Spec-first mode: when a `specs/` dir exists, `kit.files.routes` and
+ *   `kit.files.lib` point into `.norns/generated/` (the emitted tree owns the
+ *   app; `src/` holds custom bodies only), and hook detection also searches
+ *   the generated tree (`src/` wins — a hand-written hook is a deliberate
+ *   override).
  *
  * Spread your own overrides at the call site to extend or replace defaults.
  *
@@ -33,11 +40,16 @@ export function nornsConfig(overrides = {}) {
 	const userFiles = kitOverrides.files ?? {};
 	const userHooks = userFiles.hooks ?? {};
 
+	const specFirst = existsSync(join(cwd, 'specs'));
+	const gen = join('.norns', 'generated');
+	const hookDirs = specFirst ? ['src', gen] : ['src'];
+	const candidates = (name) => hookDirs.flatMap((d) => [join(d, `${name}.c`), join(d, `${name}.civet`)]);
+
 	const hooks = {
 		...userHooks,
-		server: userHooks.server ?? findHook(cwd, ['src/hooks.server.c', 'src/hooks.server.civet']),
-		client: userHooks.client ?? findHook(cwd, ['src/hooks.client.c', 'src/hooks.client.civet']),
-		universal: userHooks.universal ?? findHook(cwd, ['src/hooks.c', 'src/hooks.civet'])
+		server: userHooks.server ?? findHook(cwd, candidates('hooks.server')),
+		client: userHooks.client ?? findHook(cwd, candidates('hooks.client')),
+		universal: userHooks.universal ?? findHook(cwd, candidates('hooks'))
 	};
 	// Drop keys whose value is undefined so SvelteKit applies its defaults
 	for (const k of /** @type {const} */ (['server', 'client', 'universal'])) {
@@ -52,7 +64,9 @@ export function nornsConfig(overrides = {}) {
 		kit: {
 			moduleExtensions: ['.js', '.ts', '.c', '.civet'],
 			...kitRest,
+			alias: { $custom: 'src', ...kitRest.alias },
 			files: {
+				...(specFirst && { routes: join(gen, 'routes'), lib: join(gen, 'lib') }),
 				...userFiles,
 				hooks
 			}

package/src/kernel/absorb.js

@@ -0,0 +1,279 @@
+/**
+ * Absorb — propose replacing custom bodies with spec (K-19, PLAN §268).
+ *
+ * `absorbUnit` statically analyses a Level-2 (`impl: custom`) action body
+ * and, when every statement is expressible in the vetted step vocabulary
+ * (`set` with literal fields, `emit`), returns spec ops that `spec.apply`
+ * can run to make the unit generated again. The analyser is deliberately
+ * conservative: any statement, import, or expression it cannot prove
+ * equivalent makes the unit non-absorbable with a reason — absorb never
+ * guesses. Custom ratio per module is the companion health metric,
+ * surfaced past ~25% (PLAN: remedied by absorb suggestions, never refusal).
+ */
+
+import { listUnits, parseAddress } from './address.js';
+import { actionEntity } from './emit-units.js';
+
+export const CUSTOM_RATIO_THRESHOLD = 0.25;
+
+/** Every `impl: custom` unit across the app, as address records. */
+export function customUnits(specs) {
+	const units = [];
+	for (const [moduleName, moduleSpec] of Object.entries(specs.modules ?? {})) {
+		for (const unit of listUnits(moduleName, moduleSpec)) {
+			if (unit.value?.impl === 'custom') units.push(unit);
+		}
+	}
+	return units;
+}
+
+/** Per-module custom-body health: { modules: { m: { custom, total, ratio, surfaced } }, app }. */
+export function customRatio(specs, { threshold = CUSTOM_RATIO_THRESHOLD } = {}) {
+	const modules = {};
+	let custom = 0;
+	let total = 0;
+	for (const [moduleName, moduleSpec] of Object.entries(specs.modules ?? {})) {
+		const units = listUnits(moduleName, moduleSpec);
+		const own = units.filter((u) => u.value?.impl === 'custom').length;
+		const ratio = units.length === 0 ? 0 : own / units.length;
+		modules[moduleName] = { custom: own, total: units.length, ratio, surfaced: ratio > threshold };
+		custom += own;
+		total += units.length;
+	}
+	const ratio = total === 0 ? 0 : custom / total;
+	return { modules, app: { custom, total, ratio, surfaced: ratio > threshold } };
+}
+
+/** Where a custom body lives, relative to the project root. */
+export function customBodyPath(address) {
+	const { module, kind, name } = parseAddress(address);
+	if (kind === 'Action') return `src/${module}/actions/${name}.c`;
+	if (kind === 'Page') return `src/${module}/pages/${name}.n`;
+	return null;
+}
+
+function stripComments(source) {
+	return source
+		.replace(/\/\*[\s\S]*?\*\//g, ' ')
+		.replace(/(^|\s)\/\/.*$/gm, '$1');
+}
+
+/** Merge lines into statements by bracket balance. Strings that unbalance
+ * brackets just make the statement unrecognisable — a safe failure. */
+function splitStatements(text) {
+	const out = [];
+	let buf = '';
+	let depth = 0;
+	for (const raw of text.split('\n')) {
+		const line = raw.trim();
+		if (line === '') continue;
+		buf = buf === '' ? line : `${buf} ${line}`;
+		for (const ch of line) {
+			if (ch === '(' || ch === '[' || ch === '{') depth += 1;
+			else if (ch === ')' || ch === ']' || ch === '}') depth -= 1;
+		}
+		if (depth <= 0) {
+			out.push(buf);
+			buf = '';
+			depth = 0;
+		}
+	}
+	if (buf !== '') out.push(buf);
+	return out;
+}
+
+function splitTopCommas(text) {
+	const parts = [];
+	let depth = 0;
+	let buf = '';
+	for (const ch of text) {
+		if (ch === '(' || ch === '[' || ch === '{') depth += 1;
+		else if (ch === ')' || ch === ']' || ch === '}') depth -= 1;
+		if (ch === ',' && depth === 0) {
+			parts.push(buf);
+			buf = '';
+			continue;
+		}
+		buf += ch;
+	}
+	if (buf.trim() !== '') parts.push(buf);
+	return parts;
+}
+
+function parseLiteral(text) {
+	const t = text.trim().replace(/;$/, '').trim();
+	if (/^'(?:[^'\\]|\\.)*'$/.test(t)) return { ok: true, value: t.slice(1, -1).replace(/\\(.)/g, '$1') };
+	try {
+		const value = JSON.parse(t);
+		const type = typeof value;
+		if (value === null || type === 'string' || type === 'number' || type === 'boolean') {
+			return { ok: true, value };
+		}
+	} catch {
+		// fall through — not a literal
+	}
+	return { ok: false };
+}
+
+/** `{ field: literal, ... }` inner text → { ok, fields } */
+function parseLiteralObject(inner) {
+	const fields = {};
+	for (const part of splitTopCommas(inner)) {
+		const m = part.match(/^\s*([A-Za-z_$][\w$]*)\s*:\s*([\s\S]+)$/);
+		if (!m) return { ok: false, at: part.trim() };
+		const lit = parseLiteral(m[2]);
+		if (!lit.ok) return { ok: false, at: part.trim() };
+		fields[m[1]] = lit.value;
+	}
+	return { ok: true, fields };
+}
+
+const DB_RESOLVE_RE = /^(?:const\s+db\s*=|db\s*:=)\s*container\s*\.\s*resolve\(\s*(['"])db\1\s*\)\s*;?$/;
+const UPDATE_RE =
+	/^await\s+db\s*\.\s*update\(\s*([A-Za-z_$][\w$]*)\s*\)\s*\.\s*set\(\s*\{([\s\S]*)\}\s*\)\s*\.\s*where\(\s*eq\(\s*([A-Za-z_$][\w$]*)\s*\.\s*id\s*,\s*input\s*\.\s*([\w$]+)\s*\)\s*\)\s*;?$/;
+const EMIT_RE =
+	/^await\s+container\s*\.\s*resolve\(\s*(['"])events\1\s*\)\s*\.\s*emit\(\s*(['"])([\w.-]+)\2\s*(?:,\s*\{\s*row\s*,\s*input\s*,\s*user\s*\}\s*)?\)\s*;?$/;
+const RETURN_RE = /^return(?:\s*(\{[\s\S]*\}))?\s*;?$/;
+const CONTRACT_RE = /export\s+default\s+(?:async\s+)?\(\s*\{([^}]*)\}\s*\)\s*(?:=>|->)\s*\{/;
+const IMPORT_RE = /^import\s*\{\s*([^}]+)\}\s*from\s*(['"])([^'"]+)\2\s*;?$/;
+
+const CONTRACT_PARAMS = new Set(['row', 'input', 'container', 'user']);
+
+/**
+ * Analyse one custom unit. Returns
+ * `{ address, absorbable: false, reason }` or
+ * `{ address, absorbable: true, ops, steps, notes }`.
+ *
+ * @param {{ app: object|null, modules: Record<string, object> }} specs
+ * @param {string} address  e.g. `orders.Action.price`
+ * @param {string|null} source  the custom body's source text
+ */
+export function absorbUnit(specs, address, source) {
+	const { module, kind, name } = parseAddress(address);
+	const no = (reason) => ({ address, absorbable: false, reason });
+
+	const unit = specs.modules?.[module]?.[kind === 'Action' ? 'actions' : kind === 'Page' ? 'pages' : '']?.[name];
+	if (!unit) return no(`no ${kind} unit at ${address}`);
+	if (unit.impl !== 'custom') return no('unit is already generated (impl is not custom)');
+	if (kind === 'Page') {
+		return no('page bodies are not analysed yet — the component vocabulary does not cover arbitrary markup');
+	}
+	if (kind !== 'Action') return no(`${kind} units cannot be custom`);
+	if (typeof source !== 'string' || source.trim() === '') {
+		return no(`custom body not found (expected ${customBodyPath(address)})`);
+	}
+
+	const target = actionEntity(module, unit, specs);
+	if (!target) return no('action has no resolvable target entity — nothing to express steps against');
+	const idKey =
+		Object.keys(unit.input ?? {})
+			.sort()
+			.find((k) => unit.input[k] === `${target.entity}.id`) ?? null;
+
+	const clean = stripComments(source);
+	const contract = clean.match(CONTRACT_RE);
+	if (!contract) return no('body is not a `export default async ({ … }) => { … }` block');
+	const params = contract[1]
+		.split(',')
+		.map((p) => p.trim())
+		.filter(Boolean);
+	for (const p of params) {
+		if (!CONTRACT_PARAMS.has(p)) return no(`contract parameter "${p}" is outside { row, input, container, user }`);
+	}
+
+	// Imports: only drizzle's `eq` and the target entity's schema are vocabulary.
+	const head = clean.slice(0, contract.index);
+	for (const stmt of splitStatements(head)) {
+		const m = stmt.match(IMPORT_RE);
+		if (!m) return no(`unrecognised statement before the body: \`${stmt}\``);
+		const names = m[1].split(',').map((n) => n.trim());
+		const from = m[3];
+		if (from === 'drizzle-orm') {
+			if (names.every((n) => n === 'eq')) continue;
+			return no(`import { ${names.join(', ')} } from 'drizzle-orm' — only \`eq\` is in vocabulary`);
+		}
+		if (/(^|\/)schema\.c$/.test(from) && names.length === 1 && names[0] === target.entity) continue;
+		return no(`import from '${from}' is outside the generated vocabulary`);
+	}
+
+	const bodyStart = contract.index + contract[0].length;
+	const bodyEnd = clean.lastIndexOf('}');
+	if (bodyEnd <= bodyStart) return no('could not find the end of the body block');
+	const body = clean.slice(bodyStart, bodyEnd);
+
+	const steps = [];
+	const notes = [];
+	const setFields = {};
+	for (const stmt of splitStatements(body)) {
+		if (DB_RESOLVE_RE.test(stmt)) continue; // the generated shell resolves db itself
+
+		const update = stmt.match(UPDATE_RE);
+		if (update) {
+			const [, entity, inner, whereEntity, whereKey] = update;
+			if (entity !== target.entity || whereEntity !== target.entity) {
+				return no(`update targets ${entity} but the action's entity is ${target.entity}`);
+			}
+			if (idKey === null || whereKey !== idKey) {
+				return no(`where clause uses input.${whereKey}, not the action's ${target.entity}.id input`);
+			}
+			const parsed = parseLiteralObject(inner);
+			if (!parsed.ok) {
+				return no(`set field \`${parsed.at}\` is not a literal — the step vocabulary only takes literal values`);
+			}
+			Object.assign(setFields, parsed.fields);
+			steps.push({ set: { entity: target.entity, ...parsed.fields } });
+			if ('status' in parsed.fields) {
+				notes.push('the generated shell adds the machine-edge guard for status writes (K-17)');
+			}
+			continue;
+		}
+
+		const emit = stmt.match(EMIT_RE);
+		if (emit) {
+			steps.push({ emit: emit[3] });
+			continue;
+		}
+
+		const ret = stmt.match(RETURN_RE);
+		if (ret) {
+			if (ret[1] === undefined) continue;
+			const parsed = parseLiteralObject(ret[1].slice(1, -1));
+			if (!parsed.ok) return no(`return value \`${ret[1]}\` is not a literal object`);
+			const entries = Object.entries(parsed.fields);
+			const redundant = entries.every(([k, v]) => (k === 'ok' && v === true) || setFields[k] === v);
+			if (!redundant) {
+				return no('return value carries data the generated shell would not (it returns { ok: true })');
+			}
+			if (entries.some(([k]) => k !== 'ok')) {
+				notes.push('the custom return of row fields is dropped — generated actions return { ok: true }; read fresh values through a query');
+			}
+			continue;
+		}
+
+		return no(`statement is outside the step vocabulary: \`${stmt}\``);
+	}
+
+	const base = `${module}.Action.${name}`;
+	const ops = [];
+	if (steps.length > 0) ops.push({ op: 'set', path: `${base}.steps`, value: steps });
+	ops.push({ op: 'remove', path: `${base}.impl` });
+	notes.push(`delete ${customBodyPath(address)} after applying — the generated body replaces it`);
+
+	return { address, absorbable: true, ops, steps, notes };
+}
+
+/**
+ * Scan the whole app: every custom unit gets an absorb verdict, plus the
+ * custom-ratio health metric.
+ *
+ * @param {{ app: object|null, modules: Record<string, object> }} specs
+ * @param {(relPath: string) => string|null} readSource
+ */
+export function absorbApp(specs, readSource) {
+	const candidates = customUnits(specs).map((unit) => {
+		const rel = customBodyPath(unit.address);
+		const source = rel === null ? null : readSource(rel);
+		return absorbUnit(specs, unit.address, source);
+	});
+	return { candidates, ratio: customRatio(specs) };
+}