@bongos/core 1.23.22 → 1.24.2

package/modules/lifecycle/routes/task-write-routes.js

@@ -26,7 +26,7 @@ const { buildDependencyAdvisory } = require('../dependency-advisory');
 const { classifyTaskKind, VALID_KINDS, WRITABLE_DISCIPLINES, resolveWriteDiscipline, VOTABLE_TASK_STATUSES, TASK_FIELD_BOUNDS } = require('../task-classifier');
 const { isModuleKey, moduleKeys } = api.moduleScopeMap;
 const { validateOrRespond, LIMITS, parseId } = api;
-const { badKind, detectsMigration } = require('./task-route-helpers.js');
+const { badKind, badNeeds, detectsMigration } = require('./task-route-helpers.js');
 const { describeCheckViolation } = require('../pg-constraint-fail.js');
 const { goalNotOpenRefusal } = require('./goal-route-authz.js');
 const { resolveUpkeepHome, isUpkeepFiling, UPKEEP_HINT } = require('../upkeep-home.js'); // task 1004597
@@ -62,6 +62,7 @@ module.exports = function registerTaskWriteRoutes(router) {
       newcomer_friendly: { type: 'boolean' },  // V3.R15 #239 — Xenos-claimable flag
       security_sensitive: { type: 'boolean' },  // task 990 — Archon-only ship broadcast
       requires_rank: { type: 'string', maxLength: 16 },  // task 1498 / ADR 0084 — per-task rank floor (auto-derived; explicit value can only raise it)
+      needs: {},  // task 1004950 / ADR 0395 — ['owner'|'server'] or a comma list; checked inline
       auto_detect_touches: { type: 'boolean' },
       // task 438: link the new task to done-when criteria at creation time. Each
       // element is a criterion_id slug (required on a multi-goal version — task
@@ -169,6 +170,9 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('bad_requires_rank', { status: 400, message: `requires_rank must be one of ${db.LIVE_RANK_LADDER.join(' | ')}. The floor auto-derives from touches + security_sensitive; an explicit value can only raise it.`, details: { valid: db.LIVE_RANK_LADDER } });
       }
     }
+    // task 1004950 / ADR 0395: what the task needs beyond the build loop.
+    const createNeeds = api.taskNeeds.normalizeNeeds(body.needs);
+    if (!createNeeds.ok) return badNeeds(res, createNeeds.bad);
     // BV1.R53 (task 1422): validate module_key against MODULE_SCOPE_MAP.
     if (body.module_key != null && !isModuleKey(body.module_key)) {
       return res.fail('bad_module_key', { status: 400, message: `module_key must be one of the known module keys, or omitted. Valid keys: ${moduleKeys().join(', ')}.`, details: { valid: moduleKeys() } });
@@ -245,6 +249,7 @@ module.exports = function registerTaskWriteRoutes(router) {
         requiresRank: body.requires_rank ?? null,
         moduleKey: body.module_key ?? null,
         goalId: body.goal_id ?? null,
+        needs: createNeeds.needs,
         // task 1003278 — attribution, from the AUTHENTICATED request, never the
         // body: who created a task is a fact about the caller, not an input.
         createdBy: req.builder.id,
@@ -348,6 +353,7 @@ module.exports = function registerTaskWriteRoutes(router) {
       xenos_claimable: { type: 'boolean' },              // pre-rename alias for newcomer_friendly
       security_sensitive: { type: 'boolean' },           // task 990 — Archon-only ship broadcast
       automation_tag: { type: 'string', maxLength: 64 },
+      needs: {},                                         // task 1004950 — ['owner'|'server'], a comma list, or null/[] to clear; checked inline
       needs_migration: { type: 'boolean' },              // task 1002648 — correct the create-time heuristic's flag (the claim-time allocator keys off it)
       // task 1002647 (map s4.3): the task body is a load-bearing builder prompt
       // and was settable only at create — no route edited it at any rank. Now
@@ -397,6 +403,7 @@ module.exports = function registerTaskWriteRoutes(router) {
     const hasParallelSafe = Object.prototype.hasOwnProperty.call(body, 'parallel_safe');
     const hasSecuritySensitive = Object.prototype.hasOwnProperty.call(body, 'security_sensitive');
     const hasAutomationTag = Object.prototype.hasOwnProperty.call(body, 'automation_tag');
+    const hasNeeds = Object.prototype.hasOwnProperty.call(body, 'needs');
     const hasNeedsMigration = Object.prototype.hasOwnProperty.call(body, 'needs_migration');
     const hasRequiresRank = Object.prototype.hasOwnProperty.call(body, 'requires_rank');
     const hasModuleKey = Object.prototype.hasOwnProperty.call(body, 'module_key');
@@ -416,8 +423,8 @@ module.exports = function registerTaskWriteRoutes(router) {
     if (Object.prototype.hasOwnProperty.call(body, 'status')) {
       return res.fail('status_not_patchable', { status: 400, message: STATUS_HINT });
     }
-    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority && !hasValueSummary) {
-      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, value_summary, priority, parallel_safe, security_sensitive, automation_tag, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
+    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeeds && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority && !hasValueSummary) {
+      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, value_summary, priority, parallel_safe, security_sensitive, automation_tag, needs, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
     }
     // ---- task 1002609 (G-22): settle EVERY gate and validation before the ----
     // ---- FIRST write. The previous shape validated-and-wrote per field in ----
@@ -476,6 +483,8 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('bad_automation_tag', { status: 400, message: 'automation_tag must be one of overnight-safe | live-only | needs-input, or null to clear', details: { valid: Array.from(VALID_AUTOMATION_TAGS) } });
       }
     }
+    const patchNeeds = hasNeeds ? api.taskNeeds.normalizeNeeds(body.needs) : null;
+    if (patchNeeds && !patchNeeds.ok) return badNeeds(res, patchNeeds.bad);
     if (hasModuleKey) {
       // BV1.R53 (task 1422): assign or clear the module affinity label. null clears.
       if (body.module_key !== null && !isModuleKey(body.module_key)) {
@@ -577,6 +586,15 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('patch_failed', { status: 500, message: 'internal error' });
       }
     }
+    if (hasNeeds) {
+      try {
+        updated = await db.updateTaskNeeds(id, patchNeeds.needs);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        log.error('[gds] PATCH /tasks/:id needs', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
     if (hasNeedsMigration) {
       try {
         updated = await db.updateTaskNeedsMigration(id, body.needs_migration);

package/modules/lifecycle/routes/tasks.js

@@ -91,7 +91,7 @@ const PUBLISH_BUNDLE_MAX_BYTES = 20 * 1024 * 1024; // 20 MB decoded bundle
 // autolinks to GitHub's own issue space (dead links for GDS task ids — task 916).
 // Mirrors ship.js sanitizeGitHubRefs (which lives in scripts/ and isn't requirable
 // here).
-const { MIGRATION_KEYWORD_RE, VALID_FITS, badKind, deHashRefs, detectsMigration, gateTaskOwnership, graderBypassEnabled, isVerifyTask, peerVoteNet, postGateAuthorTrust, rankAttestsGateTrust } = require('./task-route-helpers.js');
+const { MIGRATION_KEYWORD_RE, VALID_FITS, badKind, badNeedsFilter, parseNeedsFilter, deHashRefs, detectsMigration, gateTaskOwnership, graderBypassEnabled, isVerifyTask, peerVoteNet, postGateAuthorTrust, rankAttestsGateTrust } = require('./task-route-helpers.js');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('lifecycle');
 const registerTaskWriteRoutes = require('./task-write-routes.js'); // task 1003206 — POST /tasks + PATCH /tasks/:id
@@ -176,10 +176,11 @@ module.exports = function buildTasksRouter() {
     if (limit && limit.bad) return res.fail('bad_limit', { status: 400, message: 'limit must be a positive integer up to 1000.' });
     const offset = posInt(offsetRaw, 'bad_offset');
     if (offset && offset.bad) return res.fail('bad_offset', { status: 400, message: 'offset must be a positive integer.' });
+    const needs = parseNeedsFilter(req.query.needs); if (needs && needs.bad) return badNeedsFilter(res); // task 1004950
 
     const tasks = await db.listTasks({
       versionId: version, status, kind, discipline, goalId,
-      createdBy, staleDays, limit, offset,
+      createdBy, staleDays, limit, offset, needs,
     });
     // ?include=deps (hall redesign task 1002439) — enrich each task with its
     // dependency summary (`blocked_by[]` with per-target satisfied state, and a
@@ -216,16 +217,15 @@ module.exports = function buildTasksRouter() {
     if (claimStaleDays && claimStaleDays.bad) return res.fail('bad_stale_days', { status: 400, message: 'stale_days must be a positive integer number of days.' });
     // ?limit=N — opt-in, for a caller that renders N rows (goal 1000072). It slices the
     // RETURNED feed, never the query — lifecycle/CLAUDE.md has the why.
+    const claimNeeds = parseNeedsFilter(req.query.needs); if (claimNeeds && claimNeeds.bad) return badNeedsFilter(res); // task 1004950
     const claimLimit = posInt(req.query.limit, 'bad_limit', 1000);
     if (claimLimit && claimLimit.bad) return res.fail('bad_limit', { status: 400, message: 'limit must be a positive integer (max 1000).' });
     const [feed, active] = await Promise.all([
       db.listClaimableTasks({
-        versionId: version || null,
-        builderId: req.builder.id,
-        discipline: discipline || null,
-        fit: fit || null,
+        versionId: version || null, builderId: req.builder.id,
+        discipline: discipline || null, fit: fit || null,
         createdBy: claimCreatedBy ?? null,
-        staleDays: claimStaleDays ?? null,
+        staleDays: claimStaleDays ?? null, needs: claimNeeds ?? null,
       }),
       req.query.group === 'goal' ? [] : db.listActiveClaims(),
     ]);
@@ -507,11 +507,11 @@ module.exports = function buildTasksRouter() {
   // the numeric done_when_criteria.id, mirroring DELETE deps/:depId).
   // rank: metic+archon — removes a criterion↔task edge; task-shaping, Metic+ (ADR 0090).
   router.delete('/tasks/:id/criteria/:criterionId', auth.requireBuilder, auth.requirePermission('task.criterion.manage'), async (req, res) => {
-    const id = Number(req.params.id);
-    const criterionId = Number(req.params.criterionId);
-    if (!Number.isFinite(id) || !Number.isFinite(criterionId)) {
-      return res.fail('bad_task_id', 400);
-    }
+    // task 1004984: whole positive ids only (Number.isFinite let 7.5 through).
+    const id = parseId(req, res, { code: 'bad_task_id', positiveInt: true });
+    if (id === null) return;
+    const criterionId = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id', positiveInt: true });
+    if (criterionId === null) return;
     const removed = await db.removeTaskCriterion(id, criterionId);
     res.json({ ok: true, removed });
   });

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