@nanobpm/urban 0.27.0 → 0.29.0

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(),
   };

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

@@ -16,6 +16,12 @@ import type { SqliteDb } from "../host.ts";
 
 export type Row = Record<string, unknown>;
 
+/** Best-effort observer invoked after a successful {@link Table.insert}, with the table name and
+ *  the new primary-key value. The DataLayer uses it to capture write-provenance. It MUST NOT
+ *  throw — an app insert must never fail because provenance capture did — but {@link Table.insert}
+ *  also wraps it defensively. */
+export type InsertObserver = (table: string, pk: number | bigint) => void;
+
 export interface ExecResult {
   /** Rows changed by an INSERT/UPDATE/DELETE. */
   changed: number;
@@ -92,11 +98,13 @@ export class Table<T extends object = Row> {
   readonly name: string;
   readonly pk: string;
   readonly #src: DataSource;
+  readonly #onInsert?: InsertObserver;
 
-  constructor(src: DataSource, name: string, pk = "id") {
+  constructor(src: DataSource, name: string, pk = "id", onInsert?: InsertObserver) {
     this.#src = src;
     this.name = name;
     this.pk = pk;
+    this.#onInsert = onInsert;
   }
 
   /** Insert one row; returns the new primary-key value (the inserted rowid for an INTEGER
@@ -124,6 +132,16 @@ export class Table<T extends object = Row> {
       // silently returning 0, which a caller could mistake for a real primary key.
       throw new Error(`Table(${this.name}).insert: driver reported no lastInsertId`);
     }
+    if (this.#onInsert) {
+      // Provenance capture is strictly observational: never let it break the app insert, which
+      // executed successfully above. If this insert runs inside a transaction, commit/rollback
+      // semantics still belong to that surrounding transaction.
+      try {
+        this.#onInsert(this.name, r.lastInsertId);
+      } catch {
+        // swallow — an insert must never fail because provenance capture did
+      }
+    }
     return r.lastInsertId;
   }
 
@@ -202,8 +220,10 @@ export class Table<T extends object = Row> {
  * are async to hold the app-facing contract; the work underneath is synchronous. */
 class SqliteGateway implements DataSource {
   readonly #db: SqliteDb;
-  constructor(db: SqliteDb) {
+  readonly #onInsert?: InsertObserver;
+  constructor(db: SqliteDb, onInsert?: InsertObserver) {
     this.#db = db;
+    this.#onInsert = onInsert;
   }
 
   async query<T extends object = Row>(sql: string, params: unknown[] = []): Promise<T[]> {
@@ -272,11 +292,13 @@ class SqliteGateway implements DataSource {
   }
 
   table<T extends object = Row>(name: string, pk = "id"): Table<T> {
-    return new Table<T>(this, name, pk);
+    return new Table<T>(this, name, pk, this.#onInsert);
   }
 }
 
-/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. */
-export function makeGateway(db: SqliteDb): DataSource {
-  return new SqliteGateway(db);
+/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. An optional
+ *  `onInsert` observer is invoked after every successful `Table.insert` (used for
+ *  write-provenance capture); it is threaded to each `Table` this gateway creates. */
+export function makeGateway(db: SqliteDb, onInsert?: InsertObserver): DataSource {
+  return new SqliteGateway(db, onInsert);
 }