create-pmos 0.52.0 → 0.53.1

package/workspace/lib/measurements.js

@@ -0,0 +1,189 @@
+'use strict';
+/* measurements.js — THE ONE WRITER and THE ONE FOLD of measurements.jsonl: a measured value of a KR or a health
+ * budget, with its target, its date and its source (pm-os-absorb, PRD R17, R23, R24; D86).
+ *
+ *   readMeasurements(root) → {
+ *     ok: true,
+ *     byAnchor: { [anchor]: [{ value, target, unit, as_of, source, by, at }] },   oldest first; `source` is "path@sha"
+ *     flags: [{ kind, eid, why }],
+ *   }
+ *   latest(result, anchor)                       → the newest measurement of `anchor` by as_of, or null
+ *   appendFromUi(root, events, { actor, now })   → { ok, written, lines } | { ok: false, status, error, index }
+ *   appendFromCli(root, events, { actor, now })  → the same
+ *   checkEvent(ev) → null | error text            the caller-side checks, shared with `pmos measure`
+ *
+ * `anchor` is the initiative's parent_kr as written (a KR id, or `health:<id>`, D59). A measurement needs a source; an
+ * agent may write one (it is evidence, not a PM act), so the actor comes from actor.js, never from the caller.
+ * The workspace never computes a value (PRD Non-goals): a group shows a value only from a line here.
+ *
+ * THE `measured` LINE (the shared contract):
+ *   { v: 1, eid, ev: 'measured', anchor, value: <number>, target: <number> | null, unit?: '%'|…, as_of: 'YYYY-MM-DD',
+ *     source: '<path>@<sha>', by, via, at }
+ *   pmOnly(rec) → false: a measurement is evidence, not a PM act.
+ *
+ * `source` is a repository-relative path, `@`, and a commit sha of 7 to 40 hex characters: the file the number was
+ * read from, at the commit it was read at. The writer does not open it (no read outside the call's own checks), so a
+ * wrong path is the writer's caller's error; scripts/check-measurements.js reports a path that is not in the tree.
+ *
+ * The fold is order-free, like lib/plan-items.js: byte-identical duplicates count once, one eid with two contents keeps
+ * the first. The ledger is one per repository: lib/plan-ledgers.js ledgerPath(root, 'measurements'). Nothing is cached.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const ledgers = require('./plan-ledgers.js');
+const actorLib = require('./actor.js');
+const { createSinkGuard } = require('./sink.js');
+
+const MAX_LINES = 50;
+const EID_RE = /^[0-9a-z]{12}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+/** A KR id as the OKR files write it, or a health budget or a domain (D59, D67). One line, no control characters. */
+const ANCHOR_RE = /^(?:health:[a-z0-9][a-z0-9-]{0,59}|domain:[a-z0-9][a-z0-9-]{0,59}|[A-Za-z0-9][A-Za-z0-9 .:_-]{0,79})$/;
+const SOURCE_RE = /^([A-Za-z0-9_][A-Za-z0-9_./-]{0,239})@([0-9a-f]{7,40})$/;
+const UNIT_RE = /^[^\s\x00-\x1f]{1,12}$/;
+const WRITER_SET = Object.freeze(['v', 'eid', 'by', 'via', 'at', 'override', 'pm', 'actor', 'nonce']);
+const CALLER_KEYS = Object.freeze(['anchor', 'value', 'target', 'unit', 'as_of', 'source']);
+const STORED_KEYS = Object.freeze(['v', 'eid', 'ev', 'by', 'via', 'at', ...CALLER_KEYS]);
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+
+const isStr = (v) => typeof v === 'string';
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+const dateOk = (v) => isStr(v) && DATE_RE.test(v) && !Number.isNaN(Date.parse(v + 'T00:00:00Z'))
+  && new Date(v + 'T00:00:00Z').toISOString().slice(0, 10) === v;
+
+function newEventId() {
+  let out = '';
+  while (out.length < 12) {
+    for (const b of crypto.randomBytes(24)) {
+      if (b >= 252) continue;
+      out += ALPHABET[b % 36];
+      if (out.length === 12) break;
+    }
+  }
+  return out;
+}
+
+/** The source as { path, sha }, or null when it is not "<repository-relative path>@<sha>". */
+function parseSource(s) {
+  const m = isStr(s) ? SOURCE_RE.exec(s) : null;
+  if (!m) return null;
+  if (m[1].split('/').some((seg) => seg === '..' || seg === '.' || seg === '')) return null;
+  return { path: m[1], sha: m[2] };
+}
+
+/** The checks on what a caller sends (the writer runs them; `pmos measure` runs them before it writes). */
+function checkEvent(ev) {
+  if (!ev || typeof ev !== 'object' || Array.isArray(ev)) return 'each line must be a JSON object';
+  const sent = WRITER_SET.find((k) => has(ev, k));
+  if (sent) return `the writer sets "${sent}"; do not send it`;
+  if (ev.ev !== 'measured') return 'ev must be measured';
+  const extra = Object.keys(ev).filter((k) => k !== 'ev' && !CALLER_KEYS.includes(k));
+  if (extra.length) return `a measured line has no field ${extra.join(', ')}`;
+  if (!isStr(ev.anchor) || !ANCHOR_RE.test(ev.anchor.trim()) || ev.anchor !== ev.anchor.trim()) return 'anchor must be a KR id, health:<id> or domain:<id>';
+  if (typeof ev.value !== 'number' || !Number.isFinite(ev.value)) return 'value must be a number';
+  if (has(ev, 'target') && ev.target !== null && (typeof ev.target !== 'number' || !Number.isFinite(ev.target))) return 'target must be a number, or null';
+  if (has(ev, 'unit') && !(isStr(ev.unit) && UNIT_RE.test(ev.unit))) return 'unit must be a short word with no spaces, like %';
+  if (!dateOk(ev.as_of)) return 'as_of must be YYYY-MM-DD';
+  if (!has(ev, 'source') || ev.source === '' || ev.source == null) return 'a measurement needs a source: <path>@<commit sha>';
+  if (!parseSource(ev.source)) return 'source must be <repository-relative path>@<commit sha of 7 to 40 hex characters>';
+  return null;
+}
+
+/** Why a stored line is not a valid line of this ledger, or null. */
+function lineErr(r) {
+  if (r.v !== 1) return 'v must be 1';
+  if (!isStr(r.eid) || !EID_RE.test(r.eid)) return 'eid must be 12 characters of [0-9a-z]';
+  if (!isStr(r.by) || !actorLib.BY_RE.test(r.by)) return 'by must be pm:<slug>, agent:unknown or agent:<session>';
+  if (!actorLib.VIA.includes(r.via)) return 'via must be ui or cli';
+  if (!isStr(r.at) || !AT_RE.test(r.at)) return 'at must be an ISO UTC time';
+  const extra = Object.keys(r).filter((k) => !STORED_KEYS.includes(k));
+  if (extra.length) return `a measured line has no field ${extra.join(', ')}`;
+  const body = {};
+  for (const k of ['ev', ...CALLER_KEYS]) if (has(r, k)) body[k] = r[k];
+  return checkEvent(body);
+}
+
+function readMeasurements(root) {
+  const out = { ok: true, byAnchor: {}, flags: [] };
+  const { lines, bad } = ledgers.readLines(root, 'measurements');
+  for (const b of bad) out.flags.push({ kind: 'unreadable', eid: null, why: `line ${b.n}: ${b.why}` });
+  const kept = [];
+  for (const { n, rec } of lines) {
+    if (rec.ev !== 'measured') { out.flags.push({ kind: 'invalid', eid: isStr(rec.eid) ? rec.eid : null, why: `line ${n}: ev must be measured` }); continue; }
+    const why = lineErr(rec);
+    if (why) { out.flags.push({ kind: 'invalid', eid: isStr(rec.eid) ? rec.eid : null, why: `line ${n}: ${why}` }); continue; }
+    kept.push({ n, rec });
+  }
+  kept.sort((a, b) => (Date.parse(a.rec.at) - Date.parse(b.rec.at)) || (a.rec.eid < b.rec.eid ? -1 : a.rec.eid > b.rec.eid ? 1 : 0) || (a.n - b.n));
+  const seen = new Map();
+  for (const { n, rec } of kept) {
+    const text = JSON.stringify(rec);
+    if (seen.has(rec.eid)) {
+      if (seen.get(rec.eid) !== text) out.flags.push({ kind: 'duplicate-event', eid: rec.eid, why: `line ${n}: the eid ${rec.eid} is used by two different lines; the first one counts` });
+      continue;
+    }
+    seen.set(rec.eid, text);
+    (out.byAnchor[rec.anchor] = out.byAnchor[rec.anchor] || []).push({
+      value: rec.value, target: Number.isFinite(rec.target) ? rec.target : null, unit: rec.unit || null,
+      as_of: rec.as_of, source: rec.source, by: rec.by, at: rec.at,
+    });
+  }
+  for (const rows of Object.values(out.byAnchor)) rows.sort((a, b) => String(a.as_of).localeCompare(String(b.as_of)) || String(a.at).localeCompare(String(b.at)));
+  return out;
+}
+
+const pmOnly = () => false;
+
+function latest(result, anchor) {
+  const rows = result && result.byAnchor && Object.prototype.hasOwnProperty.call(result.byAnchor, anchor) ? result.byAnchor[anchor] : null;
+  if (!Array.isArray(rows) || !rows.length) return null;
+  return rows.reduce((a, b) => (String(b.as_of) >= String(a.as_of) ? b : a));
+}
+
+const refuse = (status, error, index) => ({ ok: false, status, error, index: index == null ? null : index });
+
+function append(root, events, actor, { now } = {}) {
+  if (!actorLib.valid(actor)) return refuse(500, 'measurements: the caller must pass the actor from pm-guard.js or actor.js', null);
+  if (!Array.isArray(events) || !events.length) return refuse(400, 'send at least one line', null);
+  if (events.length > MAX_LINES) return refuse(413, `send at most ${MAX_LINES} lines at once`, null);
+  for (let i = 0; i < events.length; i++) {
+    const why = checkEvent(events[i]);
+    if (why) return refuse(400, why, i);
+  }
+  const read = ledgers.readLines(root, 'measurements');
+  if (read.bad.some((b) => b.n === 0)) return refuse(500, 'could not read the measurements ledger — nothing was saved: ' + read.bad[0].why.slice(0, 160), null);
+  const clock = now == null ? Date.now() : now;
+  let last = 0;
+  for (const l of read.lines) {
+    const t = isStr(l.rec.at) ? Date.parse(l.rec.at) : NaN;
+    if (Number.isFinite(t) && t <= clock + 1000 && t > last) last = t;
+  }
+  const recs = events.map((ev) => {
+    last = Math.max(clock, last + 1);
+    const rec = { v: 1, eid: newEventId(), ev: 'measured', anchor: ev.anchor, value: ev.value, target: has(ev, 'target') ? ev.target : null };
+    if (has(ev, 'unit')) rec.unit = ev.unit;
+    Object.assign(rec, { as_of: ev.as_of, source: ev.source, by: actor.by, via: actor.via, at: new Date(last).toISOString() });
+    return rec;
+  });
+  let file;
+  try { file = ledgers.ledgerPath(root, 'measurements'); fs.mkdirSync(path.dirname(file), { recursive: true }); }
+  catch { return refuse(500, 'could not record — nothing was saved', null); }
+  const guard = createSinkGuard({ sink: file, what: 'measurements' });
+  let wrote = 0;
+  for (const rec of recs) {
+    try { guard.appendLine(file, rec); wrote++; }
+    catch {
+      return refuse(500, wrote ? `could not record — ${wrote} of ${recs.length} lines were saved before the write failed` : 'could not record — nothing was saved', wrote);
+    }
+  }
+  return { ok: true, written: recs.length, lines: recs.map((r) => ({ eid: r.eid, anchor: r.anchor })) };
+}
+
+/** A page press (requirePagePress's actor). */
+function appendFromUi(root, events, { actor, now } = {}) { return append(root, events, actor, { now }); }
+/** `pmos measure` (actor.fromCli's actor; an agent may write a measurement). */
+function appendFromCli(root, events, { actor, now } = {}) { return append(root, events, actor, { now }); }
+
+module.exports = { MAX_LINES, readMeasurements, latest, pmOnly, checkEvent, parseSource, lineErr, appendFromUi, appendFromCli };

package/workspace/lib/mobile-nav.js

@@ -17,13 +17,14 @@
  *
  * The screen model:
  *   { dest, kind, mode, id, dk, title, column }
- *     dest    one of DESTS — which destination this screen belongs to
- *     kind    'list' | 'detail' | 'terminal' | 'doc' | 'more'
+ *     dest    one of DESTS — which tab this screen belongs to
+ *     kind    'dest' | 'agent' (the frame) · 'list' | 'more' (the old shell) · 'detail' | 'terminal' | 'doc'
  *     mode    a MODES key, for kind 'list'
- *     id      the detail id / session id / viewer id
+ *     id      the frame destination (kind 'dest') / detail id / session id / viewer id
  *     dk      the DETAIL kind, for kind 'detail'
  *     title   only for 'terminal' and 'doc', where the name is not derivable
- *     column  'side' | 'term' | 'rail' — determined by `kind` and by nothing else
+ *     column  'side' | 'term' | 'rail' — determined by `kind` and by nothing else (panelOf is the same for the four
+ *             panel grid)
  *
  * `column` is the whole of the exclusivity guarantee: the stylesheet shows exactly one of the three
  * column nodes per value, so P1 is a property of the CSS rather than something this reducer has to
@@ -65,87 +66,90 @@ const DETAIL_TITLE = {
   addprod: 'add repository', new: 'file new',
 };
 
-const MOBILE_DESTS = ['board', 'scheduled', 'agents', 'memory', 'more'];
-// Every MODES key has an entry. The suite ITERATES `MODES` against this map rather than a literal
-// list, so adding a mode without giving it a phone path fails the suite instead of going silently
-// unreachable — which is the failure P2 exists to catch.
-const MOBILE_DEST = { product: 'board', scheduled: 'scheduled', agent: 'agents', memory: 'memory',
-  workflow: 'more', skills: 'more', knowledge: 'more' };
+/* ── the frame's five phone tabs (pm-os-absorb Run 3, slice 3A; PRD R15) ─────────────────────────────────────────
+ * Today · Initiatives · Board · Reports · Agent. The first four are the frame's destinations (a `dest` screen, drawn
+ * in the frame's place, panel index 0); Agent is the dock (an `agent` screen, panel 4, the live terminals). Settings
+ * is not a tab: it is pushed on top of the current tab as a `dest` screen with id `settings`, so Back returns.
+ * The old cockpit's list modes still map to a tab (MOBILE_DEST), for the old shell (fixture mode, ?layout=legacy). */
+const MOBILE_DESTS = ['today', 'initiatives', 'board', 'reports', 'agent'];
+// What each tab and Settings is called. The same words as the desktop bar (public/pm/frame-copy.js COPY.nav), which
+// MOBNAV-P7 holds equal.
+const DEST_TITLE = { today: 'Today', initiatives: 'Initiatives', board: 'Board', reports: 'Reports', agent: 'Agent', settings: 'Settings' };
+// Every old MODES key has a tab. The suite ITERATES this map, so a mode without a phone path fails.
+const MOBILE_DEST = { product: 'initiatives', scheduled: 'reports', agent: 'agent', memory: 'initiatives',
+  workflow: 'initiatives', skills: 'initiatives', knowledge: 'initiatives' };
 const MOBILE_ROOT = {
-  board: { kind: 'list', mode: 'product' },
-  scheduled: { kind: 'list', mode: 'scheduled' },
-  agents: { kind: 'list', mode: 'agent' },
-  memory: { kind: 'list', mode: 'memory' },
-  more: { kind: 'more', mode: null },
+  today: { kind: 'dest', id: 'today' },
+  initiatives: { kind: 'dest', id: 'initiatives' },
+  board: { kind: 'dest', id: 'board' },
+  reports: { kind: 'dest', id: 'reports' },
+  agent: { kind: 'agent', id: null },
 };
+// The tab every stored value of the retired five-tab nav (board · scheduled · agents · memory · more) and of the
+// three-way switcher before it lands on. Read once from the old key; a new value is never passed through it.
+const LEGACY_DEST = { board: 'initiatives', scheduled: 'reports', agents: 'agent', memory: 'today', more: 'today',
+  sessions: 'agent', terminal: 'agent', library: 'today' };
 // kind → column. There is no second input, and no screen may carry a column its kind does not give.
-const MOBILE_COLUMN = { list: 'side', more: 'side', detail: 'rail', terminal: 'term', doc: 'term' };
+const MOBILE_COLUMN = { list: 'side', more: 'side', dest: 'side', detail: 'rail', terminal: 'term', doc: 'term', agent: 'term' };
 function mobColumnOf(kind) { return MOBILE_COLUMN[kind] || 'side'; }
 
-/* kind → PANEL INDEX, for the four-panel surface (public/pm/).
- *
- * WHY THIS EXISTS ALONGSIDE `column`, RATHER THAN REPLACING IT. `column` names one of the three
- * columns of the retired `public/app.js` layout, and MOBNAV-P1 pins it to exactly those three
- * values. The surface that ships now has FOUR panels — repositories · mode list · detail · tabs —
- * and two of the old `side` screens belong to DIFFERENT panels there: a `list` screen is panel 2
- * (the mode list) while a `more` screen is panel 1, which is the structure/settings panel and is
- * therefore the phone's "more" destination in the four-panel design.
- *
- * So this is an ADDITIVE widening, not an edit: `columnOf` is untouched and still describes the
- * three-column layout truthfully for the surface that owns it, and `panelOf` describes the
- * four-panel one. Both are pure functions of `kind` alone, so the exclusivity guarantee — one
- * visible surface per screen — is the same property stated against a different layout. Putting it
- * HERE rather than in pm/mobile.js keeps a single node-walkable source of truth for "which surface
- * does this screen show", which is the whole reason the reducer was pulled out of app.js.
- */
-const MOBILE_PANEL = { more: 0, list: 1, detail: 2, terminal: 3, doc: 3 };
+/* kind → PANEL INDEX: which child of the body grid a phone shows (pm/mobile.css `data-mpanel`). In the frame the body
+ * grid holds the place, the dock's rail (never shown on a phone), the detail and the dock, in that order; in the old
+ * shell it holds its four panels. `dest` is the frame's place, `agent` the dock. A pure function of `kind` alone, so
+ * one visible surface per screen is a property of the CSS. */
+const MOBILE_PANEL = { dest: 0, more: 0, list: 1, detail: 2, terminal: 3, doc: 3, agent: 3 };
 function mobPanelOf(kind) {
-  return Object.prototype.hasOwnProperty.call(MOBILE_PANEL, kind) ? MOBILE_PANEL[kind] : 1;
+  return Object.prototype.hasOwnProperty.call(MOBILE_PANEL, kind) ? MOBILE_PANEL[kind] : 0;
 }
 function mobDestForMode(k) { return MOBILE_DEST[k] || null; }
 // Complete a partial screen. The column is derived, never passed in, so a caller cannot put a
 // detail on the terminal column by writing it down.
 function mobScreen(s) {
-  const kind = (s && s.kind) || 'list';
-  return { dest: (s && s.dest) || 'board', kind, mode: (s && s.mode) || null,
+  const kind = (s && s.kind) || 'dest';
+  return { dest: (s && s.dest) || 'today', kind, mode: (s && s.mode) || null,
     id: (s && s.id) || null, dk: (s && s.dk) || null, title: (s && s.title) || null,
     column: mobColumnOf(kind) };
 }
 function mobRootOf(dest) {
-  const r = MOBILE_ROOT[dest] || MOBILE_ROOT.board;
-  return mobScreen({ dest: MOBILE_ROOT[dest] ? dest : 'board', kind: r.kind, mode: r.mode });
+  const d = MOBILE_ROOT[dest] ? dest : 'today';
+  const r = MOBILE_ROOT[d];
+  return mobScreen({ dest: d, kind: r.kind, id: r.id });
 }
-/* The title map. `list` and `more` derive; `detail` reads DETAIL_TITLE (declared far below — this
- * is only ever called at runtime, long after that const has evaluated); `terminal` and `doc` carry
- * a title because a session's name and a document's name are not derivable from a screen. */
+/* The title map. `dest` and `agent` read DEST_TITLE; `list` and `more` derive (the old shell); `detail` reads
+ * DETAIL_TITLE; `terminal` and `doc` carry a title because a session's name and a document's name are not derivable. */
 function mobTitleOf(s) {
   if (!s) return '';
+  if (s.kind === 'dest') return DEST_TITLE[s.id] || DEST_TITLE[s.dest] || '';
+  if (s.kind === 'agent') return DEST_TITLE.agent;
   if (s.kind === 'list') return MODE_TITLE[s.mode] || String(s.mode || '');
   if (s.kind === 'more') return 'more';
   if (s.kind === 'detail') return DETAIL_TITLE[s.dk] || 'detail';
   return s.title || String(s.id || '');
 }
-function mobNavInit(dest) { return { dest: MOBILE_ROOT[dest] ? dest : 'board', stack: [] }; }
+function mobNavInit(dest) { return { dest: MOBILE_ROOT[dest] ? dest : 'today', stack: [] }; }
 function mobPush(nav, screen) {
-  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('board');
+  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('today');
   return { dest: n.dest, stack: n.stack.concat([mobScreen(Object.assign({ dest: n.dest }, screen))]) };
 }
-// Removes EXACTLY one. Back from a destination root is a no-op — it never exits the app and never
-// unwinds into another destination, which is the second half of P3.
+// Removes EXACTLY one. Back from a tab's root is a no-op — it never exits the app and never
+// unwinds into another tab.
 function mobPop(nav) {
-  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('board');
+  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('today');
   return n.stack.length ? { dest: n.dest, stack: n.stack.slice(0, -1) } : { dest: n.dest, stack: [] };
 }
-// Choosing a destination RESETS it to its root with an empty stack — the prototype's {tab, stack:[]}.
+// Choosing a tab RESETS it to its root with an empty stack.
 function mobSwitchDest(nav, dest) { return mobNavInit(dest); }
 function mobCurrentOf(nav) {
-  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('board');
+  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('today');
   return n.stack.length ? n.stack[n.stack.length - 1] : mobRootOf(n.dest);
 }
-/* R11 — the legacy key is read ONCE, for migration, and never written again. Every value the old
- * three-way switcher could hold, plus anything unrecognised and nothing at all, lands on `board`:
- * the destination root is the only screen that is safe to draw without re-reading anything. */
-function mobMigrateView(v) { return MOBILE_ROOT[v] ? v : 'board'; }
+/* R11 — a value stored by an older nav is read ONCE, for migration. Every value the retired navs could hold, plus
+ * anything unrecognised and nothing at all, lands on a tab's root: the only screen that is safe to draw without
+ * re-reading anything. */
+function mobMigrateView(v) {
+  if (typeof v === 'string' && Object.prototype.hasOwnProperty.call(LEGACY_DEST, v)) return LEGACY_DEST[v];
+  return MOBILE_ROOT[v] ? v : 'today';
+}
 
   return { push: mobPush, pop: mobPop, switchDest: mobSwitchDest, init: mobNavInit,
     current: mobCurrentOf, titleOf: mobTitleOf, columnOf: mobColumnOf, panelOf: mobPanelOf,
@@ -153,5 +157,5 @@ function mobMigrateView(v) { return MOBILE_ROOT[v] ? v : 'board'; }
     MODE_TITLE,
     migrateView: mobMigrateView, screen: mobScreen, root: mobRootOf,
     DESTS: MOBILE_DESTS, DEST_FOR_MODE: MOBILE_DEST, ROOTS: MOBILE_ROOT,
-    PANEL_OF_KIND: MOBILE_PANEL, DETAIL_TITLE };
+    PANEL_OF_KIND: MOBILE_PANEL, DETAIL_TITLE, DEST_TITLE, LEGACY_DEST };
 });

package/workspace/lib/needs-providers.js

@@ -0,0 +1,120 @@
+'use strict';
+/* needs-providers.js — the planning layer's needs-you rows, one file per run, folded into server.js deriveNeeds
+ * (pm-os-absorb Runs 2 to 5, PRD R12).
+ *
+ *   rowsFor(w, { lead }) → rows      every provider's rows for workspace `w`, each tagged { derived: true, ws, provider }
+ *   sigFor(w)            → string    one signature over every provider (server.js needsSig), so a count is never stale
+ *   isProviderRow(n)     → boolean   server.js keeps these rows out of derived state, next steps and the portfolio,
+ *                                    as it keeps Run 1's plan rows out (notPlanNeed)
+ *   PROVIDERS · RESERVED_KINDS · status()
+ *
+ * Four runs add needs rows (kind 8 "needs repair", kind 7 cycle rows, kind 4 work to check, kind 1 report to issue).
+ * Each adds ONE file, named in PROVIDERS before it exists, instead of a block in deriveNeeds. A PROVIDER exports:
+ *   module.exports = {
+ *     kinds: ['pm-line'],                                   // the row kinds it makes; unique across providers
+ *     rowsFor(w, { lead }) → [{ run_id, kind, initiative_id, question, doc?, today? }],
+ *     sig(w) → string,                                      // optional: changes whenever its rows may change
+ *   };
+ * `w` is a registered workspace ({ id, root, … }). `lead` is true for the one registered tree that speaks for a
+ * repository's ledgers (server.js isPlanNeedsTree): a provider of repository-wide rows returns [] when it is false, or
+ * a repository with a linked worktree registered counts every row twice. `run_id` is unique and stable per row and
+ * starts with the provider's name: the needs queue de-duplicates by it.
+ * `today` (optional) is what a Today card needs, passed through /api/needs unchanged:
+ *   { kind: 1..8, source: '<provider>', cause, evidence, act: { label, cli? } }
+ * A row the page receives never carries a session token: name an agent by its page name (`agent:sess-<n>`).
+ *
+ * A provider file that is not on disk yet is skipped. One that fails to load, claims a kind another uses, or throws
+ * gives ONE row of kind 'provider-error' that names it: a broken source is never an empty list (R10).
+ */
+const path = require('path');
+
+const PROVIDERS = Object.freeze([
+  'pm-lines-needs',     // Run 2 (2B): a PM-only line that is not attested (kind 8)
+  'initiative-needs',   // Run 2 (2C): day one, agent proposals, passed check-by (kind 7); a record with no anchor (kind 8)
+  'work-check-needs',   // Run 4 (4D): a person's item in Review, a batched Release (kind 4)
+  'report-needs',       // Run 5 (5C): a report to issue (kind 1), cycle rows (kind 7), a schedule left no output (kind 8)
+]);
+/** Kinds that already mean something in the needs queue. A provider may not reuse one. */
+const RESERVED_KINDS = Object.freeze(['question', 'accept', 'outcome', 'keep', 'evidence', 'plan-flag', 'provider-error']);
+
+let table = null;
+function load() {
+  if (table) return table;
+  const mods = [];
+  const broken = [];
+  const owner = new Map(RESERVED_KINDS.map((k) => [k, '(reserved)']));
+  for (const name of PROVIDERS) {
+    const full = path.join(__dirname, name + '.js');
+    let mod;
+    try { mod = require(full); }
+    catch (e) {
+      if (e && e.code === 'MODULE_NOT_FOUND' && String(e.message).includes(full)) continue;   // not built yet
+      broken.push({ name, error: `failed to load: ${String((e && e.message) || e).slice(0, 160)}` });
+      continue;
+    }
+    const kinds = mod && Array.isArray(mod.kinds) ? mod.kinds : null;
+    if (!kinds || !kinds.length || typeof mod.rowsFor !== 'function') { broken.push({ name, error: 'must export kinds and rowsFor' }); continue; }
+    const clash = kinds.find((k) => typeof k !== 'string' || owner.has(k));
+    if (clash !== undefined) { broken.push({ name, error: `kind ${JSON.stringify(clash)} is already used by ${owner.get(clash) || 'nobody (not a string)'}` }); continue; }
+    for (const k of kinds) owner.set(k, name);
+    mods.push({ name, mod, kinds });
+  }
+  table = { mods, broken };
+  return table;
+}
+
+const errorRow = (w, name, error) => ({
+  run_id: `${name}:error`, kind: 'provider-error', initiative_id: null, derived: true, doc: null, ws: w.id, provider: name,
+  question: `The needs source ${name} could not be read: ${error}`,
+});
+
+function rowsFor(w, { lead = true } = {}) {
+  if (!w) return [];
+  const { mods, broken } = load();
+  const out = broken.map((b) => errorRow(w, b.name, b.error));
+  for (const { name, mod, kinds } of mods) {
+    let rows;
+    try { rows = mod.rowsFor(w, { lead: !!lead }); }
+    catch (e) { out.push(errorRow(w, name, String((e && e.message) || e).slice(0, 160))); continue; }
+    for (const r of Array.isArray(rows) ? rows : []) {
+      if (!r || typeof r.run_id !== 'string' || !kinds.includes(r.kind)) { out.push(errorRow(w, name, 'a row has no run_id or a kind it did not declare')); break; }
+      out.push({ ...r, derived: true, ws: w.id, provider: name });
+    }
+  }
+  return out;
+}
+
+/** Each provider's state-health lines (optional `banner(w, { lead })` → [{ source, error }]): a source that is still being
+ *  read, not a row. Today shows them in its banner. */
+function bannersFor(w, { lead = true } = {}) {
+  if (!w) return [];
+  const out = [];
+  for (const { name, mod } of load().mods) {
+    if (typeof mod.banner !== 'function') continue;
+    try { for (const b of mod.banner(w, { lead: !!lead }) || []) if (b && b.error) out.push({ source: String(b.source || name), error: String(b.error) }); }
+    catch { /* a banner that fails says nothing; its rows still report errors */ }
+  }
+  return out;
+}
+
+function sigFor(w) {
+  if (!w) return '';
+  const { mods, broken } = load();
+  const parts = [`broken:${broken.length}`];
+  for (const { name, mod } of mods) {
+    if (typeof mod.sig !== 'function') { parts.push(`${name}:-`); continue; }
+    let s;
+    try { s = String(mod.sig(w)); } catch { s = 'unreadable'; }
+    parts.push(`${name}:${s}`);
+  }
+  return parts.join(',');
+}
+
+const isProviderRow = (n) => !!n && n.derived === true && typeof n.provider === 'string';
+
+function status() {
+  const t = load();
+  return { loaded: t.mods.map((m) => ({ name: m.name, kinds: m.kinds.slice() })), broken: t.broken.map((b) => ({ ...b })) };
+}
+
+module.exports = { PROVIDERS, RESERVED_KINDS, rowsFor, bannersFor, sigFor, isProviderRow, status };