@nanobpm/urban 0.6.0 → 0.8.0

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

@@ -3,6 +3,8 @@
 // linked `.form` and posts completion back. The `chat` surface is stubbed as a mount point
 // (LLM wiring is a separate concern). Surfaces contribute routes to the shared server.
 import { html, json, normalizeRoutePath } from "../router.js";
+import { mountActions } from "./actions.js";
+import { mountPages } from "./pages.js";
 /** Escape HTML-significant characters before embedding a value in markup. */
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -83,6 +85,20 @@ export function mountSurfaces(ctx, app) {
 <p>Chat surface mount point (agent: <code>${escapeHtml(chat.agent ?? "?")}</code>). LLM wiring pending.</p>`),
         });
     }
+    // App-authored action overrides mount BEFORE the generic pages routes so an exact
+    // override (e.g. /app/actions/cancel) shadows the generic action; the router is
+    // first-match-wins.
+    const actions = mountActions(ctx, app);
+    if (actions.routes.length > 0) {
+        routes.push(...actions.routes);
+        enabled.push(`actions(${actions.routes.length})`);
+    }
+    // The pages surface (the schema-driven page runtime) mounts its own routes.
+    const pages = mountPages(ctx, app);
+    if (pages.routes.length > 0) {
+        routes.push(...pages.routes);
+        enabled.push("pages@/");
+    }
     ctx.host.log("info", "surfaces mounted", { enabled });
     return { name: "surfaces", routes, describe: () => ({ enabled }) };
 }

package/dist/runtime/engine/nanosdk.d.ts

@@ -53,6 +53,9 @@ export interface NanoSdkClient {
         variables?: Record<string, unknown>;
         awaitCompletion?: boolean;
     }, options?: unknown): Promise<Record<string, unknown>>;
+    cancelProcessInstance(input: {
+        processInstanceKey: string | number;
+    }, options?: unknown): Promise<unknown>;
     publishMessage(input: {
         name: string;
         correlationKey?: string;
@@ -101,6 +104,9 @@ export declare class SdkEngineClient implements EngineClient {
         processInstanceKey: string;
         variables?: Record<string, unknown>;
     }>;
+    cancelInstance(input: {
+        processInstanceKey: string;
+    }): Promise<void>;
     publishMessage(input: {
         name: string;
         correlationKey?: string;

package/dist/runtime/engine/nanosdk.js

@@ -66,6 +66,9 @@ export class SdkEngineClient {
             variables: body.variables ?? undefined,
         };
     }
+    async cancelInstance(input) {
+        await this.client.cancelProcessInstance({ processInstanceKey: input.processInstanceKey });
+    }
     async publishMessage(input) {
         await this.client.publishMessage({
             name: input.name,

package/dist/runtime/index.d.ts

@@ -1,7 +1,7 @@
 export { createUrbanApp } from "./core/runtime.ts";
 export type { CreateUrbanAppOptions, MountFlags, UrbanApp, } from "./core/runtime.ts";
 export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.ts";
-export type { AppManifest, DataSource, DomainType, SurfaceDecl, TriggerDecl, TypeField, WorkerDecl, } from "./core/manifest.ts";
+export type { ActionDecl, AppManifest, DataSource, DomainType, SurfaceDecl, TriggerDecl, TypeField, WorkerDecl, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
 export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WorkerSubscription, } from "./core/host.ts";
@@ -10,6 +10,10 @@ export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
 export { makeGateway, Table } from "./core/modules/gateway.ts";
 export type { ColumnMeta, DataSource as GatewayDataSource, ExecResult, ForeignKeyMeta, Row, TableMeta, } from "./core/modules/gateway.ts";
+export { createPagesRoutes, mountPages } from "./core/modules/pages.ts";
+export type { PagesDataSource, PagesDeps, PagesHandle, PagesOptions } from "./core/modules/pages.ts";
+export { mountActions, resolveActionHandler } from "./core/modules/actions.ts";
+export type { ActionHandler, ActionRequest, ActionResult, ActionsHandle } from "./core/modules/actions.ts";
 export type { AppJobHandler } from "./core/modules/workers.ts";
 export { resolveHandler } from "./core/modules/workers.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";

package/dist/runtime/index.js

@@ -8,6 +8,8 @@ export { collectManifestIssues, ManifestValidationError, validateManifest, } fro
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.js";
 export { makeGateway, Table } from "./core/modules/gateway.js";
+export { createPagesRoutes, mountPages } from "./core/modules/pages.js";
+export { mountActions, resolveActionHandler } from "./core/modules/actions.js";
 export { resolveHandler } from "./core/modules/workers.js";
 export { evalCorrelation } from "./core/modules/triggers.js";
 // Adapters + engine + run entrypoint

package/dist/runtime/schema/nano-app.schema.json

@@ -52,6 +52,11 @@
       "additionalProperties": { "$ref": "#/$defs/connection" }
     },
     "surfaces": { "$ref": "#/$defs/surfaces" },
+    "actions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/action" },
+      "description": "App-authored action handler overrides (ADR 0055 §3): each binds an HTTP route to a handler module that wraps the generic pages start/cancel/message actions with business logic, injected with the app's runtime API."
+    },
     "workers": {
       "type": "array",
       "items": { "$ref": "#/$defs/worker" },
@@ -367,6 +372,33 @@
         }
       }
     },
+    "action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "module"],
+      "description": "An app-authored action handler override (ADR 0055 §3): binds a route to a handler module (default-exports an ActionHandler). Mounted before the generic pages action routes, so an exact override shadows the generic one.",
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Route path to serve, e.g. '/app/actions/cancel' or '/app/actions/start/convergence-loop'."
+        },
+        "module": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Handler module path relative to the app root; default-exports (or names `handler`) an ActionHandler."
+        },
+        "method": {
+          "type": "string",
+          "minLength": 1,
+          "description": "HTTP method to match. Default 'POST'."
+        },
+        "prefix": {
+          "type": "boolean",
+          "description": "Match `path` as a prefix rather than exactly. Default false."
+        }
+      }
+    },
     "llmBinding": {
       "type": "object",
       "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",

package/src/runtime/core/host.ts

@@ -105,6 +105,8 @@ export interface EngineClient {
     variables?: Record<string, unknown>;
     awaitCompletion?: boolean;
   }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }>;
+  /** Cancel a running process instance (the pages surface's row-cancel action). */
+  cancelInstance(input: { processInstanceKey: string }): Promise<void>;
   /** Publish a message for correlation. */
   publishMessage(input: {
     name: string;

package/src/runtime/core/manifest.ts

@@ -44,6 +44,31 @@ export interface SurfaceDecl {
   enabled?: boolean;
   path?: string;
   agent?: string;
+  /** pages surface: directory of `*.page.json` (relative to app root). Default `pages`. */
+  pagesDir?: string;
+  /** pages surface: the page served at `/`. Default `home`. */
+  homePage?: string;
+  /** pages surface: max rows a `dataGrid` fetch returns. Default 200. */
+  rowLimit?: number;
+  /** pages surface: the injected default datasource name. Default `app`. */
+  sourceName?: string;
+}
+
+/**
+ * An app-authored action handler override (ADR 0055 phase 3). Each declaration binds a
+ * route to a handler module (default-exports an `ActionHandler`), letting an app wrap the
+ * generic pages start/cancel/message actions with business logic. Mounted before the
+ * generic pages action routes, so an exact override shadows the generic one.
+ */
+export interface ActionDecl {
+  /** Route path to serve, e.g. "/app/actions/cancel" or "/app/actions/start/convergence-loop". */
+  path: string;
+  /** Handler module path relative to the app root; default-exports an `ActionHandler`. */
+  module: string;
+  /** HTTP method to match. Default "POST". */
+  method?: string;
+  /** Match `path` as a prefix rather than exactly. Default false. */
+  prefix?: boolean;
 }
 
 export interface AppManifest {
@@ -59,6 +84,7 @@ export interface AppManifest {
   triggers?: TriggerDecl[];
   connections?: Record<string, { type: string; [k: string]: unknown }>;
   surfaces?: Record<string, SurfaceDecl>;
+  actions?: ActionDecl[];
   workers?: WorkerDecl[];
   llm?: Record<string, unknown>;
   security?: Record<string, unknown>;

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

@@ -0,0 +1,239 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import { makeRouter } from "../router.ts";
+import { mountActions, resolveActionHandler, type ActionHandler } from "./actions.ts";
+
+function req(method: string, path: string, opts: { query?: string; body?: string } = {}): HttpRequest {
+  return {
+    method,
+    path,
+    query: new URLSearchParams(opts.query ?? ""),
+    headers: new Headers(),
+    text: () => Promise.resolve(opts.body ?? ""),
+  };
+}
+
+interface Built {
+  router: (r: HttpRequest) => Promise<{ status?: number; body?: string }>;
+  imported: string[];
+  logs: Array<{ level: string; msg: string }>;
+}
+
+function build(
+  actions: RuntimeContext["manifest"]["actions"],
+  modules: Record<string, Record<string, unknown>>,
+  app: AppApi = {} as AppApi,
+): Built {
+  const imported: string[] = [];
+  const logs: Array<{ level: string; msg: string }> = [];
+  const ctx = {
+    root: "/app",
+    manifest: { schemaVersion: 1, id: "t", name: "T", actions } as RuntimeContext["manifest"],
+    host: {
+      importModule: (path: string) => {
+        imported.push(path);
+        const mod = modules[path];
+        if (!mod) return Promise.reject(new Error(`no module at ${path}`));
+        return Promise.resolve(mod);
+      },
+      log: (level: string, msg: string) => logs.push({ level, msg }),
+    },
+  } as unknown as RuntimeContext;
+  const handle = mountActions(ctx, app);
+  const router = makeRouter(handle.routes) as unknown as Built["router"];
+  return { router, imported, logs };
+}
+
+test("resolveActionHandler prefers default, then handler", () => {
+  const fn = () => ({});
+  assert.equal(resolveActionHandler({ default: fn }), fn);
+  assert.equal(resolveActionHandler({ handler: fn }), fn);
+  assert.equal(resolveActionHandler({ default: fn, handler: () => ({}) }), fn);
+  assert.equal(resolveActionHandler({ nope: fn }), undefined);
+});
+
+test("routes an action to its handler with parsed body + injected app", async () => {
+  const seen: unknown[] = [];
+  const app = { id: "myApp" } as unknown as AppApi;
+  const handler: ActionHandler = (input, a) => {
+    seen.push({ body: input.body, method: input.req.method, app: a });
+    return { status: 201, body: { ok: true } };
+  };
+  const { router } = build(
+    [{ path: "/app/actions/cancel", module: "actions/cancel.ts" }],
+    { "/app/actions/cancel.ts": { default: handler } },
+    app,
+  );
+  const res = await router(req("POST", "/app/actions/cancel", { body: JSON.stringify({ key: "k1" }) }));
+  assert.equal(res.status, 201);
+  assert.deepEqual(JSON.parse(res.body!), { ok: true });
+  assert.deepEqual(seen, [{ body: { key: "k1" }, method: "POST", app }]);
+});
+
+test("empty body parses to {} and a void return is 204", async () => {
+  const bodies: unknown[] = [];
+  const { router } = build(
+    [{ path: "/app/actions/ping", module: "m.ts" }],
+    { "/app/m.ts": { default: (i: { body: unknown }) => { bodies.push(i.body); } } },
+  );
+  const res = await router(req("POST", "/app/actions/ping"));
+  assert.equal(res.status, 204);
+  assert.equal(res.body, undefined);
+  assert.deepEqual(bodies, [{}]);
+});
+
+test("invalid JSON body is rejected with 400 before the handler runs", async () => {
+  let called = false;
+  const { router, imported } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { default: () => { called = true; } } },
+  );
+  const res = await router(req("POST", "/a", { body: "{not json" }));
+  assert.equal(res.status, 400);
+  assert.match(res.body!, /must be JSON/);
+  assert.equal(called, false);
+  assert.deepEqual(imported, []); // module not even loaded
+});
+
+test("a thrown handler error becomes a 500 with the message", async () => {
+  const { router } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { default: () => { throw new Error("boom"); } } },
+  );
+  const res = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(res.status, 500);
+  assert.match(res.body!, /boom/);
+});
+
+test("a module that fails to load yields a 500", async () => {
+  const { router, logs } = build([{ path: "/a", module: "missing.ts" }], {});
+  const res = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(res.status, 500);
+  assert.match(res.body!, /failed to load/);
+  assert.ok(logs.some((l) => l.level === "error"));
+});
+
+test("a module with no default/handler export yields a 500", async () => {
+  const { router } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { notAHandler: () => ({}) } },
+  );
+  const res = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(res.status, 500);
+  assert.match(res.body!, /no default function/);
+});
+
+test("the module is imported once and cached across requests", async () => {
+  const { router, imported } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: 1 }) } },
+  );
+  await router(req("POST", "/a", { body: "{}" }));
+  await router(req("POST", "/a", { body: "{}" }));
+  assert.deepEqual(imported, ["/app/m.ts"]);
+});
+
+test("method defaults to POST; a GET does not match", async () => {
+  const { router } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "ok" }) } },
+  );
+  const res = await router(req("GET", "/a"));
+  assert.equal(res.status, 404);
+});
+
+test("a custom method is honored", async () => {
+  const { router } = build(
+    [{ path: "/a", method: "PUT", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "ok" }) } },
+  );
+  assert.equal((await router(req("PUT", "/a", { body: "{}" }))).status, 200);
+  assert.equal((await router(req("POST", "/a", { body: "{}" }))).status, 404);
+});
+
+test("prefix routes match by path prefix and stay boundary-safe", async () => {
+  const { router } = build(
+    // declared without a trailing slash — the mount adds one so it can't over-match
+    [{ path: "/hooks", prefix: true, module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "hooked" }) } },
+  );
+  const hit = await router(req("POST", "/hooks/github", { body: "{}" }));
+  assert.equal(hit.status, 200);
+  assert.equal(JSON.parse(hit.body!), "hooked");
+  // "/hooks2" must NOT match "/hooks" (raw startsWith would have over-matched)
+  assert.equal((await router(req("POST", "/hooks2", { body: "{}" }))).status, 404);
+});
+
+test("an absolute module path is used as-is (not joined to root)", async () => {
+  const { router, imported } = build(
+    [{ path: "/a", module: "/abs/m.ts" }],
+    { "/abs/m.ts": { default: () => ({ body: 1 }) } },
+  );
+  await router(req("POST", "/a", { body: "{}" }));
+  assert.deepEqual(imported, ["/abs/m.ts"]);
+});
+
+test("declarations missing path or module are skipped with a warning", () => {
+  const { router, logs } = build(
+    [{ path: "/a" } as unknown as { path: string; module: string }],
+    {},
+  );
+  void router;
+  assert.ok(logs.some((l) => l.level === "warn"));
+});
+
+test("a manifest path without a leading slash is normalized to match", async () => {
+  const { router } = build(
+    [{ path: "app/actions/go", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "ok" }) } },
+  );
+  const res = await router(req("POST", "/app/actions/go", { body: "{}" }));
+  assert.equal(res.status, 200);
+});
+
+test("a rejected import is evicted from the cache so a later load can succeed", async () => {
+  let attempt = 0;
+  const imported: string[] = [];
+  const ctx = {
+    root: "/app",
+    manifest: { schemaVersion: 1, id: "t", name: "T", actions: [{ path: "/a", module: "m.ts" }] },
+    host: {
+      importModule: (path: string) => {
+        imported.push(path);
+        attempt += 1;
+        if (attempt === 1) return Promise.reject(new Error("transient"));
+        return Promise.resolve({ default: () => ({ body: "ok" }) });
+      },
+      log: () => {},
+    },
+  } as unknown as import("../context.ts").RuntimeContext;
+  const router = makeRouter(mountActions(ctx, {} as import("../context.ts").AppApi).routes) as unknown as (
+    r: HttpRequest,
+  ) => Promise<{ status?: number; body?: string }>;
+  const first = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(first.status, 500); // transient failure surfaces
+  const second = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(second.status, 200); // retry re-imports and succeeds (cache was evicted)
+  assert.deepEqual(imported, ["/app/m.ts", "/app/m.ts"]);
+});
+
+test("a prefix route at the root path does not become //", async () => {
+  const { router } = build(
+    [{ path: "/", prefix: true, module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "root" }) } },
+  );
+  const res = await router(req("POST", "/anything/at/all", { body: "{}" }));
+  assert.equal(res.status, 200);
+  assert.equal(JSON.parse(res.body!), "root");
+});
+
+test("method is trimmed and falls back to POST for whitespace", async () => {
+  const { router } = build(
+    [{ path: "/a", method: "  post  ", module: "m.ts" }, { path: "/b", method: "   ", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "ok" }) } },
+  );
+  assert.equal((await router(req("POST", "/a", { body: "{}" }))).status, 200);
+  assert.equal((await router(req("POST", "/b", { body: "{}" }))).status, 200);
+});

package/src/runtime/core/modules/actions.ts

@@ -0,0 +1,161 @@
+// actions — per-app action handler files (ADR 0055 phase 3). The pages surface serves
+// generic start/cancel/message actions; a real app usually needs to wrap those with
+// business logic (register a domain row before starting, reconcile app-owned rest state
+// on cancel, correlate a message to an aggregate). An app declares such overrides in the
+// manifest `actions[]` and authors a small module per action. Each module is injected with
+// the app's `AppApi` (typed datasource + engine + sdk + host utils) — the same contract as
+// a worker handler — so the handler code reads exactly like the app's own service layer.
+//
+// Precedence: action routes are mounted BEFORE the generic pages action routes (the router
+// is first-match-wins), so an override at `/app/actions/cancel` shadows the generic one,
+// while an unmatched process still falls through to the generic `/app/actions/start/` route.
+
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import type { ActionDecl } from "../manifest.ts";
+import { json, normalizeRoutePath, type Route } from "../router.ts";
+
+/** The request handed to an action handler: the raw request plus its parsed JSON body. */
+export interface ActionRequest {
+  /** The raw HTTP request (method, path, query, headers). */
+  req: HttpRequest;
+  /**
+   * The request body parsed as JSON (`{}` when the body is empty). A body that is present
+   * but not valid JSON is rejected with `400` before the handler runs.
+   */
+  body: unknown;
+}
+
+/** What an action handler returns; the runtime serializes `body` as JSON. */
+export interface ActionResult {
+  /** HTTP status. Default `200`, or `204` when the handler returns nothing. */
+  status?: number;
+  /** Response payload, serialized as JSON. Omit for an empty response. */
+  body?: unknown;
+  /** Response headers merged over `content-type: application/json`. */
+  headers?: Record<string, string>;
+}
+
+/**
+ * An app-authored action handler: the parsed request plus the injected app API. Return an
+ * {@link ActionResult}, or nothing for an empty `204`. Throwing yields a `500` with the
+ * error message.
+ */
+export type ActionHandler = (
+  input: ActionRequest,
+  app: AppApi,
+) => Promise<ActionResult | void> | ActionResult | void;
+
+/**
+ * Resolve an action handler from a loaded module, in priority order:
+ *   1. `default` (when it is a function — the common one-handler-per-file case)
+ *   2. a named export `handler`
+ */
+export function resolveActionHandler(mod: Record<string, unknown>): ActionHandler | undefined {
+  if (typeof mod.default === "function") return mod.default as ActionHandler;
+  if (typeof mod.handler === "function") return mod.handler as ActionHandler;
+  return undefined;
+}
+
+export interface ActionsHandle {
+  readonly name: string;
+  routes: Route[];
+  describe(): Record<string, unknown>;
+}
+
+/**
+ * Mount the declared action handlers. Each declaration contributes one route; the handler
+ * module is imported lazily (and cached) on first request, so a missing or malformed module
+ * surfaces as a clear `500` on that route rather than failing the whole boot.
+ */
+export function mountActions(ctx: RuntimeContext, app: AppApi): ActionsHandle {
+  const decls = (ctx.manifest.actions ?? []) as ActionDecl[];
+  const routes: Route[] = [];
+  const mounted: Array<{ path: string; method: string; module: string; prefix: boolean }> = [];
+
+  const joinRoot = (p: string): string =>
+    p.startsWith("/") ? p : `${ctx.root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
+
+  // Cache module loads so a module reused across several declarations is imported once.
+  const moduleCache = new Map<string, Promise<Record<string, unknown>>>();
+  const loadModule = (path: string): Promise<Record<string, unknown>> => {
+    const key = joinRoot(path);
+    let pending = moduleCache.get(key);
+    if (!pending) {
+      // Evict the entry if the import rejects, so a transient failure doesn't
+      // permanently wedge the route (a cached rejected Promise would reject forever).
+      pending = ctx.host.importModule(key).catch((err) => {
+        moduleCache.delete(key);
+        throw err;
+      });
+      moduleCache.set(key, pending);
+    }
+    return pending;
+  };
+
+  for (const decl of decls) {
+    if (!decl?.path || !decl?.module) {
+      ctx.host.log("warn", "skipping action: needs both `path` and `module`", {
+        action: decl as unknown as Record<string, unknown>,
+      });
+      continue;
+    }
+    const method = (decl.method ?? "POST").trim().toUpperCase() || "POST";
+    const prefix = decl.prefix === true;
+    // The router's prefix match is a raw `startsWith`, so a prefix route needs a trailing
+    // slash to stay boundary-safe (otherwise "/hooks" would also match "/hooks2"). Exact
+    // routes keep the normalized (trailing-slash-stripped) path. Guard the root case so a
+    // prefix path of "/" doesn't become "//" (which would never match).
+    const base = normalizeRoutePath(decl.path, decl.path);
+    const path = prefix ? (base.endsWith("/") ? base : `${base}/`) : base;
+
+    routes.push({
+      method,
+      path,
+      prefix,
+      source: `actions:${decl.module}`,
+      handler: async (req: HttpRequest) => {
+        const raw = await req.text();
+        let body: unknown;
+        try {
+          body = raw ? JSON.parse(raw) : {};
+        } catch {
+          return json({ error: "request body must be JSON" }, 400);
+        }
+
+        let handler: ActionHandler | undefined;
+        try {
+          handler = resolveActionHandler(await loadModule(decl.module));
+        } catch (e) {
+          ctx.host.log("error", "action handler module failed to load", {
+            path,
+            module: decl.module,
+            error: String((e as Error)?.message ?? e),
+          });
+          return json({ error: `action handler ${decl.module} failed to load` }, 500);
+        }
+        if (!handler) {
+          return json(
+            { error: `action handler ${decl.module} exports no default function or named \`handler\`` },
+            500,
+          );
+        }
+
+        try {
+          const result = await handler({ req, body }, app);
+          if (!result) return { status: 204 };
+          return {
+            status: result.status ?? 200,
+            headers: { "content-type": "application/json", ...(result.headers ?? {}) },
+            body: result.body === undefined ? undefined : JSON.stringify(result.body),
+          };
+        } catch (e) {
+          return json({ error: String((e as Error)?.message ?? e) }, 500);
+        }
+      },
+    });
+    mounted.push({ path, method, module: decl.module, prefix });
+  }
+
+  return { name: "actions", routes, describe: () => ({ actions: mounted }) };
+}

package/src/runtime/core/modules/gateway.ts

@@ -68,7 +68,8 @@ export interface DataSource {
   table<T extends object = Row>(name: string, pk?: string): Table<T>;
 }
 
-function quoteIdent(name: string): string {
+/** Double-quote a SQL identifier (table/column), escaping embedded quotes. */
+export function quoteIdent(name: string): string {
   return `"${name.replaceAll('"', '""')}"`;
 }