@nanobpm/urban 0.24.1 → 0.26.0

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

@@ -1,9 +1,12 @@
 import type { HostContext } from "../host.ts";
 import type { AppManifest } from "../manifest.ts";
-/** The DB-manager op protocol's known op set. `domaintypes` is part of the protocol but is not
- * yet handled here (it errors clearly — see the file header); every other op is dispatched by
- * `runDataOp`. Typing `op` as this union (instead of `string`) gives SDK/console callers
- * type-safety and catches typos at compile time. */
+import { type ShapeDecl } from "../../../toolkit/derivers/shapes.ts";
+import { type WorkerBindingDecl } from "../../../toolkit/derivers/worker-io.ts";
+import { type MessageBindingDecl } from "../../../toolkit/derivers/messages.ts";
+import { type MetaDecl } from "../../../toolkit/derivers/meta.ts";
+/** The DB-manager op protocol's known op set — every op (including `domaintypes`) is dispatched by
+ * `runDataOp`. Typing `op` as this union (instead of `string`) gives SDK/console callers type-safety
+ * and catches typos at compile time. */
 export type DataOp = "sources" | "schema" | "query" | "exec" | "script" | "migrations" | "migrate" | "domaintypes";
 export interface DataRequest {
     op: DataOp;
@@ -11,6 +14,27 @@ export interface DataRequest {
     sql?: string;
     params?: unknown[];
     statements?: string[];
+    /**
+     * `domaintypes`: persist the derived artifacts (default true). A `write:false` request is the
+     * latency-sensitive composer preview — it introspects WITHOUT migrating the DB first and returns
+     * only the artifact *content* (never a DB side-effect per keystroke). `urban data` never writes
+     * files itself (the host is read-only); the caller persists the returned content when `write` is
+     * not false. This flag only gates the pre-introspection migration side-effect.
+     */
+    write?: boolean;
+    /** `domaintypes`: the model-derived worker-IO map (`taskType → {in,out,headerKeys}`), scanned
+     * from the process models by the caller. Overlaid on the manifest `workers[]` (authoritative for
+     * the envelope). Absent → the manifest projection alone. */
+    derivedWorkers?: WorkerBindingDecl[];
+    /** `domaintypes`: the model-derived message-payload map (`messageName → {in,out}`), scanned from
+     * the models' `bpmn:message` envelopes. Authoritative (no manifest projection). */
+    derivedMessages?: MessageBindingDecl[];
+    /** `domaintypes`: the model-derived composed shapes (`nano:shape`). Each is resolved through the
+     * fuse into a flat domain type folded into the `types` registry. Absent → no shapes. */
+    derivedShapes?: ShapeDecl[];
+    /** `domaintypes`: the model-derived model-level metadata (`nano:meta`). Folded into `meta.ts` and
+     * the structured `domain.json`. Absent → no metadata. */
+    derivedMeta?: MetaDecl[];
 }
 /** One datasource the manifest declares, resolved against the environment (env templates in
  * `driver`/`url` are already expanded by `loadManifest`). Mirrors the console's `ResolvedSource`

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

@@ -14,14 +14,25 @@
 //   op = "sources" | "schema" | "query" | "exec" | "script" | "migrations" | "migrate"
 //      | "domaintypes"
 //
-// `domaintypes` (live-schema reification + shape resolution) is a known protocol op but is
-// intentionally NOT handled here yet — it is ported to `urban data` in a follow-up (PR 2 of
-// #576) and errors clearly for now.
+// `domaintypes` (live-schema reification + shape resolution) composes the domain reifier from the
+// pure toolkit derivers (ported from the console's `domain_types.ts`, host dry-out #576); it never
+// writes files (the host is read-only) — it returns every artifact's content and the caller
+// persists it.
 import { isRecord } from "../guards.js";
 import { loadManifest } from "../manifest.js";
 import { validateManifest } from "../validate.js";
 import { makeGateway } from "./gateway.js";
 import { applyMigrations, MIGRATIONS_TABLE, openSqliteSource, resolveAppPath } from "./datasource.js";
+// The `domaintypes` op composes the domain reifier from the pure toolkit derivers (single source of
+// truth for the IDE's codegen, host dry-out nano-bpm#576). Imported directly from the deriver files
+// (not the `toolkit/` barrel, which pulls the Node fs IO) so core stays free of `node:*`/Deno; the
+// derivers' only core dependency is the gateway's `TableMeta`/`ColumnMeta` *types*, which erase.
+import { GENERATED_DIR } from "../../../toolkit/artifact.js";
+import { DOMAIN_BINDINGS, emitDomainBindings, emitDomainModel, registryFromManifest, } from "../../../toolkit/derivers/domain.js";
+import { DOMAIN_MODEL_JSON, emitDomainModelJson, resolveShapes, } from "../../../toolkit/derivers/shapes.js";
+import { DOMAIN_DTS, emitWorkerBindings, emitWorkerBindingsRuntime, overlayDerivedWorkerIo, WORKER_BINDINGS_DTS, WORKER_BINDINGS_TS, } from "../../../toolkit/derivers/worker-io.js";
+import { emitMessageBindings, emitMessageBindingsRuntime, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "../../../toolkit/derivers/messages.js";
+import { emitMeta, META_TS } from "../../../toolkit/derivers/meta.js";
 const DEFAULT_MIGRATIONS_DIR = "db/migrations";
 /** JSON-safe a value: BigInt → number (when lossless) or string, recursing objects/arrays. SQLite
  * reports `lastInsertRowid` (and INTEGER columns) as BigInt, which `JSON.stringify` cannot encode. */
@@ -222,8 +233,115 @@ export async function runDataOp(host, root, manifestPath, req) {
             }
         }
         case "domaintypes": {
-            throw new Error("`domaintypes` is not yet implemented in `urban data` — the Nano console still serves it " +
-                "(tracked as PR 2 of nano-bpm#576)");
+            // ADR 0029 §4.1/§4.2/§6 + ADR 0040 §9/§10: reify the domain model from the *live* schema.
+            // Union every declared datasource (the table spine), fold in the manifest `types` registry and
+            // the model's composed `nano:shape`s (resolved through the fuse), and derive the worker/message
+            // typed accessors. Unlike the vendored data_cli, this op NEVER writes files (the host is
+            // read-only): it returns every artifact's content and the caller persists it. `write:false` is
+            // the latency-sensitive composer preview — it skips the pre-introspection migration so a
+            // debounced keystroke has no DB side-effect and pays only for `text` + `shapeDiagnostics`.
+            const { default: def, sources } = listSources(manifest);
+            const persist = req.write !== false;
+            // Introspect each sqlite source's live schema. When persisting, migrate first (the domain
+            // model is derived from `gw.schema()`, so a regen that raced ahead of `migrate` on a fresh DB
+            // would emit an empty `Domain`); the migration runs on the shared `_urban_migrations` ledger.
+            const migrated = {};
+            const schemas = [];
+            for (const s of sources) {
+                if (String(s.driver) !== "sqlite")
+                    continue; // only sqlite is introspectable (see openGateway)
+                const { gw, db } = await openGateway(host, root, manifest, s.name);
+                try {
+                    if (persist) {
+                        const applied = await applyMigrations(host, db, root, s.migrations ?? DEFAULT_MIGRATIONS_DIR);
+                        if (applied.length)
+                            migrated[s.name] = applied;
+                    }
+                    schemas.push({ source: s.name, tables: await gw.schema() });
+                }
+                finally {
+                    db.close();
+                }
+            }
+            const types = registryFromManifest(manifest);
+            // Snapshot the manifest `types` *before* folding the resolved shapes so `domain.json` can tag
+            // each entity with its true provenance (manifest vs model) — once folded they are
+            // indistinguishable in `types`.
+            const manifestTypesSnapshot = { ...types };
+            // Composed motion shapes (ADR 0040 §9/§10): resolve each `nano:shape` against the leaf fuse
+            // into a flat domain type and fold it into the registry *before* it feeds the domain model and
+            // the worker/message bindings, so a composed shape becomes a first-class `DomainTypes` entry.
+            // Broken shapes are omitted; their diagnostics are returned so the panel can surface them.
+            const shapeResolution = resolveShapes(req.derivedShapes ?? [], types, schemas);
+            const shapeDeclById = new Map((req.derivedShapes ?? []).map((s) => [s.id, s]));
+            const shapeEntities = [];
+            for (const [id, shapeDef] of Object.entries(shapeResolution.types)) {
+                types[id] = shapeDef;
+                shapeEntities.push({ decl: shapeDeclById.get(id) ?? { id, ops: [] }, def: shapeDef });
+            }
+            const declaredIds = Object.keys(types);
+            const text = emitDomainModel(schemas, def, types);
+            const bindings = emitDomainBindings(schemas, def);
+            const derivedMeta = req.derivedMeta ?? [];
+            const metaAccessor = emitMeta(derivedMeta);
+            // Worker-IO map (ADR 0033 §3): the model is authoritative for the envelope, so an injected
+            // `derivedWorkers` is overlaid on the manifest `workers[]` (which still carries non-IO
+            // bindings such as `llm`); absent, the manifest projection stands alone.
+            const manifestWorkers = (manifest.workers ?? []).map((w) => ({
+                taskType: w.taskType,
+                inputType: w.inputType,
+                outputType: w.outputType,
+            }));
+            const workers = req.derivedWorkers
+                ? overlayDerivedWorkerIo(manifestWorkers, req.derivedWorkers)
+                : manifestWorkers;
+            const workerBindings = emitWorkerBindings(workers, declaredIds);
+            const workerRuntime = emitWorkerBindingsRuntime();
+            // Message-payload registry (ADR 0040 slice 2): no manifest projection, so the model-derived
+            // map is authoritative and emitted directly.
+            const messages = req.derivedMessages ?? [];
+            const messageBindings = emitMessageBindings(messages, declaredIds);
+            const messageRuntime = emitMessageBindingsRuntime();
+            // The structured Fused Domain Model (`domain.json`, ADR 0040 §1): the largest artifact, so it
+            // is built only when persisting (the preview consumes only `text` + `shapeDiagnostics`).
+            const meta = derivedMeta;
+            const domainModel = persist
+                ? emitDomainModelJson({
+                    sources: schemas,
+                    default: def,
+                    manifestTypes: manifestTypesSnapshot,
+                    shapes: shapeEntities,
+                    meta,
+                    diagnostics: shapeResolution.diagnostics,
+                })
+                : null;
+            const rel = (name) => `${GENERATED_DIR}/${name}`;
+            const tables = schemas.reduce((n, s) => n + s.tables.length, 0);
+            // The returned `*Path` fields are the app-relative targets the caller writes to when
+            // persisting (null on a preview). `urban data` returns content only — persisting is the
+            // caller's job (host dry-out nano-bpm#576). The static runtime wrappers (`workers.ts`,
+            // `messages.ts`) are returned too so the caller can write them verbatim.
+            return {
+                path: persist ? rel(DOMAIN_DTS) : null,
+                text,
+                tables,
+                bindingsPath: persist ? rel(DOMAIN_BINDINGS) : null,
+                bindings,
+                workerBindingsPath: persist ? rel(WORKER_BINDINGS_DTS) : null,
+                workerBindings,
+                workerRuntimePath: persist ? rel(WORKER_BINDINGS_TS) : null,
+                workerRuntime,
+                messageBindingsPath: persist ? rel(MESSAGE_BINDINGS_DTS) : null,
+                messageBindings,
+                messageRuntimePath: persist ? rel(MESSAGE_BINDINGS_TS) : null,
+                messageRuntime,
+                metaPath: persist ? rel(META_TS) : null,
+                meta: metaAccessor,
+                domainModelPath: persist ? rel(DOMAIN_MODEL_JSON) : null,
+                domainModel,
+                migrated,
+                shapeDiagnostics: shapeResolution.diagnostics,
+            };
         }
         default:
             throw new Error(`unknown op "${req.op}"`);

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

@@ -319,7 +319,7 @@ function rendererShell(homePage) {
 </head>
 <body>
   <main id="page" data-home="${escapeAttr(homePage)}"><p class="pc-empty">Loading…</p></main>
-  <script type="module" src="/app/runtime.js"></script>
+  <script type="module" src="./app/runtime.js"></script>
 </body>
 </html>`;
 }
@@ -373,8 +373,23 @@ const RENDERER_JS = String.raw `
 const root = document.getElementById("page");
 const HOME = root.dataset.home || "home";
 
+// Resolve every app endpoint against where THIS module was actually served from,
+// so absolute-looking "/app/…" paths work both at the origin root (direct run,
+// e.g. the CLI on :3000) and under a path-prefixed reverse proxy (the Nano
+// console embeds the app at /console/app-view/<name>/). "../" drops the trailing
+// "app/runtime.js" to land on the app's mount root (always ends in "/").
+const APP_BASE = new URL("../", import.meta.url);
+function apiUrl(u) {
+  // Rebase root-absolute app paths ("/app/…") onto the mount root. Leave a
+  // protocol-relative ("//host/…") or otherwise non-root-relative string alone —
+  // only a single leading slash denotes an app path we own.
+  return typeof u === "string" && u.startsWith("/") && !u.startsWith("//")
+    ? new URL(u.slice(1), APP_BASE).toString()
+    : u;
+}
+
 async function getJSON(url, opts) {
-  const r = await fetch(url, opts);
+  const r = await fetch(apiUrl(url), opts);
   const body = await r.json().catch(() => ({}));
   if (!r.ok) throw new Error(body.error || ("HTTP " + r.status));
   return body;

package/dist/runtime/core/runtime.js

@@ -131,9 +131,11 @@ export async function createUrbanApp(opts) {
                         describe.connectors = c.describe?.();
                 }
                 const routes = [];
+                let hasUiSurfaces = false;
                 if (flags.surfaces) {
                     const s = mountSurfaces(ctx, api);
                     routes.push(...s.routes);
+                    hasUiSurfaces = s.routes.length > 0;
                     describe.surfaces = s.describe();
                 }
                 if (flags.triggers) {
@@ -160,6 +162,23 @@ export async function createUrbanApp(opts) {
                     server = await host.serveHttp(port, makeRouter(routes));
                     httpPort = server.port;
                     host.log("info", "urban app serving surfaces/triggers", { port: httpPort, routes: routes.length });
+                    // ADR 0057 boot handshake: under a supervising host (the nano-bpm
+                    // Studio sets NANOBPMN_APP_HANDSHAKE), announce the port we actually
+                    // bound on a machine-readable stdout control line so the host can
+                    // locate the app's UI even when the app picks its port at runtime.
+                    // Only emitted when the app actually serves UI surfaces (a trigger- or
+                    // worker-only app binds a port too, but it has no webview for the host
+                    // to frame), and gated on the env var so direct terminal runs aren't
+                    // cluttered. `=== "1"` so an app that sets the var to "0" opts out.
+                    if (httpPort !== undefined && hasUiSurfaces && host.env("NANOBPMN_APP_HANDSHAKE") === "1") {
+                        try {
+                            console.log(`@@NBPM_LISTENING@@${JSON.stringify({ port: httpPort })}`);
+                        }
+                        catch {
+                            // stdout may be closed / non-writable — the handshake is
+                            // best-effort telemetry, never fatal to the app.
+                        }
+                    }
                 }
                 host.log("info", `urban app "${manifest.id}" started`, {});
             }

package/dist/toolkit/derivers/domain.d.ts

@@ -44,6 +44,9 @@ export interface DomainTypeDef {
 }
 /** The manifest `types` registry: type id → declared record type. */
 export type DomainTypeRegistry = Record<string, DomainTypeDef>;
+/** Whether a manifest field keyword resolves to a primitive (vs a nominal ref). Shared with the
+ * shape fuse (`shapes.ts`) so the primitive-keyword set has one definition (no drift). */
+export declare function isPrimitiveKeyword(type: string): boolean;
 /**
  * Emit the `DomainTypes` block for the manifest `types` registry: an inline map keyed by type id.
  * Returns `""` when the registry is empty, so the table spine stays byte-identical when no types
@@ -55,6 +58,21 @@ export declare function emitDomainTypeRegistry(types: DomainTypeRegistry): strin
  * followed by the manifest `types` registry (§4.2).
  */
 export declare function emitDomainModel(sources: SourceSchema[], defaultSource: string | undefined, types: DomainTypeRegistry): string;
+/** The generated bindings file's basename — the typed `openDomain()` accessor materialised next to
+ * `domain-rows.d.ts` under a project's `nano-generated/`. */
+export declare const DOMAIN_BINDINGS = "domain.ts";
+/**
+ * Emit `domain.ts`: a typed data-object accessor over the App's default datasource, so a worker
+ * writes `db.orders.insert({...})` / `db.orders.get(id)` instead of hand-writing SQL (ADR 0029 §6).
+ * The generic `Table<T>` runtime lives in `data-sdk.ts`; this generated module only binds each
+ * table name to its row type (from `domain-rows.d.ts`) and primary key, so it imports nothing but
+ * the sibling SDK (relative) and a type-only `domain-rows.d.ts` — staying dual-runtime and erased at
+ * `deno compile`. When the App declares multiple datasources this emits a *keyed*
+ * `openDomain<K>(source?)` whose returned accessor is typed against that source's tables; `db.raw`
+ * is the per-source escape hatch. Single-source apps keep the zero-arg `openDomain()` concrete form
+ * (byte-stable).
+ */
+export declare function emitDomainBindings(sources: SourceSchema[], defaultSource?: string): string;
 /** The datasource table spine derived from the manifest types, grouped by source (same grouping
  * and order as the SQL migration). */
 export declare function sourcesFromManifest(manifest: ToolkitManifest): SourceSchema[];

package/dist/toolkit/derivers/domain.js

@@ -143,6 +143,11 @@ const PRIMITIVE_TS = {
     datetime: "string",
     json: "unknown",
 };
+/** Whether a manifest field keyword resolves to a primitive (vs a nominal ref). Shared with the
+ * shape fuse (`shapes.ts`) so the primitive-keyword set has one definition (no drift). */
+export function isPrimitiveKeyword(type) {
+    return Object.prototype.hasOwnProperty.call(PRIMITIVE_TS, type);
+}
 /**
  * The TS type for a registry field. A primitive keyword maps directly (and takes precedence over
  * an identically named type, per the schema); anything else is a nominal reference to another
@@ -187,6 +192,135 @@ export function emitDomainModel(sources, defaultSource, types) {
     const registry = emitDomainTypeRegistry(types);
     return registry ? `${spine}\n${registry}` : spine;
 }
+// --- domain bindings: the typed data-object accessor (ADR 0029 §6) ---------------------------
+/** The generated bindings file's basename — the typed `openDomain()` accessor materialised next to
+ * `domain-rows.d.ts` under a project's `nano-generated/`. */
+export const DOMAIN_BINDINGS = "domain.ts";
+/** Members `openDomain()` reserves on the returned handle — the `DomainBase` escape hatch
+ * (`raw`/`close`). A table whose wire name is one of these would clobber the escape hatch (or the
+ * type intersection), so it is dropped from the typed table surface; it stays reachable via
+ * `db.raw.table("<name>", pk)`. */
+const RESERVED_DOMAIN_MEMBERS = new Set(["raw", "close"]);
+/** The primary-key column for a table's `Table` gateway: its first declared PK column, or `id`
+ * when the table declares none. */
+function primaryKeyOf(t) {
+    return t.columns.find((c) => c.primaryKey)?.name ?? "id";
+}
+/**
+ * Emit `domain.ts`: a typed data-object accessor over the App's default datasource, so a worker
+ * writes `db.orders.insert({...})` / `db.orders.get(id)` instead of hand-writing SQL (ADR 0029 §6).
+ * The generic `Table<T>` runtime lives in `data-sdk.ts`; this generated module only binds each
+ * table name to its row type (from `domain-rows.d.ts`) and primary key, so it imports nothing but
+ * the sibling SDK (relative) and a type-only `domain-rows.d.ts` — staying dual-runtime and erased at
+ * `deno compile`. When the App declares multiple datasources this emits a *keyed*
+ * `openDomain<K>(source?)` whose returned accessor is typed against that source's tables; `db.raw`
+ * is the per-source escape hatch. Single-source apps keep the zero-arg `openDomain()` concrete form
+ * (byte-stable).
+ */
+export function emitDomainBindings(sources, defaultSource) {
+    const header = "// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1/§6).\n" +
+        "// The typed data-object layer: `openDomain()` → one `Table<T>` per table, so\n" +
+        "// workers manipulate typed rows instead of hand-writing SQL. Do not edit —\n" +
+        "// regenerated from the live tables. Erased to plain JS at `deno compile`.\n" +
+        "// eslint-disable\n";
+    const multi = sources.length > 1;
+    const def = defaultSource && sources.some((s) => s.source === defaultSource)
+        ? defaultSource
+        : sources[0]?.source;
+    const primary = sources.find((s) => s.source === def);
+    const tables = (primary?.tables ?? []).filter((t) => !RESERVED_DOMAIN_MEMBERS.has(t.name));
+    // Multi-source apps: emit a *keyed* accessor so `openDomain("analytics")` is typed against that
+    // source's tables, not the default's. The row-type spine (`DomainSources`, keyed by alias then
+    // wire table name) is already emitted in `domain-rows.d.ts`; here we bind a runtime
+    // table-descriptor map per source and a generic `openDomain<K>` that indexes it. Single-source
+    // apps keep the zero-arg concrete form below (byte-stable).
+    if (multi) {
+        return emitKeyedDomainBindings(header, sources, def);
+    }
+    // Interface names must match `domain-rows.d.ts` exactly (prefixed when multi-source).
+    const typeName = (table) => multi ? prefixedInterfaceName(primary.source, table) : interfaceName(table);
+    const propKey = (table) => (isIdent(table) ? table : JSON.stringify(table));
+    const typeImports = [...new Set(tables.map((t) => typeName(t.name)))].sort();
+    const importTypes = typeImports.length > 0
+        ? `import type { ${typeImports.join(", ")} } from "./${DOMAIN_DTS}";\n`
+        : "";
+    const fields = tables
+        .map((t) => `  readonly ${propKey(t.name)}: Table<${typeName(t.name)}>;`)
+        .join("\n");
+    const binds = tables
+        .map((t) => `    ${propKey(t.name)}: raw.table<${typeName(t.name)}>(` +
+        `${JSON.stringify(t.name)}, ${JSON.stringify(primaryKeyOf(t))}),`)
+        .join("\n");
+    const domainIface = `export interface Domain {\n` +
+        `  /** The underlying datasource handle — the raw-SQL escape hatch. */\n` +
+        `  readonly raw: DataSource;\n` +
+        (fields ? `${fields}\n` : "") +
+        `  /** Close the underlying connection. */\n  close(): void;\n}`;
+    const openFn = `/**\n` +
+        ` * Open the App's ${multi ? `default (\`${def}\`) ` : ""}datasource as a typed domain: each table is\n` +
+        ` * a \`Table<T>\` gateway (\`db.orders.insert(...)\`, \`db.orders.get(id)\`), with the\n` +
+        ` * raw \`DataSource\` at \`db.raw\` for anything the gateway doesn't cover.\n` +
+        ` */\n` +
+        `export async function openDomain(source?: string): Promise<Domain> {\n` +
+        `  const raw = await openDataSource(source);\n` +
+        `  return {\n    raw,\n` +
+        (binds ? `${binds}\n` : "") +
+        `    close: () => raw.close(),\n  };\n}`;
+    return `${header}\n` +
+        `import { openDataSource, type DataSource, type Table } from "./data-sdk.ts";\n` +
+        importTypes +
+        `\n${domainIface}\n\n${openFn}\n\nexport type { Table };\n`;
+}
+/**
+ * Emit the *keyed* `domain.ts` for a multi-datasource App. `openDomain(source)` is
+ * runtime-polymorphic (it opens whichever source you name); here
+ * `openDomain<K extends DomainSource>(source?: K)` selects the row-type map for the requested
+ * source from `DomainSources` (emitted in `domain-rows.d.ts`), and a runtime per-source
+ * table-descriptor map binds the matching `Table<T>` gateways. Zero-arg / default-source calls keep
+ * resolving to the default source.
+ */
+function emitKeyedDomainBindings(header, sources, def) {
+    const tableDescriptors = sources
+        .map((s) => {
+        const rows = s.tables
+            .filter((t) => !RESERVED_DOMAIN_MEMBERS.has(t.name))
+            .map((t) => `{ name: ${JSON.stringify(t.name)}, pk: ${JSON.stringify(primaryKeyOf(t))} }`)
+            .join(", ");
+        return `  ${JSON.stringify(s.source)}: [${rows}],`;
+    })
+        .join("\n");
+    const runtimeMap = `const DOMAIN_TABLES: Record<string, { name: string; pk: string }[]> = {\n` +
+        `${tableDescriptors}\n};\n` +
+        `const DEFAULT_SOURCE = ${JSON.stringify(def)};`;
+    const types = `/** The App's datasource aliases (ADR 0024). */\n` +
+        `export type DomainSource = keyof DomainSources;\n\n` +
+        `interface DomainBase {\n` +
+        `  /** The underlying datasource handle — the raw-SQL escape hatch. */\n` +
+        `  readonly raw: DataSource;\n` +
+        `  /** Close the underlying connection. */\n  close(): void;\n}\n\n` +
+        `type DomainTablesOf<M extends Record<string, object>> = { readonly [K in keyof M as K extends "raw" | "close" ? never : K]: Table<M[K]> };\n\n` +
+        `/** A datasource opened as a typed domain: one \`Table<T>\` per table, plus\n` +
+        ` * \`raw\`/\`close\`. Defaults to the default source (\`${def}\`) when unparameterised. */\n` +
+        `export type Domain<M extends Record<string, object> = DomainSources[${JSON.stringify(def)}]> =\n` +
+        `  DomainBase & DomainTablesOf<M>;`;
+    const openFn = `/**\n` +
+        ` * Open one of the App's datasources as a typed domain. The \`source\` key\n` +
+        ` * selects that source's tables (\`openDomain("analytics").customers\`); omit it\n` +
+        ` * for the default source (\`${def}\`). \`db.raw\` is the raw-SQL escape hatch.\n` +
+        ` */\n` +
+        `export async function openDomain<K extends DomainSource = ${JSON.stringify(def)}>(\n` +
+        `  source?: K,\n` +
+        `): Promise<Domain<DomainSources[K]>> {\n` +
+        `  const key = (source ?? DEFAULT_SOURCE) as string;\n` +
+        `  const raw = await openDataSource(key);\n` +
+        `  const db: Record<string, unknown> = { raw, close: () => raw.close() };\n` +
+        `  for (const t of DOMAIN_TABLES[key] ?? []) db[t.name] = raw.table(t.name, t.pk);\n` +
+        `  return db as Domain<DomainSources[K]>;\n}`;
+    return `${header}\n` +
+        `import { openDataSource, type DataSource, type Table } from "./data-sdk.ts";\n` +
+        `import type { DomainSources } from "./${DOMAIN_DTS}";\n\n` +
+        `${runtimeMap}\n\n${types}\n\n${openFn}\n\nexport type { Table };\n`;
+}
 // --- manifest bridge (code-first, ADR 0054) --------------------------------------------------
 /** Project one manifest type's canonical schema into a `TableMeta` for the row-type spine. Reuses
  * the *same* `tableSchemaForType` the SQL migration uses, so the row types can't drift from the DB. */

package/dist/toolkit/derivers/messages.d.ts

@@ -2,6 +2,9 @@ import type { DerivedArtifact, Deriver } from "../artifact.ts";
 import { type ModelSource } from "./worker-io.ts";
 /** Filename the console uses for the derived message-payload map; kept identical (drop-in). */
 export declare const MESSAGE_BINDINGS_DTS = "message-io.d.ts";
+/** The generated typed-`publishMessage` wrapper's basename — re-exports the worker SDK's
+ * `publishMessage` with a messageName-keyed typed signature. */
+export declare const MESSAGE_BINDINGS_TS = "messages.ts";
 /** One message-IO entry scanned from a model: a `bpmn:message` name plus the envelope
  * type refs it carries. `inputType` is the received payload (what a `publishMessage`
  * caller sends); `outputType` is reserved. Mirrors the Rust `MessageIo`. */
@@ -34,3 +37,14 @@ export declare const messagesDeriver: Deriver<{
     models: ModelSource[];
     declaredTypeIds: Iterable<string>;
 }>;
+/**
+ * The static typed-`publishMessage` wrapper (`messages.ts`). It re-exports the worker SDK's
+ * `publishMessage` (and its option/result types) and overrides `publishMessage` with a signature
+ * that keys off the `name` string literal: when a message is present in the generated
+ * `MessagePayloads` (ADR 0040 slice 2), the call's `variables` are typed from the declared domain
+ * type; otherwise they fall back to `MessageVars`. The body is a pass-through — the wire stays
+ * untyped JSON. This file never changes with the model, so it is written verbatim (unlike the
+ * regenerated `message-io.d.ts`). A byte-faithful port of the console's
+ * `emitMessageBindingsRuntime`.
+ */
+export declare function emitMessageBindingsRuntime(): string;

package/dist/toolkit/derivers/messages.js

@@ -9,6 +9,9 @@ import { GENERATED_DIR } from "../artifact.js";
 import { byModelPath, DOMAIN_DTS, typeRefFor } from "./worker-io.js";
 /** Filename the console uses for the derived message-payload map; kept identical (drop-in). */
 export const MESSAGE_BINDINGS_DTS = "message-io.d.ts";
+/** The generated typed-`publishMessage` wrapper's basename — re-exports the worker SDK's
+ * `publishMessage` with a messageName-keyed typed signature. */
+export const MESSAGE_BINDINGS_TS = "messages.ts";
 const ENVELOPE_IN = "io.nanobpm.dataEnvelope.in";
 const ENVELOPE_OUT = "io.nanobpm.dataEnvelope.out";
 function attr(tag, name) {
@@ -132,3 +135,37 @@ export const messagesDeriver = {
     describe: "Derive message-io.d.ts (bpmn:message name + envelope payload) from BPMN models.",
     derive: ({ models, declaredTypeIds }) => deriveMessageBindings(models, declaredTypeIds),
 };
+/**
+ * The static typed-`publishMessage` wrapper (`messages.ts`). It re-exports the worker SDK's
+ * `publishMessage` (and its option/result types) and overrides `publishMessage` with a signature
+ * that keys off the `name` string literal: when a message is present in the generated
+ * `MessagePayloads` (ADR 0040 slice 2), the call's `variables` are typed from the declared domain
+ * type; otherwise they fall back to `MessageVars`. The body is a pass-through — the wire stays
+ * untyped JSON. This file never changes with the model, so it is written verbatim (unlike the
+ * regenerated `message-io.d.ts`). A byte-faithful port of the console's
+ * `emitMessageBindingsRuntime`.
+ */
+export function emitMessageBindingsRuntime() {
+    return "// AUTO-GENERATED by nanobpmn (ADR 0040 slice 2): the typed `publishMessage`.\n" +
+        "// Re-exports the worker SDK's `publishMessage` and overrides it with a\n" +
+        "// messageName-keyed typed signature (variables typed from the message's declared\n" +
+        "// envelope). Erased to a pass-through at runtime. Do not edit.\n" +
+        "// eslint-disable\n\n" +
+        `import { publishMessage as publishMessageRaw } from "./worker-sdk.ts";\n` +
+        `import type { PublishMessageOptions, PublishMessageResult } from "./worker-sdk.ts";\n` +
+        `import type { MessageName, MessagePayloads, MessageVars } from "./${MESSAGE_BINDINGS_DTS}";\n\n` +
+        `export type { PublishMessageOptions, PublishMessageResult } from "./worker-sdk.ts";\n\n` +
+        `type PayloadFor<K extends MessageName> = K extends keyof MessagePayloads ? MessagePayloads[K] : MessageVars;\n\n` +
+        `/**\n` +
+        ` * Typed \`publishMessage\`: \`name\` is constrained to the model's declared message\n` +
+        ` * names (\`MessageName\`, ADR 0040 slice 2) so it autocompletes and rejects unknown\n` +
+        ` * messages, and \`variables\` are typed from the message's declared envelope. A\n` +
+        ` * declared message with no domain type falls back to MessageVars.\n` +
+        ` */\n` +
+        `export function publishMessage<K extends MessageName>(\n` +
+        `  name: K,\n` +
+        `  opts?: PublishMessageOptions<PayloadFor<K> & object>,\n` +
+        `): Promise<PublishMessageResult> {\n` +
+        `  return publishMessageRaw(name, opts as unknown as PublishMessageOptions);\n` +
+        `}\n`;
+}

package/dist/toolkit/derivers/shapes.d.ts

@@ -0,0 +1,96 @@
+import type { ColumnMeta } from "../../runtime/core/modules/gateway.ts";
+import { type DomainFieldDef, type DomainTypeDef, type DomainTypeRegistry, type SourceSchema } from "./domain.ts";
+/** One composition operation of a `nano:shape`, in author (XML) order. */
+export type ShapeOp = {
+    op: "carry";
+    ref: string;
+} | {
+    op: "project";
+    ref: string;
+    fields: string[];
+    via?: string;
+} | {
+    op: "extend";
+    name: string;
+    type: string;
+    optional?: boolean;
+    list?: boolean;
+} | {
+    op: "reference";
+    name: string;
+    ref: string;
+    spread?: boolean;
+    list?: boolean;
+};
+/** A composed motion-shape declaration lifted from the model (ADR 0040 §9). */
+export interface ShapeDecl {
+    /** The fuse identity; also the `DomainTypes` key the resolved shape lands under. */
+    id: string;
+    /** Optional human label (`nano:shape name`). */
+    name?: string;
+    /** The defining process id, for the `model:<processId>` provenance tag. */
+    process?: string;
+    /** The ordered composition operations. */
+    ops: ShapeOp[];
+    /** Model-level metadata (`nano:meta`), free-form key/value (ADR 0040 §5). */
+    meta?: Record<string, string>;
+}
+/** A scan/resolve-time problem with a shape, surfaced like the `workers[]` drift warning (never a
+ * silent merge). A shape with any `error` diagnostic is omitted from the fuse; a `warning` (e.g. a
+ * deliberate field shadow) still resolves. */
+export interface ShapeDiagnostic {
+    /** The offending shape id. */
+    shape: string;
+    kind: "unresolved-reference" | "reference-cycle" | "field-conflict" | "unknown-field" | "duplicate-id" | "ambiguous-reference" | "nominal-table-ref" | "same-id-collision";
+    severity: "error" | "warning";
+    message: string;
+}
+/** The result of resolving the project's shapes against the leaf fuse. */
+export interface ShapeResolution {
+    /** The resolved shapes as registry entries, keyed by shape id, ready to fold into the manifest
+     * `types` registry before `emitDomainModel`. */
+    types: DomainTypeRegistry;
+    diagnostics: ShapeDiagnostic[];
+}
+/** Map one datasource column to a domain field. A nullable column widens to `optional` (the
+ * composed shape is a motion snapshot: an absent value reads as undefined, not SQL NULL). The
+ * manifest keyword is inferred from the column's SQLite affinity so it flows through `fieldTsType`
+ * like any declared field; affinities with no keyword (BLOB/opaque) fall back to `json`. */
+export declare function columnToField(col: ColumnMeta): DomainFieldDef;
+/**
+ * Resolve the project's composed shapes into `DomainTypeDef`s and diagnostics (ADR 0040 §10).
+ * Leaves (DB tables, manifest types) fuse first; shapes resolve in dependency order so a shape can
+ * carry another shape regardless of declaration order. A shape in a reference cycle, or one that
+ * names an unresolvable id, is omitted (degrades to untyped) with an `error` diagnostic; a
+ * deliberate field shadow with a differing type resolves with a `field-conflict` warning.
+ */
+export declare function resolveShapes(shapes: ShapeDecl[], types: DomainTypeRegistry, sources?: SourceSchema[]): ShapeResolution;
+/** The basename of the generated structured fuse cache (ADR 0040 §1). */
+export declare const DOMAIN_MODEL_JSON = "domain.json";
+/** One model-level metadata entry (`nano:meta`) as `emitDomainModelJson` consumes it. Mirrors
+ * `meta.ts`'s `MetaDecl` (kept local so the fuse cache does not depend on the meta deriver). */
+export interface FusedMetaDecl {
+    process?: string;
+    key: string;
+    value: string;
+}
+/**
+ * Emit `domain.json`: the structured Fused Domain Model (ADR 0040 §1). Assembles every fused
+ * entity — DB tables (`db:` provenance), manifest `types` (`manifest:`), and composed motion shapes
+ * (`model:<processId>`, or bare `model` for an unsaved editor shape with no process) — with its
+ * resolved fields, plus the model-level metadata and the shape diagnostics. An `inputsHash` —
+ * FNV-1a (hex) over the compact `JSON.stringify` of the model object with `inputsHash` omitted
+ * (property-insertion order, not the pretty-printed bytes) — tags the cache for staleness.
+ */
+export declare function emitDomainModelJson(input: {
+    sources: SourceSchema[];
+    default?: string;
+    manifestTypes: DomainTypeRegistry;
+    /** Resolved shapes paired with their declaration (for provenance/label). */
+    shapes: {
+        decl: ShapeDecl;
+        def: DomainTypeDef;
+    }[];
+    meta: FusedMetaDecl[];
+    diagnostics: ShapeDiagnostic[];
+}): string;