@nanobpm/urban 0.28.0 → 0.29.0

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

@@ -5,6 +5,7 @@
 import { isRecord } from "../guards.js";
 import { json, normalizeRoutePath } from "../router.js";
 import { nextCronFire, parseCron } from "./cron.js";
+import { defaultScheduler, MAX_TIMER_DELAY_MS } from "./scheduler.js";
 /**
  * Resolve a tiny FEEL-ish expression against the event scope: a `= body.a.b` path walk
  * returns the raw value at that path (or `undefined` if any segment is missing); a literal
@@ -92,22 +93,6 @@ export async function runTriggerAction(app, action, scope) {
     return { kind: "none" };
 }
 const emptyScope = { body: {}, headers: {}, query: {} };
-/** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
-const MAX_TIMER_DELAY_MS = 2_147_483_647;
-/** Default (live) scheduler seam, backed by the global timer functions. */
-function defaultScheduler() {
-    return {
-        setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
-        clearTimer: (h) => {
-            if (isTimerHandle(h))
-                globalThis.clearTimeout(h);
-        },
-        now: () => Date.now(),
-    };
-}
-function isTimerHandle(handle) {
-    return typeof handle === "number" || (typeof handle === "object" && handle !== null);
-}
 /** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
  *  background timers that fire their action on schedule. `stop()` clears every timer. */
 export function mountTriggers(ctx, app, sched = defaultScheduler()) {

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

@@ -4,6 +4,7 @@
 import { isRecord } from "../guards.js";
 import { workerJobType } from "../manifest.js";
 import { runLlmJob } from "./llm.js";
+import { runInJobContext } from "../execContext.js";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
  *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
@@ -98,7 +99,7 @@ export async function mountWorkers(ctx, app) {
                 env: (n) => app.env(n),
                 evaluateDecision: app.sdk ? sdkDecisionEvaluator(app.sdk) : undefined,
             };
-            const wrapped = (job) => runLlmJob(job.variables, binding, rt);
+            const wrapped = (job) => runInJobContext({ instanceKey: job.processInstanceKey, elementId: job.elementId, jobType }, () => runLlmJob(job.variables, binding, rt));
             const sub = await ctx.engine.registerWorker(jobType, wrapped, {
                 workerName: `${ctx.manifest.id}:${jobType}`,
             });
@@ -113,7 +114,7 @@ export async function mountWorkers(ctx, app) {
             throw new Error(`worker "${jobType}": ${decl.handler} exports no handler for it ` +
                 `(expected handlers["${jobType}"], a named export, or a default function)`);
         }
-        const wrapped = (job) => handler(job, app);
+        const wrapped = (job) => runInJobContext({ instanceKey: job.processInstanceKey, elementId: job.elementId, jobType }, () => handler(job, app));
         const sub = await ctx.engine.registerWorker(jobType, wrapped, {
             workerName: `${ctx.manifest.id}:${jobType}`,
         });

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

@@ -13,6 +13,9 @@ export interface MountFlags {
     surfaces?: boolean;
     triggers?: boolean;
     security?: boolean;
+    /** The `instanceTracking` reconciler poll loop. Shares no HTTP surface; safe to disable
+     *  in hosts that only render surfaces (e.g. the console preview). */
+    instanceTracking?: boolean;
 }
 export interface CreateUrbanAppOptions {
     host: HostContext;

package/dist/runtime/core/runtime.js

@@ -7,10 +7,12 @@ import { validateManifest } from "./validate.js";
 import { makeRouter } from "./router.js";
 import { deployModels } from "./modules/deploy.js";
 import { provisionData, DataLayer } from "./modules/datasource.js";
+import { installExecStore } from "./execContext.js";
 import { mountWorkers } from "./modules/workers.js";
 import { mountConnectors } from "./modules/connectors.js";
 import { mountSurfaces } from "./modules/surfaces.js";
 import { mountTriggers } from "./modules/triggers.js";
+import { mountInstanceTracking } from "./modules/instance-tracking.js";
 import { mountSecurity } from "./modules/security.js";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
  * error when $PORT is set but not a valid integer in 0..65535. */
@@ -43,8 +45,13 @@ export async function createUrbanApp(opts) {
         surfaces: opts.mount?.surfaces ?? true,
         triggers: opts.mount?.triggers ?? true,
         security: opts.mount?.security ?? true,
+        instanceTracking: opts.mount?.instanceTracking ?? true,
     };
     const ctx = { manifest, host, engine, root, templates: opts.templates };
+    // Install the ambient job-execution store once per process (idempotent) so worker dispatch can
+    // stamp write-provenance onto DataLayer inserts. Absent-safe: a host without `createAsyncStore`
+    // leaves provenance capture disabled.
+    installExecStore(() => host.createAsyncStore?.());
     let data;
     let security;
     let server;
@@ -144,6 +151,11 @@ export async function createUrbanApp(opts) {
                     mounted.push(t);
                     describe.triggers = t.describe?.();
                 }
+                if (flags.instanceTracking && (manifest.instanceTracking?.length ?? 0) > 0) {
+                    const it = mountInstanceTracking(ctx, api);
+                    mounted.push(it);
+                    describe.instanceTracking = it.describe?.();
+                }
                 if (security)
                     describe.security = security.describe();
                 if (data)

package/dist/runtime/core/validate.js

@@ -131,6 +131,44 @@ export function collectManifestIssues(m) {
                 issues.push({ path: `triggers[${i}].type`, message: "missing type" });
         });
     }
+    // instanceTracking: each binding must name the table + key column it tracks and a
+    // non-empty `onTerminated.set` patch — a reconciler with nothing to write is inert
+    // and almost certainly a mistake. `activeStatuses` without `statusField` is incoherent
+    // (no column to read the statuses from), so the runtime would silently poll every row.
+    const tracking = Array.isArray(obj.instanceTracking) ? obj.instanceTracking : undefined;
+    if (tracking) {
+        tracking.forEach((t, i) => {
+            const b = isRecord(t) ? t : undefined;
+            if (typeof b?.table !== "string" || b.table.length === 0) {
+                issues.push({ path: `instanceTracking[${i}].table`, message: "missing table" });
+            }
+            if (typeof b?.keyField !== "string" || b.keyField.length === 0) {
+                issues.push({ path: `instanceTracking[${i}].keyField`, message: "missing keyField" });
+            }
+            const onTerminated = isRecord(b?.onTerminated) ? b.onTerminated : undefined;
+            const set = isRecord(onTerminated?.set) ? onTerminated.set : undefined;
+            if (!set || Object.keys(set).length === 0) {
+                issues.push({
+                    path: `instanceTracking[${i}].onTerminated.set`,
+                    message: "missing onTerminated.set patch (a non-empty column → value map)",
+                });
+            }
+            if (Array.isArray(b?.activeStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
+                issues.push({
+                    path: `instanceTracking[${i}].activeStatuses`,
+                    message: "activeStatuses requires statusField",
+                });
+            }
+            // `pollMs`, when set, schedules a self-rescheduling timer; a non-number/NaN/non-positive
+            // value would become a 0-delay hot loop at runtime, so reject it at author time.
+            if (b?.pollMs !== undefined && (typeof b.pollMs !== "number" || !Number.isFinite(b.pollMs) || b.pollMs <= 0)) {
+                issues.push({
+                    path: `instanceTracking[${i}].pollMs`,
+                    message: "pollMs must be a finite positive number of milliseconds",
+                });
+            }
+        });
+    }
     return issues;
 }
 export function assertValidManifest(m) {

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

@@ -1,8 +1,13 @@
-import type { EngineClient, JobHandler, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
 export declare function requireProcessInstanceKey(key: string | number | null | undefined): string;
+/** Map the engine's process-instance `state` onto the transport-agnostic
+ *  {@link ProcessInstanceState} union, or `undefined` for an unrecognized value
+ *  (which the caller skips rather than mis-reconciling). Case-insensitive so a
+ *  future casing tweak on the engine side doesn't silently drop instances. */
+export declare function normalizeProcessInstanceState(raw: unknown): ProcessInstanceState | undefined;
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -76,6 +81,10 @@ export interface NanoSdkClient {
         userTaskKey: string;
         variables?: Record<string, unknown>;
     }, options?: unknown): Promise<unknown>;
+    searchProcessInstances(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
     createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
     /** Stop every worker created on this client. Used on teardown to also drain a
      * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
@@ -134,6 +143,10 @@ export declare class SdkEngineClient implements EngineClient {
         variables?: Record<string, unknown>;
     }[]>;
     completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
+    searchProcessInstances(filter?: {
+        processInstanceKeys?: string[];
+        state?: ProcessInstanceState;
+    }): Promise<ProcessInstanceSnapshot[]>;
     registerWorker(jobType: string, handler: JobHandler, options?: {
         workerName?: string;
         maxParallelJobs?: number;

package/dist/runtime/engine/nanosdk.js

@@ -28,6 +28,24 @@ export function requireProcessInstanceKey(key) {
     }
     return String(key);
 }
+/** Map the engine's process-instance `state` onto the transport-agnostic
+ *  {@link ProcessInstanceState} union, or `undefined` for an unrecognized value
+ *  (which the caller skips rather than mis-reconciling). Case-insensitive so a
+ *  future casing tweak on the engine side doesn't silently drop instances. */
+export function normalizeProcessInstanceState(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    switch (raw.toUpperCase()) {
+        case "ACTIVE":
+            return "ACTIVE";
+        case "COMPLETED":
+            return "COMPLETED";
+        case "TERMINATED":
+            return "TERMINATED";
+        default:
+            return undefined;
+    }
+}
 /**
  * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
  * message, and user-task calls map one-to-one onto the SDK's client methods; workers
@@ -101,6 +119,37 @@ export class SdkEngineClient {
     async completeUserTask(userTaskKey, variables) {
         await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
     }
+    async searchProcessInstances(filter) {
+        const f = {};
+        if (filter?.state)
+            f.state = filter.state;
+        const keys = filter?.processInstanceKeys?.filter((k) => k != null && k !== "");
+        if (keys && keys.length > 0)
+            f.processInstanceKey = { $in: keys };
+        // A process-instance search is an eventually consistent read; ask for zero-wait
+        // consistency so it reflects what is currently visible without blocking. Cap the page
+        // to the number of keys asked for (each key matches at most one instance), so a bounded
+        // reconcile query never silently truncates on the API's default page size.
+        const page = keys && keys.length > 0 ? { limit: keys.length } : undefined;
+        const body = await this.client.searchProcessInstances({ filter: f, ...(page ? { page } : {}) }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+        return items.flatMap((it) => {
+            const key = it.processInstanceKey;
+            if (key == null || key === "") {
+                this.log("warn", "skipping process instance with no key in engine response");
+                return [];
+            }
+            const state = normalizeProcessInstanceState(it.state);
+            if (!state) {
+                this.log("warn", "skipping process instance with unrecognized state", {
+                    processInstanceKey: String(key),
+                    state: String(it.state),
+                });
+                return [];
+            }
+            return [{ processInstanceKey: String(key), state }];
+        });
+    }
     async registerWorker(jobType, handler, options) {
         const worker = this.client.createJobWorker({
             jobType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.28.0",
+  "version": "0.29.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",
@@ -62,7 +62,7 @@
     "test:deno": "deno test -A --no-check src/"
   },
   "dependencies": {
-    "@nanobpm/nano-app-schema": "^0.3.0",
+    "@nanobpm/nano-app-schema": "^0.4.0",
     "@nanobpm/nano-sdk": "^1.2.3",
     "@nanobpm/workflow": "^0.8.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",

package/src/runtime/adapters/deno.ts

@@ -6,7 +6,9 @@
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+import { AsyncLocalStorage } from "node:async_hooks";
 import type {
+  AsyncStore,
   HostContext,
   HttpHandler,
   HttpRequest,
@@ -134,6 +136,10 @@ export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
       };
     },
     now: () => Date.now(),
+    createAsyncStore<T>(): AsyncStore<T> {
+      const als = new AsyncLocalStorage<T>();
+      return { run: <R>(value: T, fn: () => R): R => als.run(value, fn), current: () => als.getStore() };
+    },
     log,
   };
 }

package/src/runtime/adapters/node.ts

@@ -9,7 +9,9 @@ import { register } from "node:module";
 import { isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+import { AsyncLocalStorage } from "node:async_hooks";
 import type {
+  AsyncStore,
   HostContext,
   HttpHandler,
   HttpRequest,
@@ -176,6 +178,10 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
       return { close: () => w.close() } satisfies WatchHandle;
     },
     now: () => Date.now(),
+    createAsyncStore<T>(): AsyncStore<T> {
+      const als = new AsyncLocalStorage<T>();
+      return { run: <R>(value: T, fn: () => R): R => als.run(value, fn), current: () => als.getStore() };
+    },
     log,
   };
 }

package/src/runtime/core/execContext.ts

@@ -0,0 +1,56 @@
+// Ambient job execution context — threads the active job's process instance / element through
+// to DataLayer writes so write-provenance capture (ProcessOS domain-signal plane, D0) can join
+// written rows back to the instance/element that wrote them, WITHOUT plumbing the job through
+// every call. Entirely domain-free: it knows nothing about any app's tables or their meaning.
+//
+// The async primitive (`AsyncLocalStorage`) is a host capability (`node:async_hooks`), so it is
+// injected through the `HostContext` seam; core stays `node:*`-free per the host contract. When
+// no store is installed — a host that doesn't provide one, or a plain unit test — `run()` just
+// calls `fn` and `current()` returns undefined, so capture degrades to a no-op. Absent-safe and
+// zero-cost when off, by construction.
+
+import type { AsyncStore } from "./host.ts";
+
+/** The ambient context of the job currently executing on a worker. All fields are optional so a
+ *  job dispatched without an instance/element still runs; provenance is only recorded when an
+ *  `instanceKey` is present. */
+export interface JobExecContext {
+  /** The process instance that dispatched the running job. */
+  instanceKey?: string;
+  /** The BPMN element (e.g. service task) the job is for. */
+  elementId?: string;
+  /** The job type (worker) currently executing. */
+  jobType?: string;
+}
+
+let store: AsyncStore<JobExecContext> | undefined;
+
+/**
+ * Install the host-backed ambient store once per process. Idempotent — the first store created
+ * wins: every Node/Deno store is an equivalent `AsyncLocalStorage` instance, and a process that
+ * hosts several apps shares one async store safely (values are keyed by async execution context,
+ * not by app). A `factory` that returns undefined (a host without the capability) leaves capture
+ * disabled, but a later capable host may still install the process store.
+ */
+export function installExecStore(factory: () => AsyncStore<JobExecContext> | undefined): void {
+  if (store) return;
+  const next = factory();
+  if (next) store = next;
+}
+
+/** Run `fn` with `ctx` as the ambient job context. A transparent pass-through when no store is
+ *  installed (returns `fn()` directly). */
+export function runInJobContext<R>(ctx: JobExecContext, fn: () => R): R {
+  return store ? store.run(ctx, fn) : fn();
+}
+
+/** The ambient job context of the current async execution, or undefined outside a job (or when
+ *  no store is installed). */
+export function currentJobContext(): JobExecContext | undefined {
+  return store?.current();
+}
+
+/** Test seam: drop the installed store so a subsequent {@link installExecStore} re-installs. */
+export function __resetExecStoreForTests(): void {
+  store = undefined;
+}

package/src/runtime/core/host.ts

@@ -35,6 +35,17 @@ export interface WatchHandle {
   close(): void;
 }
 
+/** A minimal ambient async-scoped store — the subset of `AsyncLocalStorage` the runtime needs
+ *  to thread a job's execution context to DataLayer writes for write-provenance capture. Backed
+ *  by `node:async_hooks` in both the Node and Deno adapters (both provide it); core depends only
+ *  on this interface, never on `node:*`. */
+export interface AsyncStore<T> {
+  /** Run `fn` with `value` as the current store value, restoring the prior value afterwards. */
+  run<R>(value: T, fn: () => R): R;
+  /** The current store value, or undefined outside any `run`. */
+  current(): T | undefined;
+}
+
 /** A tiny synchronous SQLite handle — the subset the runtime needs. */
 export interface SqliteDb {
   /** Execute one or more statements with no result (DDL, PRAGMA, migrations). */
@@ -89,6 +100,12 @@ export interface HostContext {
   watch?(onChange: (path: string) => void): WatchHandle;
   /** Current wall-clock time in ms since epoch (seam for tests). */
   now(): number;
+  /**
+   * Create an ambient async-scoped store (backed by `AsyncLocalStorage`). Used to thread the
+   * active job's execution context to DataLayer writes for write-provenance capture. Optional:
+   * a host that cannot provide one leaves provenance capture disabled (absent-safe).
+   */
+  createAsyncStore?<T>(): AsyncStore<T>;
   /** Structured log sink. */
   log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }
@@ -146,6 +163,21 @@ export interface WorkerSubscription {
   unsubscribe(): Promise<void>;
 }
 
+/**
+ * A process instance's terminal-relevant lifecycle state, as the engine reports it.
+ * `ACTIVE` (still running), `COMPLETED` (ended normally at an end event), or
+ * `TERMINATED` (cancelled/terminated — via a row-cancel, an operator, or a crash).
+ * Deliberately the small set the instance-tracking reconciler keys on, not the richer
+ * element-instance state set (which adds SKIPPED/CANCELED/FAILED for tokens).
+ */
+export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
+
+/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
+export interface ProcessInstanceSnapshot {
+  readonly processInstanceKey: string;
+  readonly state: ProcessInstanceState;
+}
+
 /**
  * EngineClient is the seam onto a Nano engine. The SDK/REST-backed adapter implements
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
@@ -177,6 +209,18 @@ export interface EngineClient {
   }): Promise<{ userTaskKey: string; elementId?: string; variables?: Record<string, unknown> }[]>;
   /** Complete a user task. */
   completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
+  /**
+   * Search process instances by key and/or lifecycle state. The instance-tracking
+   * reconciler uses this to detect a tracked instance reaching a terminal state
+   * (`TERMINATED`/`COMPLETED`) even though no completion worker ran for it — the
+   * read-model row it backs would otherwise stay "active" forever. An eventually
+   * consistent read (zero-wait); pass the keys currently marked active in the
+   * read model and, optionally, a `state` to narrow the result.
+   */
+  searchProcessInstances(filter?: {
+    processInstanceKeys?: string[];
+    state?: ProcessInstanceState;
+  }): Promise<ProcessInstanceSnapshot[]>;
   /** Register a push worker for a job type. Draining is handled by the adapter. */
   registerWorker(
     jobType: string,

package/src/runtime/core/manifest.ts

@@ -21,6 +21,7 @@ export type {
   DataSource,
   DomainField,
   DomainType,
+  InstanceTracking,
   LlmBinding,
   Models,
   PagesSurface,

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

@@ -29,6 +29,7 @@ const engine: EngineClient = {
   publishMessage: async () => {},
   searchUserTasks: async () => [],
   completeUserTask: async () => {},
+  searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

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

@@ -17,6 +17,7 @@ class MiniEngine implements EngineClient {
   async publishMessage(): Promise<void> {}
   async searchUserTasks(): Promise<[]> { return []; }
   async completeUserTask(): Promise<void> {}
+  async searchProcessInstances(): Promise<[]> { return []; }
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);
     return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };

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

@@ -24,6 +24,7 @@ import {
   type ConnectorWorkerJob,
   type DefinedConnectorWorker,
 } from "../../connector-worker-sdk.ts";
+import { runInJobContext } from "../execContext.ts";
 
 /** A config field a pack declares (subset of ext-types `ConfigField`): an env
  *  pointer with an optional default. */
@@ -244,7 +245,12 @@ export async function mountConnectors(ctx: RuntimeContext, app: AppApi): Promise
       );
     }
 
-    const wrapped = adaptConnectorHandler(worker);
+    const inner = adaptConnectorHandler(worker);
+    const wrapped: JobHandler = (job) =>
+      runInJobContext(
+        { instanceKey: job.processInstanceKey, elementId: job.elementId, jobType },
+        () => inner(job),
+      );
     const sub = await ctx.engine.registerWorker(jobType, wrapped, {
       workerName: `${ctx.manifest.id}:${jobType}`,
       // The pack's `defineWorker({ maxParallelJobs })` is the authoritative runtime

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

@@ -17,6 +17,7 @@ const noEngine: EngineClient = {
   publishMessage: async () => {},
   searchUserTasks: async () => [],
   completeUserTask: async () => {},
+  searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

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

@@ -6,7 +6,13 @@
 import type { RuntimeContext } from "../context.ts";
 import type { HostContext, SqliteDb } from "../host.ts";
 import type { AppManifest, DataSource, DomainType } from "../manifest.ts";
-import { makeGateway, Table, type DataSource as GatewayDataSource } from "./gateway.ts";
+import {
+  makeGateway,
+  Table,
+  type DataSource as GatewayDataSource,
+  type InsertObserver,
+} from "./gateway.ts";
+import { currentJobContext } from "../execContext.ts";
 
 export function sqlitePathFromUrl(url: string): string {
   // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
@@ -51,6 +57,65 @@ export function resolveAppPath(root: string, p: string): string {
  * both import this constant and the ledger name can never drift between application and listing. */
 export const MIGRATIONS_TABLE = "_urban_migrations";
 
+/** Name of the urban-owned write-provenance sidecar table (ProcessOS domain-signal plane, D0).
+ *  One append per app `Table.insert` performed inside a job, linking the written row —
+ *  `(source, table_name, pk_value)` — to the process instance/element that wrote it. Follows the
+ *  `_urban_` convention so it is automatically excluded from domain-model introspection,
+ *  DB Manager, and forms (see `gateway.ts` `schema()`), and never collides with an app table. */
+export const WRITE_PROVENANCE_TABLE = "_urban_write_provenance";
+
+/** Provision the write-provenance sidecar on a source (idempotent). Domain-free: it records only
+ *  the join key + timestamps, never any row content. */
+export function ensureProvenanceTable(db: SqliteDb): void {
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS ${WRITE_PROVENANCE_TABLE} (` +
+      "seq INTEGER PRIMARY KEY AUTOINCREMENT, " +
+      "source TEXT NOT NULL, " +
+      "table_name TEXT NOT NULL, " +
+      "pk_value TEXT NOT NULL, " +
+      "instance_key TEXT, " +
+      "element_id TEXT, " +
+      "job_type TEXT, " +
+      "op TEXT NOT NULL DEFAULT 'insert', " +
+      "at TEXT NOT NULL)",
+  );
+}
+
+/** Build the {@link InsertObserver} that captures write-provenance for one source. Best-effort:
+ *  it records a row only when a job execution context with an instance key is active (a worker
+ *  handler is running) — writes outside a job (e.g. HTTP actions) record nothing, degrading
+ *  gracefully. It skips urban/engine-internal tables so the provenance table never records
+ *  itself. It runs on the same connection as the insert, so inside a `tx` the provenance row is
+ *  committed/rolled back atomically with the app write. `Table.insert` wraps this defensively, so
+ *  a throw here can never break the app insert. */
+export function makeProvenanceRecorder(
+  host: HostContext,
+  db: SqliteDb,
+  source: string,
+): InsertObserver {
+  return (table, pk) => {
+    if (table.startsWith("_urban_") || table.startsWith("_nano_") || table.startsWith("sqlite_")) {
+      return;
+    }
+    const ctx = currentJobContext();
+    if (!ctx || ctx.instanceKey == null) return;
+    db.run(
+      `INSERT INTO ${WRITE_PROVENANCE_TABLE} ` +
+        "(source, table_name, pk_value, instance_key, element_id, job_type, op, at) " +
+        "VALUES (?, ?, ?, ?, ?, ?, 'insert', ?)",
+      [
+        source,
+        table,
+        String(pk),
+        ctx.instanceKey,
+        ctx.elementId ?? null,
+        ctx.jobType ?? null,
+        new Date(host.now()).toISOString(),
+      ],
+    );
+  };
+}
+
 /** Resolve a datasource `url` to its on-disk SQLite path against `root`. The result is absolute
  * when the resolved path is absolute (either because `url` names an absolute path or `root` is
  * absolute); if `root` is relative (e.g. "." as used by the CLI/tests) a relative `url` stays
@@ -320,6 +385,11 @@ async function provisionSqlite(
   const migrationsApplied = src.migrations
     ? await applyMigrations(ctx.host, db, ctx.root, src.migrations)
     : [];
+  // Provision the write-provenance sidecar and wire the gateway's insert observer to it, so
+  // every app `Table.insert` performed inside a job is linked to its process instance/element
+  // (ProcessOS domain-signal capture, D0). Domain-free and non-invasive — the sidecar lives
+  // outside the domain model.
+  ensureProvenanceTable(db);
   ctx.host.log("info", `datasource: provisioned "${name}"`, {
     driver: "sqlite",
     path: resolveSqlitePath(ctx.root, src.url),
@@ -329,7 +399,7 @@ async function provisionSqlite(
     name,
     driver: "sqlite",
     db,
-    source: makeGateway(db),
+    source: makeGateway(db, makeProvenanceRecorder(ctx.host, db, name)),
     migrationsApplied,
     close: () => db.close(),
   };