@nanobpm/urban 0.28.0 → 0.30.0

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

@@ -0,0 +1,310 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import { makeGateway } from "./gateway.ts";
+import type { Table } from "./gateway.ts";
+import { DataLayer, type ProvisionedSource } from "./datasource.ts";
+import type { AppApi } from "../context.ts";
+import type { EngineClient, ProcessInstanceSnapshot } from "../host.ts";
+import type { InstanceTracking } from "../manifest.ts";
+import { cancelInstanceReconciling } from "./cancel.ts";
+
+type State = ProcessInstanceSnapshot["state"];
+
+const PR_DDL = `CREATE TABLE pull_requests (
+  pr_key TEXT PRIMARY KEY,
+  process_key TEXT,
+  status TEXT NOT NULL
+);`;
+
+interface PrRow {
+  pr_key: string;
+  process_key: string | null;
+  status: string;
+}
+
+// The pull_requests binding: an ACTIVE row flips to `abandoned` (and drops the process pointer)
+// when its instance terminates — the exact patch the poll reconciler applies.
+const PR_BINDING: InstanceTracking = {
+  table: "pull_requests",
+  keyField: "process_key",
+  statusField: "status",
+  activeStatuses: ["converging"],
+  onTerminated: { set: { status: "abandoned", process_key: null } },
+};
+
+/** An EngineClient double for the cancel primitive. `cancelInstance` runs `onCancel` (which may
+ *  throw and/or mutate `states`); `searchProcessInstances` reflects the current `states` map, or
+ *  throws when `verifyThrows` is set (to exercise the unverifiable-read path). */
+function cancelEngine(opts: {
+  states: Record<string, State>;
+  onCancel: (key: string, states: Record<string, State>) => void;
+  verifyThrows?: boolean;
+}): { engine: EngineClient; cancels: string[] } {
+  const cancels: string[] = [];
+  const notUsed = (m: string) => (): never => {
+    throw new Error(`cancelEngine.${m} is not exercised by this test`);
+  };
+  const engine: EngineClient = {
+    async cancelInstance(args: { processInstanceKey: string }): Promise<void> {
+      cancels.push(args.processInstanceKey);
+      opts.onCancel(args.processInstanceKey, opts.states);
+    },
+    async searchProcessInstances(filter?: {
+      processInstanceKeys?: string[];
+      state?: State;
+    }): Promise<ProcessInstanceSnapshot[]> {
+      if (opts.verifyThrows) throw new Error("read model unavailable");
+      const keys = filter?.processInstanceKeys ?? [];
+      const out: ProcessInstanceSnapshot[] = [];
+      for (const key of keys) {
+        const state = opts.states[key];
+        if (state && (!filter?.state || filter.state === state)) {
+          out.push({ processInstanceKey: key, state });
+        }
+      }
+      return out;
+    },
+    deployResources: notUsed("deployResources"),
+    createInstance: notUsed("createInstance"),
+    publishMessage: notUsed("publishMessage"),
+    searchUserTasks: notUsed("searchUserTasks"),
+    completeUserTask: notUsed("completeUserTask"),
+    registerWorker: notUsed("registerWorker"),
+    close: notUsed("close"),
+  };
+  return { engine, cancels };
+}
+
+interface Harness {
+  api: AppApi;
+  table: Table<PrRow>;
+  logs: { level: string; msg: string }[];
+  close: () => Promise<void>;
+}
+
+async function withHarness(engine: EngineClient, seedStatus = "converging"): Promise<Harness> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-cancel-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  db.exec(PR_DDL);
+  const source: ProvisionedSource = {
+    name: "app",
+    driver: "sqlite",
+    db,
+    source: makeGateway(db),
+    migrationsApplied: [],
+    close: () => db.close(),
+  };
+  const data = new DataLayer(new Map([["app", source]]), "app", {});
+  const table = data.table<PrRow>("pull_requests", "process_key");
+  await table.insert({ pr_key: "pr-1", process_key: "100", status: seedStatus });
+  const logs: { level: string; msg: string }[] = [];
+  const api: AppApi = {
+    manifest: { schemaVersion: 1, id: "app", name: "App" },
+    data,
+    engine,
+    env: () => undefined,
+    log: (level, msg) => logs.push({ level, msg }),
+  };
+  return {
+    api,
+    table,
+    logs,
+    close: async () => {
+      db.close();
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+test("terminating a tracked instance reconciles its row immediately", async () => {
+  // cancelInstance succeeds (no throw) and the engine commits the termination.
+  const { engine, cancels } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: (key, states) => {
+      states[key] = "TERMINATED";
+    },
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.deepEqual(cancels, ["100"]);
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "TERMINATED");
+    assert.equal(r.reconciled, 1);
+    const row = await h.table.get("100");
+    assert.equal(row, undefined); // process_key was cleared to null, so no row keyed by "100"
+    const byPr = (await h.table.all()).find((x) => x.pr_key === "pr-1");
+    assert.equal(byPr?.status, "abandoned");
+    assert.equal(byPr?.process_key, null);
+  } finally {
+    await h.close();
+  }
+});
+
+test("a cancel that throws but reads back TERMINATED is idempotent success + reconciles", async () => {
+  // The instance was already terminated; the engine rejects a second cancel, but the verify read
+  // confirms it is gone — treat as success and still reconcile the (stale-active) row.
+  const { engine } = cancelEngine({
+    states: { "100": "TERMINATED" },
+    onCancel: () => {
+      throw new Error("instance is not active");
+    },
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "TERMINATED");
+    assert.equal(r.reconciled, 1);
+    const byPr = (await h.table.all()).find((x) => x.pr_key === "pr-1");
+    assert.equal(byPr?.status, "abandoned");
+  } finally {
+    await h.close();
+  }
+});
+
+test("a failed cancel with a still-ACTIVE instance is an honest failure and touches no row", async () => {
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: () => {
+      throw new Error("permission denied");
+    },
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, false);
+    assert.equal(r.state, "ACTIVE");
+    assert.equal(r.reconciled, 0);
+    assert.match(r.error ?? "", /permission denied/);
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging"); // untouched — instance still running
+    assert.ok(h.logs.some((l) => l.level === "error"));
+  } finally {
+    await h.close();
+  }
+});
+
+test("a COMPLETED instance is not reconciled (the app's finalize logic owns that row)", async () => {
+  const { engine } = cancelEngine({
+    states: { "100": "COMPLETED" },
+    onCancel: () => {}, // engine accepts the request; instance had already completed
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "COMPLETED");
+    assert.equal(r.reconciled, 0);
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging"); // left for the finalize worker, not clobbered
+  } finally {
+    await h.close();
+  }
+});
+
+test("a gone/unknown instance is idempotent success with no reconcile", async () => {
+  const { engine } = cancelEngine({
+    states: {}, // the engine has no record of this key
+    onCancel: () => {},
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "999999");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "gone");
+    assert.equal(r.reconciled, 0);
+  } finally {
+    await h.close();
+  }
+});
+
+test("a TERMINATED instance with no matching binding row reconciles nothing", async () => {
+  const { engine } = cancelEngine({
+    states: { "555": "TERMINATED" },
+    onCancel: () => {},
+  });
+  const h = await withHarness(engine);
+  try {
+    // "555" matches no row (the seeded row tracks "100").
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "555");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "TERMINATED");
+    assert.equal(r.reconciled, 0);
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging");
+  } finally {
+    await h.close();
+  }
+});
+
+test("a reconcile write failure does not fail the cancel (the engine already terminated it)", async () => {
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: (key, states) => {
+      states[key] = "TERMINATED";
+    },
+  });
+  const h = await withHarness(engine);
+  try {
+    // A binding pointing at a table that does not exist makes the reconcile UPDATE throw.
+    const badBinding: InstanceTracking = {
+      table: "does_not_exist",
+      keyField: "process_key",
+      onTerminated: { set: { status: "abandoned" } },
+    };
+    const r = await cancelInstanceReconciling(h.api, [badBinding], "100");
+    assert.equal(r.ok, true); // engine termination succeeded — the cancel is a success
+    assert.equal(r.state, "TERMINATED");
+    assert.equal(r.reconciled, 0);
+    assert.ok(r.error); // the reconcile failure is surfaced, not swallowed
+    assert.ok(h.logs.some((l) => l.level === "error"));
+  } finally {
+    await h.close();
+  }
+});
+
+test("an accepted cancel whose verify read fails is trusted (gone) — the 204 committed", async () => {
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: () => {}, // accepted
+    verifyThrows: true,
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "gone");
+    assert.equal(r.reconciled, 0);
+    assert.ok(h.logs.some((l) => l.level === "warn"));
+  } finally {
+    await h.close();
+  }
+});
+
+test("a thrown cancel whose verify read also fails is reported as an honest failure", async () => {
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: () => {
+      throw new Error("transport error");
+    },
+    verifyThrows: true,
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, false);
+    assert.equal(r.state, "ACTIVE");
+    assert.equal(r.reconciled, 0);
+    assert.match(r.error ?? "", /transport error/);
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging");
+  } finally {
+    await h.close();
+  }
+});

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

@@ -0,0 +1,119 @@
+// The Urban-native "cancel a process instance" primitive.
+//
+// Cancelling a running process from a page action must do two honest things that a bare
+// `engine.cancelInstance` call does not:
+//
+//   1. Report the *real* outcome. A cancel can fail (permissions, the instance already gone,
+//      a transport error). Swallowing that and reporting success leaves an instance running in
+//      the engine while the UI claims it stopped — the worst possible lie for a "cancel" button.
+//   2. Reconcile the tracked row immediately. Apps bind process instances to rows via
+//      `instanceTracking`; the poll reconciler flips a row to its terminal status within a few
+//      seconds of the instance terminating. When *we* are the one terminating it, we can apply
+//      that same declared patch right away instead of waiting for the next poll tick.
+//
+// This primitive keys success on the engine's response, then reconciles off the read model: a
+// non-throwing `cancelInstance` is a committed termination (trusted even if the read model still
+// lags at ACTIVE), while a throw whose instance reads back still-ACTIVE is an honest failure. It
+// reuses the instanceTracking bindings' `onTerminated.set` patch, so the immediate reconcile can
+// never drift from the poll reconciler's.
+
+import type { AppApi } from "../context.ts";
+import type { InstanceTracking } from "../manifest.ts";
+import { errorMessage } from "../guards.ts";
+import { reconcileTerminatedKey } from "./instance-tracking.ts";
+
+export type CancelInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED" | "gone";
+
+export interface CancelInstanceResult {
+  ok: boolean;
+  processInstanceKey: string;
+  /** The instance state as read back from the engine after the cancel attempt.
+   *  `"gone"` means the engine has no record of the key (already cleaned up / never existed). */
+  state: CancelInstanceState;
+  /** Rows flipped to their terminal status by the immediate instanceTracking reconcile. */
+  reconciled: number;
+  error?: string;
+}
+
+type CancelApi = Pick<AppApi, "engine" | "data" | "log">;
+
+/**
+ * Cancel a process instance honestly: terminate it, verify it is actually gone, and immediately
+ * reconcile any instanceTracking row bound to its key.
+ *
+ * Outcome rules:
+ *  - `cancelInstance` returns without throwing → the engine accepted the termination (a committed
+ *    204); trust it even if the read model still lags at ACTIVE.
+ *  - `cancelInstance` throws but the instance reads back non-ACTIVE (already TERMINATED/COMPLETED
+ *    /gone) → the cancel was effectively idempotent; treat as success.
+ *  - `cancelInstance` throws and the instance is still ACTIVE → an honest failure: report it and
+ *    do NOT touch any row (the instance is still running).
+ *
+ * Reconcile only on `TERMINATED`: a COMPLETED instance's terminal row-write is owned by the app's
+ * own finalize logic, and a gone/ACTIVE instance has nothing to flip here.
+ */
+export async function cancelInstanceReconciling(
+  api: CancelApi,
+  bindings: InstanceTracking[],
+  processInstanceKey: string,
+): Promise<CancelInstanceResult> {
+  const key = String(processInstanceKey);
+
+  let threw: unknown;
+  try {
+    await api.engine.cancelInstance({ processInstanceKey: key });
+  } catch (error) {
+    threw = error;
+  }
+
+  const state = await readState(api, key, threw);
+
+  if (threw && state === "ACTIVE") {
+    // The cancel genuinely failed and the instance is still running — never flip a row to a
+    // terminal status while the engine keeps executing it.
+    api.log("error", "cancel: engine termination failed, instance still active", {
+      processInstanceKey: key,
+      error: errorMessage(threw),
+    });
+    return { ok: false, processInstanceKey: key, state, reconciled: 0, error: errorMessage(threw) };
+  }
+
+  let reconciled = 0;
+  if (state === "TERMINATED") {
+    try {
+      reconciled = await reconcileTerminatedKey(api, bindings, key);
+    } catch (error) {
+      // The engine termination itself succeeded — a reconcile *write* failure (bad binding,
+      // transient DB error) must not turn that into an unhandled 500. Log it and let the
+      // instanceTracking poll reconciler catch the row up on its next tick.
+      api.log("error", "cancel: instance terminated but row reconcile failed", {
+        processInstanceKey: key,
+        error: errorMessage(error),
+      });
+      return { ok: true, processInstanceKey: key, state, reconciled: 0, error: errorMessage(error) };
+    }
+  }
+
+  return { ok: true, processInstanceKey: key, state, reconciled };
+}
+
+/** Read the instance state back from the engine to verify what actually happened. When the read
+ *  itself fails we fall back to the cancel call's own result: a thrown cancel with an unverifiable
+ *  state is reported as still-ACTIVE (honest worst case); an accepted cancel is trusted as gone. */
+async function readState(
+  api: CancelApi,
+  key: string,
+  threw: unknown,
+): Promise<CancelInstanceState> {
+  try {
+    const [snapshot] = await api.engine.searchProcessInstances({ processInstanceKeys: [key] });
+    if (snapshot) return snapshot.state;
+    return "gone";
+  } catch (error) {
+    api.log("warn", "cancel: could not verify post-cancel state", {
+      processInstanceKey: key,
+      error: errorMessage(error),
+    });
+    return threw ? "ACTIVE" : "gone";
+  }
+}

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,14 @@
 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";
+import { isAbsolutePath } from "../../../toolkit/artifact.ts";
 
 export function sqlitePathFromUrl(url: string): string {
   // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
@@ -19,10 +26,10 @@ export function sqlitePathFromUrl(url: string): string {
  * that starts with a single backslash ("\data\app.db") and a Windows UNC path
  * ("\\\\server\\share"). A single leading backslash covers both the drive-root and UNC cases,
  * matching Node's `path.win32.isAbsolute`. Used by `resolveAppPath` so a caller-supplied absolute
- * path is never incorrectly prefixed with the app root. */
-export function isAbsolutePath(p: string): boolean {
-  return /^(\/|\\|[A-Za-z]:[/\\])/.test(p);
-}
+ * path is never incorrectly prefixed with the app root. Defined once in `toolkit/artifact.ts` (the
+ * shared, dependency-free layer) and re-exported here so the toolkit's gen path-join and this
+ * runtime resolver apply the identical rule (no gen/runtime drift). */
+export { isAbsolutePath };
 
 /** Resolve `p` against the app `root`: an absolute `p` (see `isAbsolutePath`) is returned as-is;
  * a relative `p` is joined onto `root`. Trims a trailing separator of either kind off `root` so
@@ -51,6 +58,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 +386,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 +400,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);
 }