@nanobpm/urban 0.79.0 → 0.81.0

package/dist/runtime/core/modules/instance-tracking.d.ts

@@ -1,5 +1,7 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
-import { type InstanceTracking } from "../manifest.ts";
+import type { UserTaskSummary } from "../host.ts";
+import { InstanceStateStore } from "./instance-state-store.ts";
+import { OpenUserTasksStore } from "./open-user-tasks-store.ts";
 import { type SchedulerDeps } from "./scheduler.ts";
 /** Default poll interval when a binding does not set `pollMs`. */
 export declare const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15000;
@@ -13,24 +15,50 @@ export interface InstanceTrackingHandle extends Mounted {
     /** `table.keyField` labels of the armed bindings, for `inspect()`. */
     readonly bindings: string[];
 }
-/** Apply a binding's `onTerminated.set` patch to the single row keyed by `processInstanceKey`.
- *  Only the binding whose table owns that key has a matching row, so callers can fan this over
- *  every binding and let the no-match ones be no-ops. Returns rows changed. The single place that
- *  writes the terminal patch (and logs the reconcile): both the poll reconciler below (`reconcileOnce`,
- *  once per TERMINATED key it discovers) and the cancel primitive (immediately when it terminates an
- *  instance) route through here, so the two can never drift on the patch or the log. */
-export declare function reconcileTerminatedKey(api: Pick<AppApi, "data" | "log">, bindings: InstanceTracking[], processInstanceKey: string): Promise<number>;
-/** Apply a binding's `onWaitingHuman.set` patch to the single row keyed by `processInstanceKey`
- *  — the wait-on-human twin of {@link reconcileTerminatedKey} (issue #355). The caller establishes
- *  the precondition (the instance is non-terminated and has an open user task); this is the single
- *  place that writes `onWaitingHuman.set` and logs the reconcile. Bindings without an
- *  `onWaitingHuman` edge are no-ops, so callers can fan this over every binding. It skips the write
- *  when the row already carries the patch (quiet-idempotent — a long-parked instance is re-polled
- *  every tick and must not re-log). Returns rows changed. */
-export declare function reconcileWaitingHumanKey(api: Pick<AppApi, "data" | "log">, bindings: InstanceTracking[], processInstanceKey: string): Promise<number>;
 /**
- * Mount the `instanceTracking` reconciler: arm one poll loop per binding. Each loop selects
- * the active rows, asks the engine which of their instances are terminated, and applies the
- * declared patch. `stop()` cancels every armed timer.
+ * The canonical engine-truth projections the reconciler feeds as a SOURCE (ADR 0065, the writer→source
+ * inversion): the instance-state projection (feeds the terminal edge) and the open-user-tasks projection
+ * (feeds the wait-on-human edge). Both are sidecars on the app's own default data source; the derived
+ * status read model `EXISTS`-derives its edges from them.
+ */
+export interface InstanceProjections {
+    readonly instanceState: InstanceStateStore;
+    readonly openUserTasks: OpenUserTasksStore;
+}
+/**
+ * Construct the canonical projection stores over the app's default data source and ensure their schema
+ * (idempotent), exactly the per-source boot path `tryLineageStore` / `tryProvisionCanonicalProjections`
+ * use. Absent-safe: with no default source there is nothing to feed, so return `undefined` at `debug`
+ * (the expected sidecar-absent case). A genuine provisioning fault (missing named source, schema error)
+ * degrades to `undefined` at `warn` rather than breaking the mount — a projection feed must never break
+ * a job.
+ */
+export declare function tryInstanceProjections(api: Pick<AppApi, "data" | "log">): InstanceProjections | undefined;
+/** Record engine-truth that an instance is TERMINATED into the canonical `urban_instance_state`
+ *  projection and retire its open-user-task rows — the writer→source replacement for the old
+ *  `onTerminated.set` `table.update` patch (ADR 0065; #439-L1 / #318). The derived terminal status edge
+ *  (a VIEW / function over the projection) reflects this on the next read, so there is no stored-derived
+ *  column to tear from its inputs (nano-workforce#422). This is the SINGLE place that records the terminal
+ *  source: both the poll reconciler (`reconcileOnce`, once per TERMINATED key it discovers) and the cancel
+ *  primitive (`cancel.ts`, immediately when it terminates an instance) route through it, so the two can
+ *  never drift. Absent-safe (no projections / blank key ⇒ 0) and never throws through — a projection write
+ *  must never break a job or a cancel. Returns 1 when it recorded the terminal source, else 0. */
+export declare function reconcileTerminatedKey(api: Pick<AppApi, "log">, projections: InstanceProjections | undefined, processInstanceKey: string): number;
+/** Feed an instance's CURRENT open-user-task set into the canonical `urban_open_user_tasks` projection
+ *  — the wait-on-human twin of {@link reconcileTerminatedKey} (issue #355). `syncInstance` is
+ *  authoritative-per-instance: it inserts the still-open tasks and RETIRES any previously-projected task
+ *  that is no longer open, so an answered/closed escalation makes the derived wait-on-human edge go false
+ *  on the next read by construction (nano-workforce#422 — no stored column to leave stale). Passing an
+ *  EMPTY `openTasks` clears the instance, which is exactly the answered-escalation transition; callers
+ *  MUST therefore feed every probed non-terminated key, including those with no open task, or a retired
+ *  task would linger and the edge would tear. Absent-safe (no projections / blank key ⇒ 0) and never
+ *  throws through. Returns 1 when it fed the projection, else 0. */
+export declare function reconcileWaitingHumanKey(api: Pick<AppApi, "log">, projections: InstanceProjections | undefined, processInstanceKey: string, openTasks: readonly UserTaskSummary[]): number;
+/**
+ * Mount the `instanceTracking` reconciler: provision each binding's derived read-model VIEW, construct
+ * the canonical projection stores once, and arm one poll loop per binding. Each loop selects the active
+ * rows, asks the engine which of their instances are terminated / parked on a human, and FEEDS that
+ * engine truth into the canonical projections (never a base-row write — the status edges are DERIVED;
+ * ADR 0065). `stop()` cancels every armed timer.
  */
 export declare function mountInstanceTracking(ctx: RuntimeContext, api: AppApi, sched?: SchedulerDeps): InstanceTrackingHandle;