@nanobpm/nano-workforce 0.101.1 → 0.102.1

package/app/mergesPerDay.ts

@@ -0,0 +1,150 @@
+// Merged-per-day throughput / burn-up read model (issue #344).
+//
+// A simple time-series behind the console's "Velocity" page: how many PRs the fleet landed each
+// calendar day (throughput), plus a running `cumulative` burn-up total. Every land is already
+// audited in the `merges` table (004_merge.sql) — one row per merge attempt, whose `outcome`
+// includes `merged`, `queued`, `blocked` and `retry` (see the merge classifier in github.ts; the
+// set is not exhaustive), `at` = ISO timestamp. Only `outcome = 'merged'` rows feed this aggregate,
+// so merged-per-day is
+// fully DERIVABLE from that audit trail with NO new write-path bookkeeping (AGENTS.md: "Derivation
+// over duplication"). The canonical aggregate is the one in the issue:
+//
+//   SELECT date(at) AS day, COUNT(DISTINCT pr_key) AS merged
+//   FROM merges WHERE outcome = 'merged' GROUP BY date(at);
+//
+// Two halves, mirroring the `deriveDelivery`/`pollDelivery` and `deriveLineage`/`pollLineage`
+// convention:
+//   • `deriveMergesPerDay` — a PURE function: merge audit rows → one ordered `MergeDay` per calendar
+//     day (merged count, burn-up cumulative, a proportional bar string). No I/O, fully tested. Counts
+//     `COUNT(DISTINCT pr_key)` — a PR with several `merged` rows on one day (an `already-merged`
+//     short-circuit or retry) counts once — and ignores `queued`/`blocked` rows entirely.
+//   • `pollMergesPerDay` — the gateway glue: read the `merges` rows and project them onto the
+//     `merges_per_day` read table (051_merges_per_day.sql) the schema-driven Velocity page binds. A
+//     denormalised flat table because Urban's datasource cannot read a SQL VIEW (gateway.ts
+//     `schema()` whitelists `type='table'` only — same reason `lineage_threads`/`plans.delivery` are
+//     flat tables). Writes only when a day's projection actually changes, so a steady-state pass is a
+//     no-op.
+import type { DataLayer } from "@nanobpm/urban";
+
+const now = () => new Date().toISOString();
+
+/** The subset of a `merges` audit row (004_merge.sql) the projection reads. */
+export interface MergeAuditRow {
+  pr_key: string;
+  outcome: string;
+  at: string;
+}
+
+/** One projected calendar day of merge throughput. */
+export interface MergeDay {
+  /** Calendar day, ISO `YYYY-MM-DD` (SQLite `date(at)`). */
+  day: string;
+  /** Distinct PRs merged that day (`COUNT(DISTINCT pr_key)`). */
+  merged: number;
+  /** Running total of merged PRs up to and including this day — the burn-up line. */
+  cumulative: number;
+  /** Proportional block-character bar (length scaled to the busiest day), for the prose chart. */
+  bar: string;
+}
+
+/** Widest bar (in block glyphs) the busiest day draws; every other day scales against it. */
+const BAR_WIDTH = 30;
+const BAR_FULL = "█";
+
+/** The calendar day of an ISO timestamp — the JS twin of SQLite `date(at)`. A well-formed `merges.at`
+ *  is an ISO string, so the first 10 chars are `YYYY-MM-DD`; fall back to the whole trimmed value for
+ *  any non-ISO shape so a malformed row still groups deterministically rather than throwing. */
+function dayOf(at: string): string {
+  const s = String(at).trim();
+  return /^\d{4}-\d{2}-\d{2}/.test(s) ? s.slice(0, 10) : s;
+}
+
+/** Render a proportional bar: `merged` glyphs scaled against the busiest day's `max`, min one glyph
+ *  for any non-zero day so a lone merge is still visible. Zero renders as an empty bar. */
+function barFor(merged: number, max: number): string {
+  if (merged <= 0 || max <= 0) return "";
+  const n = Math.max(1, Math.round((merged / max) * BAR_WIDTH));
+  return BAR_FULL.repeat(n);
+}
+
+/** PURE aggregate: merge audit rows → one ordered `MergeDay` per calendar day (ascending).
+ *
+ * Only `outcome === "merged"` rows count; `queued`/`blocked` attempts are ignored. Within a day a
+ * `pr_key` is counted once (`COUNT(DISTINCT pr_key)`), so duplicate `merged` audit rows — an
+ * `already-merged` short-circuit or a retry — do not double-count. `cumulative` is the running total
+ * across days (burn-up); `bar` is scaled against the busiest day so the chart is comparable. */
+export function deriveMergesPerDay(rows: readonly MergeAuditRow[]): MergeDay[] {
+  // day -> set of distinct merged pr_keys that day.
+  const prKeysByDay = new Map<string, Set<string>>();
+  for (const r of rows) {
+    if (r.outcome !== "merged") continue;
+    if (r.pr_key == null || r.at == null) continue;
+    const day = dayOf(r.at);
+    let set = prKeysByDay.get(day);
+    if (!set) {
+      set = new Set<string>();
+      prKeysByDay.set(day, set);
+    }
+    set.add(r.pr_key);
+  }
+
+  const counts = [...prKeysByDay.entries()]
+    .map(([day, set]) => ({ day, merged: set.size }))
+    .sort((a, b) => a.day.localeCompare(b.day));
+  const max = counts.reduce((m, c) => Math.max(m, c.merged), 0);
+
+  let cumulative = 0;
+  const out: MergeDay[] = [];
+  for (const { day, merged } of counts) {
+    cumulative += merged;
+    out.push({ day, merged, cumulative, bar: barFor(merged, max) });
+  }
+  return out;
+}
+
+/** The denormalised read-table row `pollMergesPerDay` projects, one per calendar day. */
+interface MergesPerDayRow extends MergeDay {
+  updated_at: string;
+}
+
+const mergesPerDay = (data: DataLayer) => data.table<MergesPerDayRow>("merges_per_day", "day");
+const mergesAudit = (data: DataLayer) => data.table<MergeAuditRow>("merges", "id");
+
+/** Idempotent read-model pass: recompute merged-per-day from the `merges` audit table and denormalise
+ * it onto the `merges_per_day` read table the Velocity page reads. Additive/derived only — never
+ * touches `merges`. Upserts a day only when its projection actually changes (so a steady-state pass is
+ * a no-op) and prunes any stale day row that no longer derives (defensive — days are append-only in
+ * practice, but a purge/rewrite of the audit must not leave a phantom). */
+export async function pollMergesPerDay(data: DataLayer): Promise<void> {
+  try {
+    // Only `outcome === "merged"` rows contribute to the aggregate, so filter at the read rather than
+    // scanning queued/blocked rows as the audit grows (deriveMergesPerDay ignores non-merged rows too).
+    const audit = await mergesAudit(data).find({ outcome: "merged" });
+    const want = deriveMergesPerDay(audit);
+    const wantByDay = new Map(want.map((d) => [d.day, d]));
+
+    const existing = await mergesPerDay(data).all();
+    const existingByDay = new Map(existing.map((r) => [r.day, r]));
+
+    for (const d of want) {
+      const cur = existingByDay.get(d.day);
+      if (!cur) {
+        await mergesPerDay(data).insert({ ...d, updated_at: now() });
+      } else if (cur.merged !== d.merged || cur.cumulative !== d.cumulative || cur.bar !== d.bar) {
+        await mergesPerDay(data).update(d.day, {
+          merged: d.merged,
+          cumulative: d.cumulative,
+          bar: d.bar,
+          updated_at: now(),
+        });
+      }
+    }
+
+    // Prune any projected day that no longer derives from the audit trail.
+    for (const r of existing) {
+      if (!wantByDay.has(r.day)) await mergesPerDay(data).delete(r.day);
+    }
+  } catch (err) {
+    console.error(`[poller] merges-per-day: ${err}`);
+  }
+}

package/app/reviewReadinessGate.test.ts

@@ -76,7 +76,10 @@ test("the migrated wait stays bounded: an event-based gateway races the signal a
 });
 
 test("the timeout arm escalates to a human (the wait cannot hang forever)", () => {
-  // timer catch → persist-review-stalled (records the escalation) → wait-answer (native userTask).
+  // timer catch → persist-review-stalled (records the escalation) → gw-escalated → wait-answer.
+  // Since #340 every escalation arm converges on the shared `gw-escalated` gateway (no per-arm twin
+  // edge to the userTask — derivation over duplication), which routes to the native `wait-answer`
+  // userTask when an escalation actually opened (`escalated = true`). Assert that canonical path.
   assert(
     /sourceRef="wait-review-timeout"[^>]*targetRef="persist-review-stalled"|targetRef="persist-review-stalled"[^>]*sourceRef="wait-review-timeout"/.test(
       flat,
@@ -84,9 +87,18 @@ test("the timeout arm escalates to a human (the wait cannot hang forever)", () =
     "a timed-out review wait routes to the stalled-review escalation",
   );
   assert(
-    /sourceRef="persist-review-stalled"[^>]*targetRef="wait-answer"|targetRef="wait-answer"[^>]*sourceRef="persist-review-stalled"/.test(
+    /sourceRef="persist-review-stalled"[^>]*targetRef="gw-escalated"|targetRef="gw-escalated"[^>]*sourceRef="persist-review-stalled"/.test(
       flat,
     ),
-    "the stalled-review escalation parks on the human answer userTask",
+    "the stalled-review escalation converges on the shared gw-escalated gateway",
+  );
+  const escWait = flat.match(
+    /<bpmn:sequenceFlow\b[^>]*\bsourceRef="gw-escalated"[^>]*\btargetRef="wait-answer"[^>]*>[\s\S]*?<\/bpmn:sequenceFlow>/,
+  );
+  assert(escWait, "gw-escalated must route to the human answer userTask (wait-answer)");
+  assertStringIncludes(
+    escWait![0],
+    "escalated = true",
+    "gw-escalated parks on wait-answer only when an escalation actually opened",
   );
 });

package/app/service.ts

@@ -43,6 +43,7 @@ import {
 import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
+import { pollMergesPerDay } from "./mergesPerDay.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
 import {
   backfillPlanBuckets,
@@ -2116,6 +2117,7 @@ export async function pollOnce(
   await pollPromotion(data, engine, token);
   await pollFeatureDelivery(data);
   await pollLineage(data);
+  await pollMergesPerDay(data);
   await pollUserTasks(data, engine);
   if (engineRest) {
     const base = engineRest.restAddress.replace(/\/+$/, "");

package/db/migrations/051_merges_per_day.sql

@@ -0,0 +1,33 @@
+-- Merged-per-day throughput / burn-up read model (issue #344).
+--
+-- Every land is already audited in `merges` (004_merge.sql): one row per merge attempt, whose
+-- `outcome` includes `merged`, `queued`, `blocked` and `retry` (the set is not exhaustive) and
+-- `at` = ISO timestamp. Only `outcome = 'merged'` rows count. The per-calendar-day merged count is
+-- therefore fully DERIVABLE from that audit trail — no new write-path bookkeeping (AGENTS.md:
+-- "Derivation over duplication"). The canonical aggregate is:
+--
+--   SELECT date(at) AS day, COUNT(DISTINCT pr_key) AS merged
+--   FROM merges WHERE outcome = 'merged' GROUP BY date(at);
+--
+-- `COUNT(DISTINCT pr_key)` (not `COUNT(*)`) so a PR that produced several audit rows on one day —
+-- e.g. an `already-merged` short-circuit or a retry — counts once per day.
+--
+-- The natural home for that aggregate would be a SQL VIEW, but Urban's page datasource cannot read
+-- one: `gateway.ts schema()` whitelists `sqlite_master.type = 'table'` only, so a page binding to a
+-- VIEW 400s at request time (see the `lineage_threads` / `plans.delivery` precedent, 037_lineage.sql).
+-- So — following the codebase convention for read-model projections — this is a DENORMALISED flat
+-- table the schema-driven Velocity page reads directly, recomputed idempotently each poll pass by
+-- `pollMergesPerDay` (app/mergesPerDay.ts) from the `merges` audit rows. `cumulative` is the burn-up
+-- running total; `bar` is a precomputed proportional block-character bar so the declarative `prose`
+-- renderer can draw a horizontal bar per day with no chart node type.
+--
+-- Forward-only, additive (expand): a new derived read table. The runner wraps each file in its own
+-- transaction, so this file must NOT contain BEGIN/COMMIT. Numbered after the current highest prefix
+-- (050). `day` is the PRIMARY KEY, which SQLite already indexes, so no extra index is needed.
+CREATE TABLE IF NOT EXISTS merges_per_day (
+  day        TEXT PRIMARY KEY,             -- calendar day (date(at), ISO YYYY-MM-DD)
+  merged     INTEGER NOT NULL DEFAULT 0,   -- COUNT(DISTINCT pr_key) merged that day
+  cumulative INTEGER NOT NULL DEFAULT 0,   -- running total of merged PRs up to and including `day` (burn-up)
+  bar        TEXT NOT NULL DEFAULT '',     -- proportional block-character bar for the prose chart
+  updated_at TEXT NOT NULL
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.101.1",
+  "version": "0.102.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/_nav.json

@@ -23,7 +23,8 @@
         }
       },
       { "label": "Cockpit", "page": "cockpit" },
-      { "label": "Board", "page": "board" }
+      { "label": "Board", "page": "board" },
+      { "label": "Velocity", "page": "velocity" }
     ],
     "sticky": true
   }

package/pages/board.page.json

@@ -48,6 +48,10 @@
           {
             "label": "Board",
             "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
           }
         ],
         "sticky": true

package/pages/cockpit.page.json

@@ -48,6 +48,10 @@
           {
             "label": "Board",
             "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
           }
         ],
         "sticky": true

package/pages/epic-detail.page.json

@@ -48,6 +48,10 @@
           {
             "label": "Board",
             "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
           }
         ],
         "sticky": true

package/pages/epic.page.json

@@ -48,6 +48,10 @@
           {
             "label": "Board",
             "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
           }
         ],
         "sticky": true

package/pages/feature.page.json

@@ -48,6 +48,10 @@
           {
             "label": "Board",
             "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
           }
         ],
         "sticky": true

package/pages/home.page.json

@@ -48,6 +48,10 @@
           {
             "label": "Board",
             "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
           }
         ],
         "sticky": true

package/pages/lineage.page.json

@@ -48,6 +48,10 @@
           {
             "label": "Board",
             "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
           }
         ],
         "sticky": true

package/pages/overview.page.json

@@ -48,6 +48,10 @@
           {
             "label": "Board",
             "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
           }
         ],
         "sticky": true

package/pages/tasks.page.json

@@ -48,6 +48,10 @@
           {
             "label": "Board",
             "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
           }
         ],
         "sticky": true

package/pages/velocity.page.json

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": "1.0",
+  "title": "Velocity",
+  "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "title": "Nano Workforce",
+        "items": [
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          },
+          {
+            "label": "Velocity",
+            "page": "velocity"
+          }
+        ],
+        "sticky": true
+      }
+    },
+    {
+      "type": "text",
+      "id": "title",
+      "props": { "text": "Velocity", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "props": {
+        "text": "Merged-per-day throughput \u2014 how many PRs the fleet landed each calendar day, derived directly from the merge audit trail. Each row is one day: the bar is scaled against the busiest day, the header shows that day's merged count and the running burn-up total.",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "prose",
+      "id": "merges-per-day",
+      "props": {
+        "title": "PRs merged per day",
+        "refreshMs": 5000,
+        "measure": 60,
+        "empty": "No merges recorded yet.",
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "merges_per_day",
+          "orderBy": { "field": "day", "dir": "asc" }
+        },
+        "header": "{{day}} \u00b7 {{merged}} merged \u00b7 \u03a3 {{cumulative}}",
+        "body": "bar"
+      }
+    }
+  ]
+}