@nanobpm/urban 0.16.0 → 0.17.0

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

@@ -1,138 +1,8 @@
 import type { HostContext } from "./host.ts";
-export interface DataSource {
-    driver: string;
-    url: string;
-    migrations?: string;
-}
-export interface TypeField {
-    type: string;
-    optional?: boolean;
-}
-export interface DomainType {
-    name?: string;
-    table?: string;
-    fields?: Record<string, TypeField>;
-}
-export interface WorkerDecl {
-    /** Job/task type the worker subscribes to. Schema allows `taskType` or `type`. */
-    taskType?: string;
-    type?: string;
-    /** Path to the handler module, relative to the app root. Mutually exclusive with `llm`. */
-    handler?: string;
-    /** Name of an `llm[]` binding used as the worker (LLM-as-worker). Mutually exclusive with `handler`. */
-    llm?: string;
-}
-/**
- * One named LLM binding (`llm.<id>` in the manifest). A binding is usable as a worker
- * (LLM-as-worker, ADR 0022 §E role 1) or as a chat surface agent. `provider` selects how
- * the endpoint is resolved (`"env"` reads it from the environment); `model` is typically
- * an env template. When `output.decision` is set, the model's JSON reply is fed through
- * that DMN decision (the "rails") and the decision's output is returned instead.
- */
-export interface LlmBinding {
-    /** Provider selector. `"env"` resolves an OpenAI-compatible endpoint from the environment. */
-    provider: string;
-    /** Model id, typically an env template (e.g. `${NANO_APP_LLM_MODEL}`). */
-    model: string;
-    /** Constrains the model's structured output — currently a DMN decision id (the rails). */
-    output?: {
-        decision?: string;
-    };
-    /** Action-API tools the agent may call (chat-agent role; unused by the worker role). */
-    tools?: string[];
-}
-export interface TriggerDecl {
-    id: string;
-    type: string;
-    path?: string;
-    auth?: string;
-    /** cron: the 5-field crontab spec (UTC), e.g. "0 6 * * *". */
-    spec?: string;
-    /** cron catch-up policy for fires missed while the app was down. Default "skip". */
-    onMissed?: "skip" | "once" | "all";
-    /** Source-kind-specific settings (e.g. file `{ pollMs }`). */
-    config?: Record<string, unknown>;
-    /** Name of a connections[] entry supplying this source's credentials. */
-    connection?: string;
-    /** Maps the event to one engine call: start a process OR publish a message (ADR 0025 §1). */
-    action?: {
-        /** Process id/name to start. */
-        start?: string;
-        /** messageName to publish as a CorrelateMessage. */
-        message?: string;
-        /** correlationKey (literal, or `= body.path`) for a message action. */
-        correlationKey?: string;
-        /**
-         * Variables for the started instance / published message. Per the manifest schema
-         * (`#/$defs/triggerAction.variables`) this is a FEEL string over the event body
-         * (e.g. `= body.payload`); an inline object literal is also accepted for convenience.
-         */
-        variables?: string | Record<string, unknown>;
-    };
-}
-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 {
-    $schema?: string;
-    schemaVersion: 1;
-    id: string;
-    name: string;
-    codename?: string;
-    runtime?: {
-        engine?: string;
-        node?: string;
-    };
-    models?: {
-        processes?: string[];
-        decisions?: string[];
-        forms?: string[];
-    };
-    data?: {
-        default?: string;
-        sources?: Record<string, DataSource>;
-    };
-    types?: Record<string, DomainType>;
-    triggers?: TriggerDecl[];
-    connections?: Record<string, {
-        type: string;
-        [k: string]: unknown;
-    }>;
-    surfaces?: Record<string, SurfaceDecl>;
-    actions?: ActionDecl[];
-    workers?: WorkerDecl[];
-    llm?: Record<string, LlmBinding>;
-    security?: Record<string, unknown>;
-    [k: string]: unknown;
-}
-/** The normalised job type for a worker declaration (`taskType` preferred, `type` fallback). */
-export declare function workerJobType(w: WorkerDecl): string | undefined;
+import type { AppManifest, Worker } from "@nanobpm/nano-app-schema";
+export type { ActionDecl, AppManifest, ChatSurface, Connection, Data, DataSource, DomainField, DomainType, LlmBinding, Models, PagesSurface, Runtime, Security, Surfaces, TaskInboxSurface, Trigger, TriggerAction, Worker, } from "@nanobpm/nano-app-schema";
+/** The job type a worker subscribes to (schema key: `taskType`). */
+export declare function workerJobType(w: Worker): string | undefined;
 /**
  * Expand `${VAR}` and `${VAR:-default}` placeholders in a string using `lookup`.
  * Unset vars with no default expand to "" (matching common shell semantics).

package/dist/runtime/core/manifest.js

@@ -1,10 +1,15 @@
-// Manifest types (a hand-mirrored subset of nano-app.schema.json — the block shapes the
-// runtime actually consumes) plus env-placeholder expansion and a host-driven loader.
-// The schema itself (src/schema/nano-app.schema.json) remains the source of truth for
-// validation; see validate.ts.
-/** The normalised job type for a worker declaration (`taskType` preferred, `type` fallback). */
+// Manifest types + env-placeholder expansion + a host-driven loader.
+//
+// The App manifest contract (nano.app.json) is owned by the canonical
+// @nanobpm/nano-app-schema package (ADR 0027): the JSON Schema and its generated
+// TypeScript types are the single source of truth. This module re-exports those
+// types (type-only, so nothing from the package is pulled into the runtime
+// bundle) and adds the runtime-side helpers the App loader needs. No shape is
+// hand-mirrored here — that eliminated the schema/type drift the vendored copies
+// used to cause.
+/** The job type a worker subscribes to (schema key: `taskType`). */
 export function workerJobType(w) {
-    return w.taskType ?? w.type;
+    return w.taskType;
 }
 const ENV_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
 /**

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

@@ -48,8 +48,17 @@ export class TypeRepo {
     }
     insert(row) {
         this.assertFields(row);
-        const keys = Object.keys(row);
+        // Omit keys whose value is `undefined` so the column's own `DEFAULT`/`NULL` governs;
+        // `undefined` means "not provided", never a bound value. An explicit `null` is preserved.
+        const provided = Object.keys(row);
+        const keys = provided.filter((k) => row[k] !== undefined);
         if (keys.length === 0) {
+            // A present-but-all-undefined payload throws (parity with Table.insert): the caller
+            // meant to write those values, so silently inserting a full DEFAULT row would create
+            // an unintended record. A genuinely empty `insert({})` is the explicit "default row".
+            if (provided.length > 0) {
+                throw new Error(`insert into type "${this.typeName}": no columns to insert (all values were undefined)`);
+            }
             return this.db.run(`INSERT INTO ${this.table()} DEFAULT VALUES`, []);
         }
         const cols = keys.join(", ");

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

@@ -59,8 +59,10 @@ export declare class Table<T extends object = Row> {
     readonly name: string;
     readonly pk: string;
     constructor(src: DataSource, name: string, pk?: string);
-    /** Insert one row (only the present keys are written); returns the new primary-key value
-     * (the inserted rowid for an INTEGER PRIMARY KEY). */
+    /** Insert one row; returns the new primary-key value (the inserted rowid for an INTEGER
+     * PRIMARY KEY). Keys whose value is `undefined` are omitted, so the table's own column
+     * `DEFAULT`/`NULL` governs — `undefined` means "not provided, let the schema decide", never
+     * a bound value. An explicit `null` is preserved (it stores `NULL`). */
     insert(row: Partial<T>): Promise<number | bigint>;
     /** Fetch the row with the given primary key, or `undefined`. */
     get(id: unknown): Promise<T | undefined>;
@@ -70,7 +72,9 @@ export declare class Table<T extends object = Row> {
     find(where?: Partial<T>): Promise<T[]>;
     /** The first row matching an equality filter, or `undefined`. */
     findOne(where?: Partial<T>): Promise<T | undefined>;
-    /** Patch the row with the given primary key; returns rows changed. */
+    /** Patch the row with the given primary key; returns rows changed. Keys whose value is
+     * `undefined` are skipped (that column is left unchanged); an explicit `null` clears the
+     * column to `NULL`. A patch with no defined keys is a no-op. */
     update(id: unknown, patch: Partial<T>): Promise<number>;
     /** Delete the row with the given primary key; returns rows changed. */
     delete(id: unknown): Promise<number>;

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

@@ -40,12 +40,17 @@ export class Table {
         this.name = name;
         this.pk = pk;
     }
-    /** Insert one row (only the present keys are written); returns the new primary-key value
-     * (the inserted rowid for an INTEGER PRIMARY KEY). */
+    /** Insert one row; returns the new primary-key value (the inserted rowid for an INTEGER
+     * PRIMARY KEY). Keys whose value is `undefined` are omitted, so the table's own column
+     * `DEFAULT`/`NULL` governs — `undefined` means "not provided, let the schema decide", never
+     * a bound value. An explicit `null` is preserved (it stores `NULL`). */
     async insert(row) {
-        const keys = Object.keys(row);
+        const provided = Object.keys(row);
+        const keys = provided.filter((k) => row[k] !== undefined);
         if (keys.length === 0) {
-            throw new Error(`Table(${this.name}).insert: no columns to insert`);
+            throw new Error(provided.length === 0
+                ? `Table(${this.name}).insert: no columns to insert (empty row)`
+                : `Table(${this.name}).insert: no columns to insert (all values were undefined)`);
         }
         const cols = keys.map(quoteIdent).join(", ");
         const ph = keys.map(() => "?").join(", ");
@@ -80,9 +85,11 @@ export class Table {
         const rows = await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${clause} LIMIT 1`, params);
         return rows[0];
     }
-    /** Patch the row with the given primary key; returns rows changed. */
+    /** Patch the row with the given primary key; returns rows changed. Keys whose value is
+     * `undefined` are skipped (that column is left unchanged); an explicit `null` clears the
+     * column to `NULL`. A patch with no defined keys is a no-op. */
     async update(id, patch) {
-        const keys = Object.keys(patch);
+        const keys = Object.keys(patch).filter((k) => patch[k] !== undefined);
         if (keys.length === 0)
             return 0;
         const set = keys.map((k) => `${quoteIdent(k)} = ?`).join(", ");

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

@@ -1,6 +1,5 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import { type Route } from "../router.ts";
-import type { TriggerDecl } from "../manifest.ts";
 export interface TriggersHandle extends Mounted {
     routes: Route[];
 }
@@ -38,7 +37,20 @@ export declare function resolveActionVariables(expr: unknown, scope: Scope): Rec
  * of `correlationKey`/`variables`; cron passes a minimal `{ firedAt }` body. Returns what
  * was done.
  */
-export declare function runTriggerAction(app: AppApi, action: TriggerDecl["action"], scope: Scope): Promise<{
+/**
+ * The trigger action as the *runtime* helper reads it: the fields `runTriggerAction`
+ * consumes, with `variables` permitting an inline object literal as well as a FEEL string.
+ * The manifest surface keeps `variables` string-only (a FEEL expression);
+ * `resolveActionVariables` tolerates both, so this shape matches runtime behaviour without
+ * loosening the schema. A locked `Trigger["action"]` is assignable to it.
+ */
+export interface RuntimeTriggerAction {
+    start?: string;
+    message?: string;
+    correlationKey?: string;
+    variables?: string | Record<string, unknown>;
+}
+export declare function runTriggerAction(app: AppApi, action: RuntimeTriggerAction | undefined, scope: Scope): Promise<{
     kind: "start" | "message" | "none";
     target?: string;
     correlationKey?: string;

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

@@ -75,12 +75,6 @@ function headerRecord(req) {
     req.headers.forEach((v, k) => (out[k.toLowerCase()] = v));
     return out;
 }
-/**
- * Fire a trigger's action against the engine: start a process or publish a message
- * (ADR 0025 §1). `scope` supplies the event body/headers/query for FEEL-ish resolution
- * of `correlationKey`/`variables`; cron passes a minimal `{ firedAt }` body. Returns what
- * was done.
- */
 export async function runTriggerAction(app, action, scope) {
     if (!action)
         return { kind: "none" };

package/dist/runtime/core/validate.js

@@ -1,12 +1,13 @@
-// 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" };
+// Manifest validation. We deliberately avoid a heavyweight JSON-Schema engine here to keep
+// core lean and runtime-agnostic. Instead we drive validation *from* the canonical
+// nano-app.schema.json (the ADR 0027 source of truth, imported from the
+// @nanobpm/nano-app-schema package) 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). Importing the shared
+// schema JSON means the envelope check tracks the published schema and can't drift from it
+// silently — the whole point of consuming the package rather than vendoring a copy.
+import schema from "@nanobpm/nano-app-schema/schema" with { type: "json" };
 import { workerJobType } from "./manifest.js";
 export class ManifestValidationError extends Error {
     issues;
@@ -53,7 +54,7 @@ export function collectManifestIssues(m) {
     if (Array.isArray(man.workers)) {
         man.workers.forEach((w, i) => {
             if (!workerJobType(w)) {
-                issues.push({ path: `workers[${i}]`, message: "missing taskType/type" });
+                issues.push({ path: `workers[${i}]`, message: "missing taskType" });
             }
             // The schema allows a worker backed by either a `handler` file or an `llm`
             // binding (oneOf). Require exactly one — don't force `handler`.

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 { ActionDecl, AppManifest, DataSource, DomainType, LlmBinding, SurfaceDecl, TriggerDecl, TypeField, WorkerDecl, } from "./core/manifest.ts";
+export type { ActionDecl, AppManifest, ChatSurface, DataSource, DomainField, DomainType, LlmBinding, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } 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, WatchHandle, WorkerSubscription, } from "./core/host.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.16.0",
+  "version": "0.17.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",
@@ -55,14 +55,15 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node -e \"const fs=require('fs');fs.mkdirSync('dist/runtime/schema',{recursive:true});fs.copyFileSync('src/runtime/schema/nano-app.schema.json','dist/runtime/schema/nano-app.schema.json')\"",
+    "build": "tsc -p tsconfig.build.json",
     "prepack": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "node --test --experimental-strip-types \"src/**/*.test.ts\"",
     "test:deno": "deno test -A --no-check src/"
   },
   "dependencies": {
-    "@nanobpm/nano-sdk": "^1.2.2",
+    "@nanobpm/nano-app-schema": "^0.1.0",
+    "@nanobpm/nano-sdk": "^1.2.3",
     "@nanobpm/workflow": "^0.7.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
     "create-urban-app": "^0.5.0"

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

@@ -24,8 +24,7 @@ test("parseManifest expands env in place", () => {
   assert.equal(m.name, "App");
 });
 
-test("workerJobType prefers taskType then type", () => {
+test("workerJobType returns the taskType", () => {
   assert.equal(workerJobType({ taskType: "a", handler: "h" }), "a");
-  assert.equal(workerJobType({ type: "b", handler: "h" }), "b");
-  assert.equal(workerJobType({ handler: "h" }), undefined);
+  assert.equal(workerJobType({ taskType: "llm-job", llm: "gpt" }), "llm-job");
 });

package/src/runtime/core/manifest.ts

@@ -1,139 +1,40 @@
-// Manifest types (a hand-mirrored subset of nano-app.schema.json — the block shapes the
-// runtime actually consumes) plus env-placeholder expansion and a host-driven loader.
-// The schema itself (src/schema/nano-app.schema.json) remains the source of truth for
-// validation; see validate.ts.
+// Manifest types + env-placeholder expansion + a host-driven loader.
+//
+// The App manifest contract (nano.app.json) is owned by the canonical
+// @nanobpm/nano-app-schema package (ADR 0027): the JSON Schema and its generated
+// TypeScript types are the single source of truth. This module re-exports those
+// types (type-only, so nothing from the package is pulled into the runtime
+// bundle) and adds the runtime-side helpers the App loader needs. No shape is
+// hand-mirrored here — that eliminated the schema/type drift the vendored copies
+// used to cause.
 
 import type { HostContext } from "./host.ts";
-
-export interface DataSource {
-  driver: string;
-  url: string;
-  migrations?: string;
-}
-
-export interface TypeField {
-  type: string;
-  optional?: boolean;
-}
-
-export interface DomainType {
-  name?: string;
-  table?: string;
-  fields?: Record<string, TypeField>;
-}
-
-export interface WorkerDecl {
-  /** Job/task type the worker subscribes to. Schema allows `taskType` or `type`. */
-  taskType?: string;
-  type?: string;
-  /** Path to the handler module, relative to the app root. Mutually exclusive with `llm`. */
-  handler?: string;
-  /** Name of an `llm[]` binding used as the worker (LLM-as-worker). Mutually exclusive with `handler`. */
-  llm?: string;
-}
-
-/**
- * One named LLM binding (`llm.<id>` in the manifest). A binding is usable as a worker
- * (LLM-as-worker, ADR 0022 §E role 1) or as a chat surface agent. `provider` selects how
- * the endpoint is resolved (`"env"` reads it from the environment); `model` is typically
- * an env template. When `output.decision` is set, the model's JSON reply is fed through
- * that DMN decision (the "rails") and the decision's output is returned instead.
- */
-export interface LlmBinding {
-  /** Provider selector. `"env"` resolves an OpenAI-compatible endpoint from the environment. */
-  provider: string;
-  /** Model id, typically an env template (e.g. `${NANO_APP_LLM_MODEL}`). */
-  model: string;
-  /** Constrains the model's structured output — currently a DMN decision id (the rails). */
-  output?: { decision?: string };
-  /** Action-API tools the agent may call (chat-agent role; unused by the worker role). */
-  tools?: string[];
-}
-
-export interface TriggerDecl {
-  id: string;
-  type: string;
-  path?: string;
-  auth?: string;
-  /** cron: the 5-field crontab spec (UTC), e.g. "0 6 * * *". */
-  spec?: string;
-  /** cron catch-up policy for fires missed while the app was down. Default "skip". */
-  onMissed?: "skip" | "once" | "all";
-  /** Source-kind-specific settings (e.g. file `{ pollMs }`). */
-  config?: Record<string, unknown>;
-  /** Name of a connections[] entry supplying this source's credentials. */
-  connection?: string;
-  /** Maps the event to one engine call: start a process OR publish a message (ADR 0025 §1). */
-  action?: {
-    /** Process id/name to start. */
-    start?: string;
-    /** messageName to publish as a CorrelateMessage. */
-    message?: string;
-    /** correlationKey (literal, or `= body.path`) for a message action. */
-    correlationKey?: string;
-    /**
-     * Variables for the started instance / published message. Per the manifest schema
-     * (`#/$defs/triggerAction.variables`) this is a FEEL string over the event body
-     * (e.g. `= body.payload`); an inline object literal is also accepted for convenience.
-     */
-    variables?: string | Record<string, unknown>;
-  };
-}
-
-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 {
-  $schema?: string;
-  schemaVersion: 1;
-  id: string;
-  name: string;
-  codename?: string;
-  runtime?: { engine?: string; node?: string };
-  models?: { processes?: string[]; decisions?: string[]; forms?: string[] };
-  data?: { default?: string; sources?: Record<string, DataSource> };
-  types?: Record<string, DomainType>;
-  triggers?: TriggerDecl[];
-  connections?: Record<string, { type: string; [k: string]: unknown }>;
-  surfaces?: Record<string, SurfaceDecl>;
-  actions?: ActionDecl[];
-  workers?: WorkerDecl[];
-  llm?: Record<string, LlmBinding>;
-  security?: Record<string, unknown>;
-  [k: string]: unknown;
-}
-
-/** The normalised job type for a worker declaration (`taskType` preferred, `type` fallback). */
-export function workerJobType(w: WorkerDecl): string | undefined {
-  return w.taskType ?? w.type;
+import type { AppManifest, Worker } from "@nanobpm/nano-app-schema";
+
+export type {
+  ActionDecl,
+  AppManifest,
+  ChatSurface,
+  Connection,
+  Data,
+  DataSource,
+  DomainField,
+  DomainType,
+  LlmBinding,
+  Models,
+  PagesSurface,
+  Runtime,
+  Security,
+  Surfaces,
+  TaskInboxSurface,
+  Trigger,
+  TriggerAction,
+  Worker,
+} from "@nanobpm/nano-app-schema";
+
+/** The job type a worker subscribes to (schema key: `taskType`). */
+export function workerJobType(w: Worker): string | undefined {
+  return w.taskType;
 }
 
 const ENV_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;

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

@@ -60,8 +60,19 @@ export class TypeRepo {
 
   insert(row: Record<string, unknown>): { changes: number; lastInsertRowid: number | bigint } {
     this.assertFields(row);
-    const keys = Object.keys(row);
+    // Omit keys whose value is `undefined` so the column's own `DEFAULT`/`NULL` governs;
+    // `undefined` means "not provided", never a bound value. An explicit `null` is preserved.
+    const provided = Object.keys(row);
+    const keys = provided.filter((k) => row[k] !== undefined);
     if (keys.length === 0) {
+      // A present-but-all-undefined payload throws (parity with Table.insert): the caller
+      // meant to write those values, so silently inserting a full DEFAULT row would create
+      // an unintended record. A genuinely empty `insert({})` is the explicit "default row".
+      if (provided.length > 0) {
+        throw new Error(
+          `insert into type "${this.typeName}": no columns to insert (all values were undefined)`,
+        );
+      }
       return this.db.run(`INSERT INTO ${this.table()} DEFAULT VALUES`, []);
     }
     const cols = keys.join(", ");

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

@@ -162,3 +162,60 @@ test("query/exec run raw parameterised SQL", async () => {
     assert.equal(Number((rows[0] as { total: number }).total), 42);
   });
 });
+
+test("insert omits undefined-valued keys so the column DEFAULT applies", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    // `total` is `NOT NULL DEFAULT 0`; passing it as undefined must omit the column
+    // (not bind NULL, which would violate NOT NULL), letting the DEFAULT fill it.
+    const id = await orders.insert({ status: "new", total: undefined });
+    assert.equal((await orders.get(id))?.total, 0);
+  });
+});
+
+test("insert preserves an explicit null; omits undefined", async () => {
+  await withGateway(async (src) => {
+    await src.exec("CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT, tag TEXT DEFAULT 'none')");
+    const notes = src.table("notes");
+    const id = await notes.insert({ body: null, tag: undefined });
+    const row = await notes.get(id);
+    assert.equal(row?.body, null); // explicit null is stored as NULL
+    assert.equal(row?.tag, "none"); // undefined omitted → column DEFAULT
+  });
+});
+
+test("update skips undefined keys and clears on explicit null", async () => {
+  await withGateway(async (src) => {
+    await src.exec("CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT, tag TEXT DEFAULT 'none')");
+    const notes = src.table("notes");
+    const id = await notes.insert({ body: "hello", tag: "x" });
+    // tag:undefined must be left unchanged; body updated.
+    await notes.update(id, { tag: undefined, body: "world" });
+    let row = await notes.get(id);
+    assert.equal(row?.body, "world");
+    assert.equal(row?.tag, "x");
+    // explicit null clears the column.
+    await notes.update(id, { body: null });
+    row = await notes.get(id);
+    assert.equal(row?.body, null);
+    // a patch of only-undefined keys is a no-op.
+    assert.equal(await notes.update(id, { tag: undefined }), 0);
+  });
+});
+
+test("insert throws when every provided value is undefined", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    await assert.rejects(
+      orders.insert({ status: undefined, total: undefined }),
+      /all values were undefined/,
+    );
+  });
+});
+
+test("insert throws a distinct message for a genuinely empty row", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    await assert.rejects(orders.insert({} as Partial<Order>), /empty row/);
+  });
+});