@human-synthesis/norns 0.0.16 → 0.1.0

package/src/kernel/trace.js

@@ -0,0 +1,277 @@
+/**
+ * Trace runner (K-18): execute Action `examples` against a sandboxed
+ * in-memory SQLite and report per-case pass/fail with step values.
+ *
+ * The traced artifact is the *generated* code, not a re-interpretation of
+ * the spec: the generated tree is compiled (Civet → JS) into a scratch
+ * dir with imports rewritten to resolvable paths, then imported and run.
+ *
+ * Conventions:
+ *   - `$name` input values are fixture handles: a row with that id is
+ *     seeded in the action's entity table; if `name` is one of the
+ *     entity's states, the row starts in that state. Owner/ref fields
+ *     are seeded to the trace user so `owner` policies pass.
+ *   - `expect` keys are checked against the entity row after the run,
+ *     falling back to the action's return value.
+ *   - external calls (`container.resolve(...)`) hit `opts.fixtures` when
+ *     provided, otherwise a recording stub — every call is reported.
+ */
+
+import { mkdirSync, readFileSync, readdirSync, rmSync, existsSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { actionEntity } from './emit-units.js';
+import { normalizeField } from './emit-schema.js';
+import { generateApp } from './generate.js';
+import { loadSpecs } from './validate.js';
+
+const require = createRequire(import.meta.url);
+
+export const TRACE_USER = { id: 'trace-user', roles: ['admin'] };
+
+/* ------------------------------------------------------------------ */
+/* Scratch tree: compile generated Civet to importable JS              */
+/* ------------------------------------------------------------------ */
+
+const BARE = {
+	'@human-synthesis/norns/server': new URL('../server/index.js', import.meta.url).href,
+	'@human-synthesis/norns/kernel': new URL('./index.js', import.meta.url).href
+};
+
+function resolveBare(spec) {
+	if (BARE[spec]) return BARE[spec];
+	return import.meta.resolve(spec);
+}
+
+function rewriteImports(js, { scratch, appRoot, compileCivet }) {
+	return js.replace(/(from\s+)(['"])([^'"]+)\2/g, (whole, from, q, spec) => {
+		if (spec.startsWith('.')) return `${from}${q}${spec.replace(/\.c$/, '.js')}${q}`;
+		if (spec.startsWith('$lib/')) {
+			const target = join(scratch, 'lib', spec.slice('$lib/'.length).replace(/\.c$/, '.js'));
+			return `${from}${q}${pathToFileURL(target).href}${q}`;
+		}
+		if (spec.startsWith('$custom/')) {
+			const rel = spec.slice('$custom/'.length);
+			const target = join(scratch, 'custom', rel.replace(/\.c$/, '.js'));
+			if (!existsSync(target)) {
+				const src = join(appRoot, 'src', rel);
+				mkdirSync(dirname(target), { recursive: true });
+				if (existsSync(src)) {
+					writeFileSync(
+						target,
+						rewriteImports(compileCivet(readFileSync(src, 'utf-8')), { scratch, appRoot, compileCivet })
+					);
+				} else {
+					writeFileSync(
+						target,
+						`export default () => { throw new Error(${JSON.stringify(`missing custom body: src/${rel}`)}) }\n`
+					);
+				}
+			}
+			return `${from}${q}${pathToFileURL(target).href}${q}`;
+		}
+		return `${from}${q}${resolveBare(spec)}${q}`;
+	});
+}
+
+/** Compile `lib/**` of the generated tree into `<scratch>/lib` as JS. */
+function buildScratch(genRoot, scratch, appRoot) {
+	const { compile } = require('@danielx/civet');
+	const compileCivet = (src) => compile(src, { sync: true, js: true });
+	const libRoot = join(genRoot, 'lib');
+	if (!existsSync(libRoot)) return;
+	for (const moduleName of readdirSync(libRoot)) {
+		const dir = join(libRoot, moduleName);
+		for (const file of readdirSync(dir)) {
+			if (!file.endsWith('.c')) continue;
+			const js = rewriteImports(compileCivet(readFileSync(join(dir, file), 'utf-8')), {
+				scratch,
+				appRoot,
+				compileCivet
+			});
+			const out = join(scratch, 'lib', moduleName, file.replace(/\.c$/, '.js'));
+			mkdirSync(dirname(out), { recursive: true });
+			writeFileSync(out, js);
+		}
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* Sandbox database                                                    */
+/* ------------------------------------------------------------------ */
+
+const sqlLit = (v) =>
+	typeof v === 'number' ? String(v) : typeof v === 'boolean' ? (v ? '1' : '0') : `'${String(v).replaceAll("'", "''")}'`;
+
+async function tableDDL(tables) {
+	const { getTableConfig } = await import('drizzle-orm/sqlite-core');
+	return tables.map((table) => {
+		const cfg = getTableConfig(table);
+		const cols = cfg.columns.map((c) => {
+			let s = `"${c.name}" ${c.getSQLType()}`;
+			if (c.primary) s += ' PRIMARY KEY';
+			else if (c.notNull) s += ' NOT NULL';
+			if (c.hasDefault && c.default !== undefined) s += ` DEFAULT ${sqlLit(c.default)}`;
+			return s;
+		});
+		return `CREATE TABLE "${cfg.name}" (${cols.join(', ')})`;
+	});
+}
+
+/** Collect every sqliteTable export across the compiled schema modules. */
+async function loadTables(scratch, specs) {
+	const tables = {};
+	for (const moduleName of Object.keys(specs.modules)) {
+		const file = join(scratch, 'lib', moduleName, 'schema.js');
+		if (!existsSync(file)) continue;
+		const mod = await import(pathToFileURL(file).href);
+		for (const [entity] of Object.entries(specs.modules[moduleName].entities ?? {})) {
+			if (mod[entity]) tables[`${moduleName}.${entity}`] = mod[entity];
+		}
+	}
+	return tables;
+}
+
+const SEED_VALUES = {
+	text: 'trace',
+	email: 'trace@example.com',
+	url: 'https://example.com',
+	file: 'trace.bin',
+	int: 0,
+	money: 0,
+	number: 0,
+	bool: false,
+	json: {}
+};
+
+function seedRow(id, entitySpec) {
+	const row = { id };
+	const owner = entitySpec.owner;
+	for (const [field, def0] of Object.entries(entitySpec.fields ?? {})) {
+		const def = normalizeField(def0);
+		if (def.optional) continue;
+		if (field === owner || def.type === 'ref') row[field] = TRACE_USER.id;
+		else if (def.type === 'date' || def.type === 'datetime') row[field] = new Date(0);
+		else row[field] = def.default ?? SEED_VALUES[def.type] ?? 'trace';
+	}
+	const states = Object.keys(entitySpec.status ?? {});
+	const name = id.startsWith('$') ? id.slice(1) : null;
+	if (name && states.includes(name)) row.status = name;
+	return row;
+}
+
+/* ------------------------------------------------------------------ */
+/* Runner                                                              */
+/* ------------------------------------------------------------------ */
+
+function recordingContainer(db, { fixtures = {}, events, calls }) {
+	return {
+		resolve(name) {
+			if (name === 'db') return db;
+			if (name === 'events') {
+				return {
+					emit: async (evt, payload) => {
+						events.push({ name: evt, payload });
+					}
+				};
+			}
+			if (name in fixtures) return fixtures[name];
+			return async (...args) => {
+				calls.push({ name, args });
+			};
+		}
+	};
+}
+
+const looseEq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * Run every Action example in the app's specs.
+ *
+ * @param {string} [dir] specs directory, defaults to `<cwd>/specs`
+ * @param {{ out?: string, fixtures?: Record<string, *>, user?: * }} [opts]
+ * @returns {Promise<{ version: string, pass: number, fail: number, cases: * }>}
+ */
+export async function traceApp(dir, opts = {}) {
+	const specs = loadSpecs(dir);
+	const appRoot = dirname(specs.dir);
+	const genRoot = opts.out ?? join(appRoot, '.norns', 'generated');
+	generateApp(dir, { out: opts.out });
+
+	const scratch = join(appRoot, '.norns', 'cache', 'trace', `${specs.version.slice(0, 8)}-${Date.now()}`);
+	const user = opts.user ?? TRACE_USER;
+	const cases = [];
+
+	try {
+		buildScratch(genRoot, scratch, appRoot);
+		const tables = await loadTables(scratch, specs);
+		const ddl = await tableDDL(Object.values(tables));
+		const { betterSqlite } = await import('../server/db.js');
+		const { sql, eq } = await import('drizzle-orm');
+
+		for (const [moduleName, moduleSpec] of Object.entries(specs.modules)) {
+			const actionsFile = join(scratch, 'lib', moduleName, 'actions.js');
+			const actionNames = Object.entries(moduleSpec.actions ?? {})
+				.filter(([, a]) => (a.examples ?? []).length > 0)
+				.map(([n]) => n)
+				.sort();
+			if (actionNames.length === 0 || !existsSync(actionsFile)) continue;
+			const mod = await import(pathToFileURL(actionsFile).href);
+
+			for (const name of actionNames) {
+				const actionSpec = moduleSpec.actions[name];
+				const address = `${moduleName}.Action.${name}`;
+				const target = actionEntity(moduleName, actionSpec, specs);
+
+				for (const [index, example] of (actionSpec.examples ?? []).entries()) {
+					const events = [];
+					const calls = [];
+					const record = { address, index, input: example.input ?? {}, expect: example.expect ?? {}, events, calls };
+					cases.push(record);
+					try {
+						const db = await betterSqlite(':memory:');
+						for (const stmt of ddl) await db.run(sql.raw(stmt));
+
+						// seed every `$handle` input value into its entity table
+						let seededId = null;
+						for (const [key, value] of Object.entries(example.input ?? {})) {
+							if (typeof value !== 'string' || !value.startsWith('$')) continue;
+							const ref = actionSpec.input?.[key];
+							const entity = typeof ref === 'string' ? ref.replace(/\?$/, '').split('.')[0] : target?.entity;
+							const entityModule = target && target.entity === entity ? target.module : moduleName;
+							const table = tables[`${entityModule}.${entity}`];
+							const entitySpec = specs.modules[entityModule]?.entities?.[entity];
+							if (!table || !entitySpec) continue;
+							await db.insert(table).values(seedRow(value, entitySpec));
+							if (ref?.endsWith('.id')) seededId = { table, value };
+						}
+
+						const container = recordingContainer(db, { fixtures: opts.fixtures, events, calls });
+						record.result = await mod[name].run({ input: example.input ?? {}, container, user });
+
+						if (seededId && target) {
+							record.row = (
+								await db.select().from(seededId.table).where(eq(seededId.table.id, seededId.value)).limit(1)
+							)[0];
+						}
+
+						record.pass = Object.entries(record.expect).every(
+							([k, want]) => looseEq(record.row?.[k], want) || looseEq(record.result?.[k], want)
+						);
+					} catch (e) {
+						record.pass = false;
+						record.error = e?.body?.message ?? e?.message ?? String(e);
+						record.status = e?.status;
+					}
+				}
+			}
+		}
+	} finally {
+		rmSync(scratch, { recursive: true, force: true });
+	}
+
+	const pass = cases.filter((c) => c.pass).length;
+	return { version: specs.version, pass, fail: cases.length - pass, cases };
+}

package/src/kernel/validate.js

@@ -0,0 +1,92 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { APP_SPEC, readSpecs } from '@human-synthesis/norns-tron/spec';
+
+import { indexUnits, listUnits } from './address.js';
+import { APP_SCHEMA, MODULE_SCHEMA, UNIT_SCHEMAS, schemaIssues } from './meta.js';
+import { refineSpecs } from './refine.js';
+
+/**
+ * @typedef {{ level: 'error' | 'warning', address: string, message: string }} Issue
+ * @typedef {{
+ *   dir: string,
+ *   app: *,
+ *   modules: Record<string, *>,
+ *   hashes: Record<string, string>,
+ *   version: string
+ * }} LoadedSpecs
+ */
+
+/**
+ * Load a `specs/` directory. Throws when the directory is missing —
+ * everything past this point can assume specs exist.
+ *
+ * @param {string} [dir] defaults to `<cwd>/specs`
+ * @returns {LoadedSpecs}
+ */
+export function loadSpecs(dir = resolve(process.cwd(), 'specs')) {
+	const abs = resolve(dir);
+	if (!existsSync(abs)) {
+		throw new Error(`norns: no specs directory at ${abs} (expected specs/*.tron)`);
+	}
+	return { dir: abs, ...readSpecs(abs) };
+}
+
+/**
+ * Validate a specs directory and return every issue found: structural
+ * checks, per-kind meta-schemas, uid uniqueness. Cross-unit refinements
+ * (K-06) register here as they land.
+ *
+ * @param {string} [dir]
+ * @returns {{ ok: boolean, version: string, modules: string[], issues: Issue[] }}
+ */
+export function validateSpecs(dir) {
+	const specs = loadSpecs(dir);
+	/** @type {Issue[]} */
+	const issues = [];
+
+	if (specs.app === null) {
+		issues.push({
+			level: 'error',
+			address: APP_SPEC,
+			message: `missing ${APP_SPEC}.tron — every app needs an app spec`
+		});
+	}
+
+	for (const [name, value] of Object.entries(specs.modules)) {
+		if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+			issues.push({
+				level: 'error',
+				address: name,
+				message: `${name}.tron must be an object, got ${Array.isArray(value) ? 'array' : typeof value}`
+			});
+			continue;
+		}
+		if (value.module !== name) {
+			issues.push({
+				level: 'error',
+				address: name,
+				message: `module field ${JSON.stringify(value.module)} does not match file name "${name}"`
+			});
+		}
+		issues.push(...schemaIssues(MODULE_SCHEMA, value, name));
+		for (const unit of listUnits(name, value)) {
+			issues.push(...schemaIssues(UNIT_SCHEMAS[unit.kind], unit.value, unit.address));
+		}
+	}
+
+	if (specs.app !== null) {
+		issues.push(...schemaIssues(APP_SCHEMA, specs.app, APP_SPEC));
+	}
+
+	issues.push(...indexUnits(specs.modules).issues);
+	issues.push(...refineSpecs(specs));
+
+	return {
+		ok: !issues.some((i) => i.level === 'error'),
+		version: specs.version,
+		modules: Object.keys(specs.modules),
+		issues
+	};
+}

package/src/live-client.js

@@ -0,0 +1,72 @@
+/**
+ * Browser side of the live-query bridge (R-11). Generated pages with
+ * `live: true` queries call `liveQueries` from an `$effect`; the server
+ * counterpart streams refresh signals from `/_norns/live` (see
+ * `src/server/live.js`).
+ *
+ * No SvelteKit import here — the caller passes `invalidate` from
+ * `$app/navigation` so this module stays framework-neutral and testable.
+ */
+
+/** SvelteKit `depends`/`invalidate` key for a query address. */
+export const dependsKey = (address) => `norns:${address}`;
+
+/**
+ * Subscribe to refresh signals and invalidate the given query addresses
+ * when they change. Returns a cleanup function (safe for `$effect`).
+ *
+ * @param {string[]} addresses query addresses this page depends on
+ * @param {(key: string) => *} invalidate `invalidate` from `$app/navigation`
+ * @param {{ path?: string, EventSource?: typeof EventSource }} [opts]
+ * @returns {() => void}
+ */
+export function liveQueries(addresses, invalidate, opts = {}) {
+	const ES = opts.EventSource ?? globalThis.EventSource;
+	if (typeof ES !== 'function') return () => {};
+
+	const wanted = new Set(addresses);
+	const source = new ES(opts.path ?? '/_norns/live');
+	source.onmessage = (e) => {
+		let payload;
+		try {
+			payload = JSON.parse(e.data);
+		} catch {
+			return;
+		}
+		for (const address of Array.isArray(payload?.queries) ? payload.queries : []) {
+			if (wanted.has(address)) invalidate(dependsKey(address));
+		}
+	};
+	return () => source.close();
+}
+
+/**
+ * Call a `transport: remote` action endpoint
+ * (`module.Action.name` → POST `/api/<module>/<name>`).
+ *
+ * @param {string} address action address
+ * @param {*} [input]
+ * @param {{ fetch?: typeof fetch }} [opts]
+ */
+export async function remoteCall(address, input, opts = {}) {
+	const parts = String(address).split('.');
+	if (parts.length !== 3 || parts[1] !== 'Action') {
+		throw new Error(`remoteCall: "${address}" is not an Action address`);
+	}
+	const f = opts.fetch ?? globalThis.fetch;
+	const res = await f(`/api/${parts[0]}/${parts[2]}`, {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: JSON.stringify(input ?? {})
+	});
+	if (!res.ok) {
+		let detail = '';
+		try {
+			detail = (await res.json())?.message ?? '';
+		} catch {
+			/* body may not be JSON */
+		}
+		throw new Error(`remoteCall ${address}: ${res.status}${detail ? ` — ${detail}` : ''}`);
+	}
+	return res.json();
+}

package/src/server/boot.js

@@ -1,8 +1,12 @@
 import { sequence } from '@sveltejs/kit/hooks';
 import { Container } from './container.js';
 import { contextHandle } from './handle/context.js';
+import { authHandle } from './handle/auth.js';
 import { errorHandle } from './handle/error.js';
 import { setSerializer } from './route.js';
+import { createEvents, registerTriggers } from './events.js';
+import { createLive } from './live.js';
+import { scheduledHandler, startCronShim } from './cron.js';
 
 /**
  * Create a fresh root container with no features registered. Useful for tests
@@ -34,16 +38,42 @@ export function createApp() {
  * Each `module.c` must default-export a function `(app) -> ...` that calls
  * `app.bind(...)` / `app.single(...)` / `app.migrations(...)`.
  *
+ * Spec-first extras:
+ * - `triggers` — generated trigger tables (`lib/<m>/triggers.c` exports),
+ *   nested arrays are flattened. Event triggers are wired into the bus;
+ *   cron ones are served by the returned `scheduled` handler.
+ * - `queue` — Cloudflare Queues producer binding; `emit` enqueues instead of
+ *   dispatching in-process.
+ * - `cronShim: true` — local minute-timer for cron triggers (`norns dev`).
+ * - `auth` — a better-auth-shaped instance (`.handler(request)` +
+ *   `.api.getSession({ headers })`); requests under `authBasePath`
+ *   (default `/api/auth`) are handed to it, every other request gets
+ *   `event.locals.user` / `event.locals.session` and scope bindings.
+ * - `room` — the `ROOM` Durable Object namespace binding (Workers prod);
+ *   live-query publishes and the `/_norns/live` stream go through it. Omit
+ *   in dev: signals ride the in-process bus.
+ * - an `events` singleton is bound automatically unless a feature bound one,
+ *   and a `live` bridge singleton likewise (actions with `refresh` lists
+ *   publish through it).
+ *
  * @param {{
  *   features?: Record<string, FeatureModule>,
  *   extraHandle?: import('@sveltejs/kit').Handle | import('@sveltejs/kit').Handle[],
  *   handleError?: import('@sveltejs/kit').HandleServerError,
- *   serializer?: import('./route.js').Serializer | null
+ *   serializer?: import('./route.js').Serializer | null,
+ *   triggers?: *[],
+ *   queue?: { send(body: *): Promise<void> | void },
+ *   cronShim?: boolean,
+ *   room?: *,
+ *   auth?: { handler(request: Request): Promise<Response> | Response, api: { getSession(input: *): Promise<*> } },
+ *   authBasePath?: string
  * }} [opts]
  * @returns {Promise<{
  *   container: Container,
  *   handle: import('@sveltejs/kit').Handle,
- *   handleError: import('@sveltejs/kit').HandleServerError
+ *   handleError: import('@sveltejs/kit').HandleServerError,
+ *   scheduled: (event: *) => Promise<void>,
+ *   stopCronShim: () => void
  * }>}
  */
 export async function boot(opts = {}) {
@@ -73,8 +103,35 @@ export async function boot(opts = {}) {
 			: [opts.extraHandle]
 		: [];
 
-	const handle = sequence(contextHandle(container), ...extras);
+	if (!container.has('events')) {
+		container.single('events', () => createEvents(opts.queue ? { queue: opts.queue } : {}));
+	}
+	if (!container.has('live')) {
+		container.single('live', () =>
+			createLive({ events: container.resolve('events'), room: opts.room })
+		);
+	}
+
+	const triggers = (opts.triggers ?? []).flat(Infinity);
+	if (triggers.length > 0) {
+		registerTriggers(container, triggers.filter((t) => !t.schedule));
+	}
+	const stopCronShim = opts.cronShim ? startCronShim(container, triggers) : () => {};
+
+	// contextHandle must come first so authHandle can bind user/session into
+	// the per-request scope it creates.
+	const handle = sequence(
+		contextHandle(container),
+		...(opts.auth ? [authHandle(opts.auth, { basePath: opts.authBasePath })] : []),
+		...extras
+	);
 	const handleError = opts.handleError ?? errorHandle();
 
-	return { container, handle, handleError };
+	return {
+		container,
+		handle,
+		handleError,
+		scheduled: scheduledHandler(container, triggers),
+		stopCronShim
+	};
 }

package/src/server/cron.js

@@ -0,0 +1,105 @@
+/**
+ * Cron triggers: Workers `scheduled` adapter + local timer shim for
+ * `norns dev`. Triggers are the generated tables (`[{ on, action, schedule? }]`).
+ */
+
+/**
+ * Match a 5-field cron expression (min hour dom mon dow) against a Date.
+ * Supports `*`, `n`, `a-b`, `*​/n`, `a-b/n`, and comma lists; dow 0/7 = Sunday.
+ *
+ * @param {string} expr
+ * @param {Date} date
+ */
+export function cronMatches(expr, date) {
+	const fields = expr.trim().split(/\s+/);
+	if (fields.length !== 5) return false;
+	const values = [
+		date.getUTCMinutes(),
+		date.getUTCHours(),
+		date.getUTCDate(),
+		date.getUTCMonth() + 1,
+		date.getUTCDay()
+	];
+	return fields.every((field, i) => fieldMatches(field, values[i], i === 4));
+}
+
+function fieldMatches(field, value, isDow) {
+	return field.split(',').some((part) => {
+		const [range, stepStr] = part.split('/');
+		const step = stepStr === undefined ? 1 : Number(stepStr);
+		if (!Number.isInteger(step) || step < 1) return false;
+		let lo;
+		let hi;
+		if (range === '*') {
+			lo = 0;
+			hi = Infinity;
+		} else if (range.includes('-')) {
+			[lo, hi] = range.split('-').map(Number);
+		} else {
+			lo = hi = Number(range);
+			if (isDow && lo === 7) lo = hi = 0;
+		}
+		if (!Number.isInteger(lo) || (hi !== Infinity && !Number.isInteger(hi))) return false;
+		return value >= lo && value <= hi && (value - (lo === 0 || range === '*' ? 0 : lo)) % step === 0;
+	});
+}
+
+/** @param {{ schedule?: string }[]} triggers */
+export function cronTriggers(triggers) {
+	return triggers.filter((t) => typeof t.schedule === 'string');
+}
+
+async function runTrigger(container, trigger) {
+	await trigger.action.run({ input: {}, container });
+}
+
+/**
+ * Cloudflare Workers `scheduled` handler. Runs every cron trigger whose
+ * schedule equals `event.cron` (how Workers routes multi-cron Workers), or —
+ * when `event.cron` is absent — whose schedule matches the event time.
+ *
+ * @param {*} container
+ * @param {{ schedule?: string, action: { run(ctx: *): * } }[]} triggers
+ */
+export function scheduledHandler(container, triggers) {
+	const crons = cronTriggers(triggers);
+	return async (event) => {
+		const due = event?.cron
+			? crons.filter((t) => t.schedule === event.cron)
+			: crons.filter((t) => cronMatches(t.schedule, new Date(event?.scheduledTime ?? Date.now())));
+		for (const t of due) await runTrigger(container, t);
+	};
+}
+
+/**
+ * Local dev shim: checks once per minute (aligned to the minute) and runs
+ * matching cron triggers. Returns a stop function.
+ *
+ * @param {*} container
+ * @param {{ schedule?: string, action: { run(ctx: *): * } }[]} triggers
+ * @param {{ onError?: (err: *, trigger: *) => void }} [opts]
+ */
+export function startCronShim(container, triggers, { onError } = {}) {
+	const crons = cronTriggers(triggers);
+	if (crons.length === 0) return () => {};
+	let timer;
+	const tick = async () => {
+		const now = new Date();
+		for (const t of crons.filter((t) => cronMatches(t.schedule, now))) {
+			try {
+				await runTrigger(container, t);
+			} catch (err) {
+				onError?.(err, t);
+			}
+		}
+	};
+	const arm = () => {
+		const msToMinute = 60_000 - (Date.now() % 60_000);
+		timer = setTimeout(async () => {
+			await tick();
+			arm();
+		}, msToMinute);
+	};
+	arm();
+	return () => clearTimeout(timer);
+}