@bongos/core 1.23.21 → 1.24.1

package/tests/market_watch_module.mjs

@@ -0,0 +1,114 @@
+// tests/market_watch_module.mjs — the market-watch module is registered, accepted by
+// the loader, and an instance boots with it present and DISABLED (task 1004935, goal
+// 1000137). DB-free, so it runs in the unit lane.
+//
+// The module mounts no routes yet; task 1004936 gave it its tables and a one-shot hub seed
+// poller (tests/market_watch_data.mjs covers those). What this file
+// pins is everything the later Market Watch tasks will stand on:
+//   1. the manifest validates, ships default:false, and declares spend.requiresPayer;
+//   2. the loader discovers it from the live tree with no error and no skip;
+//   3. the resolved module set has it OFF with no config, and the spend guard refuses
+//      to turn it on behind an open join door with no payer;
+//   4. the real platform app boots and its hall reports market-watch present and false;
+//   5. the creation picker does not offer it while it does nothing.
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import http from 'node:http';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const KEY = 'market-watch';
+const manifest = JSON.parse(readFileSync(new URL('../modules/market-watch/module.json', import.meta.url), 'utf8'));
+const { validateManifest } = require('../src/module-loader/manifest-schema.js');
+const loader = require('../src/module-loader/loader.js');
+const mods = require('../src/modules.js');
+const bundles = require('../modules/provisioning/starter-bundles.js');
+const scopeMap = require('../src/bongos/module-scope-map.js');
+
+test('the manifest validates, ships disabled, declares a payer, and contributes only its data', () => {
+  const v = validateManifest(manifest);
+  assert.equal(v.valid, true, `manifest errors: ${v.errors.join('; ')}`);
+  assert.equal(manifest.key, KEY);
+  assert.equal(manifest.default, false, 'shipped is not enabled (ADR 0083)');
+  assert.equal(manifest.spend && manifest.spend.requiresPayer, true,
+    'every run spends the project AI budget, so the payer guard is declared before the first route');
+  // Task 1004936 added its tables and the one-shot hub seed; task 1004937 the weekly-run
+  // poller. There are still no routes.
+  assert.deepEqual(manifest.contributes, { migrations: true, pollers: ['hub-seed', 'weekly-run'] },
+    'its tables, the hub seed and the weekly run, nothing to mount');
+});
+
+test('the loader discovers it from the live tree — loaded, not an error, not skipped', () => {
+  loader._reset();
+  const snap = loader.loaderSnapshot();
+  assert.ok(snap.loaded.includes(KEY), `loaded: ${snap.loaded.join(', ')}`);
+  assert.deepEqual(snap.errors.filter((e) => JSON.stringify(e).includes(KEY)), []);
+  assert.deepEqual(snap.skipped.filter((s) => JSON.stringify(s).includes(KEY)), []);
+  const reg = loader.discoveredRegistry();
+  assert.equal(reg[KEY].default, false);
+  assert.equal(mods.metersSpend(reg[KEY]), true, 'the declaration rides through the loader to the spend guard');
+  loader._reset();
+});
+
+test('with no config it resolves OFF, and isModuleEnabled answers rather than throwing "unknown module"', () => {
+  mods._resetForTests && mods._resetForTests();
+  assert.ok(mods.knownModules().includes(KEY));
+  const set = mods.resolveModules({ registry: mods.effectiveRegistry() });
+  assert.equal(set[KEY], false);
+  assert.equal(mods.isModuleEnabled(KEY, set), false);
+});
+
+test('the spend guard bites it: an open door with no payer cannot enable it; a closed door can', () => {
+  const registry = mods.effectiveRegistry();
+  const on = { modules: { [KEY]: true } };
+  const silent = () => {};
+  assert.equal(mods.resolveModules({ instance: on, registry, spendGuard: { joinDoorOpen: true, payer: null }, warn: silent })[KEY], false);
+  assert.equal(mods.resolveModules({ instance: on, registry, spendGuard: { joinDoorOpen: false, payer: null }, warn: silent })[KEY], true);
+});
+
+test('it has a scope-roster key, and the creation picker does not offer it while it is empty', () => {
+  assert.ok(Array.isArray(scopeMap.MODULE_GLOBS[KEY]) && scopeMap.MODULE_GLOBS[KEY].includes('modules/market-watch/'));
+  // Every entry is an exact path or a dir prefix (the touches[] convention has no
+  // wildcards), and this test's own path resolves to the module's scope.
+  for (const g of scopeMap.MODULE_GLOBS[KEY]) assert.ok(!g.includes('*'), `wildcard glob never matches: ${g}`);
+  assert.ok(scopeMap.MODULE_GLOBS[KEY].includes('tests/market_watch_module.mjs'));
+  assert.ok(bundles.HUB_ONLY_MODULES.includes(KEY));
+  assert.ok(!bundles.OPTIONAL_MODULES.some((m) => m.key === KEY));
+  assert.ok(!bundles.ALWAYS_ON_CORE.includes(KEY));
+});
+
+// --- an instance boots with it present and disabled -------------------------
+let server;
+let port;
+before(async () => {
+  loader._reset();
+  mods._resetForTests && mods._resetForTests();
+  const { buildPlatformApp } = require('../src/platform-server.js');
+  server = http.createServer(buildPlatformApp());
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  port = server.address().port;
+});
+after(async () => { if (server) await new Promise((resolve) => server.close(resolve)); });
+
+function get(pathname, host) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, path: pathname, method: 'GET', headers: { Host: host } }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => resolve({ status: res.statusCode, body }));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+test('the platform boots and its hall reports market-watch present and OFF', async () => {
+  const res = await get('/', 'builders.test.local');
+  assert.equal(res.status, 200);
+  const m = res.body.match(/window\.__MODULES__=(\{.*?\});/);
+  assert.ok(m, 'a __MODULES__ assignment is present');
+  const enabled = JSON.parse(m[1]).enabled;
+  assert.ok(Object.prototype.hasOwnProperty.call(enabled, KEY), 'present: the booted instance knows the key');
+  assert.equal(enabled[KEY], false, 'disabled');
+});

package/tests/market_watch_run.mjs

@@ -0,0 +1,503 @@
+// tests/market_watch_run.mjs — the weekly Market Watch run with no database and no network
+// (task 1004937, goal 1000137, ADR 0394).
+//
+// The Messages API client is a fake whose `messages.create` records the request it was
+// handed and answers with a scripted response, so every test asserts on the REAL request
+// the run builds (model, web tool caps, the key) and on the run's handling of the reply.
+// The store is an in-memory stand-in with store.js's method names and its two guarantees
+// (an item result is recorded once; a result for another project's item throws
+// cross_project). store.js's own SQL guard is tested at the bottom against a recording
+// pool. Nothing here can make a paid call: no test ever constructs the real SDK.
+//
+// The SQL runs on real Postgres in tests/market_watch_data_db.mjs (INTEGRATION set).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const seed = require('../modules/market-watch/seed.js');
+const research = require('../modules/market-watch/research.js');
+const run = require('../modules/market-watch/run.js');
+const store = require('../modules/market-watch/store.js');
+const key = require('../modules/market-watch/key.js');
+const weekly = require('../modules/market-watch/pollers/weekly-run.js');
+const { priceWebSearches, WEB_SEARCH_USD_PER_REQUEST } = require('../src/bongos/llm-pricing.js');
+
+const P = 'https://watch.example.test';
+const OTHER = 'https://other.example.test';
+const KEY = 'sk-ant-api03-project-own-key-ABCD';
+const NOW = Date.parse('2026-11-20T10:00:00Z');
+const DAY = 24 * 60 * 60 * 1000;
+
+const built = seed.buildSeed({ market: seed.readSeed('market-data.json'), partners: seed.readSeed('partners-data.json') });
+
+// --- a fake Messages API ---------------------------------------------------
+
+const NEWS_URL = 'https://news.example.com/launch';
+const FETCHED_URL = 'https://blog.example.com/post';
+
+function reply(obj, { stop = 'end_turn', usage, extra = [] } = {}) {
+  return {
+    stop_reason: stop,
+    content: [
+      { type: 'server_tool_use', id: 's1', name: 'web_search', input: { query: 'x' } },
+      { type: 'web_search_tool_result', tool_use_id: 's1', content: [{ type: 'web_search_result', url: NEWS_URL, title: 'Launch' }] },
+      { type: 'server_tool_use', id: 'f1', name: 'web_fetch', input: { url: FETCHED_URL } },
+      { type: 'web_fetch_tool_result', tool_use_id: 'f1', content: { type: 'web_fetch_result', url: FETCHED_URL, content: {} } },
+      ...extra,
+      { type: 'text', text: typeof obj === 'string' ? obj : JSON.stringify(obj) },
+    ],
+    usage: usage || { input_tokens: 20_000, output_tokens: 1_500, server_tool_use: { web_search_requests: 2 } },
+  };
+}
+// 20k in × $2/M + 1.5k out × $10/M + 2 searches × $0.01
+const REPLY_COST = 0.075;
+
+const GOOD = {
+  entries: [
+    { type: 'news', takeaway: 'Shipped agent mode to self-hosted customers.', source_url: NEWS_URL, source_label: 'news', confidence: 'high', dimension: 'human_gates' },
+    { type: 'insight', takeaway: 'Pricing moved to usage.', source_url: `${FETCHED_URL}/`, source_label: '', confidence: 'medium', dimension: null },
+    { type: 'news', takeaway: 'An invented scoop.', source_url: 'https://made-up.example.org/x', source_label: 'x', confidence: 'high', dimension: null },
+  ],
+  scores: [
+    { dimension: 'overall', value: 6.24, reason: 'Closer to us after the self-host launch.' },
+    { dimension: 'human_gates', value: 7, reason: 'Adds an approval step.' },
+    { dimension: 'not_a_dimension', value: 5, reason: 'x' },
+    { dimension: 'open_source_ethos', value: 11, reason: 'out of range' },
+  ],
+  candidates: [{ name: 'Newco Agents', url: 'https://newco.example.com', kind: 'competitor', why: 'Named as the rival in the launch post.' }],
+};
+
+function fakeClient(respond = () => reply(GOOD)) {
+  const calls = [];
+  return {
+    calls,
+    client: { messages: { create: async (req) => { calls.push(req); return respond(req, calls.length); } } },
+  };
+}
+
+// --- an in-memory store with store.js's contract ----------------------------
+
+function memStore({ items, settings, runs = [], runItems = [], spendThrows = false, spendThrowsAfter = Infinity, rules } = {}) {
+  const s = {
+    items: items || built.items.slice(0, 4).map((it, i) => ({ id: i + 1, project: P, kind: it.kind, name: it.name, url: it.url, description: it.description, why_tracked: it.whyTracked, status: 'active' })),
+    settings: settings === undefined ? { enabled: true, monthly_cap_usd: 20, cadence: 'weekly' } : settings,
+    runs: runs.map((r) => ({ ...r })),
+    runItems: new Map(runItems.map((r) => [`${r.run_id}:${r.item_id}`, { ...r }])),
+    entries: [], scores: [], proposals: [], newItems: [],
+    spendReads: 0,
+    rules: rules === undefined ? { id: 1, ...built.rules, search_queries: built.rules.searchQueries } : rules,
+  };
+  let nextRun = 100;
+  const api = {
+    state: s,
+    async readSettings(project) { assert.equal(project, P); return s.settings ? { ...s.settings } : { enabled: false, monthly_cap_usd: 20, cadence: 'weekly' }; },
+    async lastRun(project) { const r = s.runs.filter((x) => x.project === project).sort((a, b) => b.created_at - a.created_at)[0]; return r || null; },
+    async openRun(project) {
+      const r = s.runs.find((x) => x.project === project && ['queued', 'running'].includes(x.status));
+      return r ? { ...r, leased: r.claimed_until > NOW } : null;
+    },
+    async insertSkipped(project, o) { const id = nextRun++; s.runs.push({ id, project, status: 'skipped', ...o, created_at: NOW }); return id; },
+    async createRun(project, o) {
+      if (s.runs.some((x) => x.project === project && ['queued', 'running'].includes(x.status))) return null;
+      const id = nextRun++;
+      s.runs.push({ id, project, status: 'running', ...o, claimed_until: NOW + o.leaseMs, created_at: NOW });
+      return id;
+    },
+    async claimRun(project, id, leaseMs) {
+      const r = s.runs.find((x) => x.id === id && x.project === project);
+      if (!r || r.claimed_until > NOW) return false;
+      r.claimed_until = NOW + leaseMs; r.status = 'running'; return true;
+    },
+    async renewLease(project, id) { return s.runs.some((x) => x.id === id && x.project === project && x.status === 'running'); },
+    async finishRun(project, id, { status, reason }) { const r = s.runs.find((x) => x.id === id && x.project === project); Object.assign(r, { status, reason }); return true; },
+    async startItem(project, runId, itemId) {
+      const k = `${runId}:${itemId}`;
+      const row = s.runItems.get(k);
+      if (row && ['done', 'error'].includes(row.status)) return false;
+      s.runItems.set(k, { run_id: runId, item_id: itemId, status: 'running' });
+      return true;
+    },
+    async recordItem(project, runId, itemId, r) {
+      const item = s.items.find((i) => i.id === itemId);
+      const runRow = s.runs.find((x) => x.id === runId);
+      if (!item || item.project !== project || !runRow || runRow.project !== project) {
+        const e = new Error('cross_project'); e.code = 'cross_project'; throw e;
+      }
+      const row = s.runItems.get(`${runId}:${itemId}`);
+      if (row && ['done', 'error'].includes(row.status)) return { recorded: false, counts: { entries: 0, scores: 0, proposals: 0 } };
+      const counts = { entries: 0, scores: 0, proposals: 0 };
+      if (r.ok) {
+        for (const e of r.entries) { assert.match(e.sourceUrl, /^https?:\/\//, 'never an entry without a source'); s.entries.push({ item_id: itemId, run_id: runId, ...e }); counts.entries += 1; }
+        for (const sc of r.scores) { s.scores.push({ item_id: itemId, run_id: runId, ...sc }); counts.scores += 1; }
+        for (const c of r.candidates) { s.proposals.push({ project, run_id: runId, kind: 'add_item', origin: 'run', payload: c }); counts.proposals += 1; }
+      }
+      s.runItems.set(`${runId}:${itemId}`, { run_id: runId, item_id: itemId, status: r.ok ? 'done' : 'error', error: r.ok ? null : r.error, cost_usd: r.costUsd });
+      return { recorded: true, counts };
+    },
+    async remainingItems(project, runId) {
+      return s.items.filter((i) => i.status === 'active' && !['done', 'error'].includes((s.runItems.get(`${runId}:${i.id}`) || {}).status));
+    },
+    async monthSpend() {
+      s.spendReads += 1;
+      if (spendThrows || s.spendReads > spendThrowsAfter) throw new Error('db down');
+      return [...s.runItems.values()].reduce((a, r) => a + (Number(r.cost_usd) || 0), 0);
+    },
+    async activeRules() { return s.rules; },
+  };
+  return api;
+}
+
+function fakeEconomy() {
+  const rows = new Map();
+  const calls = [];
+  return {
+    calls, rows,
+    async logCost(row) { calls.push(row); const k = `${row.source}|${row.sourceRef}`; if (!rows.has(k)) rows.set(k, row); },
+  };
+}
+
+function deps(over = {}) {
+  const fc = over.fake || fakeClient();
+  const keysSeen = [];
+  return {
+    fc,
+    keysSeen,
+    d: {
+      project: P,
+      now: () => NOW,
+      readKey: async () => KEY,
+      createClient: (k) => { keysSeen.push(k); return fc.client; },
+      economy: fakeEconomy(),
+      warn: () => {},
+      ...over.d,
+    },
+  };
+}
+
+// --- the request -----------------------------------------------------------
+
+test('the request: Sonnet 5, web search capped at 3 and fetch at 2, rules cached first, a JSON reply', () => {
+  const req = research.buildRequest({ item: { name: 'Acme', kind: 'competitor', url: 'https://acme.test' }, rules: { ...built.rules, search_queries: built.rules.searchQueries }, today: '2026-11-20' });
+  assert.equal(req.model, 'claude-sonnet-5');
+  const search = req.tools.find((t) => t.name === 'web_search');
+  const fetch = req.tools.find((t) => t.name === 'web_fetch');
+  assert.deepEqual([search.type, search.max_uses], ['web_search_20260209', 3]);
+  assert.deepEqual([fetch.type, fetch.max_uses, fetch.max_content_tokens], ['web_fetch_20260209', 2, 10_000]);
+  assert.equal(req.tools.length, 2, 'no other tool: dynamic filtering brings its own code execution');
+  assert.ok(req.max_tokens > 0 && req.max_tokens <= 8_000, 'bounded output');
+  assert.deepEqual(req.system[0].cache_control, { type: 'ephemeral' });
+  assert.match(req.system[0].text, /Every finding needs a source link/, 'the approved rules are the cached prefix');
+  assert.doesNotMatch(req.system[0].text, /2026-11-20|Acme/, 'nothing per-item or per-day in the cached prefix');
+  assert.match(req.messages[0].content, /Acme/);
+  assert.equal(req.output_config.format.type, 'json_schema');
+  assert.equal(req.output_config.format.schema, research.REPLY_SCHEMA);
+});
+
+test('the run calls the API on the PROJECT key it read, and only that key', async () => {
+  const { d, fc, keysSeen } = deps();
+  const r = await run.runDue({ ...d, store: memStore() });
+  assert.equal(r.outcome, 'done');
+  assert.deepEqual(keysSeen, [KEY], 'one client, built on the project key');
+  assert.equal(fc.calls.length, 4, 'one call per tracked item');
+  assert.ok(fc.calls.every((c) => c.model === 'claude-sonnet-5'));
+});
+
+test('the key accessor decrypts inside a run only, and a blob it cannot open is no key', async () => {
+  const pool = (enc) => ({ query: async (sql, params) => { assert.equal(sql, key.KEY_SQL); assert.equal(params[0], P); return { rows: enc === undefined ? [] : [{ anthropic_key_enc: enc }] }; } });
+  assert.equal(await key.readProjectKey(pool('v1.a.b.c'), P, { decrypt: () => KEY }), KEY);
+  assert.equal(await key.readProjectKey(pool(undefined), P, { decrypt: () => KEY }), null);
+  assert.equal(await key.readProjectKey(pool(null), P, { decrypt: () => KEY }), null);
+  assert.equal(await key.readProjectKey(pool('v1.a.b.c'), P, { decrypt: () => { throw new Error('bad tag'); } }), null);
+  const sealed = key.sealProjectKey(`  ${KEY} `, { encrypt: (s) => `v1.sealed(${s.length})` });
+  assert.deepEqual(sealed, { key_enc: `v1.sealed(${KEY.length})`, last4: 'ABCD' });
+  assert.equal(key.sealProjectKey('short', { encrypt: () => 'x' }).error, 'key_wrong_length');
+  const spaced = key.sealProjectKey('has a space in it here', { encrypt: () => 'x' });
+  assert.deepEqual(spaced, { error: 'key_has_spaces' }, 'refused, and the key is never echoed back');
+});
+
+// --- the reply -------------------------------------------------------------
+
+test('parsing: only entries sourced from THIS response survive, scores stay on the rubric and in 0..10', () => {
+  const seen = research.seenUrls(reply(GOOD).content);
+  const p = research.parseReply(JSON.stringify(GOOD), { seen, dimensions: ['human_gates', 'open_source_ethos'] });
+  assert.equal(p.ok, true);
+  assert.deepEqual(p.entries.map((e) => e.sourceUrl), [NEWS_URL, `${FETCHED_URL}/`], 'the invented link is dropped');
+  assert.deepEqual(p.entries.map((e) => e.confidence), [3, 2]);
+  assert.equal(p.entries[1].sourceLabel, 'blog.example.com', 'an empty label falls back to the host');
+  assert.deepEqual(p.scores.map((s) => [s.dimension, s.value]), [['overall', 6.2], ['human_gates', 7]]);
+  assert.deepEqual(p.dropped, { entries: 1, scores: 2, candidates: 0 });
+  assert.equal(p.candidates[0].name, 'Newco Agents');
+});
+
+test('parsing: a malformed reply is an error, never a partial guess', () => {
+  const seen = new Set([NEWS_URL]);
+  for (const bad of ['', 'not json', '{"entries": [}', '[]', '{"entries": []}', JSON.stringify({ entries: 'x', scores: [], candidates: [] }), 'null']) {
+    assert.deepEqual(research.parseReply(bad, { seen }), { ok: false, error: 'malformed_reply' }, `input: ${bad}`);
+  }
+  const fenced = '```json\n' + JSON.stringify({ entries: [], scores: [], candidates: [] }) + '\n```';
+  assert.equal(research.parseReply(fenced, { seen }).ok, true, 'a fenced object is still the object');
+  const noSource = { entries: [{ type: 'news', takeaway: 'x', source_url: '', source_label: '', confidence: 'high', dimension: null }], scores: [], candidates: [] };
+  assert.equal(research.parseReply(JSON.stringify(noSource), { seen }).entries.length, 0, 'no source, no entry');
+});
+
+test('a refusal, a max_tokens or pause_turn stop, a tool error or a thrown call ends the item, costed', async () => {
+  const item = { name: 'Acme', kind: 'competitor' };
+  const rules = built.rules;
+  for (const stop of ['refusal', 'max_tokens', 'pause_turn']) {
+    const { client } = fakeClient(() => reply(GOOD, { stop }));
+    const r = await research.researchItem({ client, item, rules, today: '2026-11-20' });
+    assert.deepEqual([r.ok, r.error, r.costUsd], [false, stop, REPLY_COST]);
+  }
+  const toolErr = { type: 'web_fetch_tool_result', tool_use_id: 'f2', content: { type: 'web_fetch_tool_result_error', error_code: 'url_not_accessible' } };
+  let r = await research.researchItem({ client: fakeClient(() => reply(GOOD, { extra: [toolErr] })).client, item, rules, today: 'x' });
+  assert.deepEqual([r.ok, r.error], [false, 'tool_error:url_not_accessible']);
+  const capped = { type: 'web_search_tool_result', tool_use_id: 's9', content: { type: 'web_search_tool_result_error', error_code: 'max_uses_exceeded' } };
+  r = await research.researchItem({ client: fakeClient(() => reply(GOOD, { extra: [capped] })).client, item, rules, today: 'x' });
+  assert.equal(r.ok, true, 'the search cap refusing a 4th search is the cap working, not a failure');
+  r = await research.researchItem({ client: fakeClient(() => reply('I could not find anything.')).client, item, rules, today: 'x' });
+  assert.deepEqual([r.ok, r.error, r.costUsd], [false, 'malformed_reply', REPLY_COST]);
+  r = await research.researchItem({ client: { messages: { create: async () => { const e = new Error('overloaded'); e.status = 529; throw e; } } }, item, rules, today: 'x' });
+  assert.deepEqual([r.ok, r.error, r.costUsd], [false, 'api_error 529', 0]);
+});
+
+test('cost: tokens at the Sonnet 5 rate plus $0.01 a search, and an item ceiling that covers the bounds', () => {
+  assert.equal(WEB_SEARCH_USD_PER_REQUEST, 0.01);
+  assert.equal(priceWebSearches(3), 0.03);
+  assert.equal(priceWebSearches(undefined), 0);
+  assert.equal(research.priceResponse(reply(GOOD).usage), REPLY_COST);
+  assert.equal(research.priceResponse({ input_tokens: 1000, cache_read_input_tokens: 3000, output_tokens: 0 }), 0.0026);
+  const ceiling = research.itemCeilingUsd();
+  assert.ok(Math.abs(ceiling - 0.27) < 1e-9, `ceiling ${ceiling}`);
+  const worst = research.priceResponse({ input_tokens: 80_000, output_tokens: 8_000, server_tool_use: { web_search_requests: 3 } });
+  assert.ok(worst <= ceiling + 1e-9, 'a response at every bound fits in the ceiling');
+});
+
+// --- a run on seed data ----------------------------------------------------
+
+test('a run on seed data writes sourced entries, score snapshots and proposals, and mirrors each item cost', async () => {
+  const { d } = deps();
+  const st = memStore();
+  const r = await run.runDue({ ...d, store: st });
+  assert.equal(r.outcome, 'done');
+  assert.equal(r.done, 4);
+  assert.equal(st.state.entries.length, 8, 'two sourced entries per item; the invented one never lands');
+  assert.ok(st.state.entries.every((e) => e.sourceUrl === NEWS_URL || e.sourceUrl === `${FETCHED_URL}/`));
+  assert.equal(st.state.scores.length, 8);
+  assert.ok(st.state.scores.every((s) => s.reason));
+  const runId = r.runId;
+  assert.equal(st.state.runs.find((x) => x.id === runId).status, 'done');
+  // The cost roll-up: one cost_log row per item, in-process, under market-watch:<run id>.
+  const rows = [...d.economy.rows.values()];
+  assert.equal(rows.length, 4);
+  for (const row of rows) {
+    assert.equal(row.source, `market-watch:${runId}`);
+    assert.match(row.sourceRef, /^item-\d+$/);
+    assert.equal(row.category, 'api');
+    assert.equal(row.amountUsd, REPLY_COST);
+    assert.equal(row.builderId, null, 'the project pays, not a builder');
+    assert.ok(row.description.includes(P), 'recorded against the project');
+  }
+  assert.ok(Math.abs(r.costUsd - 4 * REPLY_COST) < 1e-9);
+});
+
+test('a new candidate becomes a proposal, never a tracked item', async () => {
+  const { d } = deps();
+  const st = memStore();
+  const before = st.state.items.length;
+  await run.runDue({ ...d, store: st });
+  assert.equal(st.state.items.length, before, 'no item added');
+  assert.ok(st.state.proposals.length >= 1);
+  assert.ok(st.state.proposals.every((p) => p.kind === 'add_item' && p.origin === 'run' && p.project === P));
+  // and the SQL that writes it targets proposals only, scoped to the project
+  assert.match(store.SQL.PROPOSAL_SQL, /INSERT INTO market_watch_proposals/);
+  assert.doesNotMatch(store.SQL.PROPOSAL_SQL, /INSERT INTO market_watch_items/);
+});
+
+// --- nothing runs, and the row says why ---------------------------------------
+
+test('Market Watch off: nothing runs, the run row says off', async () => {
+  const { d, fc, keysSeen } = deps();
+  const st = memStore({ settings: { enabled: false, monthly_cap_usd: 20, cadence: 'weekly' } });
+  const r = await run.runDue({ ...d, store: st });
+  assert.deepEqual([r.outcome, r.reason], ['skipped', 'off']);
+  assert.equal(st.state.runs.at(-1).status, 'skipped');
+  assert.equal(st.state.runs.at(-1).reason, 'off');
+  assert.equal(fc.calls.length + keysSeen.length, 0);
+});
+
+test('no key: nothing runs, the run row says no_key', async () => {
+  const { d, fc, keysSeen } = deps({ d: { readKey: async () => null } });
+  const st = memStore();
+  const r = await run.runDue({ ...d, store: st });
+  assert.deepEqual([r.outcome, r.reason], ['skipped', 'no_key']);
+  assert.deepEqual([st.state.runs.at(-1).status, st.state.runs.at(-1).reason], ['skipped', 'no_key']);
+  assert.equal(fc.calls.length + keysSeen.length, 0);
+});
+
+// --- the cap ---------------------------------------------------------------
+
+test('over the cap before the run: skipped and visible, with the cap and the spend recorded', async () => {
+  const { d, fc } = deps();
+  const st = memStore({ settings: { enabled: true, monthly_cap_usd: 5, cadence: 'weekly' },
+    runs: [{ id: 1, project: P, status: 'done', created_at: NOW - 10 * DAY }],
+    runItems: [{ run_id: 1, item_id: 1, status: 'done', cost_usd: 4.8 }] });
+  const r = await run.runDue({ ...d, store: st });
+  assert.deepEqual([r.outcome, r.reason], ['skipped', 'cap_reached']);
+  const row = st.state.runs.at(-1);
+  assert.deepEqual([row.status, row.reason, row.capUsd, row.spentBeforeUsd], ['skipped', 'cap_reached', 5, 4.8]);
+  assert.equal(fc.calls.length, 0);
+});
+
+test('the cap is checked before EVERY item: a run stops mid-way, partial, and never passes the cap', async () => {
+  const { d, fc } = deps();
+  // $0.70 cap, $0.27 ceiling, $0.075 an item: items 1..6 fit (0.375 + 0.27 = 0.645), the 7th would not.
+  const items = built.items.slice(0, 10).map((it, i) => ({ id: i + 1, project: P, kind: it.kind, name: it.name, url: it.url, status: 'active' }));
+  const st = memStore({ items, settings: { enabled: true, monthly_cap_usd: 0.7, cadence: 'weekly' } });
+  const r = await run.runDue({ ...d, store: st });
+  assert.deepEqual([r.outcome, r.reason, r.done], ['partial', 'cap_reached', 6]);
+  assert.equal(fc.calls.length, 6, 'no call after the cap check refused');
+  assert.equal(st.state.runs.at(-1).status, 'partial');
+  const spent = [...st.state.runItems.values()].reduce((a, x) => a + x.cost_usd, 0);
+  assert.ok(spent <= 0.7);
+  assert.ok(st.state.spendReads >= 7, 'the spend was re-read before each item');
+});
+
+test('a cap of zero, or one that is not a number, allows nothing (fail closed)', async () => {
+  for (const cap of [0, -1, NaN, 'lots']) {
+    const { d, fc } = deps();
+    const st = memStore({ settings: { enabled: true, monthly_cap_usd: cap, cadence: 'weekly' } });
+    const r = await run.runDue({ ...d, store: st });
+    assert.equal(r.reason, 'cap_reached', `cap ${cap}`);
+    assert.equal(fc.calls.length, 0);
+  }
+});
+
+test('an unreadable spend runs nothing: before the run it is a skipped row, mid-run it stops the run', async () => {
+  let { d, fc } = deps();
+  let st = memStore({ spendThrows: true });
+  let r = await run.runDue({ ...d, store: st });
+  assert.deepEqual([r.outcome, r.reason, fc.calls.length], ['skipped', 'spend_unreadable', 0]);
+  ({ d, fc } = deps());
+  st = memStore({ spendThrowsAfter: 3 }); // the precheck read, then items 1 and 2
+  r = await run.runDue({ ...d, store: st });
+  assert.deepEqual([r.outcome, r.reason, r.done, fc.calls.length], ['partial', 'spend_unreadable', 2, 2]);
+});
+
+// --- resume after a cut-off --------------------------------------------------
+
+test('a cut-off run resumes only the items it has not finished, and never mirrors a cost twice', async () => {
+  const { d, fc } = deps();
+  const st = memStore({
+    runs: [{ id: 7, project: P, status: 'running', claimed_until: NOW - 60_000, created_at: NOW - 2 * 3600_000 }],
+    runItems: [
+      { run_id: 7, item_id: 1, status: 'done', cost_usd: 0.09 },
+      { run_id: 7, item_id: 2, status: 'error', error: 'refusal', cost_usd: 0.02 },
+      { run_id: 7, item_id: 3, status: 'running' }, // the call in flight when the deploy hit
+    ],
+  });
+  // The first run's mirrors are already in cost_log.
+  await d.economy.logCost({ source: 'market-watch:7', sourceRef: 'item-1', amountUsd: 0.09 });
+  d.economy.calls.length = 0;
+  const r = await run.runDue({ ...d, store: st });
+  assert.equal(r.resumed, true);
+  assert.equal(r.runId, 7);
+  assert.equal(fc.calls.length, 2, 'items 3 and 4 only');
+  assert.deepEqual(d.economy.calls.map((c) => c.sourceRef).sort(), ['item-3', 'item-4']);
+  assert.equal(st.state.runs[0].status, 'done');
+  // A second write of an already-recorded item is refused by the store, so nothing is mirrored.
+  const again = await st.recordItem(P, 7, 3, { ok: true, entries: [], scores: [], candidates: [], costUsd: 0.5 });
+  assert.equal(again.recorded, false);
+});
+
+test('a run still leased by another process is left alone (a lapsed lease is the resume case above)', async () => {
+  const { d, fc } = deps();
+  const st = memStore({ runs: [{ id: 9, project: P, status: 'running', claimed_until: NOW + 60_000, created_at: NOW - 600_000 }] });
+  assert.deepEqual(await run.runDue({ ...d, store: st }), { skipped: 'in_flight', runId: 9 });
+  assert.equal(fc.calls.length, 0);
+});
+
+test('due by the ledger: a week after the last run (minus 30 minutes), never by the boot', () => {
+  assert.equal(run.isDue(null, 'weekly', NOW), true, 'no run yet');
+  assert.equal(run.isDue({ created_at: NOW - 3 * DAY }, 'weekly', NOW), false);
+  assert.equal(run.isDue({ created_at: NOW - 7 * DAY + 20 * 60_000 }, 'weekly', NOW), true);
+  assert.equal(run.isDue({ created_at: NOW - 7 * DAY + 40 * 60_000 }, 'weekly', NOW), false);
+  assert.equal(run.isDue({ created_at: NOW - 10 * DAY }, 'biweekly', NOW), false);
+});
+
+test('a run that is not due does nothing at all', async () => {
+  const { d, fc } = deps();
+  const st = memStore({ runs: [{ id: 1, project: P, status: 'done', created_at: NOW - 2 * DAY }] });
+  assert.deepEqual(await run.runDue({ ...d, store: st }), { skipped: 'not_due' });
+  assert.equal(st.state.runs.length, 1, 'not even a skipped row');
+  assert.equal(fc.calls.length, 0);
+});
+
+// --- the cross-project guard -------------------------------------------------
+
+test('a run never researches or writes another project\'s item', async () => {
+  const { d, fc } = deps();
+  const st = memStore();
+  st.state.items[1].project = OTHER; // a read that leaked a foreign row
+  const r = await run.runDue({ ...d, store: st });
+  assert.equal(r.refused, 1);
+  assert.equal(fc.calls.length, 3, 'no spend on the foreign item');
+  assert.ok(!st.state.entries.some((e) => e.item_id === 2));
+  assert.ok(![...d.economy.rows.values()].some((x) => x.sourceRef === 'item-2'));
+  // and the store itself refuses it, even if the caller did not
+  await assert.rejects(st.recordItem(P, r.runId, 2, { ok: true, entries: [], scores: [], candidates: [], costUsd: 0 }), /cross_project/);
+});
+
+test('store.js: the guard is in the SQL, and a foreign item writes nothing', async () => {
+  const calls = [];
+  const client = {
+    async query(sql, params) { calls.push({ sql, params }); return /FROM market_watch_items i\s+JOIN market_watch_runs/.test(sql) ? { rows: [] } : { rows: [], rowCount: 0 }; },
+    release() {},
+  };
+  const pool = { connect: async () => client };
+  await assert.rejects(store.recordItem(pool, P, 5, 2, { ok: true, entries: [{ type: 'news', takeaway: 't', sourceUrl: NEWS_URL, sourceLabel: '', confidence: 2, dimension: null }], scores: [], candidates: [], costUsd: 0.1 }), /cross_project/);
+  assert.ok(!calls.some((c) => /INSERT/.test(c.sql)), 'nothing inserted');
+  assert.ok(calls.some((c) => c.sql === 'ROLLBACK'));
+  for (const sql of [store.SQL.GUARD_SQL, store.SQL.ENTRY_SQL, store.SQL.SCORE_SQL, store.SQL.START_ITEM_SQL]) {
+    assert.match(sql, /\.project = \$1/, `scoped to the project: ${sql.trim().slice(0, 50)}`);
+  }
+  assert.match(store.SQL.PROPOSAL_SQL, /SELECT \$1::text, 'add_item', 'run'/);
+});
+
+test('store.js: an item result is recorded once; a second write rolls back and reports it', async () => {
+  const calls = [];
+  const client = {
+    async query(sql, params) {
+      calls.push(sql);
+      if (/JOIN market_watch_runs r ON r.project = i.project/.test(sql)) return { rows: [{ '?column?': 1 }] };
+      if (/UPDATE market_watch_run_items/.test(sql)) return { rows: [] }; // already finished
+      return { rows: [], rowCount: 1 };
+    },
+    release() {},
+  };
+  const r = await store.recordItem({ connect: async () => client }, P, 5, 2, { ok: false, error: 'refusal', costUsd: 0.02 });
+  assert.equal(r.recorded, false);
+  assert.equal(calls.at(-1), 'ROLLBACK');
+});
+
+// --- the poller --------------------------------------------------------------
+
+test('the poller tick never throws, and is quiet on a machine with no database', async () => {
+  const boom = { openRun: async () => { throw new Error('connect ECONNREFUSED 127.0.0.1:5432'); } };
+  assert.deepEqual(await weekly.tick({ project: P, store: boom, readKey: async () => KEY }), { skipped: 'db_unreachable' });
+  const bad = { openRun: async () => { throw new Error('syntax error'); } };
+  let reported = 0;
+  const r = await weekly.tick({ project: P, store: bad, readKey: async () => KEY, reportError: () => { reported += 1; } });
+  assert.equal(r.skipped, 'error');
+  assert.equal(reported, 1);
+  assert.deepEqual(await weekly.tick({ project: null }), { skipped: 'no_project_origin' });
+});
+
+test('the migration widens proposals for the run, adds the key columns, and one open run per project', () => {
+  const sql = readFileSync(new URL('../modules/market-watch/migrations/market_watch_002_run.sql', import.meta.url), 'utf8');
+  assert.match(sql, /CHECK \(origin IN \('member', 'weekly_ask', 'run'\)\)/);
+  assert.match(sql, /anthropic_key_enc LIKE 'v1\.%'/);
+  assert.match(sql, /market_watch_runs_one_open\s+ON market_watch_runs \(project\) WHERE status IN \('queued', 'running'\)/);
+  assert.match(store.SQL.CREATE_SQL, /ON CONFLICT \(project\) WHERE status IN \('queued', 'running'\) DO NOTHING/);
+});