@bongos/core 1.23.22 → 1.24.2

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

package/modules/market-watch/run.js

@@ -0,0 +1,245 @@
+'use strict';
+
+// modules/market-watch/run.js — the weekly Market Watch run (task 1004937, ADR 0394).
+//
+// One call, runDue(), decides and does everything a tick needs for ONE project:
+//
+//   1. An open run whose lease lapsed (a deploy cut it off) is RESUMED: it is claimed
+//      again and does only the items with no finished row. An item already done or
+//      errored is never researched, or charged, twice.
+//   2. Otherwise, if the newest run is less than a cadence old (minus a 30-minute slack),
+//      nothing happens: due by the ledger, never by the boot.
+//   3. Otherwise the pre-checks run, in this order, and the first that fails records a
+//      SKIPPED run with its reason — a row on the settings strip, never only a log line:
+//        off               the owner's switch is off
+//        no_key            no project key, or one the master key cannot open
+//        spend_unreadable  this month's spend could not be read (FAIL CLOSED: an unknown
+//                          spend is never treated as zero; agents/lib/spend-ceiling.js)
+//        cap_reached       the cap is not a positive number, or this month's spend plus
+//                          one item's whole ceiling would pass it
+//        error             no approved (active) watch rules to run
+//   4. A run row is created already leased (one open run per project, by index), and each
+//      item is researched in turn. BEFORE EACH ITEM the spend is read again and the cap
+//      checked again, so a run stops partway (status 'partial', reason cap_reached or
+//      spend_unreadable) rather than run past the cap.
+//   5. Each item's result is written in one transaction, and its cost is mirrored into
+//      cost_log through the economy port: source `market-watch:<run id>`, source_ref
+//      `item-<item id>`, category 'api'. logCost is insert-once on (source, source_ref)
+//      and the mirror only runs when this process is the one that recorded the item, so
+//      a retry can never post it twice. Never via HTTP POST /cost.
+//
+// THE ACCOUNTING is market_watch_run_items.cost_usd: it is what the cap sums (db.monthSpend)
+// and it is written in the same transaction as the item's findings. cost_log is the
+// project-wide roll-up the cost dashboard reads, a projection like agents/spawn.js
+// mirrorCostToLedger: best-effort, logged loudly when it fails, because the spend has
+// already happened and the cap does not depend on it.
+//
+// ONE PROJECT. Every project is its own instance and database (ADR 0394 Context); the
+// project key is the instance's own public origin. Every read and write is scoped to it
+// (store.js puts the guard in the SQL), and an item that comes back from a read with any
+// other project is refused here before a cent is spent on it.
+//
+// Everything is injected (store, clock, key reader, client factory, economy), so the
+// whole run is tested with no database and no network.
+
+const api = require('../../src/module-api');
+const research = require('./research');
+const { CADENCE_DAYS } = require('./db');
+
+const log = api.logger('market-watch');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DUE_SLACK_MS = 30 * 60_000;
+// Long enough for one item's call (5 min timeout) many times over; renewed before each
+// item, so only a run whose process died lets it lapse.
+const LEASE_MS = 30 * 60_000;
+
+function costSourceTag(runId) {
+  return `market-watch:${runId}`;
+}
+
+// isDue(lastRun, cadence, nowMs) — the weekly clock, by the ledger.
+function isDue(last, cadence, nowMs) {
+  if (!last) return true;
+  const at = new Date(last.created_at).getTime();
+  if (!Number.isFinite(at)) return true;
+  const days = CADENCE_DAYS[cadence] || CADENCE_DAYS.weekly;
+  return nowMs - at >= days * DAY_MS - DUE_SLACK_MS;
+}
+
+// capAllows(capUsd, spentUsd, ceilingUsd) — true only when one more item, at its whole
+// ceiling, still fits. A cap that is not a positive finite number allows nothing.
+function capAllows(capUsd, spentUsd, ceilingUsd) {
+  const cap = Number(capUsd);
+  if (!Number.isFinite(cap) || cap <= 0) return false;
+  if (!Number.isFinite(spentUsd) || spentUsd < 0) return false;
+  return spentUsd + ceilingUsd <= cap;
+}
+
+// readSpend — this month's spend, or null for "I don't know" (which always refuses).
+async function readSpend(store, project, now) {
+  try {
+    const n = Number(await store.monthSpend(project, now));
+    return Number.isFinite(n) && n >= 0 ? n : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// The pre-checks of step 3. Returns { reason } or { key, cap, spent, rules }.
+async function precheck(deps, project, settings, now) {
+  if (!settings || settings.enabled !== true) return { reason: 'off' };
+  let key = null;
+  try { key = await deps.readKey(project); } catch (_) { key = null; }
+  if (!key) return { reason: 'no_key' };
+  const cap = Number(settings.monthly_cap_usd);
+  const spent = await readSpend(deps.store, project, now);
+  if (spent === null) return { reason: 'spend_unreadable', cap };
+  if (!capAllows(cap, spent, deps.ceilingUsd)) return { reason: 'cap_reached', cap, spent };
+  const rules = await deps.store.activeRules(project);
+  if (!rules) return { reason: 'error', cap, spent, note: 'no active watch rules' };
+  return { key, cap, spent, rules };
+}
+
+async function mirrorCost(deps, project, runId, item, costUsd) {
+  if (!(costUsd > 0)) return false;
+  const economy = deps.economy
+    || (typeof api.resolveOptional === 'function' ? api.resolveOptional('reward', null) : null);
+  if (!economy || typeof economy.logCost !== 'function') {
+    deps.warn(`[weekly-run] run ${runId} item ${item.id}: no economy port, cost_log is missing $${costUsd}`);
+    return false;
+  }
+  try {
+    await economy.logCost({
+      amountUsd: costUsd,
+      category: 'api',
+      source: costSourceTag(runId),
+      sourceRef: `item-${item.id}`,
+      // The project pays (its own key); no builder asked for a weekly run.
+      builderId: null,
+      description: `Market Watch run ${runId}: ${item.name} (${project})`.slice(0, 1000),
+    });
+    return true;
+  } catch (e) {
+    deps.warn(`[weekly-run] run ${runId} item ${item.id}: cost mirror failed (${e && e.message}); run_items still has the cost`);
+    return false;
+  }
+}
+
+// Research every remaining item of one claimed run, then finish it.
+async function execute(deps, project, runId, ctx) {
+  const { store } = deps;
+  const client = deps.createClient(ctx.key);
+  const items = await store.remainingItems(project, runId);
+  const nowDate = new Date(deps.now());
+  const today = nowDate.toISOString().slice(0, 10);
+  const out = { runId, done: 0, errors: 0, refused: 0, entries: 0, scores: 0, proposals: 0, costUsd: 0 };
+  let stop = null;
+
+  for (const item of items) {
+    // The cross-project guard, before any spend: a row from another project is refused.
+    if (!item || item.project !== project) {
+      out.refused += 1;
+      deps.warn(`[weekly-run] run ${runId}: refused item ${item && item.id} from another project`);
+      continue;
+    }
+    const spent = await readSpend(store, project, new Date(deps.now()));
+    if (spent === null) { stop = 'spend_unreadable'; break; }
+    if (!capAllows(ctx.cap, spent, deps.ceilingUsd)) { stop = 'cap_reached'; break; }
+    if (!(await store.renewLease(project, runId, LEASE_MS))) { stop = 'lease_lost'; break; }
+    if (!(await store.startItem(project, runId, item.id))) continue;
+
+    const res = await deps.researchItem({ client, item, rules: ctx.rules, today });
+    let rec;
+    try {
+      rec = await store.recordItem(project, runId, item.id, res);
+    } catch (e) {
+      if (e && e.code === 'cross_project') {
+        out.refused += 1;
+        deps.warn(`[weekly-run] run ${runId}: item ${item.id} is not this project's; nothing written`);
+        continue;
+      }
+      throw e;
+    }
+    if (!rec.recorded) continue;
+    out.costUsd += res.costUsd || 0;
+    await mirrorCost(deps, project, runId, item, res.costUsd);
+    if (res.ok) {
+      out.done += 1;
+      out.entries += rec.counts.entries;
+      out.scores += rec.counts.scores;
+      out.proposals += rec.counts.proposals;
+    } else {
+      out.errors += 1;
+      deps.warn(`[weekly-run] run ${runId}: ${item.name} ended with ${res.error}`);
+    }
+  }
+
+  if (stop === 'lease_lost') {
+    // Another process holds the run now; leave it to them.
+    return { outcome: 'lease_lost', ...out };
+  }
+  let status = 'done';
+  let reason = null;
+  if (stop) { status = 'partial'; reason = stop; } else if (out.errors > 0 && out.done === 0) { status = 'failed'; reason = 'error'; } else if (out.errors > 0) { status = 'partial'; reason = 'error'; }
+  await store.finishRun(project, runId, { status, reason });
+  return { outcome: status, reason, ...out };
+}
+
+function resolveDeps(deps) {
+  return {
+    store: deps.store,
+    now: deps.now || Date.now,
+    readKey: deps.readKey,
+    createClient: deps.createClient || ((key) => research.createClient(key)),
+    researchItem: deps.researchItem || research.researchItem,
+    ceilingUsd: deps.ceilingUsd != null ? deps.ceilingUsd : research.itemCeilingUsd(),
+    economy: deps.economy || null,
+    warn: deps.warn || ((m) => log.warn(m)),
+  };
+}
+
+// runDue({ store, project, readKey, ... }) — one tick's worth of work for one project.
+async function runDue(rawDeps = {}) {
+  const deps = resolveDeps(rawDeps);
+  const { store } = deps;
+  const project = rawDeps.project;
+  if (typeof project !== 'string' || !project) return { skipped: 'no_project' };
+  const nowMs = deps.now();
+  const now = new Date(nowMs);
+
+  const open = await store.openRun(project);
+  if (open) {
+    if (open.leased) return { skipped: 'in_flight', runId: open.id };
+    if (!(await store.claimRun(project, open.id, LEASE_MS))) return { skipped: 'in_flight', runId: open.id };
+    const settings = await store.readSettings(project);
+    const pre = await precheck(deps, project, settings, now);
+    if (pre.reason) {
+      await store.finishRun(project, open.id, { status: 'partial', reason: pre.reason });
+      return { outcome: 'partial', reason: pre.reason, runId: open.id, resumed: true };
+    }
+    return { resumed: true, ...(await execute(deps, project, open.id, pre)) };
+  }
+
+  const settings = await store.readSettings(project);
+  const last = await store.lastRun(project);
+  if (!isDue(last, settings.cadence, nowMs)) return { skipped: 'not_due' };
+
+  const pre = await precheck(deps, project, settings, now);
+  if (pre.reason) {
+    const runId = await store.insertSkipped(project, {
+      reason: pre.reason,
+      capUsd: Number.isFinite(pre.cap) ? pre.cap : null,
+      spentBeforeUsd: Number.isFinite(pre.spent) ? pre.spent : null,
+    });
+    if (pre.note) deps.warn(`[weekly-run] run ${runId} skipped: ${pre.note}`);
+    return { outcome: 'skipped', reason: pre.reason, runId };
+  }
+  const runId = await store.createRun(project, {
+    ruleVersionId: pre.rules.id, capUsd: pre.cap, spentBeforeUsd: pre.spent, leaseMs: LEASE_MS,
+  });
+  if (runId === null) return { skipped: 'in_flight' };
+  return execute(deps, project, runId, pre);
+}
+
+module.exports = { runDue, isDue, costSourceTag };