@bongos/core 1.23.22 → 1.24.1

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

@@ -0,0 +1,249 @@
+-- market_watch_001_tables.sql - the Market Watch data model (task 1004936, goal 1000137).
+--
+-- What the owner-approved screens (docs/design/mocks/market-watch/) and the run model of
+-- ADR 0393 need stored. Everything else they show is DERIVED in modules/market-watch/db.js
+-- (an item's level and streak, a dimension's sparkline, this month's spend), so there is
+-- one source for each number and nothing to keep in step.
+--
+--   market_watch_settings        one row per project: on/off, the monthly AI cap, cadence
+--   market_watch_rule_versions   the watch rules as versioned rows; 'proposed' is the next one
+--   market_watch_items           what is watched: competitor | partner | topic
+--   market_watch_runs            one row per run, including skipped ones (ADR 0393 s3-4)
+--   market_watch_run_items       per-item progress inside a run: what makes a cut-off run
+--                                resumable without charging an item twice (ADR 0393 s2)
+--   market_watch_log_entries     the case file: found, run, type, takeaway, confidence, source
+--   market_watch_score_snapshots one value per item, dimension and run: the sparklines
+--   market_watch_weekly_asks     the weekly question to every member
+--   market_watch_ask_answers     each member's taps on it
+--   market_watch_proposals       a change asked for by a member or born of a weekly-ask tap
+--
+-- PROJECT. Every project is its own instance with its own database (ADR 0393 Context), so a
+-- row's `project` is that instance's public origin, read from branding at write time and
+-- never hardcoded. It is still a column so a read can never mix two projects if a database
+-- is ever shared, and so the hub can tell its own seed rows from anything else.
+--
+-- PEOPLE. A person is a builders(id). Seeded rows have no author (NULL): the 2026-10-28
+-- research was not a member's act, and naming someone here would be inventing a record.
+--
+-- Additive and market_watch_-prefixed (ADR 0083 s5, fitness checkModuleMigrationsAdditive).
+-- Idempotent: every statement survives a re-run on a database that already has it.
+
+BEGIN;
+
+-- The project's switch, cap and cadence (the settings screen). `enabled` is the owner's
+-- watch switch, distinct from the module being enabled: the module can be on with the
+-- watch paused. The cap is in US dollars, like cost_log.
+CREATE TABLE IF NOT EXISTS market_watch_settings (
+  project           text PRIMARY KEY,
+  enabled           boolean     NOT NULL DEFAULT false,
+  monthly_cap_usd   numeric(10,2) NOT NULL DEFAULT 20 CHECK (monthly_cap_usd >= 0),
+  cadence           text        NOT NULL DEFAULT 'weekly'
+                    CHECK (cadence IN ('weekly', 'biweekly', 'monthly')),
+  updated_by        bigint      REFERENCES builders(id),
+  updated_at        timestamptz NOT NULL DEFAULT now()
+);
+
+-- The watch rules. One row per version; the rules page's slider walks them by `version`.
+-- Exactly one 'active' version per project (the rules in use) and at most one 'proposed'
+-- (the next one), each held by a partial unique index rather than by every writer's care.
+-- rubric is { "<kind>": [ { "key", "label", "definition", "weight" } ] }: competitors and
+-- partners are scored on different dimensions.
+CREATE TABLE IF NOT EXISTS market_watch_rule_versions (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  version           integer     NOT NULL CHECK (version >= 1),
+  status            text        NOT NULL DEFAULT 'proposed'
+                    CHECK (status IN ('proposed', 'active', 'superseded', 'rejected')),
+  search_queries    jsonb       NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(search_queries) = 'array'),
+  sources           jsonb       NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(sources) = 'array'),
+  rubric            jsonb       NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(rubric) = 'object'),
+  instructions      text        NOT NULL DEFAULT '',
+  summary           text        NOT NULL DEFAULT '',          -- the slider's one line ("+ GitHub releases as a source")
+  reason            text        NOT NULL CHECK (length(btrim(reason)) > 0),
+  author_id         bigint      REFERENCES builders(id),      -- NULL: seeded, not a member's act
+  approved_by       bigint      REFERENCES builders(id),
+  approved_at       timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (project, version)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_rule_versions_one_active
+  ON market_watch_rule_versions (project) WHERE status = 'active';
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_rule_versions_one_proposed
+  ON market_watch_rule_versions (project) WHERE status = 'proposed';
+
+-- What is watched. Keyed by (project, kind, url, name): the research scored five names both as
+-- a competitor and as a partner, on different rubrics, so they are two items. Removing an
+-- item is status 'removed', never a DELETE: its log and scores stay readable, and a re-run
+-- of the seed cannot bring it back (ON CONFLICT DO NOTHING finds the removed row).
+CREATE TABLE IF NOT EXISTS market_watch_items (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  kind              text        NOT NULL CHECK (kind IN ('competitor', 'partner', 'topic')),
+  name              text        NOT NULL CHECK (length(btrim(name)) > 0),
+  url               text        NOT NULL,                     -- a topic has none: ''
+  category          text        NOT NULL DEFAULT '',
+  description       text        NOT NULL DEFAULT '',          -- "what it is", one line
+  why_tracked       text        NOT NULL DEFAULT '',
+  facts             jsonb       NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(facts) = 'object'),
+  status            text        NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'paused', 'removed')),
+  added_via         text        NOT NULL DEFAULT 'member'
+                    CHECK (added_via IN ('seed', 'member', 'proposal', 'run')),
+  added_by          bigint      REFERENCES builders(id),
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (project, kind, url, name)
+);
+CREATE INDEX IF NOT EXISTS market_watch_items_project_status
+  ON market_watch_items (project, status, kind);
+
+-- One row per run, INCLUDING the runs that never started: a skipped run is a row with a
+-- reason, never only a log line (ADR 0393 "What R04 must build" s4). The settings strip
+-- reads these, and a dash there is a 'skipped' row.
+--   status:  queued -> running -> done | partial | skipped | failed
+--   reason:  why a run is partial, skipped or failed (NULL when done)
+--   trigger: 'poller' (the weekly clock), 'manual' (an owner's "run now"), 'seed' (the
+--            2026-10-28 research loaded as run zero, so seeded scores carry a run id)
+-- claimed_until is the single-flight lease: the poller takes a run with
+-- UPDATE ... WHERE status IN ('queued','running') AND claimed_until < now() RETURNING, so a
+-- second process on the same database cannot run it too, and a run whose process died
+-- mid-way is picked up again once its lease lapses.
+CREATE TABLE IF NOT EXISTS market_watch_runs (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  status            text        NOT NULL DEFAULT 'queued'
+                    CHECK (status IN ('queued', 'running', 'done', 'partial', 'skipped', 'failed')),
+  reason            text        CHECK (reason IS NULL OR reason IN
+                    ('off', 'no_key', 'cap_reached', 'spend_unreadable', 'timeout', 'error')),
+  trigger           text        NOT NULL DEFAULT 'poller' CHECK (trigger IN ('poller', 'manual', 'seed')),
+  rule_version_id   bigint      REFERENCES market_watch_rule_versions(id),
+  cap_usd           numeric(10,2),                            -- the cap as it stood when the run was planned
+  spent_before_usd  numeric(10,4),                            -- this month's spend read before the run
+  claimed_until     timestamptz,
+  started_at        timestamptz,
+  finished_at       timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  CHECK (status NOT IN ('skipped', 'partial', 'failed') OR reason IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS market_watch_runs_project_created
+  ON market_watch_runs (project, created_at DESC);
+-- The 2026-10-28 research is ONE run per project: what makes the seed idempotent.
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_runs_one_seed
+  ON market_watch_runs (project) WHERE trigger = 'seed';
+
+-- Per-item progress inside a run (ADR 0393 s2, "resumable"). One row per (run, item),
+-- written as each item finishes. A resumed run does only the rows that are not 'done',
+-- and an item's cost is recorded here once: cost_usd is set in the same statement that
+-- moves the row to 'done', so a retry finds it done and never prices it again. The
+-- cost_log projection (source market-watch:<run id>) keys on (run, item) for the same
+-- reason.
+CREATE TABLE IF NOT EXISTS market_watch_run_items (
+  run_id            bigint      NOT NULL REFERENCES market_watch_runs(id),
+  item_id           bigint      NOT NULL REFERENCES market_watch_items(id),
+  status            text        NOT NULL DEFAULT 'pending'
+                    CHECK (status IN ('pending', 'running', 'done', 'error', 'skipped')),
+  error             text,                                     -- refusal | max_tokens | tool_error | ... (ADR 0393 s1)
+  cost_usd          numeric(10,4) CHECK (cost_usd IS NULL OR cost_usd >= 0),
+  started_at        timestamptz,
+  finished_at       timestamptz,
+  PRIMARY KEY (run_id, item_id),
+  CHECK (status <> 'done' OR cost_usd IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS market_watch_run_items_open
+  ON market_watch_run_items (run_id) WHERE status <> 'done';
+
+-- The case file. confidence is 1 (low) ... 3 (high), the mock's three dots. source_url is
+-- required: an entry without a source is not an entry (ADR 0393 s1 drops them in code;
+-- this is the floor no future writer can step under). One takeaway per item and run is
+-- stored once, so a resumed run that rewrites an item's findings cannot duplicate them.
+CREATE TABLE IF NOT EXISTS market_watch_log_entries (
+  id                bigserial PRIMARY KEY,
+  item_id           bigint      NOT NULL REFERENCES market_watch_items(id),
+  run_id            bigint      REFERENCES market_watch_runs(id),
+  type              text        NOT NULL CHECK (type IN ('insight', 'news', 'datapoint')),
+  found_on          date        NOT NULL DEFAULT current_date,
+  takeaway          text        NOT NULL CHECK (length(btrim(takeaway)) > 0),
+  dimension         text,                                     -- the rubric key it bears on, if any
+  source_url        text        NOT NULL CHECK (source_url ~ '^https?://'),
+  source_label      text        NOT NULL DEFAULT '',
+  confidence        smallint    NOT NULL CHECK (confidence BETWEEN 1 AND 3),
+  pinned            boolean     NOT NULL DEFAULT false,
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_log_entries_once
+  ON market_watch_log_entries (item_id, run_id, md5(takeaway));
+CREATE INDEX IF NOT EXISTS market_watch_log_entries_item
+  ON market_watch_log_entries (item_id, found_on DESC, id DESC);
+
+-- Scores over time: one value per (item, dimension, run). 'overall' is a dimension like
+-- the others, so the likeness line and the five dimension lines are one query.
+CREATE TABLE IF NOT EXISTS market_watch_score_snapshots (
+  id                bigserial PRIMARY KEY,
+  item_id           bigint      NOT NULL REFERENCES market_watch_items(id),
+  run_id            bigint      NOT NULL REFERENCES market_watch_runs(id),
+  dimension         text        NOT NULL CHECK (length(btrim(dimension)) > 0),
+  value             numeric(4,1) NOT NULL CHECK (value BETWEEN 0 AND 10),
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (item_id, run_id, dimension)
+);
+
+-- The weekly question. question_key names which of the card's questions this is
+-- ('rival' = what counts as a competitor, 'watch' = what else should we watch); options
+-- are the chips, each { "label", "example" }.
+CREATE TABLE IF NOT EXISTS market_watch_weekly_asks (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  week_of           date        NOT NULL,
+  question_key      text        NOT NULL CHECK (length(btrim(question_key)) > 0),
+  prompt            text        NOT NULL CHECK (length(btrim(prompt)) > 0),
+  options           jsonb       NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(options) = 'array'),
+  closes_at         timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (project, week_of, question_key)
+);
+
+-- A member's taps. A chip is a `choice`; "name one" and "add a topic" carry free_text.
+-- One row per member and choice, so a second tap on the same chip is a no-op.
+CREATE TABLE IF NOT EXISTS market_watch_ask_answers (
+  id                bigserial PRIMARY KEY,
+  ask_id            bigint      NOT NULL REFERENCES market_watch_weekly_asks(id),
+  builder_id        bigint      NOT NULL REFERENCES builders(id),
+  choice            text        NOT NULL CHECK (length(btrim(choice)) > 0),
+  free_text         text,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (ask_id, builder_id, choice)
+);
+
+-- A change someone asked for. origin 'member' is the item page's "Propose a change" or
+-- the rules page; 'weekly_ask' is born of a tap (answer_id says which). What it changes
+-- is `kind` plus the row it points at; `payload` carries the specifics (a new score, the
+-- source to add, the corrected text, the proposed rules version's id).
+CREATE TABLE IF NOT EXISTS market_watch_proposals (
+  id                bigserial PRIMARY KEY,
+  project           text        NOT NULL,
+  kind              text        NOT NULL CHECK (kind IN
+                    ('rule_change', 'add_item', 'remove_item', 'rescore', 'move_kind', 'add_source', 'correct_entry')),
+  origin            text        NOT NULL CHECK (origin IN ('member', 'weekly_ask')),
+  item_id           bigint      REFERENCES market_watch_items(id),
+  log_entry_id      bigint      REFERENCES market_watch_log_entries(id),
+  rule_version_id   bigint      REFERENCES market_watch_rule_versions(id),
+  answer_id         bigint      REFERENCES market_watch_ask_answers(id),
+  payload           jsonb       NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(payload) = 'object'),
+  reason            text        NOT NULL DEFAULT '',
+  proposed_by       bigint      REFERENCES builders(id),
+  status            text        NOT NULL DEFAULT 'open'
+                    CHECK (status IN ('open', 'approved', 'rejected', 'withdrawn', 'applied')),
+  decided_by        bigint      REFERENCES builders(id),
+  decided_at        timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  CHECK (origin <> 'weekly_ask' OR answer_id IS NOT NULL),
+  CHECK (kind <> 'rule_change' OR rule_version_id IS NOT NULL),
+  CHECK (kind NOT IN ('remove_item', 'rescore', 'move_kind', 'add_source') OR item_id IS NOT NULL),
+  CHECK (kind <> 'correct_entry' OR log_entry_id IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS market_watch_proposals_open
+  ON market_watch_proposals (project, created_at DESC) WHERE status = 'open';
+-- One tap is one proposal: re-pooling the answers is a no-op.
+CREATE UNIQUE INDEX IF NOT EXISTS market_watch_proposals_one_per_answer
+  ON market_watch_proposals (answer_id) WHERE answer_id IS NOT NULL;
+
+COMMIT;

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