@bongos/core 1.24.11 → 1.24.12

package/modules/market-watch/pages.js

@@ -0,0 +1,323 @@
+'use strict';
+
+// modules/market-watch/pages.js — what the Market Watch home (the watchtower desk) and
+// the tracked-item page (the dossier) read and write (task 1004939, goal 1000137). The
+// designs of record are docs/design/mocks/market-watch/home.html (option D) and item.html
+// (option B).
+//
+// READS go through db.js (levels, streaks, run numbers, sparklines, spend and the next
+// due date are derived there) plus the two queries below that only these pages need: the
+// latest score per item and dimension (the landscape scope's dots) and the entries found
+// in the last seven days (this week's reports). Every query filters on the project key.
+//
+// SHAPES are pure (shapeHome, shapeItem): the routes call them on what the reads return,
+// and tests/market_watch_pages.mjs calls them on the committed seed, so the page's
+// numbers are checked without a database.
+//
+// THE ONE WRITE is a proposal (market_watch_proposals, origin 'member'). Every button on
+// the item page that would change what is watched files one: re-score, move between
+// partner and competitor, add a source, correct an entry, and stop tracking (a
+// remove_item). The home's "send a new scout" files an add_item. Approving them is the
+// rules page's (task 1004941); nothing here changes an item, a score or an entry.
+
+const db = require('./db');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_DAYS = 7;
+const KINDS = Object.freeze(['competitor', 'partner', 'topic']);
+const REPORT_LIMIT = 8;
+const STREAK_SLOTS = 9;
+const REASON_MAX = 280;
+const NAME_MAX = 120;
+const URL_MAX = 500;
+const DIM_RE = /^[a-z][a-z0-9_]{0,59}$/;
+// The four the item page's "Propose a change" offers, then the two the other buttons file.
+const ITEM_KINDS = Object.freeze(['rescore', 'move_kind', 'add_source', 'correct_entry', 'remove_item']);
+const PROPOSAL_KINDS = Object.freeze([...ITEM_KINDS, 'add_item']);
+
+const num = (v) => (v == null ? null : Number(v));
+const isoDay = (d) => (d instanceof Date ? d.toISOString().slice(0, 10) : String(d).slice(0, 10));
+
+// ---- reads only these pages need -------------------------------------------
+
+const LATEST_SCORES_SQL = `
+  SELECT DISTINCT ON (s.item_id, s.dimension) s.item_id, s.dimension, s.value
+    FROM market_watch_score_snapshots s
+    JOIN market_watch_items i ON i.id = s.item_id
+    JOIN market_watch_runs r ON r.id = s.run_id
+   WHERE i.project = $1 AND i.status <> 'removed'
+   ORDER BY s.item_id, s.dimension, r.created_at DESC, r.id DESC`;
+
+async function latestScores(pool, { project }) {
+  const { rows } = await pool.query(LATEST_SCORES_SQL, [project]);
+  return rows;
+}
+
+const WEEK_ENTRIES_SQL = `
+  SELECT e.id, e.item_id, e.run_id, e.type, e.found_on, e.takeaway, e.confidence,
+         e.source_url, e.source_label, e.pinned
+    FROM market_watch_log_entries e
+    JOIN market_watch_items i ON i.id = e.item_id
+   WHERE i.project = $1 AND i.status <> 'removed' AND e.found_on >= $2::date
+   ORDER BY e.found_on DESC, e.id DESC
+   LIMIT 1000`;
+
+async function weekEntries(pool, { project, now = new Date() }) {
+  const since = isoDay(new Date(new Date(now).getTime() - WEEK_DAYS * DAY_MS));
+  const { rows } = await pool.query(WEEK_ENTRIES_SQL, [project, since]);
+  return rows;
+}
+
+// ---- pure shapes ------------------------------------------------------------
+
+// The labels a kind's dimensions carry, from the rules in use: { <key>: label }.
+function rubricLabels(rules, kind) {
+  const rubric = (rules && rules.active && rules.active.rubric) || {};
+  const out = {};
+  for (const d of Array.isArray(rubric[kind]) ? rubric[kind] : []) if (d && d.key) out[d.key] = String(d.label || d.key);
+  return out;
+}
+
+// One report per item: a pinned entry first, then the surest, then an insight over a
+// datapoint, then the newest. Items ordered by their overall score, best first.
+const TYPE_RANK = { insight: 0, news: 1, datapoint: 2 };
+function pickReports(entries, itemsById, limit = REPORT_LIMIT) {
+  const best = new Map();
+  const better = (a, b) => (Number(!!b.pinned) - Number(!!a.pinned))
+    || (Number(b.confidence) - Number(a.confidence))
+    || ((TYPE_RANK[a.type] ?? 3) - (TYPE_RANK[b.type] ?? 3))
+    || (isoDay(b.found_on) > isoDay(a.found_on) ? 1 : isoDay(b.found_on) < isoDay(a.found_on) ? -1 : 0)
+    || (Number(b.id) - Number(a.id));
+  for (const e of entries) {
+    const it = itemsById.get(String(e.item_id));
+    if (!it) continue;
+    const k = String(e.item_id);
+    if (!best.has(k) || better(e, best.get(k)) < 0) best.set(k, e);
+  }
+  const all = [...best.values()]
+    .map((e) => {
+      const it = itemsById.get(String(e.item_id));
+      return {
+        id: Number(e.id),
+        item_id: Number(e.item_id),
+        item_name: it.name,
+        kind: it.kind,
+        overall: it.overall,
+        type: e.type,
+        takeaway: e.takeaway,
+        confidence: Number(e.confidence),
+        found_on: isoDay(e.found_on),
+        source_url: e.source_url,
+      };
+    })
+    .sort((a, b) => ((b.overall ?? -1) - (a.overall ?? -1)) || a.item_name.localeCompare(b.item_name));
+  // Competitors and partners are scored on different scales, so one ranking across both
+  // would be a false comparison: take each kind's best in turn instead.
+  const queues = KINDS.map((k) => all.filter((r) => r.kind === k));
+  const out = [];
+  while (out.length < limit && queues.some((q) => q.length)) {
+    for (const q of queues) if (q.length && out.length < limit) out.push(q.shift());
+  }
+  return out;
+}
+
+// shapeHome — the watchtower desk: scouts, the run streak, the next sweep and budget,
+// the landscape's axes and dots, and this week's reports.
+function shapeHome({ items, runs, settings, scores, entries, rules, now = new Date() }) {
+  const live = items.filter((it) => it.status !== 'removed');
+  const itemsById = new Map(live.map((it) => [String(it.id), it]));
+  const reports = pickReports(entries, itemsById);
+  const weekByKind = {};
+  for (const e of entries) {
+    const it = itemsById.get(String(e.item_id));
+    if (it) (weekByKind[it.kind] = weekByKind[it.kind] || new Set()).add(String(it.id));
+  }
+  const scouts = KINDS.map((kind) => {
+    const mine = live.filter((it) => it.kind === kind);
+    return {
+      kind,
+      watched: mine.filter((it) => it.status === 'active').length,
+      level: mine.reduce((m, it) => Math.max(m, it.level || 0), 0),
+      reports: weekByKind[kind] ? weekByKind[kind].size : 0,
+    };
+  });
+  const ranRuns = runs.filter((r) => r.n != null);
+  const streak = runs.slice(-STREAK_SLOTS).map((r) => ({ n: r.n, ran: r.n != null, date: isoDay(r.created_at), reason: r.reason || null }));
+
+  const labels = rubricLabels(rules, 'competitor');
+  const byItem = new Map();
+  for (const s of scores) {
+    const k = String(s.item_id);
+    if (!byItem.has(k)) byItem.set(k, {});
+    byItem.get(k)[s.dimension] = num(s.value);
+  }
+  const seen = new Set(Object.keys(labels));
+  const dots = live.filter((it) => it.kind === 'competitor').map((it) => {
+    const sc = byItem.get(String(it.id)) || {};
+    for (const k of Object.keys(sc)) if (k !== 'overall') seen.add(k);
+    return { id: it.id, name: it.name, overall: it.overall, level: it.level, scores: sc };
+  });
+  const axes = [...seen].map((key) => ({ key, label: labels[key] || key.replace(/_/g, ' ') }));
+  axes.push({ key: 'overall', label: 'overall likeness' });
+
+  const s = settings.settings;
+  const cap = Number(s.monthly_cap_usd) || 0;
+  const spent = Number(settings.spentThisMonthUsd) || 0;
+  return {
+    generated_at: new Date(now).toISOString(),
+    watch: { enabled: !!s.enabled, configured: !!s.configured, cadence: s.cadence },
+    weeks_watched: ranRuns.length,
+    scouts,
+    streak,
+    next_sweep: { due: settings.nextRunDue ? new Date(settings.nextRunDue).toISOString() : null, enabled: !!s.enabled },
+    budget: { cap_usd: cap, spent_usd: Math.round(spent * 100) / 100, left_usd: Math.max(0, Math.round((cap - spent) * 100) / 100) },
+    axes,
+    dots,
+    reports,
+    hot: reports.map((r) => r.item_id),
+    // Every tracked item by name: the desk's "open a file" picker, the way to any item
+    // page that is not a dot (a partner, a topic) or a report this week.
+    index: live.map((it) => ({ id: it.id, kind: it.kind, name: it.name }))
+      .sort((a, b) => (KINDS.indexOf(a.kind) - KINDS.indexOf(b.kind)) || a.name.localeCompare(b.name)),
+  };
+}
+
+// shapeItem — the dossier: the card (level, streak, overall line, one sparkline per
+// dimension), why it is watched, its known facts and the sortable case file.
+function shapeItem({ item, entries, history, rules, openProposals = 0 }) {
+  const labels = rubricLabels(rules, item.kind);
+  const series = history.series || {};
+  const keys = [...Object.keys(labels), ...Object.keys(series).filter((k) => k !== 'overall' && !(k in labels))];
+  const point = (vals) => {
+    const v = (vals || []).filter((x) => x != null);
+    return { first: v.length ? v[0] : null, latest: v.length ? v[v.length - 1] : null };
+  };
+  const dimensions = keys.map((key) => ({ key, label: labels[key] || key.replace(/_/g, ' '), series: series[key] || [], ...point(series[key]) }));
+  return {
+    item: {
+      id: item.id, kind: item.kind, name: item.name, url: item.url, category: item.category,
+      description: item.description, why_tracked: item.why_tracked, facts: item.facts || {},
+      status: item.status, added_via: item.added_via, created_at: item.created_at,
+      overall: item.overall, level: item.level, streak: item.streak,
+    },
+    runs: (history.runs || []).map((r) => ({ n: r.n, date: isoDay(r.date) })),
+    overall: { series: series.overall || [], ...point(series.overall) },
+    dimensions,
+    moved: dimensions.filter((d) => d.first != null && d.latest != null && d.first !== d.latest).length,
+    entries: entries.map((e) => ({
+      id: Number(e.id), run: e.run, type: e.type, found_on: isoDay(e.found_on), takeaway: e.takeaway,
+      dimension: e.dimension, source_url: e.source_url, source_label: e.source_label,
+      confidence: Number(e.confidence), pinned: !!e.pinned,
+    })),
+    open_proposals: Number(openProposals) || 0,
+  };
+}
+
+// ---- the views --------------------------------------------------------------
+
+// Each view reads the numbered runs ONCE and hands them to every db.js read that would
+// otherwise read market_watch_runs again (listItems, getItem, caseFile, scoreHistory).
+async function homeView(pool, { project, now = new Date() }) {
+  const runs = await db.numberedRuns(pool, { project });
+  const [items, settings, scores, entries, rules] = await Promise.all([
+    db.listItems(pool, { project, knownRuns: runs }),
+    db.settingsView(pool, { project, now }),
+    latestScores(pool, { project }),
+    weekEntries(pool, { project, now }),
+    db.rules(pool, { project }),
+  ]);
+  return shapeHome({ items, runs, settings, scores, entries, rules, now });
+}
+
+async function itemView(pool, { project, id }) {
+  const runs = await db.numberedRuns(pool, { project });
+  const item = await db.getItem(pool, { project, id, knownRuns: runs });
+  if (!item) return null;
+  const [entries, history, rules, open] = await Promise.all([
+    db.caseFile(pool, { project, itemId: id, knownRuns: runs }),
+    db.scoreHistory(pool, { project, itemId: id, knownRuns: runs }),
+    db.rules(pool, { project }),
+    db.proposals(pool, { project, status: 'open', itemId: id, limit: 100 }),
+  ]);
+  return shapeItem({ item, entries, history, rules, openProposals: open.length });
+}
+
+// ---- proposals --------------------------------------------------------------
+
+const oneLine = (s) => String(s == null ? '' : s).replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim();
+const isHttp = (u) => /^https?:\/\/[^\s/]+\.[^\s]+$/i.test(u);
+
+// normalizeProposal(body, { item, rubricKeys }) → { ok, value } | { ok: false, error, message }.
+// `item` is the tracked item the proposal is about (null for add_item); rubricKeys is the
+// set of dimensions the item's kind is scored on. Everything a member typed is trimmed
+// to one line and bounded; nothing here trusts the client's idea of the item's kind.
+function normalizeProposal(body, { item = null, rubricKeys = null } = {}) {
+  const b = body && typeof body === 'object' ? body : {};
+  const kind = String(b.kind || '');
+  if (!PROPOSAL_KINDS.includes(kind)) return { ok: false, error: 'invalid_kind', message: 'Pick what should change.' };
+  const reason = oneLine(b.reason);
+  if (!reason) return { ok: false, error: 'reason_required', message: 'Say why, in one line.' };
+  if (reason.length > REASON_MAX) return { ok: false, error: 'reason_too_long', message: `Keep the reason to ${REASON_MAX} characters.` };
+  if (kind === 'add_item') {
+    const name = oneLine(b.name);
+    const scout = String(b.scout || '');
+    const url = oneLine(b.url);
+    if (!KINDS.includes(scout)) return { ok: false, error: 'invalid_scout', message: 'Pick a competitor, a partner or a topic.' };
+    if (!name || name.length > NAME_MAX) return { ok: false, error: 'invalid_name', message: `Name it in up to ${NAME_MAX} characters.` };
+    if (url && (url.length > URL_MAX || !isHttp(url))) return { ok: false, error: 'invalid_url', message: 'A link starts with http:// or https://.' };
+    return { ok: true, value: { kind, item_id: null, log_entry_id: null, reason, payload: { kind: scout, name, url: url || null } } };
+  }
+  if (!item) return { ok: false, error: 'item_not_found', message: 'That item is not tracked here.' };
+  const base = { kind, item_id: item.id, log_entry_id: null, reason };
+  if (kind === 'rescore') {
+    const dimension = String(b.dimension || '');
+    const value = Number(b.value);
+    const known = dimension === 'overall' || (rubricKeys ? rubricKeys.has(dimension) : DIM_RE.test(dimension));
+    if (!DIM_RE.test(dimension) || !known) return { ok: false, error: 'invalid_dimension', message: 'Pick a score to change.' };
+    if (b.value === '' || b.value == null || !Number.isFinite(value) || value < 0 || value > 10) return { ok: false, error: 'invalid_value', message: 'A score is from 0 to 10.' };
+    return { ok: true, value: { ...base, payload: { dimension, value: Math.round(value * 10) / 10 } } };
+  }
+  if (kind === 'move_kind') {
+    if (item.kind === 'topic') return { ok: false, error: 'cannot_move_topic', message: 'A topic is not a partner or a competitor.' };
+    return { ok: true, value: { ...base, payload: { from: item.kind, to: item.kind === 'partner' ? 'competitor' : 'partner' } } };
+  }
+  if (kind === 'add_source') {
+    const url = oneLine(b.url);
+    if (!url || url.length > URL_MAX || !isHttp(url)) return { ok: false, error: 'invalid_url', message: 'A source is a link that starts with http:// or https://.' };
+    return { ok: true, value: { ...base, payload: { source_url: url } } };
+  }
+  if (kind === 'correct_entry') {
+    const entry = String(b.log_entry_id || '');
+    if (!/^[1-9]\d{0,17}$/.test(entry)) return { ok: false, error: 'invalid_entry', message: 'Pick the entry to correct.' };
+    return { ok: true, value: { ...base, log_entry_id: Number(entry), payload: {} } };
+  }
+  return { ok: true, value: { ...base, payload: {} } }; // remove_item: stop tracking
+}
+
+// The INSERT checks ownership in SQL: the item must be this project's, and an entry to
+// correct must be that item's. A row from another project inserts nothing.
+const INSERT_ITEM_PROPOSAL_SQL = `
+  INSERT INTO market_watch_proposals (project, kind, origin, item_id, log_entry_id, payload, reason, proposed_by)
+  SELECT $1, $2, 'member', i.id, $4, $5::jsonb, $6, $7
+    FROM market_watch_items i
+   WHERE i.id = $3 AND i.project = $1
+     AND ($4::bigint IS NULL OR EXISTS (SELECT 1 FROM market_watch_log_entries e WHERE e.id = $4 AND e.item_id = i.id))
+  RETURNING id, kind, status, created_at`;
+const INSERT_NEW_ITEM_PROPOSAL_SQL = `
+  INSERT INTO market_watch_proposals (project, kind, origin, payload, reason, proposed_by)
+  VALUES ($1, 'add_item', 'member', $2::jsonb, $3, $4)
+  RETURNING id, kind, status, created_at`;
+
+async function insertProposal(pool, { project, proposal, builderId }) {
+  const p = proposal;
+  const { rows: [row] } = p.kind === 'add_item'
+    ? await pool.query(INSERT_NEW_ITEM_PROPOSAL_SQL, [project, JSON.stringify(p.payload), p.reason, builderId])
+    : await pool.query(INSERT_ITEM_PROPOSAL_SQL, [project, p.kind, p.item_id, p.log_entry_id, JSON.stringify(p.payload), p.reason, builderId]);
+  return row ? { ...row, id: Number(row.id) } : null;
+}
+
+module.exports = {
+  homeView, itemView, insertProposal,
+  shapeHome, shapeItem, pickReports, rubricLabels, normalizeProposal,
+  PROPOSAL_KINDS, KINDS,
+};

package/modules/market-watch/proposals.js

@@ -15,9 +15,17 @@
 //   add_item     the tracked item is created (added_via 'proposal', added_by the proposer).
 //                An item already there under the same key (a removed one) is re-activated.
 //   remove_item  the item's status becomes 'removed' (never a DELETE; its log stays).
-//   any other    (rescore, move_kind, add_source, correct_entry) the decision is recorded
-//                as 'approved'. Those kinds belong to the item page, which says what each
-//                payload means; this file does not guess at a payload it did not define.
+//   rescore      payload { dimension, value }: the item's score on that dimension in the
+//                latest run that ran is set to the value (a snapshot upsert), so the card,
+//                the landscape and the sparkline's last point read it.
+//   move_kind    payload { from, to }: the item moves between partner and competitor. It
+//                does not apply when the item is no longer the 'from' kind, or the same
+//                name and link are already tracked as the 'to' kind.
+//   add_source   payload { source_url }: the link joins the item's facts.watch_sources
+//                (shown on the item page; the weekly run does not read it yet).
+//   correct_entry payload {} with log_entry_id: the reason IS the correction, written for
+//                a person to act on, so the decision is recorded as 'approved' only.
+//   The four item-page payloads are written by modules/market-watch/pages.js (task 1004939).
 // A carried-out approval is status 'applied'; a recorded one is 'approved'. A decline is
 // 'rejected'. Every decision names who made it and when (decided_by, decided_at).
 //
@@ -86,6 +94,29 @@ const SQL = Object.freeze({
   getOpen: `-- mw:proposal-get-open
     SELECT id, kind, payload, reason FROM market_watch_proposals
      WHERE id = $1 AND project = $2 AND status = 'open'`,
+  itemRescore: `-- mw:item-rescore
+    INSERT INTO market_watch_score_snapshots (item_id, run_id, dimension, value)
+    SELECT i.id, r.id, $3, $4
+      FROM market_watch_items i
+      JOIN market_watch_runs r ON r.project = i.project AND r.status IN ('done', 'partial')
+     WHERE i.id = $1 AND i.project = $2 AND i.status <> 'removed'
+     ORDER BY r.created_at DESC, r.id DESC
+     LIMIT 1
+    ON CONFLICT (item_id, run_id, dimension) DO UPDATE SET value = EXCLUDED.value
+    RETURNING item_id`,
+  itemMove: `-- mw:item-move
+    UPDATE market_watch_items i SET kind = $3, updated_at = now()
+     WHERE i.id = $1 AND i.project = $2 AND i.kind = $4 AND i.status <> 'removed'
+       AND NOT EXISTS (SELECT 1 FROM market_watch_items o
+                        WHERE o.project = i.project AND o.kind = $3 AND o.url = i.url AND o.name = i.name)
+    RETURNING i.id`,
+  itemAddSource: `-- mw:item-add-source
+    UPDATE market_watch_items
+       SET facts = CASE WHEN COALESCE(facts->'watch_sources', '[]'::jsonb) ? $3 THEN facts
+                        ELSE jsonb_set(facts, '{watch_sources}', COALESCE(facts->'watch_sources', '[]'::jsonb) || to_jsonb($3::text)) END,
+           updated_at = now()
+     WHERE id = $1 AND project = $2 AND status <> 'removed'
+    RETURNING id`,
   atVote: `-- mw:proposal-at-vote
     UPDATE market_watch_proposals SET payload = payload || jsonb_build_object('matter_id', $3::text)
      WHERE id = $1 AND project = $2 AND status = 'open'`,
@@ -152,6 +183,29 @@ function itemFromPayload(payload) {
   return name ? { name, kind, url: /^https?:\/\//i.test(url) ? url : '', why } : null;
 }
 
+// itemChange(kind, payload) → { sql, params } | null — the item page's three kinds an
+// approval applies, re-checked here: a payload is only as good as the row it was read from.
+const DIM_RE = /^[a-z][a-z0-9_]{0,59}$/;
+function itemChange(kind, payload) {
+  const p = payload || {};
+  if (kind === 'rescore') {
+    const v = Number(p.value);
+    if (!DIM_RE.test(String(p.dimension || '')) || p.value == null || !Number.isFinite(v) || v < 0 || v > 10) return null;
+    return { sql: 'itemRescore', params: [p.dimension, Math.round(v * 10) / 10] };
+  }
+  if (kind === 'move_kind') {
+    const pair = ['competitor', 'partner'];
+    if (!pair.includes(p.from) || !pair.includes(p.to) || p.from === p.to) return null;
+    return { sql: 'itemMove', params: [p.to, p.from] };
+  }
+  if (kind === 'add_source') {
+    const u = String(p.source_url || '').trim();
+    if (!/^https?:\/\/\S+$/i.test(u) || u.length > 500) return null;
+    return { sql: 'itemAddSource', params: [u] };
+  }
+  return null;
+}
+
 // decideProposal(pool, { project, id, decision, decidedBy, via, withTx }) →
 //   { ok: true, status, applied, version?, item_id? } |
 //   { ok: false, reason: 'not_found' | 'not_open' | 'no_active_rules' | 'no_longer_applies' | 'bad_payload' | 'item_gone' }
@@ -206,9 +260,17 @@ async function decideProposal({ project, id, decision, decidedBy, via = null, wi
       await decide('applied');
       return { ok: true, status: 'applied', applied: true, item_id: Number(it.id) };
     }
+    if (p.kind === 'rescore' || p.kind === 'move_kind' || p.kind === 'add_source') {
+      const a = itemChange(p.kind, p.payload);
+      if (!a) return { ok: false, reason: 'bad_payload' };
+      const { rows: [it] } = await client.query(SQL[a.sql], [p.item_id, project, ...a.params]);
+      if (!it) return { ok: false, reason: p.kind === 'move_kind' ? 'no_longer_applies' : 'item_gone' };
+      await decide('applied');
+      return { ok: true, status: 'applied', applied: true, item_id: Number(p.item_id) };
+    }
     await decide('approved');
     return { ok: true, status: 'approved', applied: false };
   });
 }
 
-module.exports = { createProposal, decideProposal, getOpen, markAtVote, itemFromPayload, MAX_OPEN_PER_MEMBER };
+module.exports = { createProposal, decideProposal, getOpen, markAtVote, itemFromPayload, itemChange, MAX_OPEN_PER_MEMBER };

package/modules/market-watch/routes/pages.js

@@ -0,0 +1,116 @@
+// modules/market-watch/routes/pages.js — the reads and the one write behind the Market
+// Watch home and tracked-item pages (task 1004939, goal 1000137).
+//
+//   GET  /market-watch/home         the watchtower desk: scouts, streak, next sweep,
+//                                   budget, the landscape and this week's reports
+//   GET  /market-watch/items/:id    one tracked item: its card, sparklines and case file
+//   POST /market-watch/proposals    a member proposes a change (re-score, move between
+//                                   partner and competitor, add a source, correct an
+//                                   entry, stop tracking, or a new scout)
+//
+// rank: any-builder — every route needs a signed-in builder, and every builder on this
+// instance is a member of its project (each project is its own instance, ADR 0393). A
+// visitor with no session gets a 401 and no data (tests/market_watch_pages.mjs). These
+// routes mount only while the module is on; where it is off they do not exist, and the
+// page shows its quiet off state instead.
+//
+// A proposal changes nothing it names. It is a row in market_watch_proposals for the
+// government to decide on the rules page (task 1004941). Its text is untrusted member
+// input: it is stored as typed, bounded to one line, and escaped wherever it is shown.
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const pages = require('../pages');
+const db = require('../db');
+const { projectKey } = require('../seed');
+
+const ID_RE = /^[1-9]\d{0,17}$/;
+
+function currentProject() {
+  try { return projectKey(api.branding().domains.publicOrigin); } catch { return null; }
+}
+
+module.exports = function buildMarketWatchPagesRouter(deps = {}) {
+  const router = express.Router();
+  const pool = () => deps.pool || api.pool;
+  const project = () => (deps.project !== undefined ? deps.project : currentProject());
+
+  // The in-handler membership check: every active builder of this instance is a member of
+  // its project (ADR 0393), so a member is a signed-in builder with an id who is not
+  // offboarded. requireBuilder already refuses 'inactive'; this holds it per handler too.
+  const isMember = (req, res) => {
+    const b = req.builder;
+    if (!b || b.id == null || b.status === 'inactive') { res.fail('not_a_member', 403); return false; }
+    return true;
+  };
+
+  const needProject = (res) => {
+    const p = project();
+    if (!p) res.fail('no_project_origin', { status: 503, message: 'This project has no public address set, so Market Watch cannot tell its rows apart.' });
+    return p;
+  };
+
+  // rank: any-builder — every member reads the desk.
+  router.get('/market-watch/home', api.requireBuilder, api.asyncHandler('GET /market-watch/home', async (req, res) => {
+    if (!isMember(req, res)) return;
+    const p = needProject(res);
+    if (!p) return;
+    res.set('Cache-Control', 'no-store');
+    res.json(await pages.homeView(pool(), { project: p }));
+  }));
+
+  // rank: any-builder — every member reads an item's case file.
+  router.get('/market-watch/items/:id', api.requireBuilder, api.asyncHandler('GET /market-watch/items/:id', async (req, res) => {
+    if (!isMember(req, res)) return;
+    const id = String(req.params.id || '');
+    if (!ID_RE.test(id)) return res.fail('invalid_item_id', 400);
+    const p = needProject(res);
+    if (!p) return;
+    const view = await pages.itemView(pool(), { project: p, id: Number(id) });
+    if (!view) return res.fail('item_not_found', 404);
+    res.set('Cache-Control', 'no-store');
+    res.json(view);
+  }));
+
+  // rank: any-builder — every member may propose; the government decides (task 1004941).
+  router.post('/market-watch/proposals', api.requireBuilder, api.asyncHandler('POST /market-watch/proposals', async (req, res) => {
+    if (!isMember(req, res)) return;
+    // Strict: an unknown field is refused. The ids and the score arrive as a number or as
+    // the form's string, so they carry no type here; normalizeProposal checks each.
+    if (api.validateOrRespond(req, res, {
+      kind: { required: true, type: 'string', enum: pages.PROPOSAL_KINDS },
+      reason: { type: 'string', maxLength: 2000 },
+      item_id: {},
+      dimension: { type: 'string', maxLength: 60 },
+      value: {},
+      url: { type: 'string', maxLength: 2000 },
+      log_entry_id: {},
+      scout: { type: 'string', enum: pages.KINDS },
+      name: { type: 'string', maxLength: 2000 },
+    })) return;
+    const p = needProject(res);
+    if (!p) return;
+    const body = req.body && typeof req.body === 'object' ? req.body : {};
+    let item = null;
+    let rubricKeys = null;
+    if (body.kind !== 'add_item') {
+      const id = String(body.item_id || '');
+      if (!ID_RE.test(id)) return res.fail('invalid_item_id', 400);
+      item = await db.getItem(pool(), { project: p, id: Number(id) });
+      if (!item || item.status === 'removed') return res.fail('item_not_found', 404);
+      if (body.kind === 'rescore') {
+        rubricKeys = new Set(Object.keys(pages.rubricLabels(await db.rules(pool(), { project: p }), item.kind)));
+        if (!rubricKeys.size) rubricKeys = null;
+      }
+    }
+    const n = pages.normalizeProposal(body, { item, rubricKeys });
+    if (!n.ok) return res.fail(n.error, { status: 400, message: n.message });
+    const row = await pages.insertProposal(pool(), { project: p, proposal: n.value, builderId: req.builder.id });
+    if (!row) return res.fail('item_not_found', 404); // the entry to correct is not this item's
+    res.status(201).json({ proposal: { id: row.id, kind: row.kind, status: row.status, created_at: row.created_at } });
+  }));
+
+  return router;
+};

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.11",
+  "version": "1.24.12",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.24.11",
+      "version": "1.24.12",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.11",
+  "version": "1.24.12",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -10901,5 +10901,11 @@
       "id": "1004990",
       "text": "A project can now say in its own words what a task pays, and set its standing pay terms on the settings page with a record of who changed them; builders see the pay on the task page and in their task list before claiming, and"
     }
+  ],
+  "1.24.12": [
+    {
+      "id": "1004939",
+      "text": "Every member of a project can now open Market Watch to see its scouts on competitors, partners and topics, the landscape chart, the next sweep, the budget left and this week's reports, and open any tracked item's card and case"
+    }
   ]
 }

package/src/bongos/module-scope-map.js

@@ -202,6 +202,7 @@ const MODULE_GLOBS = {
     'tests/market_watch_rules.mjs', 'tests/market_watch_rules_db.mjs',
     'tests/market_watch_ask.mjs', 'tests/market_watch_ask_db.mjs',
     'tests/market_watch_settings.mjs',
+    'tests/market_watch_pages.mjs', 'tests/fixtures/market-watch-seed-rows.cjs',
   ],
   // --- builder prefs (wandering/skill/sound/render) + builder-needs ---
   // Carved into modules/builder-settings/ (BV1.R80 / ADR 0093 §1): the five pref

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.11'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.12'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/fixtures/market-watch-seed-rows.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+// tests/fixtures/market-watch-seed-rows.cjs — the committed 2026-10-28 research as the
+// rows seed.js writes to the hub (task 1004939): one seed run, one item per researched
+// company or partner, their score snapshots and their case-file entries, with ids handed
+// out in seed order as a fresh database would. tests/market_watch_pages.mjs runs the
+// Market Watch page shapes on these, and the hall-preview fixtures market-watch__*.json
+// were generated from them, so the pages are checked against the real seed without a
+// database.
+
+const RESEARCH_DATE = '2026-10-28';
+const RESEARCH_AT = `${RESEARCH_DATE}T12:00:00.000Z`;
+
+function seedRows(seed) {
+  const built = seed.buildSeed({ market: seed.readSeed('market-data.json'), partners: seed.readSeed('partners-data.json') });
+  const runs = [{ id: 1, status: 'done', reason: null, trigger: 'seed', created_at: RESEARCH_AT }];
+  const items = [];
+  const scores = [];
+  const entries = [];
+  let entryId = 0;
+  built.items.forEach((it, i) => {
+    const id = i + 1;
+    items.push({
+      id, kind: it.kind, name: it.name, url: it.url, category: it.category, description: it.description,
+      why_tracked: it.whyTracked, facts: it.facts, status: 'active', added_via: 'seed', created_at: RESEARCH_AT,
+    });
+    for (const [dimension, value] of Object.entries(it.scores)) scores.push({ item_id: id, run_id: 1, dimension, value });
+    for (const e of it.entries) {
+      entries.push({
+        id: ++entryId, item_id: id, run_id: 1, type: e.type, found_on: RESEARCH_DATE, takeaway: e.takeaway,
+        dimension: e.dimension, source_url: e.sourceUrl, source_label: e.sourceLabel, confidence: e.confidence,
+        pinned: false, created_at: RESEARCH_AT,
+      });
+    }
+  });
+  return { rules: { version: 1, status: 'active', rubric: built.rules.rubric }, runs, items, scores, entries };
+}
+
+// What db.listItems returns for these rows: latest overall, level and streak.
+function listItemsFrom(r, numbered, db) {
+  return r.items.map((it) => {
+    const overall = r.scores.find((s) => s.item_id === it.id && s.dimension === 'overall');
+    const foundIn = [...new Set(r.entries.filter((e) => e.item_id === it.id).map((e) => e.run_id))];
+    return { ...it, overall: overall ? Number(overall.value) : null, ...db.progress(numbered, foundIn) };
+  });
+}
+
+function latestScoresFrom(r) {
+  return r.scores.map((s) => ({ item_id: s.item_id, dimension: s.dimension, value: s.value }));
+}
+
+// What db.caseFile returns for one item: pinned first, newest first, with its run number.
+function caseFileFrom(r, numbered, itemId) {
+  const runN = new Map(numbered.map((x) => [String(x.id), x.n]));
+  return r.entries.filter((e) => e.item_id === itemId)
+    .sort((a, b) => (Number(b.pinned) - Number(a.pinned)) || (b.found_on > a.found_on ? 1 : b.found_on < a.found_on ? -1 : 0) || (b.id - a.id))
+    .map((e) => ({ ...e, run: runN.get(String(e.run_id)) ?? null }));
+}
+
+module.exports = { seedRows, listItemsFrom, latestScoresFrom, caseFileFrom, RESEARCH_DATE };