@nanobpm/urban 0.1.0 → 0.2.0

package/src/runtime/core/runtime.test.ts

@@ -0,0 +1,258 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../adapters/node.ts";
+import { createUrbanApp, resolvePort } from "./runtime.ts";
+import { runFromEnv } from "../run.ts";
+import type {
+  EngineClient,
+  EngineJob,
+  JobHandler,
+  WorkerSubscription,
+} from "./host.ts";
+
+// A fake engine: records everything and lets the test deliver a job to a registered worker.
+class FakeEngine implements EngineClient {
+  deployed = 0;
+  workers = new Map<string, JobHandler>();
+  messages: { name: string; correlationKey?: string; variables?: Record<string, unknown> }[] = [];
+  completedTasks: { key: string; variables?: Record<string, unknown> }[] = [];
+  userTasks = [{ userTaskKey: "ut-1", elementId: "approve", variables: {} }];
+
+  async deployResources(r: { name: string }[]) {
+    this.deployed += r.length;
+    return { deployed: r.length };
+  }
+  async createInstance() {
+    return { processInstanceKey: "pi-1" };
+  }
+  async publishMessage(input: { name: string; correlationKey?: string; variables?: Record<string, unknown> }) {
+    this.messages.push(input);
+  }
+  async searchUserTasks() {
+    return this.userTasks;
+  }
+  async completeUserTask(key: string, variables?: Record<string, unknown>) {
+    this.completedTasks.push({ key, variables });
+  }
+  async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
+    this.workers.set(jobType, handler);
+    return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };
+  }
+  async close() {}
+  // test helper
+  async deliver(jobType: string, job: EngineJob) {
+    const h = this.workers.get(jobType);
+    if (!h) throw new Error(`no worker for ${jobType}`);
+    return h(job);
+  }
+}
+
+async function makeFixture(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-rt-"));
+  await mkdir(join(dir, "processes"));
+  await mkdir(join(dir, "decisions"));
+  await mkdir(join(dir, "forms"));
+  await mkdir(join(dir, "db", "migrations"), { recursive: true });
+  await mkdir(join(dir, "workers"));
+  await writeFile(join(dir, "processes", "p.bpmn"), "<definitions/>");
+  await writeFile(join(dir, "decisions", "d.dmn"), "<definitions/>");
+  await writeFile(join(dir, "forms", "f.form"), "{}");
+  await writeFile(
+    join(dir, "db", "migrations", "001_init.sql"),
+    "CREATE TABLE crew_tasks (id INTEGER PRIMARY KEY, title TEXT, status TEXT);",
+  );
+  await writeFile(
+    join(dir, "workers", "handlers.ts"),
+    `export const handlers = {
+      "wf.claim": async (job, app) => {
+        app.data.repo("task").insert({ title: job.variables.title, status: "claimed" });
+        return { claimed: true };
+      },
+    };`,
+  );
+  const manifest = {
+    schemaVersion: 1,
+    id: "fixture-app",
+    name: "Fixture App",
+    models: { processes: ["processes/*.bpmn"], decisions: ["decisions/*.dmn"], forms: ["forms/*.form"] },
+    data: { default: "app", sources: { app: { driver: "sqlite", url: "file:./db/app.db", migrations: "db/migrations" } } },
+    types: { task: { table: "crew_tasks", fields: { title: { type: "string" }, status: { type: "string" } } } },
+    workers: [{ taskType: "wf.claim", handler: "workers/handlers.ts" }],
+    triggers: [{ id: "hook", type: "webhook", path: "/hooks/task", action: { message: "wf.requested", correlationKey: "= body.taskId" } }],
+    surfaces: { taskInbox: { enabled: true, path: "/tasks" } },
+  };
+  await writeFile(join(dir, "nano.app.json"), JSON.stringify(manifest, null, 2));
+  return dir;
+}
+
+test("runtime materializes the manifest end-to-end against a fake engine", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+
+  try {
+    // deploy
+    assert.equal(engine.deployed, 3, "3 model files deployed");
+
+    // migrations applied
+    const insp = app.inspect() as Record<string, any>;
+    assert.deepEqual(insp.data.sources[0].migrations, 1);
+
+    // workers registered + data injected: deliver a job and see a DB row
+    await engine.deliver("wf.claim", {
+      jobKey: "j1",
+      jobType: "wf.claim",
+      variables: { title: "Fix bug" },
+    });
+    const rows = app.data!.repo("task").all<{ title: string; status: string }>();
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].title, "Fix bug");
+    assert.equal(rows[0].status, "claimed");
+
+    // HTTP surfaces + triggers on the real node server
+    const port = app.httpPort!;
+    assert.ok(port > 0);
+
+    const tasksRes = await fetch(`http://localhost:${port}/tasks/api/tasks`);
+    assert.equal(tasksRes.status, 200);
+    assert.equal((await tasksRes.json() as unknown[]).length, 1);
+
+    const hookRes = await fetch(`http://localhost:${port}/hooks/task`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ taskId: "T-9", title: "from webhook" }),
+    });
+    assert.equal(hookRes.status, 200);
+    assert.equal(engine.messages.length, 1);
+    assert.equal(engine.messages[0].name, "wf.requested");
+    assert.equal(engine.messages[0].correlationKey, "T-9");
+
+    // complete a user task through the surface API
+    const done = await fetch(`http://localhost:${port}/tasks/api/complete`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ userTaskKey: "ut-1", variables: { approved: true } }),
+    });
+    assert.equal(done.status, 200);
+    assert.equal(engine.completedTasks.length, 1);
+    assert.equal(engine.completedTasks[0].key, "ut-1");
+
+    // healthz
+    const health = await fetch(`http://localhost:${port}/healthz`);
+    assert.equal((await health.json() as { ok: boolean }).ok, true);
+
+    // field-drift guard
+    assert.throws(() => app.data!.repo("task").insert({ bogus: 1 }));
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("stop() resets state so the app can be cleanly restarted", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+
+  try {
+    await app.start();
+    const firstPort = app.httpPort!;
+    assert.ok(firstPort > 0);
+    await app.stop();
+
+    // after stop, inspect() no longer carries stale describe data / port
+    const stopped = app.inspect() as Record<string, unknown>;
+    assert.equal(stopped.httpPort, undefined);
+    assert.equal(stopped.workers, undefined);
+
+    // and a fresh start works (would throw "already started" if state leaked)
+    await app.start();
+    assert.ok(app.httpPort! > 0);
+    // deploy ran again on the clean start, not doubled from the first run
+    assert.equal(engine.deployed, 6);
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a failed start() tears down and resets state (no 'already started' wedge)", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  let failNextDeploy = true;
+  const engine = new FakeEngine();
+  const origDeploy = engine.deployResources.bind(engine);
+  engine.deployResources = async (r: { name: string }[]) => {
+    if (failNextDeploy) {
+      failNextDeploy = false;
+      throw new Error("boom during deploy");
+    }
+    return origDeploy(r);
+  };
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+
+  try {
+    await assert.rejects(() => app.start(), /boom during deploy/);
+    // state reset: not wedged, no leaked port/describe
+    const s = app.inspect() as Record<string, unknown>;
+    assert.equal(s.httpPort, undefined);
+    assert.equal(s.workers, undefined);
+    // a subsequent start() succeeds rather than throwing "app already started"
+    await app.start();
+    assert.ok(app.httpPort! > 0);
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("task-inbox /api/complete returns 400 on a malformed JSON body", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+  try {
+    const res = await fetch(`http://localhost:${app.httpPort!}/tasks/api/complete`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{not json",
+    });
+    assert.equal(res.status, 400);
+    assert.equal(engine.completedTasks.length, 0);
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("resolvePort prefers explicit, then $PORT, then 8090; rejects bad $PORT", () => {
+  assert.equal(resolvePort(3000, "9999"), 3000);
+  assert.equal(resolvePort(undefined, "9999"), 9999);
+  assert.equal(resolvePort(undefined, undefined), 8090);
+  assert.equal(resolvePort(undefined, ""), 8090);
+  assert.throws(() => resolvePort(undefined, "abc"), /invalid PORT/);
+  assert.throws(() => resolvePort(undefined, "70000"), /invalid PORT/);
+});
+
+test("runFromEnv anchors the host at a non-'.' root without double-prefixing paths", async () => {
+  const dir = await makeFixture();
+  const engine = new FakeEngine();
+  // No host passed → runFromEnv selects a host anchored at `dir`. The regression
+  // guarded here: it must NOT also prefix `dir` inside createUrbanApp (which
+  // would look for "<dir>/<dir>/nano.app.json" and fail).
+  const app = await runFromEnv({ root: dir, engine, port: 0, handleSignals: false });
+  try {
+    assert.equal(app.manifest.id, "fixture-app");
+    assert.equal(engine.deployed, 3, "models deployed from the correct root");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/core/runtime.ts

@@ -0,0 +1,213 @@
+// 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 type { AppApi, Mounted } from "./context.ts";
+import type { EngineClient, HostContext, HttpServer } from "./host.ts";
+import { loadManifest, type AppManifest } from "./manifest.ts";
+import { validateManifest } from "./validate.ts";
+import { makeRouter, type Route } from "./router.ts";
+import { deployModels } from "./modules/deploy.ts";
+import { provisionData, DataLayer } from "./modules/datasource.ts";
+import { mountWorkers } from "./modules/workers.ts";
+import { mountSurfaces } from "./modules/surfaces.ts";
+import { mountTriggers } from "./modules/triggers.ts";
+import { mountSecurity, 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 function resolvePort(explicit: number | undefined, envPort: string | undefined): number {
+  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;
+}
+
+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 async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<UrbanApp> {
+  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: Required<MountFlags> = {
+    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: DataLayer | undefined;
+  let security: SecurityPolicy | undefined;
+  let server: HttpServer | undefined;
+  const mounted: Mounted[] = [];
+  const describe: Record<string, unknown> = {};
+  let started = false;
+  let httpPort: number | undefined;
+
+  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: UrbanApp = {
+    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: AppApi = {
+          manifest,
+          data,
+          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: Route[] = [];
+        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/src/runtime/core/validate.test.ts

@@ -0,0 +1,73 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { collectManifestIssues, validateManifest, ManifestValidationError } from "./validate.ts";
+
+const valid = {
+  schemaVersion: 1,
+  id: "nano-workforce",
+  name: "Nano Workforce",
+  data: { default: "app", sources: { app: { driver: "sqlite", url: "file:./x.db" } } },
+  types: { task: { table: "crew_tasks", fields: { title: { type: "string" } } } },
+  workers: [{ taskType: "a.b", handler: "workers/x.ts" }],
+  triggers: [{ id: "t", type: "webhook", path: "/h" }],
+};
+
+test("a well-formed manifest has no issues", () => {
+  assert.deepEqual(collectManifestIssues(valid), []);
+  assert.equal(validateManifest(valid).id, "nano-workforce");
+});
+
+test("missing required keys are reported (driven by the schema)", () => {
+  const issues = collectManifestIssues({ schemaVersion: 1 });
+  const paths = issues.map((i) => i.path);
+  assert.ok(paths.includes("id"));
+  assert.ok(paths.includes("name"));
+});
+
+test("unknown top-level keys are rejected (additionalProperties:false)", () => {
+  const issues = collectManifestIssues({ ...valid, bogus: 1 });
+  assert.ok(issues.some((i) => i.path === "bogus"));
+});
+
+test("bad schemaVersion and bad slug id are reported", () => {
+  const issues = collectManifestIssues({ ...valid, schemaVersion: 2, id: "Not A Slug" });
+  assert.ok(issues.some((i) => i.path === "schemaVersion"));
+  assert.ok(issues.some((i) => i.path === "id"));
+});
+
+test("binding rules: worker needs handler-or-llm, source needs driver+url", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a" }],
+    types: { t: { fields: { x: { type: "string" } } } },
+    data: { default: "app", sources: { app: { driver: "sqlite" } } },
+  });
+  assert.ok(issues.some((i) => i.path === "workers[0]" && /handler.*llm/.test(i.message)));
+  // A type with `fields` and no `table` is a valid transient type — no issue.
+  assert.ok(!issues.some((i) => i.path.startsWith("types.t")));
+  assert.ok(issues.some((i) => i.path === "data.sources.app.url"));
+});
+
+test("an llm-backed worker (no handler) is accepted", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "summarize", llm: "gpt" }],
+  });
+  assert.ok(!issues.some((i) => i.path.startsWith("workers[0]")));
+});
+
+test("data.default must reference an existing source", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    data: { default: "nope", sources: { app: { driver: "sqlite", url: "file:./x" } } },
+  });
+  assert.ok(issues.some((i) => i.path === "data.default"));
+});
+
+test("validateManifest throws ManifestValidationError with issues", () => {
+  assert.throws(() => validateManifest({ schemaVersion: 1 }), (e: unknown) => {
+    assert.ok(e instanceof ManifestValidationError);
+    assert.ok(e.issues.length >= 2);
+    return true;
+  });
+});

package/src/runtime/core/validate.ts

@@ -0,0 +1,129 @@
+// 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, type AppManifest } from "./manifest.ts";
+
+export interface ValidationIssue {
+  path: string;
+  message: string;
+}
+
+export class ManifestValidationError extends Error {
+  readonly issues: ValidationIssue[];
+  constructor(issues: ValidationIssue[]) {
+    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;
+  }
+}
+
+interface JsonSchema {
+  required?: string[];
+  properties?: Record<string, unknown>;
+  additionalProperties?: boolean;
+  $defs?: { slug?: { pattern?: string } };
+}
+
+const S = schema as unknown as JsonSchema;
+
+/** Validate a parsed manifest. Returns the list of issues (empty === valid). */
+export function collectManifestIssues(m: unknown): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  if (m === null || typeof m !== "object" || Array.isArray(m)) {
+    return [{ path: "$", message: "manifest must be a JSON object" }];
+  }
+  const obj = m as Record<string, unknown>;
+
+  // — 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 as unknown as AppManifest;
+
+  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: unknown): AppManifest {
+  const issues = collectManifestIssues(m);
+  if (issues.length > 0) throw new ManifestValidationError(issues);
+  return m as AppManifest;
+}