@nanobpm/urban 0.78.0 → 0.79.0

package/dist/runtime/core/modules/canonical-projections.d.ts

@@ -0,0 +1,13 @@
+import { type ProjectionRegistry } from "../read-model.ts";
+/** The canonical projection name → physical `_urban_` table mappings this task owns. */
+export declare const CANONICAL_PROJECTIONS: ReadonlyArray<{
+    readonly name: string;
+    readonly sqlTable: string;
+}>;
+/**
+ * Register the canonical engine-truth projections in a {@link ProjectionRegistry} (defaults to the
+ * process-wide `projectionRegistry`), so a `defineReadModel(...)` authored anywhere can
+ * `exists("urban_open_user_tasks", …)` / `exists("urban_instance_state", …)` and have the SQL backend
+ * resolve them to the `_urban_`-prefixed physical tables. Idempotent.
+ */
+export declare function registerCanonicalProjections(registry?: ProjectionRegistry): void;

package/dist/runtime/core/modules/canonical-projections.js

@@ -0,0 +1,30 @@
+// canonical-projections — register the framework's canonical engine-truth projections under their
+// stable DSL names (ADR 0065, proposal point #1). This is the concrete use of the projection-name
+// seam the read-model primitive established (`projectionRegistry.register({ name, sqlTable })`): it
+// maps each unprefixed DSL name a `defineReadModel(...)` `exists(...)` reads
+// (`urban_open_user_tasks`, `urban_instance_state`) onto its `_urban_`-prefixed physical sidecar
+// table, so the SQL backend's `EXISTS` compiles against the real table while the domain model / DB
+// Manager never sees it.
+//
+// Registration is idempotent (the registry no-ops a matching re-register), so calling this on every
+// worker mount — the boot path in `workers.ts` — is safe. It is decoupled from schema provisioning:
+// a read model must be able to reference these projections by name even in a process/app that has no
+// datasource to provision the physical tables into.
+import { INSTANCE_STATE_PROJECTION, INSTANCE_STATE_TABLE, } from "./instance-state-store.js";
+import { OPEN_USER_TASKS_PROJECTION, OPEN_USER_TASKS_TABLE, } from "./open-user-tasks-store.js";
+import { projectionRegistry } from "../read-model.js";
+/** The canonical projection name → physical `_urban_` table mappings this task owns. */
+export const CANONICAL_PROJECTIONS = [
+    { name: OPEN_USER_TASKS_PROJECTION, sqlTable: OPEN_USER_TASKS_TABLE },
+    { name: INSTANCE_STATE_PROJECTION, sqlTable: INSTANCE_STATE_TABLE },
+];
+/**
+ * Register the canonical engine-truth projections in a {@link ProjectionRegistry} (defaults to the
+ * process-wide `projectionRegistry`), so a `defineReadModel(...)` authored anywhere can
+ * `exists("urban_open_user_tasks", …)` / `exists("urban_instance_state", …)` and have the SQL backend
+ * resolve them to the `_urban_`-prefixed physical tables. Idempotent.
+ */
+export function registerCanonicalProjections(registry = projectionRegistry) {
+    for (const projection of CANONICAL_PROJECTIONS)
+        registry.register(projection);
+}

package/dist/runtime/core/modules/instance-state-store.d.ts

@@ -0,0 +1,50 @@
+import type { ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb } from "../host.ts";
+import { type Clock } from "./lineage-store.ts";
+/** The instance-state projection table. Framework bookkeeping, so `_urban_`-prefixed to stay hidden
+ *  from the domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables. */
+export declare const INSTANCE_STATE_TABLE = "_urban_instance_state";
+/** The stable DSL projection NAME a `defineReadModel` `exists(...)` references (registered in the
+ *  `projectionRegistry`, mapped to {@link INSTANCE_STATE_TABLE}). The DSL name is unprefixed so a read
+ *  model reads `EXISTS(urban_instance_state WHERE process_instance_key = base.process_instance_key)`. */
+export declare const INSTANCE_STATE_PROJECTION = "urban_instance_state";
+/**
+ * The canonical instance-state DDL — the single source of truth applied by
+ * {@link InstanceStateStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/007_urban_instance_state.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. Keyed by `process_instance_key` (one canonical state per instance) so a
+ * re-record upserts in place and is idempotent. `waiting_on_human` is 0/1 (SQLite has no boolean).
+ */
+export declare const INSTANCE_STATE_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS _urban_instance_state (\n  process_instance_key TEXT NOT NULL,\n  state                TEXT NOT NULL,\n  waiting_on_human     INTEGER NOT NULL DEFAULT 0,\n  updated_at           TEXT NOT NULL,\n  PRIMARY KEY (process_instance_key)\n);";
+export interface InstanceStateStoreOptions {
+    readonly clock?: Clock;
+}
+/** One projected instance-state row, as {@link InstanceStateStore.getState} returns it. */
+export interface InstanceStateRow {
+    readonly processInstanceKey: string;
+    readonly state: ProcessInstanceState;
+    readonly waitingOnHuman: boolean;
+}
+/**
+ * The per-source sidecar behind the `urban_instance_state` projection. A thin, idempotent
+ * persistence + query layer over the engine's per-instance lifecycle truth.
+ */
+export declare class InstanceStateStore {
+    #private;
+    constructor(db: SqliteDb, options?: InstanceStateStoreOptions);
+    /** Apply the canonical DDL (idempotent). Callers whose app DataLayer applies the boot migration
+     *  `db/migrations/007_urban_instance_state.sql` do not need this; the runtime calls it so the store
+     *  is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+    ensureSchema(): void;
+    /**
+     * Record an instance's canonical engine lifecycle state (and whether it is waiting on a human),
+     * upserting the single row keyed by `processInstanceKey`. Idempotent: re-recording the same
+     * `(state, waitingOnHuman)` is a no-op (returns `false`). A blank `processInstanceKey` is ignored.
+     */
+    recordState(processInstanceKey: string, state: ProcessInstanceState, waitingOnHuman?: boolean): boolean;
+    /** Record from a {@link ProcessInstanceSnapshot} (the engine's `searchProcessInstances` row),
+     *  carrying the optional waiting-on-human flag the reconciler probes separately. */
+    recordFromSnapshot(snapshot: ProcessInstanceSnapshot, waitingOnHuman?: boolean): boolean;
+    /** The projected canonical state for an instance, or `undefined` if none recorded. */
+    getState(processInstanceKey: string): InstanceStateRow | undefined;
+}

package/dist/runtime/core/modules/instance-state-store.js

@@ -0,0 +1,101 @@
+// instance-state-store — the canonical per-instance engine lifecycle-state projection (ADR 0065,
+// proposal point #1). A framework-level, per-source sidecar (exactly like the lineage store) that
+// records each tracked process instance's engine-truth lifecycle state (ACTIVE / COMPLETED /
+// TERMINATED) plus whether it is waiting on a human, from the same `searchProcessInstances` /
+// `openUserTasks` truth the `instanceTracking` reconciler already reads.
+//
+// A read model can then DERIVE an instance's status edge purely from this projection — e.g. the
+// terminal edge (`onTerminated`, → `abandoned`) becomes an `EXISTS(urban_instance_state WHERE
+// process_instance_key = … AND state = 'TERMINATED')` derivation, instead of a stored `status` write
+// that tears from engine truth. This projection PROVIDES that engine-truth source; retiring the
+// reconciler's writes is the downstream `writer-source-inversion` task.
+//
+// It is framework bookkeeping, so the physical table is `_urban_`-prefixed to stay hidden from the
+// domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables — and NEVER
+// app-written. Recording is idempotent: re-recording an unchanged state is a no-op.
+import { systemClock } from "./lineage-store.js";
+/** The instance-state projection table. Framework bookkeeping, so `_urban_`-prefixed to stay hidden
+ *  from the domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables. */
+export const INSTANCE_STATE_TABLE = "_urban_instance_state";
+/** The stable DSL projection NAME a `defineReadModel` `exists(...)` references (registered in the
+ *  `projectionRegistry`, mapped to {@link INSTANCE_STATE_TABLE}). The DSL name is unprefixed so a read
+ *  model reads `EXISTS(urban_instance_state WHERE process_instance_key = base.process_instance_key)`. */
+export const INSTANCE_STATE_PROJECTION = "urban_instance_state";
+/**
+ * The canonical instance-state DDL — the single source of truth applied by
+ * {@link InstanceStateStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/007_urban_instance_state.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. Keyed by `process_instance_key` (one canonical state per instance) so a
+ * re-record upserts in place and is idempotent. `waiting_on_human` is 0/1 (SQLite has no boolean).
+ */
+export const INSTANCE_STATE_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${INSTANCE_STATE_TABLE} (
+  process_instance_key TEXT NOT NULL,
+  state                TEXT NOT NULL,
+  waiting_on_human     INTEGER NOT NULL DEFAULT 0,
+  updated_at           TEXT NOT NULL,
+  PRIMARY KEY (process_instance_key)
+);`;
+function normalizeState(raw) {
+    // Validate rather than coerce: silently mapping an unknown value to "ACTIVE" would let corrupted rows
+    // or an unhandled new engine state masquerade as ACTIVE and produce incorrect derived edges. Surface
+    // the bad data loudly instead.
+    if (raw === "ACTIVE" || raw === "COMPLETED" || raw === "TERMINATED")
+        return raw;
+    throw new Error(`${INSTANCE_STATE_TABLE} contains an unexpected state ${JSON.stringify(raw)} — refusing to coerce to ACTIVE (data corruption or an unhandled engine state)`);
+}
+/**
+ * The per-source sidecar behind the `urban_instance_state` projection. A thin, idempotent
+ * persistence + query layer over the engine's per-instance lifecycle truth.
+ */
+export class InstanceStateStore {
+    #db;
+    #clock;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#clock = options.clock ?? systemClock;
+    }
+    /** Apply the canonical DDL (idempotent). Callers whose app DataLayer applies the boot migration
+     *  `db/migrations/007_urban_instance_state.sql` do not need this; the runtime calls it so the store
+     *  is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+    ensureSchema() {
+        this.#db.exec(INSTANCE_STATE_SCHEMA_SQL);
+    }
+    /**
+     * Record an instance's canonical engine lifecycle state (and whether it is waiting on a human),
+     * upserting the single row keyed by `processInstanceKey`. Idempotent: re-recording the same
+     * `(state, waitingOnHuman)` is a no-op (returns `false`). A blank `processInstanceKey` is ignored.
+     */
+    recordState(processInstanceKey, state, waitingOnHuman = false) {
+        if (!processInstanceKey)
+            return false;
+        const { changes } = this.#db.run(`INSERT INTO ${INSTANCE_STATE_TABLE}
+         (process_instance_key, state, waiting_on_human, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT (process_instance_key) DO UPDATE SET
+         state = excluded.state,
+         waiting_on_human = excluded.waiting_on_human,
+         updated_at = excluded.updated_at
+       WHERE ${INSTANCE_STATE_TABLE}.state <> excluded.state
+          OR ${INSTANCE_STATE_TABLE}.waiting_on_human <> excluded.waiting_on_human`, [processInstanceKey, state, waitingOnHuman ? 1 : 0, new Date(this.#clock.now()).toISOString()]);
+        return changes > 0;
+    }
+    /** Record from a {@link ProcessInstanceSnapshot} (the engine's `searchProcessInstances` row),
+     *  carrying the optional waiting-on-human flag the reconciler probes separately. */
+    recordFromSnapshot(snapshot, waitingOnHuman = false) {
+        return this.recordState(snapshot.processInstanceKey, snapshot.state, waitingOnHuman);
+    }
+    /** The projected canonical state for an instance, or `undefined` if none recorded. */
+    getState(processInstanceKey) {
+        const rows = this.#db.all(`SELECT process_instance_key, state, waiting_on_human
+         FROM ${INSTANCE_STATE_TABLE} WHERE process_instance_key = ?`, [processInstanceKey]);
+        const row = rows[0];
+        if (!row)
+            return undefined;
+        return {
+            processInstanceKey: row.process_instance_key,
+            state: normalizeState(row.state),
+            waitingOnHuman: row.waiting_on_human !== 0,
+        };
+    }
+}

package/dist/runtime/core/modules/open-user-tasks-store.d.ts

@@ -0,0 +1,63 @@
+import type { SqliteDb } from "../host.ts";
+import type { UserTaskSummary } from "../host.ts";
+import { type Clock } from "./lineage-store.ts";
+/** The open-user-tasks projection table. Framework bookkeeping, so `_urban_`-prefixed to stay hidden
+ *  from the domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables. */
+export declare const OPEN_USER_TASKS_TABLE = "_urban_open_user_tasks";
+/** The stable DSL projection NAME a `defineReadModel` `exists(...)` references (registered in the
+ *  `projectionRegistry`, mapped to {@link OPEN_USER_TASKS_TABLE}). The DSL name is unprefixed so a read
+ *  model reads `EXISTS(urban_open_user_tasks WHERE process_instance_key = base.process_instance_key)`. */
+export declare const OPEN_USER_TASKS_PROJECTION = "urban_open_user_tasks";
+/**
+ * The canonical open-user-tasks DDL — the single source of truth applied by
+ * {@link OpenUserTasksStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/006_urban_open_user_tasks.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. Keyed by `user_task_key` so a re-record of the same open task is a no-op;
+ * `process_instance_key` carries an index so a read model's correlated `EXISTS(... WHERE
+ * process_instance_key = …)` and the reconciler's per-instance sync read only that instance's rows.
+ */
+export declare const OPEN_USER_TASKS_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS _urban_open_user_tasks (\n  process_instance_key TEXT NOT NULL,\n  user_task_key        TEXT NOT NULL,\n  element_id           TEXT,\n  created_at           TEXT NOT NULL,\n  PRIMARY KEY (user_task_key)\n);\nCREATE INDEX IF NOT EXISTS idx__urban_open_user_tasks_instance ON _urban_open_user_tasks (process_instance_key);";
+export interface OpenUserTasksStoreOptions {
+    readonly clock?: Clock;
+}
+/** One projected open-user-task row, as {@link OpenUserTasksStore.openTasks} returns it. */
+export interface OpenUserTaskRow {
+    readonly processInstanceKey: string;
+    readonly userTaskKey: string;
+    readonly elementId?: string;
+}
+/**
+ * The per-source sidecar behind the `urban_open_user_tasks` projection. A thin, idempotent
+ * persistence + query layer over the engine's open-user-task truth; it interprets no app schema.
+ */
+export declare class OpenUserTasksStore {
+    #private;
+    constructor(db: SqliteDb, options?: OpenUserTasksStoreOptions);
+    /** Apply the canonical DDL (idempotent). Callers whose app DataLayer applies the boot migration
+     *  `db/migrations/006_urban_open_user_tasks.sql` do not need this; the runtime calls it so the store
+     *  is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+    ensureSchema(): void;
+    /**
+     * Record one open user task for an instance, idempotently. A re-record of the same `userTaskKey` is
+     * a no-op. A blank `processInstanceKey` or `userTaskKey` is ignored. Prefer {@link syncInstance} to
+     * record an instance's WHOLE current open set (which also retires closed tasks); this single-row
+     * form is the idempotent building block.
+     */
+    recordOpenTask(processInstanceKey: string, task: UserTaskSummary): boolean;
+    /**
+     * Make the projection reflect an instance's CURRENT open set exactly: insert the engine's open tasks
+     * and delete any previously-projected task for the instance that is no longer open. This is the
+     * authoritative record from engine truth (`openUserTasks({ processInstanceKey })`), the operation the
+     * reconciler drives each poll — so an answered/closed task disappears and the derived
+     * "waiting-on-human" edge re-flips by construction (nano-workforce#422). Idempotent: syncing the same
+     * open set twice leaves the table unchanged. A blank `processInstanceKey` is ignored.
+     */
+    syncInstance(processInstanceKey: string, openTasks: readonly UserTaskSummary[]): void;
+    /** Retire every projected open task for an instance (e.g. it terminated). Idempotent. */
+    clearInstance(processInstanceKey: string): void;
+    /** True iff the instance currently has any open user task — the "parked on a human" predicate. */
+    hasOpenTask(processInstanceKey: string): boolean;
+    /** The projected open tasks for an instance, in insertion order. */
+    openTasks(processInstanceKey: string): OpenUserTaskRow[];
+}

package/dist/runtime/core/modules/open-user-tasks-store.js

@@ -0,0 +1,135 @@
+// open-user-tasks-store — the canonical engine-truth projection of "which process instances are
+// parked on a human" (ADR 0065, proposal point #1). A framework-level, per-source sidecar (exactly
+// like the lineage store) that materialises the set of currently-open (CREATED-state) user tasks per
+// process instance from engine truth — the same `openUserTasks` / `searchUserTasks({state:"CREATED"})`
+// query the `instanceTracking` reconciler already runs.
+//
+// This ABSORBS nano-workforce's hand-rolled `user_tasks` table: it is the ONE authoritative projection
+// a read model can `EXISTS`-over to derive the "waiting-on-human" status edge, instead of an app
+// hand-maintaining a stored `awaiting_operator` column (the tearing surface of nano-workforce#422).
+//
+// It is framework bookkeeping, so the physical table is `_urban_`-prefixed to stay hidden from the
+// domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables — and it is NEVER
+// app-written. Recording is idempotent and authoritative-per-instance: {@link OpenUserTasksStore.syncInstance}
+// replaces an instance's rows with exactly the engine's current open set, so an answered/closed task
+// disappears on the next poll and the derived edge re-flips by construction (No Drift Surfaces).
+import { systemClock } from "./lineage-store.js";
+/** The open-user-tasks projection table. Framework bookkeeping, so `_urban_`-prefixed to stay hidden
+ *  from the domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables. */
+export const OPEN_USER_TASKS_TABLE = "_urban_open_user_tasks";
+/** The stable DSL projection NAME a `defineReadModel` `exists(...)` references (registered in the
+ *  `projectionRegistry`, mapped to {@link OPEN_USER_TASKS_TABLE}). The DSL name is unprefixed so a read
+ *  model reads `EXISTS(urban_open_user_tasks WHERE process_instance_key = base.process_instance_key)`. */
+export const OPEN_USER_TASKS_PROJECTION = "urban_open_user_tasks";
+/**
+ * The canonical open-user-tasks DDL — the single source of truth applied by
+ * {@link OpenUserTasksStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/006_urban_open_user_tasks.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. Keyed by `user_task_key` so a re-record of the same open task is a no-op;
+ * `process_instance_key` carries an index so a read model's correlated `EXISTS(... WHERE
+ * process_instance_key = …)` and the reconciler's per-instance sync read only that instance's rows.
+ */
+export const OPEN_USER_TASKS_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${OPEN_USER_TASKS_TABLE} (
+  process_instance_key TEXT NOT NULL,
+  user_task_key        TEXT NOT NULL,
+  element_id           TEXT,
+  created_at           TEXT NOT NULL,
+  PRIMARY KEY (user_task_key)
+);
+CREATE INDEX IF NOT EXISTS idx_${OPEN_USER_TASKS_TABLE}_instance ON ${OPEN_USER_TASKS_TABLE} (process_instance_key);`;
+/**
+ * The per-source sidecar behind the `urban_open_user_tasks` projection. A thin, idempotent
+ * persistence + query layer over the engine's open-user-task truth; it interprets no app schema.
+ */
+export class OpenUserTasksStore {
+    #db;
+    #clock;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#clock = options.clock ?? systemClock;
+    }
+    /** Apply the canonical DDL (idempotent). Callers whose app DataLayer applies the boot migration
+     *  `db/migrations/006_urban_open_user_tasks.sql` do not need this; the runtime calls it so the store
+     *  is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+    ensureSchema() {
+        this.#db.exec(OPEN_USER_TASKS_SCHEMA_SQL);
+    }
+    /**
+     * Record one open user task for an instance, idempotently. A re-record of the same `userTaskKey` is
+     * a no-op. A blank `processInstanceKey` or `userTaskKey` is ignored. Prefer {@link syncInstance} to
+     * record an instance's WHOLE current open set (which also retires closed tasks); this single-row
+     * form is the idempotent building block.
+     */
+    recordOpenTask(processInstanceKey, task) {
+        if (!processInstanceKey || !task.userTaskKey)
+            return false;
+        const { changes } = this.#db.run(`INSERT OR IGNORE INTO ${OPEN_USER_TASKS_TABLE}
+         (process_instance_key, user_task_key, element_id, created_at)
+       VALUES (?, ?, ?, ?)`, [processInstanceKey, task.userTaskKey, task.elementId ?? null, new Date(this.#clock.now()).toISOString()]);
+        return changes > 0;
+    }
+    /**
+     * Make the projection reflect an instance's CURRENT open set exactly: insert the engine's open tasks
+     * and delete any previously-projected task for the instance that is no longer open. This is the
+     * authoritative record from engine truth (`openUserTasks({ processInstanceKey })`), the operation the
+     * reconciler drives each poll — so an answered/closed task disappears and the derived
+     * "waiting-on-human" edge re-flips by construction (nano-workforce#422). Idempotent: syncing the same
+     * open set twice leaves the table unchanged. A blank `processInstanceKey` is ignored.
+     */
+    syncInstance(processInstanceKey, openTasks) {
+        if (!processInstanceKey)
+            return;
+        // Wrap the insert+delete replace in a SAVEPOINT so the whole sync is atomic: no reader observes a
+        // transient mixed state mid-sync, and a mid-loop failure rolls back cleanly instead of leaving the
+        // instance with a torn open set. SAVEPOINT (not BEGIN) so this also composes when called inside an
+        // existing transaction, e.g. a reconciler poll that batches many instances.
+        this.#db.exec("SAVEPOINT urban_sync_open_tasks");
+        try {
+            const keep = new Set();
+            for (const task of openTasks) {
+                if (!task.userTaskKey)
+                    continue;
+                keep.add(task.userTaskKey);
+                this.recordOpenTask(processInstanceKey, task);
+            }
+            const existing = this.#db.all(`SELECT user_task_key FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ?`, [processInstanceKey]);
+            for (const row of existing) {
+                if (!keep.has(row.user_task_key)) {
+                    this.#db.run(`DELETE FROM ${OPEN_USER_TASKS_TABLE} WHERE user_task_key = ?`, [row.user_task_key]);
+                }
+            }
+            this.#db.exec("RELEASE urban_sync_open_tasks");
+        }
+        catch (err) {
+            this.#db.exec("ROLLBACK TO urban_sync_open_tasks");
+            this.#db.exec("RELEASE urban_sync_open_tasks");
+            throw err;
+        }
+    }
+    /** Retire every projected open task for an instance (e.g. it terminated). Idempotent. */
+    clearInstance(processInstanceKey) {
+        if (!processInstanceKey)
+            return;
+        this.#db.run(`DELETE FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ?`, [processInstanceKey]);
+    }
+    /** True iff the instance currently has any open user task — the "parked on a human" predicate. */
+    hasOpenTask(processInstanceKey) {
+        if (!processInstanceKey)
+            return false;
+        // Existence predicate: `SELECT 1 … LIMIT 1` short-circuits on the first matching row rather than
+        // counting every open task for the instance.
+        const rows = this.#db.all(`SELECT 1 AS one FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ? LIMIT 1`, [processInstanceKey]);
+        return rows.length > 0;
+    }
+    /** The projected open tasks for an instance, in insertion order. */
+    openTasks(processInstanceKey) {
+        const rows = this.#db.all(`SELECT process_instance_key, user_task_key, element_id
+         FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ? ORDER BY rowid`, [processInstanceKey]);
+        return rows.map((r) => ({
+            processInstanceKey: r.process_instance_key,
+            userTaskKey: r.user_task_key,
+            ...(r.element_id ? { elementId: r.element_id } : {}),
+        }));
+    }
+}

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

@@ -8,6 +8,9 @@ import { runInJobContext } from "../execContext.js";
 import { readLineage } from "../lineage.js";
 import { LineageStore } from "./lineage-store.js";
 import { readModelRegistry } from "../read-model.js";
+import { registerCanonicalProjections } from "./canonical-projections.js";
+import { InstanceStateStore } from "./instance-state-store.js";
+import { OpenUserTasksStore } from "./open-user-tasks-store.js";
 import { defaultScheduler, schedulerClock } from "./scheduler.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
@@ -119,6 +122,28 @@ function tryProvisionReadModelViews(app, log) {
         log("warn", "read-models: failed to provision managed VIEWs", { error: String(err) });
     }
 }
+/**
+ * Provision the canonical engine-truth projection sidecars (ADR 0065, proposal point #1) on the app's
+ * DEFAULT data source — `_urban_open_user_tasks` and `_urban_instance_state`, the sources a read model
+ * `EXISTS`-derives its status edges from. Exactly the per-source boot path `tryLineageStore` uses: an
+ * app with no datasource provisions nothing, and a schema failure degrades to no projection tables
+ * rather than a failed worker mount. The DSL projection-name registration is done unconditionally by
+ * the caller (so read models compile even without a datasource); this only creates the physical tables.
+ */
+function tryProvisionCanonicalProjections(app, log) {
+    if (!app.data.hasDefaultSource()) {
+        log("debug", "canonical-projections: no default data source; projection tables not provisioned");
+        return;
+    }
+    try {
+        const { db } = app.data.source();
+        new OpenUserTasksStore(db).ensureSchema();
+        new InstanceStateStore(db).ensureSchema();
+    }
+    catch (err) {
+        log("warn", "canonical-projections: failed to provision projection tables", { error: String(err) });
+    }
+}
 /** Record an activated job's lineage edge, never letting a projection write break the job. */
 function recordJobLineage(store, job, log) {
     try {
@@ -169,6 +194,14 @@ export async function mountWorkers(ctx, app, sched = defaultScheduler()) {
     // The framework read-model VIEWs (ADR 0065): apply every registered managed VIEW to the app's
     // default data source, the same per-source boot path lineage uses. A no-op until a sibling task
     // registers a read model into `readModelRegistry`.
+    //
+    // Register the canonical engine-truth projections (`urban_open_user_tasks`, `urban_instance_state`)
+    // FIRST and unconditionally: a read model's managed VIEW resolves each projection name to its
+    // physical `_urban_` table at DDL-compile time, so the name→table mapping must exist before
+    // `tryProvisionReadModelViews` compiles any VIEW that `EXISTS`-references a projection. Then
+    // provision the projection tables per source (absent-safe), and finally the read-model VIEWs.
+    registerCanonicalProjections();
+    tryProvisionCanonicalProjections(app, ctx.host.log);
     tryProvisionReadModelViews(app, ctx.host.log);
     // Cache module loads so a multi-type handler module is imported once.
     const moduleCache = new Map();

package/dist/runtime/index.d.ts

@@ -42,6 +42,11 @@ export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, Lin
 export type { Clock as LineageClock, LineageJobLike, LineageStoreOptions, } from "./core/modules/lineage-store.ts";
 export { and, assertReadModelParity, assertSqlIdentifier, caseWhen, col, compileToFn, compileToSqlSelect, defineReadModel, deriveReadModelViewDdl, eq, exists, gt, gte, lit, lt, lte, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, ReadModelRegistry, readModelRegistry, when, } from "./core/read-model.ts";
 export type { AndExpr, BaseRow, CaseExpr, ColExpr, CompareExpr, CompareOp, DerivationFn, ExistsExpr, Expr, Literal, LitExpr, NotExpr, OrExpr, ParityDb, ParityOptions, ParitySample, ProjColExpr, ProjectionRows, ProjectionSource, ReadModel, ReadModelDecl, SqlCompileOptions, WhenClause, } from "./core/read-model.ts";
+export { CANONICAL_PROJECTIONS, registerCanonicalProjections, } from "./core/modules/canonical-projections.ts";
+export { OPEN_USER_TASKS_PROJECTION, OPEN_USER_TASKS_SCHEMA_SQL, OPEN_USER_TASKS_TABLE, OpenUserTasksStore, } from "./core/modules/open-user-tasks-store.ts";
+export type { OpenUserTaskRow, OpenUserTasksStoreOptions, } from "./core/modules/open-user-tasks-store.ts";
+export { INSTANCE_STATE_PROJECTION, INSTANCE_STATE_SCHEMA_SQL, INSTANCE_STATE_TABLE, InstanceStateStore, } from "./core/modules/instance-state-store.ts";
+export type { InstanceStateRow, InstanceStateStoreOptions, } from "./core/modules/instance-state-store.ts";
 export { buildScopeIndex, derivePhase, deriveInstancePhases, furthestReached, rollupLineagePhase, SCOPE_CONTAINERS, } from "./core/phase.ts";
 export type { CrumbKind, CrumbSource, DerivePhaseOptions, FurthestReached, InstancePhase, LineagePhaseRollup, Phase, PhaseCrumb, PhaseGranularity, ProvenanceProgressRow, ScopeElement, ScopeIndex, } from "./core/phase.ts";
 export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";

package/dist/runtime/index.js

@@ -53,7 +53,14 @@ export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, Lin
 //   • `projectionRegistry` — register a canonical engine-truth projection NAME usable in `exists(...)`.
 //     The `canonical-projections` task registers `urban_open_user_tasks` / `urban_instance_state`.
 export { and, assertReadModelParity, assertSqlIdentifier, caseWhen, col, compileToFn, compileToSqlSelect, defineReadModel, deriveReadModelViewDdl, eq, exists, gt, gte, lit, lt, lte, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, ReadModelRegistry, readModelRegistry, when, } from "./core/read-model.js";
-// Phase — the framework-level *domain phase* primitive (issue #266): derive "which phase is this
+// Canonical engine-truth projection sidecars (ADR 0065, proposal point #1): two framework-owned,
+// per-source projections the DSL `exists(...)` derives over — `urban_open_user_tasks` (which instances
+// are parked on a human) and `urban_instance_state` (per-instance engine lifecycle state). Provisioned
+// next to the lineage sidecar in core/modules/workers.ts; registered into `projectionRegistry` under
+// their stable DSL names via `registerCanonicalProjections()`.
+export { CANONICAL_PROJECTIONS, registerCanonicalProjections, } from "./core/modules/canonical-projections.js";
+export { OPEN_USER_TASKS_PROJECTION, OPEN_USER_TASKS_SCHEMA_SQL, OPEN_USER_TASKS_TABLE, OpenUserTasksStore, } from "./core/modules/open-user-tasks-store.js";
+export { INSTANCE_STATE_PROJECTION, INSTANCE_STATE_SCHEMA_SQL, INSTANCE_STATE_TABLE, InstanceStateStore, } from "./core/modules/instance-state-store.js";
 // instance in?" from the BPMN scope hierarchy + write-provenance (Tier 0, zero declaration), an
 // optional `nano:phase` override (Tier 1), and a lineage rollup for the epic frontier (Tier 2).
 export { buildScopeIndex, derivePhase, deriveInstancePhases, furthestReached, rollupLineagePhase, SCOPE_CONTAINERS, } from "./core/phase.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.78.0",
+	"version": "0.79.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",