@nanobpm/urban 0.4.0 → 0.5.1

package/dist/runtime/core/modules/triggers.d.ts

@@ -0,0 +1,15 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import { type Route } from "../router.ts";
+export interface TriggersHandle {
+    readonly name: string;
+    routes: Route[];
+    describe(): Record<string, unknown>;
+}
+/** Evaluate a tiny correlation expression: `= body.a.b`, or a literal string. */
+export declare function evalCorrelation(expr: string | undefined, scope: {
+    body: unknown;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+}): string | undefined;
+/** Mount webhook triggers and return their routes. */
+export declare function mountTriggers(ctx: RuntimeContext, app: AppApi): TriggersHandle;

package/dist/runtime/core/modules/triggers.js

@@ -0,0 +1,119 @@
+// triggers — the inbound I/O edge (ADR 0025). Turns each `webhook` trigger in the manifest
+// into an HTTP route that verifies the request, maps the payload, and publishes the declared
+// message to the engine for correlation. HMAC verification uses Web Crypto (global in both
+// Node 18+ and Deno), so this stays runtime-agnostic.
+import { json, normalizeRoutePath } from "../router.js";
+/** Evaluate a tiny correlation expression: `= body.a.b`, or a literal string. */
+export function evalCorrelation(expr, scope) {
+    if (!expr)
+        return undefined;
+    const trimmed = expr.trim();
+    if (!trimmed.startsWith("="))
+        return trimmed; // literal
+    const pathExpr = trimmed.slice(1).trim(); // e.g. "body.taskId"
+    let cur = scope;
+    for (const seg of pathExpr.split(".")) {
+        if (cur && typeof cur === "object" && seg in cur) {
+            cur = cur[seg];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur == null ? undefined : String(cur);
+}
+async function verifyHmac(secret, body, signature) {
+    const enc = new TextEncoder();
+    const key = await globalThis.crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await globalThis.crypto.subtle.sign("HMAC", key, enc.encode(body));
+    const hex = [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+    const provided = signature.replace(/^sha256=/, "").trim().toLowerCase();
+    // Constant-time-ish compare.
+    if (provided.length !== hex.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < hex.length; i++)
+        diff |= hex.charCodeAt(i) ^ provided.charCodeAt(i);
+    return diff === 0;
+}
+/** Env var holding the secret for an `hmac:<connection>` auth ref. */
+function secretEnvName(connection) {
+    return `URBAN_TRIGGER_SECRET_${connection.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+}
+function headerRecord(req) {
+    const out = {};
+    req.headers.forEach((v, k) => (out[k.toLowerCase()] = v));
+    return out;
+}
+/** Mount webhook triggers and return their routes. */
+export function mountTriggers(ctx, app) {
+    const routes = [];
+    const mounted = [];
+    const seenDeliveries = new Set();
+    for (const trig of (ctx.manifest.triggers ?? [])) {
+        if (trig.type !== "webhook") {
+            ctx.host.log("warn", `trigger "${trig.id}": type "${trig.type}" not implemented, skipped`);
+            continue;
+        }
+        const path = normalizeRoutePath(trig.path, `/hooks/${trig.id}`);
+        mounted.push(`${trig.id}@${path}`);
+        routes.push({
+            method: "POST",
+            path,
+            source: `trigger:${trig.id}`,
+            handler: async (req) => {
+                const raw = await req.text();
+                const headers = headerRecord(req);
+                // Auth (hmac:<connection>).
+                if (trig.auth?.startsWith("hmac:")) {
+                    const conn = trig.auth.slice("hmac:".length);
+                    const secret = app.env(secretEnvName(conn));
+                    if (!secret) {
+                        app.log("error", `trigger "${trig.id}": missing secret ${secretEnvName(conn)}`);
+                        return json({ error: "server not configured for hmac" }, 500);
+                    }
+                    const sig = headers["x-signature"] ?? headers["x-hub-signature-256"] ?? "";
+                    if (!sig || !(await verifyHmac(secret, raw, sig))) {
+                        return json({ error: "invalid signature" }, 401);
+                    }
+                }
+                // Idempotency by delivery id (bounded set).
+                const delivery = headers["x-delivery-id"] ?? headers["x-github-delivery"];
+                if (delivery) {
+                    if (seenDeliveries.has(delivery))
+                        return json({ ok: true, deduped: true });
+                    seenDeliveries.add(delivery);
+                    if (seenDeliveries.size > 10_000) {
+                        seenDeliveries.delete(seenDeliveries.values().next().value);
+                    }
+                }
+                let body = {};
+                try {
+                    body = raw ? JSON.parse(raw) : {};
+                }
+                catch {
+                    return json({ error: "body must be JSON" }, 400);
+                }
+                const message = trig.action?.message;
+                if (!message) {
+                    app.log("warn", `trigger "${trig.id}": no action.message; nothing published`);
+                    return json({ ok: true, published: false });
+                }
+                const correlationKey = evalCorrelation(trig.action?.correlationKey, {
+                    body,
+                    headers,
+                    query: Object.fromEntries(req.query),
+                });
+                await app.engine.publishMessage({
+                    name: message,
+                    correlationKey,
+                    variables: (body && typeof body === "object" ? body : {}),
+                });
+                app.log("info", `trigger "${trig.id}" published`, { message, correlationKey });
+                return json({ ok: true, published: true, message, correlationKey });
+            },
+        });
+    }
+    ctx.host.log("info", "triggers mounted", { mounted });
+    return { name: "triggers", routes, describe: () => ({ mounted }) };
+}

package/dist/runtime/core/modules/workers.d.ts

@@ -0,0 +1,16 @@
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import type { EngineJob } from "../host.ts";
+/** A handler as authored by an app: the job plus the injected app API. */
+export type AppJobHandler = (job: EngineJob, app: AppApi) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+/**
+ * Resolve a handler for `jobType` from a loaded module, in priority order:
+ *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)
+ *   2. a named export matching jobType (or its last dotted segment)
+ *   3. `default` (when it is a function)
+ */
+export declare function resolveHandler(mod: Record<string, unknown>, jobType: string): AppJobHandler | undefined;
+export interface WorkersHandle extends Mounted {
+    readonly jobTypes: string[];
+}
+/** Load handler modules and register a push worker per declared worker. */
+export declare function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<WorkersHandle>;

package/dist/runtime/core/modules/workers.js

@@ -0,0 +1,79 @@
+// workers — load each declared worker's handler module and register it as a push worker
+// on the engine. Handlers are resolved by a small, documented contract and are injected
+// with the app's runtime API (datasource + engine + host utils).
+import { workerJobType } from "../manifest.js";
+/**
+ * Resolve a handler for `jobType` from a loaded module, in priority order:
+ *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)
+ *   2. a named export matching jobType (or its last dotted segment)
+ *   3. `default` (when it is a function)
+ */
+export function resolveHandler(mod, jobType) {
+    const map = mod.handlers;
+    if (map && typeof map[jobType] === "function")
+        return map[jobType];
+    const seg = jobType.includes(".") ? jobType.slice(jobType.lastIndexOf(".") + 1) : jobType;
+    if (typeof mod[jobType] === "function")
+        return mod[jobType];
+    if (map && typeof map[seg] === "function")
+        return map[seg];
+    if (typeof mod[seg] === "function")
+        return mod[seg];
+    if (typeof mod.default === "function")
+        return mod.default;
+    return undefined;
+}
+/** Load handler modules and register a push worker per declared worker. */
+export async function mountWorkers(ctx, app) {
+    const decls = ctx.manifest.workers ?? [];
+    const subs = [];
+    const jobTypes = [];
+    // Cache module loads so a multi-type handler module is imported once.
+    const moduleCache = new Map();
+    const joinRoot = (p) => p.startsWith("/") ? p : `${ctx.root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
+    const loadModule = async (path) => {
+        const key = joinRoot(path);
+        const cached = moduleCache.get(key);
+        if (cached)
+            return cached;
+        const mod = await ctx.host.importModule(key);
+        moduleCache.set(key, mod);
+        return mod;
+    };
+    for (const decl of decls) {
+        const jobType = workerJobType(decl);
+        if (!jobType)
+            continue;
+        if (!decl.handler) {
+            // llm-backed workers (schema `oneOf` handler|llm) are validated but not yet
+            // executed by the runtime. Skip with a clear warning rather than crashing.
+            ctx.host.log("warn", "skipping worker: llm-backed workers are not yet implemented", {
+                jobType,
+                llm: decl.llm,
+            });
+            continue;
+        }
+        const mod = await loadModule(decl.handler);
+        const handler = resolveHandler(mod, jobType);
+        if (!handler) {
+            throw new Error(`worker "${jobType}": ${decl.handler} exports no handler for it ` +
+                `(expected handlers["${jobType}"], a named export, or a default function)`);
+        }
+        const wrapped = (job) => handler(job, app);
+        const sub = await ctx.engine.registerWorker(jobType, wrapped, {
+            workerName: `${ctx.manifest.id}:${jobType}`,
+        });
+        subs.push(sub);
+        jobTypes.push(jobType);
+        ctx.host.log("info", "worker registered", { jobType, handler: decl.handler });
+    }
+    return {
+        name: "workers",
+        jobTypes,
+        async stop() {
+            // Graceful unsubscribe on exit (defensive against the Falcon dead-subscriber stall).
+            await Promise.allSettled(subs.map((s) => s.unsubscribe()));
+        },
+        describe: () => ({ jobTypes }),
+    };
+}

package/dist/runtime/core/router.d.ts

@@ -0,0 +1,22 @@
+import type { HttpHandler, HttpResponse } from "./host.ts";
+export interface Route {
+    method: string;
+    path: string;
+    /** When true, match any path that starts with `path`. */
+    prefix?: boolean;
+    handler: HttpHandler;
+    /** For diagnostics / inspect(). */
+    source?: string;
+}
+export declare function json(body: unknown, status?: number): HttpResponse;
+export declare function html(body: string, status?: number): HttpResponse;
+export declare function text(body: string, status?: number): HttpResponse;
+/**
+ * Normalize a manifest-supplied route path: ensure a leading "/", drop trailing
+ * slashes. Incoming request paths always start with "/", so a manifest path
+ * lacking one (e.g. "hooks/x") would otherwise never match. Falls back to
+ * `fallback` when the value is missing or collapses to empty ("/").
+ */
+export declare function normalizeRoutePath(value: string | undefined, fallback: string): string;
+/** Build a single HttpHandler that dispatches across the given routes. */
+export declare function makeRouter(routes: Route[]): HttpHandler;

package/dist/runtime/core/router.js

@@ -0,0 +1,39 @@
+// A minimal path router shared by the surfaces and triggers modules so the runtime serves
+// a single HTTP port. Matching is exact path or, for a route registered with `prefix`,
+// a path-prefix match. First match wins.
+export function json(body, status = 200) {
+    return { status, headers: { "content-type": "application/json" }, body: JSON.stringify(body) };
+}
+export function html(body, status = 200) {
+    return { status, headers: { "content-type": "text/html; charset=utf-8" }, body };
+}
+export function text(body, status = 200) {
+    return { status, headers: { "content-type": "text/plain; charset=utf-8" }, body };
+}
+/**
+ * Normalize a manifest-supplied route path: ensure a leading "/", drop trailing
+ * slashes. Incoming request paths always start with "/", so a manifest path
+ * lacking one (e.g. "hooks/x") would otherwise never match. Falls back to
+ * `fallback` when the value is missing or collapses to empty ("/").
+ */
+export function normalizeRoutePath(value, fallback) {
+    const raw = (value ?? fallback).trim();
+    const withLead = raw.startsWith("/") ? raw : `/${raw}`;
+    const noTrail = withLead.replace(/\/+$/, "");
+    return noTrail || fallback;
+}
+function matches(route, req) {
+    if (route.method !== "*" && route.method.toUpperCase() !== req.method.toUpperCase())
+        return false;
+    return route.prefix ? req.path.startsWith(route.path) : req.path === route.path;
+}
+/** Build a single HttpHandler that dispatches across the given routes. */
+export function makeRouter(routes) {
+    return async (req) => {
+        for (const route of routes) {
+            if (matches(route, req))
+                return route.handler(req);
+        }
+        return text("not found", 404);
+    };
+}

package/dist/runtime/core/runtime.d.ts

@@ -0,0 +1,46 @@
+import type { EngineClient, HostContext } from "./host.ts";
+import { type AppManifest } from "./manifest.ts";
+import { DataLayer } from "./modules/datasource.ts";
+import { type SecurityPolicy } from "./modules/security.ts";
+/** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
+ * error when $PORT is set but not a valid integer in 0..65535. */
+export declare function resolvePort(explicit: number | undefined, envPort: string | undefined): number;
+export interface MountFlags {
+    deploy?: boolean;
+    data?: boolean;
+    workers?: boolean;
+    surfaces?: boolean;
+    triggers?: boolean;
+    security?: boolean;
+}
+export interface CreateUrbanAppOptions {
+    host: HostContext;
+    engine: EngineClient;
+    /** App root directory; manifest paths resolve relative to it. Default ".". */
+    root?: string;
+    /** Provide a manifest object directly, or… */
+    manifest?: AppManifest;
+    /** …a path to load it from (relative to root). Default "nano.app.json". */
+    manifestPath?: string;
+    /** HTTP port for surfaces/triggers. Default from PORT env or 8090. */
+    port?: number;
+    /** Which modules to mount (all true by default). */
+    mount?: MountFlags;
+}
+export interface UrbanApp {
+    readonly manifest: AppManifest;
+    readonly root: string;
+    /** Materialize the app (deploy → data → workers → surfaces/triggers). */
+    start(): Promise<void>;
+    /** Tear everything down cleanly: unsubscribe workers, close the DB, stop the
+     * HTTP server, and close the engine client (the app owns the engine's
+     * connection lifecycle once started). */
+    stop(): Promise<void>;
+    /** A structured snapshot of what is mounted. */
+    inspect(): Record<string, unknown>;
+    /** The provisioned data layer (available after start when `data` is mounted). */
+    readonly data: DataLayer | undefined;
+    readonly security: SecurityPolicy | undefined;
+    readonly httpPort: number | undefined;
+}
+export declare function createUrbanApp(opts: CreateUrbanAppOptions): Promise<UrbanApp>;

package/dist/runtime/core/runtime.js

@@ -0,0 +1,173 @@
+// The runtime orchestrator: createUrbanApp() takes a manifest + a host + an engine and
+// materializes the app by mounting each module. Hosts (CLI/IDE/console/bare process) call
+// this the same way; a host may mount a subset via `mount` flags (e.g. the console mounts
+// its own surfaces but reuses deploy + workers + datasource).
+import { loadManifest } from "./manifest.js";
+import { validateManifest } from "./validate.js";
+import { makeRouter } from "./router.js";
+import { deployModels } from "./modules/deploy.js";
+import { provisionData, DataLayer } from "./modules/datasource.js";
+import { mountWorkers } from "./modules/workers.js";
+import { mountSurfaces } from "./modules/surfaces.js";
+import { mountTriggers } from "./modules/triggers.js";
+import { mountSecurity } from "./modules/security.js";
+/** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
+ * error when $PORT is set but not a valid integer in 0..65535. */
+export function resolvePort(explicit, envPort) {
+    if (explicit !== undefined)
+        return explicit;
+    if (envPort === undefined || envPort === "")
+        return 8090;
+    const n = Number(envPort);
+    if (!Number.isInteger(n) || n < 0 || n > 65535) {
+        throw new Error(`invalid PORT "${envPort}": expected an integer in 0..65535`);
+    }
+    return n;
+}
+/** Read the underlying nano-sdk client off an engine when it exposes one (the
+ *  `SdkEngineClient` does). Non-SDK engines (e.g. an in-memory test double) have no
+ *  `sdk`, so handlers get `undefined` and fall back to the transport-agnostic seam. */
+function engineSdk(engine) {
+    return engine.sdk;
+}
+export async function createUrbanApp(opts) {
+    const host = opts.host;
+    const root = opts.root ?? ".";
+    const manifest = validateManifest(opts.manifest ?? (await loadManifest(host, `${root.replace(/\/+$/, "")}/${opts.manifestPath ?? "nano.app.json"}`)));
+    const engine = opts.engine;
+    const flags = {
+        deploy: opts.mount?.deploy ?? true,
+        data: opts.mount?.data ?? true,
+        workers: opts.mount?.workers ?? true,
+        surfaces: opts.mount?.surfaces ?? true,
+        triggers: opts.mount?.triggers ?? true,
+        security: opts.mount?.security ?? true,
+    };
+    const ctx = { manifest, host, engine, root };
+    let data;
+    let security;
+    let server;
+    const mounted = [];
+    const describe = {};
+    let started = false;
+    let httpPort;
+    const port = resolvePort(opts.port, host.env("PORT"));
+    // Release every mounted resource and reset internal state so a subsequent
+    // start() begins clean. Used by stop() and by start()'s failure path.
+    const teardown = async () => {
+        if (server) {
+            try {
+                await server.stop();
+            }
+            catch (e) {
+                host.log("warn", "error stopping http server", { error: String(e) });
+            }
+        }
+        for (const m of mounted) {
+            try {
+                await m.stop();
+            }
+            catch (e) {
+                host.log("warn", "error stopping module", { error: String(e) });
+            }
+        }
+        if (data)
+            data.closeAll();
+        try {
+            await engine.close();
+        }
+        catch (e) {
+            host.log("warn", "error closing engine", { error: String(e) });
+        }
+        mounted.length = 0;
+        for (const k of Object.keys(describe))
+            delete describe[k];
+        server = undefined;
+        httpPort = undefined;
+        data = undefined;
+        security = undefined;
+        started = false;
+    };
+    const app = {
+        manifest,
+        root,
+        get data() {
+            return data;
+        },
+        get security() {
+            return security;
+        },
+        get httpPort() {
+            return httpPort;
+        },
+        async start() {
+            if (started)
+                throw new Error("app already started");
+            started = true;
+            try {
+                if (flags.security)
+                    security = mountSecurity(ctx);
+                if (flags.deploy)
+                    describe.deploy = await deployModels(ctx);
+                data = flags.data ? await provisionData(ctx) : new DataLayer(new Map(), undefined, {});
+                const api = {
+                    manifest,
+                    data,
+                    engine,
+                    sdk: engineSdk(engine),
+                    env: (n) => host.env(n),
+                    log: (l, m, f) => host.log(l, m, f),
+                };
+                if (flags.workers) {
+                    const w = await mountWorkers(ctx, api);
+                    mounted.push(w);
+                    describe.workers = w.describe?.();
+                }
+                const routes = [];
+                if (flags.surfaces) {
+                    const s = mountSurfaces(ctx, api);
+                    routes.push(...s.routes);
+                    describe.surfaces = s.describe();
+                }
+                if (flags.triggers) {
+                    const t = mountTriggers(ctx, api);
+                    routes.push(...t.routes);
+                    describe.triggers = t.describe();
+                }
+                if (security)
+                    describe.security = security.describe();
+                if (data)
+                    describe.data = data.describe();
+                if (routes.length > 0) {
+                    // A tiny liveness route.
+                    routes.push({
+                        method: "GET",
+                        path: "/healthz",
+                        handler: () => ({
+                            status: 200,
+                            headers: { "content-type": "application/json" },
+                            body: JSON.stringify({ ok: true, app: manifest.id }),
+                        }),
+                    });
+                    server = await host.serveHttp(port, makeRouter(routes));
+                    httpPort = server.port;
+                    host.log("info", "urban app serving surfaces/triggers", { port: httpPort, routes: routes.length });
+                }
+                host.log("info", `urban app "${manifest.id}" started`, {});
+            }
+            catch (err) {
+                // A failed start must not leave the app half-mounted (leaked workers,
+                // a bound port) or wedged in the "already started" state.
+                await teardown();
+                throw err;
+            }
+        },
+        async stop() {
+            await teardown();
+        },
+        inspect() {
+            return { app: manifest.id, name: manifest.name, root, httpPort, ...describe };
+        },
+    };
+    return app;
+}

package/dist/runtime/core/validate.d.ts

@@ -0,0 +1,13 @@
+import { type AppManifest } from "./manifest.ts";
+export interface ValidationIssue {
+    path: string;
+    message: string;
+}
+export declare class ManifestValidationError extends Error {
+    readonly issues: ValidationIssue[];
+    constructor(issues: ValidationIssue[]);
+}
+/** Validate a parsed manifest. Returns the list of issues (empty === valid). */
+export declare function collectManifestIssues(m: unknown): ValidationIssue[];
+/** Throw ManifestValidationError if the manifest is invalid; otherwise return it typed. */
+export declare function validateManifest(m: unknown): AppManifest;

package/dist/runtime/core/validate.js

@@ -0,0 +1,108 @@
+// Manifest validation. We deliberately avoid a heavyweight JSON-Schema engine here to
+// keep core dependency-free and runtime-agnostic. Instead we drive validation *from* the
+// vendored nano-app.schema.json (the ADR 0027 source of truth) for the top-level envelope
+// — required keys, allowed keys (additionalProperties:false), the schemaVersion const, and
+// the id slug pattern — and then layer the runtime's binding rules (a worker needs a
+// handler, a data source needs driver+url, a typed table needs fields, a trigger needs
+// id+type). Reading the schema means the envelope check tracks the schema and can't drift
+// from it silently.
+import schema from "../schema/nano-app.schema.json" with { type: "json" };
+import { workerJobType } from "./manifest.js";
+export class ManifestValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid Urban manifest (${issues.length} issue${issues.length === 1 ? "" : "s"}):\n` +
+            issues.map((i) => `  • ${i.path}: ${i.message}`).join("\n"));
+        this.name = "ManifestValidationError";
+        this.issues = issues;
+    }
+}
+const S = schema;
+/** Validate a parsed manifest. Returns the list of issues (empty === valid). */
+export function collectManifestIssues(m) {
+    const issues = [];
+    if (m === null || typeof m !== "object" || Array.isArray(m)) {
+        return [{ path: "$", message: "manifest must be a JSON object" }];
+    }
+    const obj = m;
+    // — Envelope, driven by the schema —
+    for (const req of S.required ?? []) {
+        if (!(req in obj))
+            issues.push({ path: req, message: "required by nano-app.schema.json" });
+    }
+    const allowed = new Set(Object.keys(S.properties ?? {}));
+    if (S.additionalProperties === false) {
+        for (const k of Object.keys(obj)) {
+            if (!allowed.has(k)) {
+                issues.push({ path: k, message: "unknown top-level key (additionalProperties: false)" });
+            }
+        }
+    }
+    if ("schemaVersion" in obj && obj.schemaVersion !== 1) {
+        issues.push({ path: "schemaVersion", message: "must be 1" });
+    }
+    const slugPattern = S.$defs?.slug?.pattern;
+    if (slugPattern && typeof obj.id === "string" && !new RegExp(slugPattern).test(obj.id)) {
+        issues.push({ path: "id", message: `must match slug pattern ${slugPattern}` });
+    }
+    if ("name" in obj && (typeof obj.name !== "string" || obj.name.length === 0)) {
+        issues.push({ path: "name", message: "must be a non-empty string" });
+    }
+    // — Runtime binding rules —
+    const man = obj;
+    if (Array.isArray(man.workers)) {
+        man.workers.forEach((w, i) => {
+            if (!workerJobType(w)) {
+                issues.push({ path: `workers[${i}]`, message: "missing taskType/type" });
+            }
+            // The schema allows a worker backed by either a `handler` file or an `llm`
+            // binding (oneOf). Require exactly one — don't force `handler`.
+            const hasHandler = typeof w?.handler === "string" && w.handler.length > 0;
+            const hasLlm = typeof w?.llm === "string" && w.llm.length > 0;
+            if (!hasHandler && !hasLlm) {
+                issues.push({ path: `workers[${i}]`, message: "worker requires a `handler` or `llm`" });
+            }
+            else if (hasHandler && hasLlm) {
+                issues.push({ path: `workers[${i}]`, message: "worker declares both `handler` and `llm` (mutually exclusive)" });
+            }
+        });
+    }
+    if (man.data?.sources) {
+        for (const [name, src] of Object.entries(man.data.sources)) {
+            if (!src || typeof src.driver !== "string") {
+                issues.push({ path: `data.sources.${name}.driver`, message: "missing driver" });
+            }
+            if (!src || typeof src.url !== "string") {
+                issues.push({ path: `data.sources.${name}.url`, message: "missing url" });
+            }
+        }
+        if (man.data.default && !man.data.sources[man.data.default]) {
+            issues.push({ path: "data.default", message: `no such source "${man.data.default}"` });
+        }
+    }
+    if (man.types) {
+        for (const [name, t] of Object.entries(man.types)) {
+            // `table` is optional in the schema: a type may declare `fields` without a
+            // `table` (a transient / non-persisted domain type). Don't require it.
+            if (t && typeof t !== "object") {
+                issues.push({ path: `types.${name}`, message: "must be an object" });
+            }
+        }
+    }
+    if (Array.isArray(man.triggers)) {
+        man.triggers.forEach((t, i) => {
+            if (!t?.id)
+                issues.push({ path: `triggers[${i}].id`, message: "missing id" });
+            if (!t?.type)
+                issues.push({ path: `triggers[${i}].type`, message: "missing type" });
+        });
+    }
+    return issues;
+}
+/** Throw ManifestValidationError if the manifest is invalid; otherwise return it typed. */
+export function validateManifest(m) {
+    const issues = collectManifestIssues(m);
+    if (issues.length > 0)
+        throw new ManifestValidationError(issues);
+    return m;
+}