@bongos/core 1.23.21 → 1.24.1

package/modules/market-watch/db.js

@@ -0,0 +1,340 @@
+'use strict';
+
+// modules/market-watch/db.js — the read queries behind the Market Watch screens (task
+// 1004936, goal 1000137). The pages (tasks 1004938–1004941) and the weekly run (task
+// 1004937) read through these. The weekly run's own bookkeeping (its run row, its lease,
+// the item results it writes) is in store.js; nothing else spells a market_watch_* query.
+//
+// Every read takes a pool and the project key (seed.js projectKey: the instance's public
+// origin) and filters on it, so one project can never read another's rows, even on a
+// shared database.
+//
+// DERIVED, NOT STORED. The screens show an item's level and streak, a sparkline per
+// dimension, this month's spend and when the next run is due. None of those is a column:
+// each is computed here from the runs, entries and snapshots, by a pure function below
+// that is tested without a database. A stored copy would be a second number to keep true.
+//
+//   - a run's number ("run 8") counts the runs that RAN (done or partial), oldest first;
+//     a skipped or failed run is a dash on the settings strip and takes no number.
+//   - an item's level is the number of numbered runs that found something on it (at
+//     least 1 once it is tracked); its streak is how many of the latest numbered runs in a
+//     row did.
+//   - a dimension's sparkline has one point per numbered run the item was scored in;
+//     a dimension that run did not score is null, never a carried-forward value.
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const RAN = new Set(['done', 'partial']);
+const CADENCE_DAYS = Object.freeze({ weekly: 7, biweekly: 14, monthly: 30 });
+// The settings an unconfigured project reads: the watch is off until an owner turns it on.
+const DEFAULT_SETTINGS = Object.freeze({ enabled: false, monthly_cap_usd: 20, cadence: 'weekly', configured: false });
+
+function need(project) {
+  if (typeof project !== 'string' || !project) throw new Error('market-watch db: a project key is required');
+  return project;
+}
+const num = (v) => (v == null ? null : Number(v));
+
+// ---- pure helpers ---------------------------------------------------------
+
+// numberRuns(runs) — runs in any order → the same rows, oldest first, each with `n` (its
+// run number) when it ran and null when it did not.
+function numberRuns(runs) {
+  const sorted = [...runs].sort((a, b) => (new Date(a.created_at) - new Date(b.created_at)) || (Number(a.id) - Number(b.id)));
+  let n = 0;
+  return sorted.map((r) => ({ ...r, n: RAN.has(r.status) ? ++n : null }));
+}
+
+// progress(numberedRuns, runIdsWithFindings) → { level, streak } for one item.
+function progress(numbered, foundIn) {
+  const found = new Set([...foundIn].map(String));
+  const ran = numbered.filter((r) => r.n != null);
+  const level = Math.max(1, ran.filter((r) => found.has(String(r.id))).length);
+  let streak = 0;
+  for (let i = ran.length - 1; i >= 0 && found.has(String(ran[i].id)); i -= 1) streak += 1;
+  return { level, streak };
+}
+
+// sparklines(rows, numberedRuns) → { runs: [{ id, n, date }], series: { <dim>: [v|null] } }
+// rows: { run_id, dimension, value }. Points are the numbered runs that scored the item.
+function sparklines(rows, numbered) {
+  const scoredIn = new Set(rows.map((r) => String(r.run_id)));
+  const runs = numbered.filter((r) => r.n != null && scoredIn.has(String(r.id)))
+    .map((r) => ({ id: Number(r.id), n: r.n, date: r.created_at }));
+  const at = new Map(runs.map((r, i) => [String(r.id), i]));
+  const series = {};
+  for (const r of rows) {
+    const i = at.get(String(r.run_id));
+    if (i === undefined) continue;
+    if (!series[r.dimension]) series[r.dimension] = runs.map(() => null);
+    series[r.dimension][i] = num(r.value);
+  }
+  return { runs, series };
+}
+
+// weekStreak(asks, answeredAskIds) — asks newest first, each { id, open }. How many asks
+// in a row the member answered, counting back from the newest. An open ask they have not
+// answered yet does not break the streak: they still can.
+function weekStreak(asks, answered) {
+  const a = new Set([...answered].map(String));
+  let streak = 0;
+  for (let i = 0; i < asks.length; i += 1) {
+    if (a.has(String(asks[i].id))) { streak += 1; continue; }
+    if (i === 0 && asks[i].open) continue;
+    break;
+  }
+  return streak;
+}
+
+// monthBounds(now) → [start, end) of now's calendar month in UTC: the cap's window.
+function monthBounds(now = new Date()) {
+  const d = new Date(now);
+  return [new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1)), new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1))];
+}
+
+// nextRunDue(lastRunAt, cadence) → Date | null. null: no run yet, so one is due now.
+function nextRunDue(lastRunAt, cadence) {
+  const days = CADENCE_DAYS[cadence];
+  if (!days) throw new Error(`market-watch: unknown cadence ${cadence}`);
+  if (!lastRunAt) return null;
+  return new Date(new Date(lastRunAt).getTime() + days * DAY_MS);
+}
+
+// ---- reads ----------------------------------------------------------------
+
+const RUNS_SQL = `SELECT id, status, reason, trigger, created_at, started_at, finished_at
+                    FROM market_watch_runs WHERE project = $1`;
+
+async function numberedRuns(pool, { project }) {
+  const { rows } = await pool.query(RUNS_SQL, [need(project)]);
+  return numberRuns(rows);
+}
+
+const ITEMS_SQL = `
+  SELECT i.id, i.kind, i.name, i.url, i.category, i.description, i.why_tracked, i.facts,
+         i.status, i.added_via, i.created_at,
+         (SELECT s.value FROM market_watch_score_snapshots s
+            JOIN market_watch_runs r ON r.id = s.run_id
+           WHERE s.item_id = i.id AND s.dimension = 'overall'
+           ORDER BY r.created_at DESC, r.id DESC LIMIT 1) AS overall,
+         (SELECT max(e.found_on) FROM market_watch_log_entries e WHERE e.item_id = i.id) AS last_found_on
+    FROM market_watch_items i
+   WHERE i.project = $1
+     AND ($2::text IS NULL OR i.kind = $2)
+     AND ($3::boolean OR i.status <> 'removed')
+     AND ($4::bigint IS NULL OR i.id = $4)
+   ORDER BY i.kind, overall DESC NULLS LAST, i.name`;
+
+const FOUND_IN_SQL = `
+  SELECT DISTINCT e.item_id, e.run_id
+    FROM market_watch_log_entries e
+    JOIN market_watch_items i ON i.id = e.item_id
+   WHERE i.project = $1 AND e.run_id IS NOT NULL AND ($2::bigint IS NULL OR e.item_id = $2)`;
+
+// listItems — the home desk: every tracked item with its latest overall score, last
+// finding, level and streak.
+async function listItems(pool, { project, kind = null, includeRemoved = false, id = null } = {}) {
+  need(project);
+  const [{ rows: items }, { rows: found }, runs] = await Promise.all([
+    pool.query(ITEMS_SQL, [project, kind, includeRemoved, id]),
+    pool.query(FOUND_IN_SQL, [project, id]),
+    numberedRuns(pool, { project }),
+  ]);
+  const byItem = new Map();
+  for (const f of found) {
+    const k = String(f.item_id);
+    if (!byItem.has(k)) byItem.set(k, []);
+    byItem.get(k).push(f.run_id);
+  }
+  return items.map((it) => ({
+    ...it,
+    id: Number(it.id),
+    overall: num(it.overall),
+    ...progress(runs, byItem.get(String(it.id)) || []),
+  }));
+}
+
+// getItem — one item, with removed ones included (its page still opens).
+async function getItem(pool, { project, id }) {
+  const rows = await listItems(pool, { project, includeRemoved: true, id });
+  return rows[0] || null;
+}
+
+const CASE_FILE_SQL = `
+  SELECT e.id, e.run_id, e.type, e.found_on, e.takeaway, e.dimension, e.source_url,
+         e.source_label, e.confidence, e.pinned, e.created_at
+    FROM market_watch_log_entries e
+    JOIN market_watch_items i ON i.id = e.item_id
+   WHERE i.project = $1 AND e.item_id = $2
+   ORDER BY e.pinned DESC, e.found_on DESC, e.id DESC`;
+
+// caseFile — the item page's sortable table: found, run, type, takeaway, confidence, source.
+async function caseFile(pool, { project, itemId }) {
+  need(project);
+  const [{ rows }, runs] = await Promise.all([
+    pool.query(CASE_FILE_SQL, [project, itemId]),
+    numberedRuns(pool, { project }),
+  ]);
+  const runN = new Map(runs.map((r) => [String(r.id), r.n]));
+  return rows.map((e) => ({ ...e, id: Number(e.id), run: e.run_id == null ? null : runN.get(String(e.run_id)) ?? null }));
+}
+
+const SCORES_SQL = `
+  SELECT s.run_id, s.dimension, s.value
+    FROM market_watch_score_snapshots s
+    JOIN market_watch_items i ON i.id = s.item_id
+   WHERE i.project = $1 AND s.item_id = $2`;
+
+// scoreHistory — the item page's sparklines, one per dimension plus 'overall'.
+async function scoreHistory(pool, { project, itemId }) {
+  need(project);
+  const [{ rows }, runs] = await Promise.all([
+    pool.query(SCORES_SQL, [project, itemId]),
+    numberedRuns(pool, { project }),
+  ]);
+  return sparklines(rows, runs);
+}
+
+const RULES_SQL = `
+  SELECT id, version, status, search_queries, sources, rubric, instructions, summary, reason,
+         author_id, approved_by, approved_at, created_at
+    FROM market_watch_rule_versions WHERE project = $1 ORDER BY version`;
+
+// rules — the rules page: every version for the slider, the one in use, and the proposed next.
+async function rules(pool, { project }) {
+  const { rows } = await pool.query(RULES_SQL, [need(project)]);
+  const versions = rows.map((r) => ({ ...r, id: Number(r.id) }));
+  return {
+    versions,
+    active: versions.find((v) => v.status === 'active') || null,
+    proposed: versions.find((v) => v.status === 'proposed') || null,
+  };
+}
+
+const PROPOSALS_SQL = `
+  SELECT id, kind, origin, item_id, log_entry_id, rule_version_id, answer_id, payload, reason,
+         proposed_by, status, decided_by, decided_at, created_at
+    FROM market_watch_proposals
+   WHERE project = $1 AND ($2::text IS NULL OR status = $2) AND ($3::bigint IS NULL OR item_id = $3)
+   ORDER BY created_at DESC, id DESC
+   LIMIT $4`;
+
+// proposals — the government's queue (open by default), or one item's.
+async function proposals(pool, { project, status = 'open', itemId = null, limit = 100 } = {}) {
+  const { rows } = await pool.query(PROPOSALS_SQL, [need(project), status, itemId, limit]);
+  return rows.map((p) => ({ ...p, id: Number(p.id) }));
+}
+
+const WEEK_ASKS_SQL = `
+  SELECT a.id, a.week_of, a.question_key, a.prompt, a.options, a.closes_at,
+         COALESCE(json_agg(json_build_object('choice', t.choice, 'taps', t.n) ORDER BY t.n DESC, t.choice)
+                    FILTER (WHERE t.choice IS NOT NULL), '[]'::json) AS tallies
+    FROM market_watch_weekly_asks a
+    LEFT JOIN (SELECT ask_id, choice, count(*)::int AS n FROM market_watch_ask_answers GROUP BY ask_id, choice) t
+      ON t.ask_id = a.id
+   WHERE a.project = $1 AND a.week_of = $2
+   GROUP BY a.id
+   ORDER BY a.question_key`;
+
+// weeklyAsk — the week's card: its questions, their chips, and how many tapped each.
+async function weeklyAsk(pool, { project, weekOf }) {
+  const { rows } = await pool.query(WEEK_ASKS_SQL, [need(project), weekOf]);
+  return rows.map((a) => ({ ...a, id: Number(a.id) }));
+}
+
+const ASK_HISTORY_SQL = `
+  SELECT a.id, a.week_of, (a.closes_at IS NULL OR a.closes_at > $3) AS open,
+         EXISTS (SELECT 1 FROM market_watch_ask_answers x WHERE x.ask_id = a.id AND x.builder_id = $2) AS answered
+    FROM market_watch_weekly_asks a
+   WHERE a.project = $1
+   ORDER BY a.week_of DESC, a.id DESC`;
+
+// askStreak — the card's "4 weeks in a row" for one member. A week counts once however
+// many of its questions they answered.
+async function askStreak(pool, { project, builderId, now = new Date() }) {
+  const { rows } = await pool.query(ASK_HISTORY_SQL, [need(project), builderId, now]);
+  const weeks = [];
+  const byWeek = new Map();
+  for (const r of rows) {
+    const k = String(r.week_of instanceof Date ? r.week_of.toISOString().slice(0, 10) : r.week_of);
+    if (!byWeek.has(k)) { byWeek.set(k, { id: k, open: false, answered: false }); weeks.push(byWeek.get(k)); }
+    const w = byWeek.get(k);
+    w.open = w.open || r.open === true;
+    w.answered = w.answered || r.answered === true;
+  }
+  return weekStreak(weeks, weeks.filter((w) => w.answered).map((w) => w.id));
+}
+
+const SETTINGS_SQL = `SELECT enabled, monthly_cap_usd, cadence, updated_by, updated_at
+                        FROM market_watch_settings WHERE project = $1`;
+const MONTH_SPEND_SQL = `
+  SELECT COALESCE(sum(ri.cost_usd), 0) AS spent
+    FROM market_watch_run_items ri
+    JOIN market_watch_runs r ON r.id = ri.run_id
+   WHERE r.project = $1 AND ri.finished_at >= $2 AND ri.finished_at < $3`;
+const RECENT_RUNS_SQL = `
+  SELECT r.id, r.status, r.reason, r.trigger, r.created_at, r.started_at, r.finished_at,
+         COALESCE(sum(ri.cost_usd), 0) AS cost_usd,
+         count(ri.item_id)::int AS items_total,
+         (count(ri.item_id) FILTER (WHERE ri.status = 'done'))::int AS items_done
+    FROM market_watch_runs r
+    LEFT JOIN market_watch_run_items ri ON ri.run_id = r.id
+   WHERE r.project = $1 AND r.trigger <> 'seed'
+   GROUP BY r.id
+   ORDER BY r.created_at DESC, r.id DESC
+   LIMIT $2`;
+
+// monthSpend — what Market Watch spent this calendar month (UTC), from the per-item costs.
+async function monthSpend(pool, { project, now = new Date() }) {
+  const [start, end] = monthBounds(now);
+  const { rows: [r] } = await pool.query(MONTH_SPEND_SQL, [need(project), start, end]);
+  return Number(r.spent);
+}
+
+// settingsView — the fuel gauge: the switch, cap, cadence, this month's spend, the strip
+// of recent runs (a skipped run is a row with its reason) and when the next one is due.
+async function settingsView(pool, { project, now = new Date(), recent = 8 } = {}) {
+  need(project);
+  const [{ rows: [s] }, spent, { rows: runs }] = await Promise.all([
+    pool.query(SETTINGS_SQL, [project]),
+    monthSpend(pool, { project, now }),
+    pool.query(RECENT_RUNS_SQL, [project, recent]),
+  ]);
+  const settings = s
+    ? { enabled: s.enabled, monthly_cap_usd: Number(s.monthly_cap_usd), cadence: s.cadence, configured: true, updated_by: s.updated_by, updated_at: s.updated_at }
+    : { ...DEFAULT_SETTINGS };
+  const recentRuns = runs.map((r) => ({ ...r, id: Number(r.id), cost_usd: Number(r.cost_usd) }));
+  return {
+    settings,
+    spentThisMonthUsd: spent,
+    recentRuns,
+    nextRunDue: nextRunDue(recentRuns[0] ? recentRuns[0].created_at : null, settings.cadence),
+  };
+}
+
+const REMAINING_SQL = `
+  SELECT i.id, i.project, i.kind, i.name, i.url, i.description, i.why_tracked
+    FROM market_watch_items i
+    JOIN market_watch_runs r ON r.id = $2 AND r.project = i.project
+   WHERE i.project = $1 AND i.status = 'active'
+     AND NOT EXISTS (SELECT 1 FROM market_watch_run_items ri
+                      WHERE ri.run_id = r.id AND ri.item_id = i.id AND ri.status IN ('done', 'error'))
+   ORDER BY i.id`;
+
+// remainingItems — what a (resumed) run still has to do: the project's active items with
+// no finished row in this run. An item already done is never returned, so it is never
+// researched, or charged, twice (ADR 0393 §2). An item that ERRORED is finished too: the
+// model ran and was paid for (task 1004937), so a resume does not buy it a second call.
+// Each row carries its project, so the run can refuse one that is not its own.
+async function remainingItems(pool, { project, runId }) {
+  const { rows } = await pool.query(REMAINING_SQL, [need(project), runId]);
+  return rows.map((r) => ({ ...r, id: Number(r.id) }));
+}
+
+module.exports = {
+  // reads
+  numberedRuns, listItems, getItem, caseFile, scoreHistory, rules, proposals,
+  weeklyAsk, askStreak, monthSpend, settingsView, remainingItems,
+  // pure
+  numberRuns, progress, sparklines, weekStreak, monthBounds, nextRunDue,
+  CADENCE_DAYS, DEFAULT_SETTINGS,
+};

package/modules/market-watch/key.js

@@ -0,0 +1,58 @@
+'use strict';
+
+// modules/market-watch/key.js — the project's own Anthropic key (task 1004937, ADR 0394 §1).
+//
+// The weekly run calls the Messages API on the PROJECT's key, never on ours and never on a
+// builder's: the project's account pays the provider directly, and Bongos holds no money
+// (ADR 0385). The owner pastes it into Market Watch settings (the page is task 1004938);
+// it is stored encrypted with the kernel secret box, exactly as ai-studio stores a
+// builder's provider keys (task 1004919): a "v1.<iv>.<tag>.<ct>" blob plus the last four
+// characters, which are all the page ever shows.
+//
+// THE ONE ACCESSOR. readProjectKey is the only function that turns the blob back into a
+// key, and only the run calls it, right before it builds the client. It never logs the
+// key, never returns it to a route, and answers null (not a throw) for "no usable key":
+// a missing row, an empty column, or a blob the master key cannot open. The run turns
+// that null into a skipped run with reason 'no_key', visible on the settings strip.
+//
+// sealProjectKey is the writer's half, here so the settings route (task 1004938) stores
+// exactly the shape this file reads. Pure apart from the injected encrypt/decrypt, so a
+// test runs it with no master key and no database.
+
+const MIN_KEY = 16;
+const MAX_KEY = 512;
+
+const KEY_SQL = `SELECT anthropic_key_enc FROM market_watch_settings WHERE project = $1`;
+
+function defaultBox() {
+  return require('../../src/module-api').secretBox;
+}
+
+// sealProjectKey(raw, { encrypt }) → { key_enc, last4 } | { error }. Never echoes the key.
+function sealProjectKey(raw, { encrypt } = {}) {
+  if (typeof raw !== 'string') return { error: 'key_required' };
+  const key = raw.trim();
+  if (!key) return { error: 'key_required' };
+  if (key.length < MIN_KEY || key.length > MAX_KEY) return { error: 'key_wrong_length' };
+  if (/\s/.test(key)) return { error: 'key_has_spaces' };
+  const enc = (encrypt || ((s) => defaultBox().encrypt(s)))(key);
+  return { key_enc: enc, last4: key.slice(-4) };
+}
+
+// readProjectKey(pool, project, { decrypt }) → the plaintext key, or null.
+// Fails closed to null: no key means no run, never a run on some other key.
+async function readProjectKey(pool, project, { decrypt } = {}) {
+  if (typeof project !== 'string' || !project) return null;
+  const { rows } = await pool.query(KEY_SQL, [project]);
+  const blob = rows[0] && rows[0].anthropic_key_enc;
+  if (typeof blob !== 'string' || !blob) return null;
+  try {
+    const key = (decrypt || ((b) => defaultBox().decrypt(b)))(blob);
+    return typeof key === 'string' && key.trim() ? key.trim() : null;
+  } catch (_) {
+    // A wrong or missing master key, or a tampered blob. Not a key we can use.
+    return null;
+  }
+}
+
+module.exports = { readProjectKey, sealProjectKey, KEY_SQL };

package/modules/market-watch/migrations/market_watch_001_tables.sql

@@ -0,0 +1,249 @@
+-- market_watch_001_tables.sql - the Market Watch data model (task 1004936, goal 1000137).
+--
+-- What the owner-approved screens (docs/design/mocks/market-watch/) and the run model of
+-- ADR 0393 need stored. Everything else they show is DERIVED in modules/market-watch/db.js
+-- (an item's level and streak, a dimension's sparkline, this month's spend), so there is
+-- one source for each number and nothing to keep in step.
+--
+--   market_watch_settings        one row per project: on/off, the monthly AI cap, cadence
+--   market_watch_rule_versions   the watch rules as versioned rows; 'proposed' is the next one
+--   market_watch_items           what is watched: competitor | partner | topic
+--   market_watch_runs            one row per run, including skipped ones (ADR 0393 s3-4)
+--   market_watch_run_items       per-item progress inside a run: what makes a cut-off run
+--                                resumable without charging an item twice (ADR 0393 s2)
+--   market_watch_log_entries     the case file: found, run, type, takeaway, confidence, source
+--   market_watch_score_snapshots one value per item, dimension and run: the sparklines
+--   market_watch_weekly_asks     the weekly question to every member
+--   market_watch_ask_answers     each member's taps on it
+--   market_watch_proposals       a change asked for by a member or born of a weekly-ask tap
+--
+-- PROJECT. Every project is its own instance with its own database (ADR 0393 Context), so a
+-- row's `project` is that instance's public origin, read from branding at write time and
+-- never hardcoded. It is still a column so a read can never mix two projects if a database
+-- is ever shared, and so the hub can tell its own seed rows from anything else.
+--
+-- PEOPLE. A person is a builders(id). Seeded rows have no author (NULL): the 2026-10-28
+-- research was not a member's act, and naming someone here would be inventing a record.
+--
+-- Additive and market_watch_-prefixed (ADR 0083 s5, fitness checkModuleMigrationsAdditive).
+-- Idempotent: every statement survives a re-run on a database that already has it.
+
+BEGIN;
+
+-- The project's switch, cap and cadence (the settings screen). `enabled` is the owner's
+-- watch switch, distinct from the module being enabled: the module can be on with the
+-- watch paused. The cap is in US dollars, like cost_log.
+CREATE TABLE IF NOT EXISTS market_watch_settings (
+  project           text PRIMARY KEY,
+  enabled           boolean     NOT NULL DEFAULT false,
+  monthly_cap_usd   numeric(10,2) NOT NULL DEFAULT 20 CHECK (monthly_cap_usd >= 0),
+  cadence           text        NOT NULL DEFAULT 'weekly'
+                    CHECK (cadence IN ('weekly', 'biweekly', 'monthly')),
+  updated_by        bigint      REFERENCES builders(id),
+  updated_at        timestamptz NOT NULL DEFAULT now()
+);
+
+-- The watch rules. One row per version; the rules page's slider walks them by `version`.
+-- Exactly one 'active' version per project (the rules in use) and at most one 'proposed'
+-- (the next one), each held by a partial unique index rather than by every writer's care.
+-- rubric is { "<kind>": [ { "key", "label", "definition", "weight" } ] }: competitors and
+-- partners are scored on different dimensions.
+CREATE TABLE IF NOT EXISTS market_watch_rule_versions (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  version           integer     NOT NULL CHECK (version >= 1),
+  status            text        NOT NULL DEFAULT 'proposed'
+                    CHECK (status IN ('proposed', 'active', 'superseded', 'rejected')),
+  search_queries    jsonb       NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(search_queries) = 'array'),
+  sources           jsonb       NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(sources) = 'array'),
+  rubric            jsonb       NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(rubric) = 'object'),
+  instructions      text        NOT NULL DEFAULT '',
+  summary           text        NOT NULL DEFAULT '',          -- the slider's one line ("+ GitHub releases as a source")
+  reason            text        NOT NULL CHECK (length(btrim(reason)) > 0),
+  author_id         bigint      REFERENCES builders(id),      -- NULL: seeded, not a member's act
+  approved_by       bigint      REFERENCES builders(id),
+  approved_at       timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (project, version)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_rule_versions_one_active
+  ON market_watch_rule_versions (project) WHERE status = 'active';
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_rule_versions_one_proposed
+  ON market_watch_rule_versions (project) WHERE status = 'proposed';
+
+-- What is watched. Keyed by (project, kind, url, name): the research scored five names both as
+-- a competitor and as a partner, on different rubrics, so they are two items. Removing an
+-- item is status 'removed', never a DELETE: its log and scores stay readable, and a re-run
+-- of the seed cannot bring it back (ON CONFLICT DO NOTHING finds the removed row).
+CREATE TABLE IF NOT EXISTS market_watch_items (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  kind              text        NOT NULL CHECK (kind IN ('competitor', 'partner', 'topic')),
+  name              text        NOT NULL CHECK (length(btrim(name)) > 0),
+  url               text        NOT NULL,                     -- a topic has none: ''
+  category          text        NOT NULL DEFAULT '',
+  description       text        NOT NULL DEFAULT '',          -- "what it is", one line
+  why_tracked       text        NOT NULL DEFAULT '',
+  facts             jsonb       NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(facts) = 'object'),
+  status            text        NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'paused', 'removed')),
+  added_via         text        NOT NULL DEFAULT 'member'
+                    CHECK (added_via IN ('seed', 'member', 'proposal', 'run')),
+  added_by          bigint      REFERENCES builders(id),
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (project, kind, url, name)
+);
+CREATE INDEX IF NOT EXISTS market_watch_items_project_status
+  ON market_watch_items (project, status, kind);
+
+-- One row per run, INCLUDING the runs that never started: a skipped run is a row with a
+-- reason, never only a log line (ADR 0393 "What R04 must build" s4). The settings strip
+-- reads these, and a dash there is a 'skipped' row.
+--   status:  queued -> running -> done | partial | skipped | failed
+--   reason:  why a run is partial, skipped or failed (NULL when done)
+--   trigger: 'poller' (the weekly clock), 'manual' (an owner's "run now"), 'seed' (the
+--            2026-10-28 research loaded as run zero, so seeded scores carry a run id)
+-- claimed_until is the single-flight lease: the poller takes a run with
+-- UPDATE ... WHERE status IN ('queued','running') AND claimed_until < now() RETURNING, so a
+-- second process on the same database cannot run it too, and a run whose process died
+-- mid-way is picked up again once its lease lapses.
+CREATE TABLE IF NOT EXISTS market_watch_runs (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  status            text        NOT NULL DEFAULT 'queued'
+                    CHECK (status IN ('queued', 'running', 'done', 'partial', 'skipped', 'failed')),
+  reason            text        CHECK (reason IS NULL OR reason IN
+                    ('off', 'no_key', 'cap_reached', 'spend_unreadable', 'timeout', 'error')),
+  trigger           text        NOT NULL DEFAULT 'poller' CHECK (trigger IN ('poller', 'manual', 'seed')),
+  rule_version_id   bigint      REFERENCES market_watch_rule_versions(id),
+  cap_usd           numeric(10,2),                            -- the cap as it stood when the run was planned
+  spent_before_usd  numeric(10,4),                            -- this month's spend read before the run
+  claimed_until     timestamptz,
+  started_at        timestamptz,
+  finished_at       timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  CHECK (status NOT IN ('skipped', 'partial', 'failed') OR reason IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS market_watch_runs_project_created
+  ON market_watch_runs (project, created_at DESC);
+-- The 2026-10-28 research is ONE run per project: what makes the seed idempotent.
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_runs_one_seed
+  ON market_watch_runs (project) WHERE trigger = 'seed';
+
+-- Per-item progress inside a run (ADR 0393 s2, "resumable"). One row per (run, item),
+-- written as each item finishes. A resumed run does only the rows that are not 'done',
+-- and an item's cost is recorded here once: cost_usd is set in the same statement that
+-- moves the row to 'done', so a retry finds it done and never prices it again. The
+-- cost_log projection (source market-watch:<run id>) keys on (run, item) for the same
+-- reason.
+CREATE TABLE IF NOT EXISTS market_watch_run_items (
+  run_id            bigint      NOT NULL REFERENCES market_watch_runs(id),
+  item_id           bigint      NOT NULL REFERENCES market_watch_items(id),
+  status            text        NOT NULL DEFAULT 'pending'
+                    CHECK (status IN ('pending', 'running', 'done', 'error', 'skipped')),
+  error             text,                                     -- refusal | max_tokens | tool_error | ... (ADR 0393 s1)
+  cost_usd          numeric(10,4) CHECK (cost_usd IS NULL OR cost_usd >= 0),
+  started_at        timestamptz,
+  finished_at       timestamptz,
+  PRIMARY KEY (run_id, item_id),
+  CHECK (status <> 'done' OR cost_usd IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS market_watch_run_items_open
+  ON market_watch_run_items (run_id) WHERE status <> 'done';
+
+-- The case file. confidence is 1 (low) ... 3 (high), the mock's three dots. source_url is
+-- required: an entry without a source is not an entry (ADR 0393 s1 drops them in code;
+-- this is the floor no future writer can step under). One takeaway per item and run is
+-- stored once, so a resumed run that rewrites an item's findings cannot duplicate them.
+CREATE TABLE IF NOT EXISTS market_watch_log_entries (
+  id                bigserial PRIMARY KEY,
+  item_id           bigint      NOT NULL REFERENCES market_watch_items(id),
+  run_id            bigint      REFERENCES market_watch_runs(id),
+  type              text        NOT NULL CHECK (type IN ('insight', 'news', 'datapoint')),
+  found_on          date        NOT NULL DEFAULT current_date,
+  takeaway          text        NOT NULL CHECK (length(btrim(takeaway)) > 0),
+  dimension         text,                                     -- the rubric key it bears on, if any
+  source_url        text        NOT NULL CHECK (source_url ~ '^https?://'),
+  source_label      text        NOT NULL DEFAULT '',
+  confidence        smallint    NOT NULL CHECK (confidence BETWEEN 1 AND 3),
+  pinned            boolean     NOT NULL DEFAULT false,
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_log_entries_once
+  ON market_watch_log_entries (item_id, run_id, md5(takeaway));
+CREATE INDEX IF NOT EXISTS market_watch_log_entries_item
+  ON market_watch_log_entries (item_id, found_on DESC, id DESC);
+
+-- Scores over time: one value per (item, dimension, run). 'overall' is a dimension like
+-- the others, so the likeness line and the five dimension lines are one query.
+CREATE TABLE IF NOT EXISTS market_watch_score_snapshots (
+  id                bigserial PRIMARY KEY,
+  item_id           bigint      NOT NULL REFERENCES market_watch_items(id),
+  run_id            bigint      NOT NULL REFERENCES market_watch_runs(id),
+  dimension         text        NOT NULL CHECK (length(btrim(dimension)) > 0),
+  value             numeric(4,1) NOT NULL CHECK (value BETWEEN 0 AND 10),
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (item_id, run_id, dimension)
+);
+
+-- The weekly question. question_key names which of the card's questions this is
+-- ('rival' = what counts as a competitor, 'watch' = what else should we watch); options
+-- are the chips, each { "label", "example" }.
+CREATE TABLE IF NOT EXISTS market_watch_weekly_asks (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  week_of           date        NOT NULL,
+  question_key      text        NOT NULL CHECK (length(btrim(question_key)) > 0),
+  prompt            text        NOT NULL CHECK (length(btrim(prompt)) > 0),
+  options           jsonb       NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(options) = 'array'),
+  closes_at         timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (project, week_of, question_key)
+);
+
+-- A member's taps. A chip is a `choice`; "name one" and "add a topic" carry free_text.
+-- One row per member and choice, so a second tap on the same chip is a no-op.
+CREATE TABLE IF NOT EXISTS market_watch_ask_answers (
+  id                bigserial PRIMARY KEY,
+  ask_id            bigint      NOT NULL REFERENCES market_watch_weekly_asks(id),
+  builder_id        bigint      NOT NULL REFERENCES builders(id),
+  choice            text        NOT NULL CHECK (length(btrim(choice)) > 0),
+  free_text         text,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (ask_id, builder_id, choice)
+);
+
+-- A change someone asked for. origin 'member' is the item page's "Propose a change" or
+-- the rules page; 'weekly_ask' is born of a tap (answer_id says which). What it changes
+-- is `kind` plus the row it points at; `payload` carries the specifics (a new score, the
+-- source to add, the corrected text, the proposed rules version's id).
+CREATE TABLE IF NOT EXISTS market_watch_proposals (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  kind              text        NOT NULL CHECK (kind IN
+                    ('rule_change', 'add_item', 'remove_item', 'rescore', 'move_kind', 'add_source', 'correct_entry')),
+  origin            text        NOT NULL CHECK (origin IN ('member', 'weekly_ask')),
+  item_id           bigint      REFERENCES market_watch_items(id),
+  log_entry_id      bigint      REFERENCES market_watch_log_entries(id),
+  rule_version_id   bigint      REFERENCES market_watch_rule_versions(id),
+  answer_id         bigint      REFERENCES market_watch_ask_answers(id),
+  payload           jsonb       NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(payload) = 'object'),
+  reason            text        NOT NULL DEFAULT '',
+  proposed_by       bigint      REFERENCES builders(id),
+  status            text        NOT NULL DEFAULT 'open'
+                    CHECK (status IN ('open', 'approved', 'rejected', 'withdrawn', 'applied')),
+  decided_by        bigint      REFERENCES builders(id),
+  decided_at        timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  CHECK (origin <> 'weekly_ask' OR answer_id IS NOT NULL),
+  CHECK (kind <> 'rule_change' OR rule_version_id IS NOT NULL),
+  CHECK (kind NOT IN ('remove_item', 'rescore', 'move_kind', 'add_source') OR item_id IS NOT NULL),
+  CHECK (kind <> 'correct_entry' OR log_entry_id IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS market_watch_proposals_open
+  ON market_watch_proposals (project, created_at DESC) WHERE status = 'open';
+-- One tap is one proposal: re-pooling the answers is a no-op.
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_proposals_one_per_answer
+  ON market_watch_proposals (answer_id) WHERE answer_id IS NOT NULL;
+
+COMMIT;