@bongos/core 1.23.21 → 1.24.1

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

@@ -0,0 +1,46 @@
+-- market_watch_002_run.sql - what the weekly run needs beyond the data model (task 1004937,
+-- goal 1000137, ADR 0394).
+--
+--   1. The project's Anthropic key. ADR 0394 §1: the run calls the Messages API on the
+--      PROJECT's own key, which the owner sets in Market Watch settings. It is stored the
+--      way ai-studio stores a builder's provider keys (task 1004919): the kernel secret
+--      box's "v1.<iv>.<tag>.<ct>" blob, the master key only in server env, so a database
+--      dump decrypts nothing. last4 is what the settings page shows. modules/market-watch/
+--      key.js is the only reader, and it decrypts only inside a run.
+--   2. One open run per project. The poller creates a run with INSERT ... ON CONFLICT DO
+--      NOTHING against this index, so two processes on one database that both find the
+--      watch due cannot start two runs (ADR 0394 §2 "one run at a time").
+--   3. A run's own proposals. A 'new candidate' the run finds becomes a proposal, never a
+--      tracked item (the task's rule), and it was not a member's act nor a weekly-ask tap,
+--      so the origin enum gains 'run'. Widening a CHECK enum is the one DROP CONSTRAINT a
+--      module migration may carry (fitness isConstraintWidening): it is re-added, wider.
+--
+--   4. A score's one-line reason. The run re-scores each dimension "with a one-line
+--      reason" (the task); the reason is stored beside the value it explains.
+--
+-- Additive and idempotent, like 001.
+
+BEGIN;
+
+ALTER TABLE market_watch_settings ADD COLUMN IF NOT EXISTS anthropic_key_enc   text;
+ALTER TABLE market_watch_settings ADD COLUMN IF NOT EXISTS anthropic_key_last4 text;
+ALTER TABLE market_watch_settings ADD COLUMN IF NOT EXISTS anthropic_key_set_at timestamptz;
+ALTER TABLE market_watch_settings DROP CONSTRAINT IF EXISTS market_watch_settings_key_chk;
+ALTER TABLE market_watch_settings ADD CONSTRAINT market_watch_settings_key_chk CHECK (
+  (anthropic_key_enc IS NULL AND anthropic_key_last4 IS NULL)
+  OR (anthropic_key_enc LIKE 'v1.%' AND length(anthropic_key_last4) = 4));
+
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_runs_one_open
+  ON market_watch_runs (project) WHERE status IN ('queued', 'running');
+
+ALTER TABLE market_watch_proposals DROP CONSTRAINT IF EXISTS market_watch_proposals_origin_check;
+ALTER TABLE market_watch_proposals ADD CONSTRAINT market_watch_proposals_origin_check
+  CHECK (origin IN ('member', 'weekly_ask', 'run'));
+ALTER TABLE market_watch_proposals ADD COLUMN IF NOT EXISTS run_id bigint REFERENCES market_watch_runs(id);
+-- One proposal per candidate name per run, so a resumed run cannot propose it twice.
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_proposals_one_per_run_candidate
+  ON market_watch_proposals (run_id, lower(payload->>'name')) WHERE origin = 'run';
+
+ALTER TABLE market_watch_score_snapshots ADD COLUMN IF NOT EXISTS reason text;
+
+COMMIT;

package/modules/market-watch/module.json

@@ -0,0 +1,26 @@
+{
+  "key": "market-watch",
+  "title": "Market Watch (a weekly AI watch on a project's market)",
+  "description": "A weekly AI watch on a project's competitors, partners and topics, with a sourced log per tracked item and a weekly question to members (goal 1000137). Its data model (tables, read queries and the hub seed of the 2026-10-28 research) and its weekly run (an hourly poller that researches each tracked item on the project's own Anthropic key, under the monthly cap) are in; the pages and weekly ask are not yet, so it mounts no routes. Off by default, and it cannot be turned on behind an open join door with no payer, because every run will spend the project's AI budget.",
+  "version": "0.2.0",
+  "coreVersion": "^1.19.0",
+  "category": {
+    "parent": "knowledge"
+  },
+  "default": false,
+  "maintenance": {
+    "status": "core-maintained"
+  },
+  "contributes": {
+    "migrations": true,
+    "pollers": [
+      "hub-seed",
+      "weekly-run"
+    ]
+  },
+  "spend": {
+    "requiresPayer": true
+  },
+  "provides": [],
+  "consumes": []
+}

package/modules/market-watch/pollers/hub-seed.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// modules/market-watch/pollers/hub-seed.js — load the 2026-10-28 research into the hub's
+// Market Watch, once, shortly after boot (task 1004936).
+//
+// WHY A POLLER. The seed needs to know whether this instance IS the hub, which a SQL
+// migration cannot ask, and module migrations only apply once the module is enabled. A
+// poller runs exactly then: the loader starts it only on an instance with Market Watch
+// switched on, after migrations. It fires one time per boot; every boot after the first
+// load is a no-op by constraint (seed.js), so a redeploy on every merge costs a few
+// SELECTs and never a duplicate row. Off the hub it returns 'not_hub' and writes nothing.
+//
+// Never throws into the server: a failure logs and waits for the next boot, and a
+// database that is not reachable (a builder laptop) is a quiet no-op.
+
+const api = require('../../../src/module-api');
+const { seedHub } = require('../seed');
+
+const log = api.logger('market-watch');
+const FIRST_MS = Number(process.env.MARKET_WATCH_SEED_DELAY_MS) || 2 * 60_000;
+
+let timer = null;
+
+async function runOnce(deps = {}) {
+  try {
+    const r = await (deps.seedHub || seedHub)(deps);
+    if (r.seeded) {
+      const n = r.inserted;
+      log.info(`[hub-seed] ${r.project}: ${n.items} items, ${n.scores} scores, ${n.entries} entries, ${n.rules} rules, ${n.runs} runs inserted`);
+    } else {
+      log.info(`[hub-seed] skipped (${r.skipped})`);
+    }
+    return r;
+  } catch (e) {
+    log.warn(`[hub-seed] not loaded: ${e && e.message}`);
+    if (typeof deps.reportError === 'function') deps.reportError();
+    return { seeded: false, skipped: 'error', error: e && e.message };
+  }
+}
+
+// The loader passes its own deps plus reportError; only reportError is taken, so a
+// loader dep can never be read as a seed seam (isHub, project, pool).
+function start({ reportError } = {}) {
+  if (timer) return;
+  timer = setTimeout(() => { timer = null; runOnce({ reportError }); }, FIRST_MS);
+  if (timer.unref) timer.unref();
+}
+
+function stop() {
+  if (timer) clearTimeout(timer);
+  timer = null;
+}
+
+module.exports = { start, stop, runOnce };

package/modules/market-watch/pollers/weekly-run.js

@@ -0,0 +1,100 @@
+'use strict';
+
+// modules/market-watch/pollers/weekly-run.js — fire the weekly Market Watch run from the
+// server itself (task 1004937, ADR 0394 §2).
+//
+// A COPY OF THE daily-checks SHAPE, not an import of it (modules may not require each
+// other): one unref'd HOURLY tick, the first a few minutes after boot plus jitter,
+// kill-switched by ROUTINE_TIMERS_DISABLED=1, and it never throws into the server.
+//
+// DUE BY THE LEDGER, NOT BY THE BOOT. The hub redeploys on every merge, so a boot-anchored
+// timer would start (and charge) a run once per deploy. Each tick instead asks
+// market_watch_runs whether the newest run is a cadence old (run.js isDue), and a cut-off
+// run is resumed by whichever tick finds its lease lapsed. A deploy restarts this timer
+// and changes nothing about when the next run is due.
+//
+// The loader starts pollers only on an instance with Market Watch enabled, after its
+// migrations. A database that is not reachable (a builder laptop) is a quiet no-op.
+
+const api = require('../../../src/module-api');
+const { runDue } = require('../run');
+const { createStore } = require('../store');
+const { readProjectKey } = require('../key');
+const { projectKey } = require('../seed');
+
+const log = api.logger('market-watch');
+
+const TICK_MS = Number(process.env.MARKET_WATCH_TICK_MS) || 60 * 60_000;
+// After hub-seed's 2 minutes, so the hub's run zero is in before the first due check.
+const FIRST_MS = Number(process.env.MARKET_WATCH_FIRST_MS) || 4 * 60_000;
+const JITTER_MS = 60_000;
+
+function defaultProject() {
+  try { return projectKey(api.branding().domains.publicOrigin); } catch { return null; }
+}
+
+let running = false;
+let warnedUnreachable = false;
+
+// tick(deps) — one look at the ledger, and a run if one is due. NEVER throws.
+async function tick(deps = {}) {
+  if (running) return { skipped: 'busy' };
+  running = true;
+  try {
+    const project = deps.project !== undefined ? deps.project : defaultProject();
+    if (!project) return { skipped: 'no_project_origin' };
+    const pool = deps.pool || api.pool;
+    const store = deps.store || createStore(pool);
+    const r = await runDue({
+      ...deps,
+      project,
+      store,
+      readKey: deps.readKey || ((p) => readProjectKey(pool, p)),
+    });
+    if (r.outcome) {
+      log.info(`[weekly-run] ${project}: run ${r.runId} ${r.outcome}${r.reason ? ` (${r.reason})` : ''}`
+        + (r.done !== undefined ? ` — ${r.done} done, ${r.errors} errors, ${r.entries} entries, $${(r.costUsd || 0).toFixed(4)}` : ''));
+    }
+    return r;
+  } catch (e) {
+    const msg = (e && e.message) || String(e);
+    if (/ECONNREFUSED|ENOTFOUND|does not exist|connect/i.test(msg)) {
+      if (!warnedUnreachable) { warnedUnreachable = true; log.info(`[weekly-run] skipped — database unreachable (${msg})`); }
+      return { skipped: 'db_unreachable' };
+    }
+    log.error(`[weekly-run] tick failed: ${msg}`);
+    if (typeof deps.reportError === 'function') deps.reportError();
+    return { skipped: 'error', error: msg };
+  } finally {
+    running = false;
+  }
+}
+
+let firstTimer = null;
+let interval = null;
+
+// The loader passes its own deps plus reportError; only reportError is taken, so a loader
+// dep can never be read as a run seam (store, readKey, project).
+function start({ reportError } = {}) {
+  if (process.env.ROUTINE_TIMERS_DISABLED === '1') {
+    log.info('[weekly-run] disabled (ROUTINE_TIMERS_DISABLED=1)');
+    return;
+  }
+  if (firstTimer || interval) return;
+  const fire = () => tick({ reportError });
+  firstTimer = setTimeout(() => {
+    firstTimer = null;
+    fire();
+    interval = setInterval(fire, TICK_MS);
+    if (interval.unref) interval.unref();
+  }, FIRST_MS + Math.floor(Math.random() * JITTER_MS));
+  if (firstTimer.unref) firstTimer.unref();
+}
+
+function stop() {
+  if (firstTimer) clearTimeout(firstTimer);
+  if (interval) clearInterval(interval);
+  firstTimer = interval = null;
+}
+
+module.exports = { start, stop, tick, TICK_MS };

package/modules/market-watch/research.js

@@ -0,0 +1,350 @@
+'use strict';
+
+// modules/market-watch/research.js — research ONE tracked item with ONE Messages API call
+// (task 1004937, ADR 0394 §1).
+//
+// THE CALL. Model claude-sonnet-5, Anthropic's server-side web tools (web_search_20260209
+// capped at 3 uses, web_fetch_20260209 capped at 2), a bounded max_tokens, and a JSON
+// schema for the reply. The watch rules and both rubrics go first, in the system prompt,
+// under cache_control: they are the same for every item of a run, so items 2..n read them
+// from the cache. The item itself, and today's date, come after the cached prefix.
+//
+// NOT THE GRADE PORT, deliberately (ADR 0394 "Rejected options"): that port spawns a CLI
+// the server image does not have, and it replays cached answers, which for news means
+// finding nothing. This is the server's second direct LLM caller after discord-support.
+// The model id is a single constant here so the ModelProvider port (ADR 0089 §3) can
+// take it over later.
+//
+// TRUST NOTHING THE MODEL SAYS ABOUT ITS SOURCES. The reply is parsed and validated in
+// code, never trusted from the prompt:
+//   - an entry survives only if its source_url is a URL that actually appeared in a web
+//     search result or a fetched page in THIS response. An invented or remembered link
+//     is dropped, so no entry is ever written without a real source (the task's rule);
+//   - scores survive only on the item's own rubric dimensions (or 'overall'), 0..10;
+//   - a 'new candidate' is returned as a candidate, and the run turns it into a
+//     proposal. Nothing here can add a tracked item.
+// A refusal, a max_tokens or pause_turn stop, a tool error, or a reply that is not the
+// JSON asked for ends the item with a recorded error. All of these arrive with HTTP 200
+// and do not raise, so they are checked here, before any content is read.
+//
+// THE COST of each call is priced here from the response's own usage: tokens through
+// llm-pricing.priceUsage plus web searches through llm-pricing.priceWebSearches (the one
+// place the search fee is spelled). An item that errored after the model ran still cost
+// money, so its cost is returned with the error.
+//
+// Pure apart from the injected client: tests pass a fake `messages.create` and read the
+// request it was handed. Nothing here touches the network on its own.
+
+const api = require('../../src/module-api');
+
+const MODEL = 'claude-sonnet-5';
+const SEARCH_MAX_USES = 3;
+const FETCH_MAX_USES = 2;
+const FETCH_MAX_CONTENT_TOKENS = 10_000;
+const MAX_TOKENS = 8_000;
+const EFFORT = 'low';
+const CALL_TIMEOUT_MS = 5 * 60_000;
+
+// AN ITEM'S CEILING (ADR 0394 §3): the most one item may cost, so no item starts unless
+// all of it fits under the cap and the cap is never overshot by more than the estimate's
+// error. Built from the bounds above at Sonnet 5's list rates ($2 in / $10 out per MTok):
+//   searches: 3 × $0.01                                   = $0.03
+//   output:   8,000 max_tokens × $10/MTok (thinking incl.)= $0.08
+//   input:    an 80,000-token budget × $2/MTok            = $0.16
+// The input line is an ASSUMED bound, not one the API enforces: fetches are hard-capped at
+// 2 × 10,000 tokens, but search results and the server loop's re-reads are not. The two
+// measured items in ADR 0394 read 23k and 35k tokens of search content, so 80k leaves
+// room. ≈ $0.27 per item against an expected ≈ $0.09.
+const ASSUMED_MAX_INPUT_TOKENS = 80_000;
+function itemCeilingUsd() {
+  const p = api.llmPricing;
+  const rate = p.PRICES[p.familyFor(MODEL)];
+  return p.priceWebSearches(SEARCH_MAX_USES)
+    + (MAX_TOKENS * rate.output) / 1e6
+    + (ASSUMED_MAX_INPUT_TOKENS * rate.input) / 1e6;
+}
+
+const ENTRY_TYPES = new Set(['insight', 'news', 'datapoint']);
+const ITEM_KINDS = new Set(['competitor', 'partner', 'topic']);
+const CONFIDENCE = Object.freeze({ low: 1, medium: 2, high: 3 });
+
+// The reply's shape. Bounds that JSON schema strict mode cannot express (lengths, 0..10)
+// are enforced in parseReply below.
+const REPLY_SCHEMA = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  required: ['entries', 'scores', 'candidates'],
+  properties: {
+    entries: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['type', 'takeaway', 'source_url', 'source_label', 'confidence', 'dimension'],
+        properties: {
+          type: { type: 'string', enum: ['insight', 'news', 'datapoint'] },
+          takeaway: { type: 'string' },
+          source_url: { type: 'string' },
+          source_label: { type: 'string' },
+          confidence: { type: 'string', enum: ['low', 'medium', 'high'] },
+          dimension: { type: ['string', 'null'] },
+        },
+      },
+    },
+    scores: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['dimension', 'value', 'reason'],
+        properties: {
+          dimension: { type: 'string' },
+          value: { type: 'number' },
+          reason: { type: 'string' },
+        },
+      },
+    },
+    candidates: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['name', 'url', 'kind', 'why'],
+        properties: {
+          name: { type: 'string' },
+          url: { type: 'string' },
+          kind: { type: 'string', enum: ['competitor', 'partner', 'topic'] },
+          why: { type: 'string' },
+        },
+      },
+    },
+  },
+});
+
+const oneLine = (s, max) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, max);
+const isHttp = (u) => typeof u === 'string' && /^https?:\/\/[^\s]+$/.test(u);
+const normUrl = (u) => String(u || '').trim().replace(/#.*$/, '').replace(/\/+$/, '');
+
+// The system prompt: the rules and the rubrics. Stable for a whole run (the cache prefix),
+// so it must not carry the date, the item, or anything else that varies per call.
+function systemPrompt(rules) {
+  const r = rules || {};
+  const rubric = r.rubric || {};
+  const lines = [
+    'You are the weekly market watch for a software project. You research ONE tracked item per request and answer only with the JSON the response format asks for.',
+    '',
+    '## The watch rules (approved by the project)',
+    oneLine(r.instructions, 4000) || 'Find what changed this week for the item.',
+  ];
+  if (Array.isArray(r.search_queries) && r.search_queries.length) {
+    lines.push('', 'Search themes:', ...r.search_queries.map((q) => `- ${oneLine(q, 300)}`));
+  }
+  if (Array.isArray(r.sources) && r.sources.length) {
+    lines.push('', 'Preferred sources:', ...r.sources.map((s) => `- ${oneLine(s, 300)}`));
+  }
+  for (const kind of Object.keys(rubric).sort()) {
+    const dims = Array.isArray(rubric[kind]) ? rubric[kind] : [];
+    if (!dims.length) continue;
+    lines.push('', `## How a ${kind} is scored (0 to 10 per dimension, plus "overall")`,
+      ...dims.map((d) => `- ${d.key}: ${oneLine(d.definition || d.label, 300)}`));
+  }
+  lines.push('',
+    '## How to answer',
+    `- Use at most ${SEARCH_MAX_USES} web searches and ${FETCH_MAX_USES} page fetches.`,
+    '- entries: only what is new or changed. Every entry needs source_url copied exactly from a search result or fetched page you saw in this request; an entry with any other link is thrown away. confidence: high only if two sources agree, low if one source and unconfirmed.',
+    '- scores: re-score each of the item\'s rubric dimensions and "overall", each with a one-line reason. Leave a dimension out if you found nothing that bears on it.',
+    '- candidates: companies, partners or topics this item\'s news points to that are not the item itself and look worth tracking. They are proposed to the team, never added by you.',
+    '- If nothing changed, return empty entries.');
+  return lines.join('\n');
+}
+
+function userPrompt(item, { today, since } = {}) {
+  const it = item || {};
+  return [
+    `Today is ${today}. Research what changed${since ? ` since ${since}` : ' in the last week'}.`,
+    '',
+    `Item: ${oneLine(it.name, 200)}`,
+    `Kind: ${it.kind}`,
+    it.url ? `Website: ${it.url}` : null,
+    it.description ? `What it is: ${oneLine(it.description, 500)}` : null,
+    it.why_tracked ? `Why we track it: ${oneLine(it.why_tracked, 500)}` : null,
+  ].filter((l) => l !== null).join('\n');
+}
+
+// buildRequest — the exact Messages API body for one item. Exported so the test asserts
+// the model, the tool caps and the cache placement without a network.
+function buildRequest({ item, rules, today, since }) {
+  return {
+    model: MODEL,
+    max_tokens: MAX_TOKENS,
+    system: [{ type: 'text', text: systemPrompt(rules), cache_control: { type: 'ephemeral' } }],
+    tools: [
+      { type: 'web_search_20260209', name: 'web_search', max_uses: SEARCH_MAX_USES },
+      { type: 'web_fetch_20260209', name: 'web_fetch', max_uses: FETCH_MAX_USES, max_content_tokens: FETCH_MAX_CONTENT_TOKENS },
+    ],
+    output_config: { effort: EFFORT, format: { type: 'json_schema', schema: REPLY_SCHEMA } },
+    messages: [{ role: 'user', content: userPrompt(item, { today, since }) }],
+  };
+}
+
+// The URLs this response actually saw: every web_search result and every fetched page.
+function seenUrls(content) {
+  const seen = new Set();
+  for (const b of content || []) {
+    if (!b) continue;
+    if (b.type === 'web_search_tool_result' && Array.isArray(b.content)) {
+      for (const r of b.content) if (r && isHttp(r.url)) seen.add(normUrl(r.url));
+    } else if (b.type === 'web_fetch_tool_result' && b.content && !Array.isArray(b.content)) {
+      if (isHttp(b.content.url)) seen.add(normUrl(b.content.url));
+    }
+  }
+  return seen;
+}
+
+// A tool error block (HTTP 200, no exception). max_uses_exceeded is the cap doing its job
+// (the model asked for one search too many and was refused), so it does not end the item.
+function toolError(content) {
+  for (const b of content || []) {
+    if (!b) continue;
+    if (b.type === 'web_search_tool_result' || b.type === 'web_fetch_tool_result') {
+      const c = b.content;
+      const code = c && !Array.isArray(c) ? c.error_code : null;
+      if (code && code !== 'max_uses_exceeded') return String(code);
+    }
+  }
+  return null;
+}
+
+// The reply text: the text blocks after the last server tool block (the final answer),
+// or every text block if there were no tools.
+function replyText(content) {
+  const blocks = content || [];
+  let start = 0;
+  blocks.forEach((b, i) => {
+    if (b && /tool_(use|result)$/.test(String(b.type))) start = i + 1;
+  });
+  const after = blocks.slice(start).filter((b) => b && b.type === 'text').map((b) => b.text);
+  const all = blocks.filter((b) => b && b.type === 'text').map((b) => b.text);
+  return (after.length ? after : all).join('');
+}
+
+// parseReply(text, { seen, dimensions }) → { ok: true, entries, scores, candidates, dropped }
+// | { ok: false, error: 'malformed_reply' }. Pure.
+function parseReply(text, { seen = new Set(), dimensions = [] } = {}) {
+  let obj = null;
+  const s = String(text || '').trim();
+  try { obj = JSON.parse(s); } catch (_) {
+    // A reply wrapped in a code fence or a sentence: take the outermost object, once.
+    const a = s.indexOf('{');
+    const z = s.lastIndexOf('}');
+    if (a !== -1 && z > a) { try { obj = JSON.parse(s.slice(a, z + 1)); } catch (_) { obj = null; } }
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)
+    || !Array.isArray(obj.entries) || !Array.isArray(obj.scores) || !Array.isArray(obj.candidates)) {
+    return { ok: false, error: 'malformed_reply' };
+  }
+  const dims = new Set([...dimensions, 'overall']);
+  const dropped = { entries: 0, scores: 0, candidates: 0 };
+
+  const entries = [];
+  for (const e of obj.entries) {
+    const url = e && typeof e.source_url === 'string' ? e.source_url.trim() : '';
+    const takeaway = oneLine(e && e.takeaway, 1000);
+    const conf = e && CONFIDENCE[String(e.confidence).toLowerCase()];
+    if (!isHttp(url) || !seen.has(normUrl(url)) || !takeaway || !conf || !ENTRY_TYPES.has(e.type)) {
+      dropped.entries += 1;
+      continue;
+    }
+    let host = '';
+    try { host = new URL(url).hostname.replace(/^www\./, ''); } catch (_) { /* isHttp passed */ }
+    entries.push({
+      type: e.type,
+      takeaway,
+      sourceUrl: url,
+      sourceLabel: oneLine(e.source_label, 200) || host,
+      confidence: conf,
+      dimension: typeof e.dimension === 'string' && dims.has(e.dimension) && e.dimension !== 'overall' ? e.dimension : null,
+    });
+  }
+
+  const scores = [];
+  const scored = new Set();
+  for (const sc of obj.scores) {
+    const v = sc && typeof sc.value === 'number' ? sc.value : NaN;
+    const reason = oneLine(sc && sc.reason, 300);
+    if (!sc || !dims.has(sc.dimension) || scored.has(sc.dimension) || !Number.isFinite(v) || v < 0 || v > 10 || !reason) {
+      dropped.scores += 1;
+      continue;
+    }
+    scored.add(sc.dimension);
+    scores.push({ dimension: sc.dimension, value: Math.round(v * 10) / 10, reason });
+  }
+
+  const candidates = [];
+  const named = new Set();
+  for (const c of obj.candidates) {
+    const name = oneLine(c && c.name, 200);
+    const key = name.toLowerCase();
+    if (!name || named.has(key) || !c || !ITEM_KINDS.has(c.kind) || !(c.url === '' || isHttp(c.url))) {
+      dropped.candidates += 1;
+      continue;
+    }
+    named.add(key);
+    candidates.push({ name, url: c.url, kind: c.kind, why: oneLine(c.why, 500) });
+  }
+  return { ok: true, entries, scores, candidates, dropped };
+}
+
+// priceResponse(usage) → USD for one response, tokens + searches, 4 decimals (the
+// numeric(10,4) the run_items row stores).
+function priceResponse(usage) {
+  const p = api.llmPricing;
+  const u = usage || {};
+  const tokens = p.priceUsage(MODEL, u).usd;
+  const searches = p.priceWebSearches(u.server_tool_use && u.server_tool_use.web_search_requests);
+  return Math.round((tokens + searches) * 10000) / 10000;
+}
+
+// createClient(apiKey) — the live SDK client on the PROJECT's key. Required lazily, so an
+// instance with Market Watch off never loads the SDK.
+function createClient(apiKey, { sdk = null } = {}) {
+  const mod = sdk || require('@anthropic-ai/sdk');
+  const Anthropic = mod.Anthropic || mod.default || mod;
+  return new Anthropic({ apiKey, timeout: CALL_TIMEOUT_MS, maxRetries: 1 });
+}
+
+// researchItem({ client, item, rules, today, since }) →
+//   { ok: true, entries, scores, candidates, dropped, costUsd, usage }
+//   { ok: false, error, costUsd, usage }
+// Never throws: a thrown SDK error (network, 4xx, 5xx) is an item error that cost nothing.
+async function researchItem({ client, item, rules, today, since }) {
+  const req = buildRequest({ item, rules, today, since });
+  let res;
+  try {
+    res = await client.messages.create(req);
+  } catch (e) {
+    const status = e && e.status ? ` ${e.status}` : '';
+    return { ok: false, error: `api_error${status}`, costUsd: 0, usage: null };
+  }
+  const usage = (res && res.usage) || {};
+  const costUsd = priceResponse(usage);
+  const stop = res && res.stop_reason;
+  if (stop === 'refusal' || stop === 'max_tokens' || stop === 'pause_turn') {
+    return { ok: false, error: stop, costUsd, usage };
+  }
+  const content = (res && res.content) || [];
+  const tErr = toolError(content);
+  if (tErr) return { ok: false, error: `tool_error:${tErr}`, costUsd, usage };
+  const rubric = (rules && rules.rubric && rules.rubric[item.kind]) || [];
+  const parsed = parseReply(replyText(content), {
+    seen: seenUrls(content),
+    dimensions: rubric.map((d) => d.key),
+  });
+  if (!parsed.ok) return { ok: false, error: parsed.error, costUsd, usage };
+  return { ...parsed, costUsd, usage };
+}
+
+module.exports = {
+  researchItem, buildRequest, parseReply, seenUrls, priceResponse, createClient, itemCeilingUsd,
+  MODEL, REPLY_SCHEMA,
+};