@bongos/core 1.23.22 → 1.24.1

package/modules/lifecycle/task-needs-gate.js

@@ -0,0 +1,70 @@
+// taskNeedsFailures — the claim-time half of "a task says what it needs" (task
+// 1004950, ADR 0395). The goalMembershipFailures / relevanceFrictionFailures
+// shape: one DB-read check called from all THREE claim surfaces in db-claims.js
+// (claimTask, claimTasksBatch, validateClaimBatch), so no surface can advertise
+// or take a claim another refuses.
+//
+// Only `server` refuses. `owner` work is claimable — by the owner, the one person
+// the feed shows it to; refusing it here would also refuse the owner's own agent
+// session, which is how the owner does that work. The feed is where `owner`
+// narrows (db-tasks.listClaimableTasks).
+//
+// `client` is the caller's open txn client (claimTask) or the pool itself (the
+// read-only dry run). Capabilities are resolved fresh, once per call, through the
+// doorway — never from the request body (ADR 0016). Returns [{ task_id, refusal }].
+
+'use strict';
+
+const api = require('../../src/module-api');
+
+async function taskNeedsFailures({ client, tasks, builderId, deps = {} }) {
+  const ids = (tasks || []).map((t) => Number(t.id)).filter((n) => Number.isFinite(n));
+  if (ids.length === 0) return [];
+  const { rows } = await client.query(
+    `SELECT id, needs FROM tasks WHERE id = ANY($1::bigint[]) AND cardinality(needs) > 0`,
+    [ids]
+  );
+  if (rows.length === 0) return [];
+  const needsApi = api.taskNeeds;
+  const capabilities = await (deps.resolveCapabilities || needsApi.resolveCapabilities)(builderId);
+  const failures = [];
+  for (const r of rows) {
+    const refused = needsApi.claimRefusalNeeds(r.needs, capabilities);
+    if (refused.length === 0) continue;
+    failures.push({
+      task_id: Number(r.id),
+      refusal: {
+        code: 'NEEDS_SERVER_ACCESS',
+        message: needsApi.SERVER_REFUSAL_MESSAGE,
+        needs: refused,
+      },
+    });
+  }
+  return failures;
+}
+
+// --- The two list filters (task 1004950), here so db-tasks.js stays under its cap.
+
+// needsFilterWhere — the board's ?needs= filter: one need, or 'none' for work that
+// needs nothing beyond the build loop. A filter on what a list shows, never a
+// narrowing of what anyone may read. Pushes its param; returns the clause or null.
+function needsFilterWhere(needs, alias, params) {
+  const col = alias ? `${alias}.needs` : 'needs';
+  if (needs === 'none') return `cardinality(${col}) = 0`;
+  if (!needs) return null;
+  params.push(needs); // @> so tasks_needs_idx (core_285) serves it
+  return `${col} @> ARRAY[$${params.length}]::text[]`;
+}
+
+// capabilityFeedWhere — the RECOMMEND rule (ADR 0395): a task's needs must be a
+// subset of the viewer's capabilities, resolved fresh. The autonomous/parallel
+// runner is an agent working alone, so it never holds `owner` whoever it runs as —
+// an agent cannot make the owner's decision. Pushes its param; returns the clause.
+async function capabilityFeedWhere(builderId, fit, alias, params, deps = {}) {
+  const capabilities = await (deps.resolveCapabilities || api.taskNeeds.resolveCapabilities)(builderId);
+  const unattended = fit === 'autonomous' || fit === 'parallel';
+  params.push(unattended ? capabilities.filter((c) => c !== 'owner') : capabilities);
+  return api.taskNeeds.feedNeedsClause(alias, `$${params.length}`);
+}
+
+module.exports = { taskNeedsFailures, needsFilterWhere, capabilityFeedWhere };

package/modules/market-watch/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

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 };