create-walle 0.10.0 → 0.10.2

package/template/wall-e/lib/helper-rules/store.js

@@ -0,0 +1,667 @@
+'use strict';
+
+// Lead-cost routing WP-5a (design §6.6/§6.8, contract §2): the helper-rules record's ONLY
+// writer. The four write ops are registered as CUSTOM_BRAIN_CALLS (loops/brain-custom-writes.js)
+// and whitelisted (brain/owner-call-whitelist.js), so every caller reaches them through
+// brainWrite(method, ...) — the loop holds a read-write brain, the scheduler worker routes the
+// same call to the brain owner. This module takes the handle as its first argument and never
+// requires '../../brain' at module top, so a test can hand it a temp database.
+//
+// The reads (readCellState / readCell / readTrailingOutcomes / listCells) are synchronous and
+// pure-ish: they never create the tables and never throw — a missing table (a brain built
+// before migration 100) reads as 'on', the same fail-open default lib/helper-rules/cell-state.js
+// uses, so nothing that consults a cell can be broken by the record's absence.
+
+const { LABEL_VERSION, labelFromFacts } = require('./label');
+const {
+  EXPLORE_OPEN_TTL_MS,
+  REASONS,
+  EXPLORE_DEMOTION_REASONS,
+  WINDOW,
+  evaluateCell,
+} = require('./evaluate');
+// The kv watermark migration 101 seeds (`helper_rules.relabelled_to`). lib/ -> brain/ is a
+// leaf-to-leaf edge: helper-rules-schema.js requires nothing, so there is no cycle.
+const { RELABELLED_TO_KEY } = require('../../brain/helper-rules-schema');
+
+const CELL_STATES = Object.freeze(['on', 'off', 'probe']);
+const KIND_BY_PREFIX = Object.freeze({ 'wait-watch': 'wait-watch', explore: 'explore' });
+const DEFAULT_LEAD_BURST_USD = 0.46; // mirrors brain/helper-rules-schema.js's lead_burst_usd seed
+const LEAD_BURST_USD_KEY = 'helper_rules.lead_burst_usd';
+
+function kindFromCellKey(cellKey) {
+  const prefix = String(cellKey || '').split('|')[0];
+  return KIND_BY_PREFIX[prefix] || 'wait-watch';
+}
+
+// --- round-2 facts plumbing (D-1/D-5) -----------------------------------------------
+
+/** The row's stored facts object, or null. Never throws: unreadable facts are "no facts". */
+function _parseFacts(value) {
+  if (value == null || value === '') return null;
+  if (typeof value === 'object') return value;
+  try {
+    const parsed = JSON.parse(String(value));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    // HANDLE: a row whose facts_json cannot be parsed carries no observed inputs -- it stays as
+    // stored and is never re-labelled or counted as measured.
+    return null;
+  }
+}
+
+/** `recordOutcome` accepts the facts as an object or as the JSON string the hook sends. */
+function _factsJsonOf(outcome) {
+  const raw = outcome.facts_json;
+  if (raw == null) return null;
+  if (typeof raw === 'string') return raw === '' ? null : raw;
+  if (typeof raw === 'object') return JSON.stringify(raw);
+  return null;
+}
+
+/** D-5: the incoming facts fill nulls in the stored ones -- they never blank a known value. */
+function _nonNullEntries(facts) {
+  const out = {};
+  if (!facts || typeof facts !== 'object') return out;
+  for (const [key, value] of Object.entries(facts)) {
+    if (value !== null && value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+function _toMs(value) {
+  if (value == null) return null;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  const text = String(value).trim();
+  if (!text) return null;
+  // SQLite's datetime('now') writes 'YYYY-MM-DD HH:MM:SS' in UTC -- Date.parse reads that as local.
+  const iso = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}$/.test(text) ? `${text.replace(' ', 'T')}Z` : text;
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+// --- watcher spend from the usage ledger (D-9, WP-4b) -------------------------------
+
+// The one feature string the CTM watcher writes (worker-wait-watcher.js WATCH_FEATURE) and the
+// ledger's window tail: a tick that started inside the window can be journaled a little after the
+// last outcome row was written.
+const WATCHER_LEDGER_FEATURE = 'lead-wait-watch';
+const WATCHER_USD_TAIL_MS = 10 * 60 * 1000;
+
+/** SQLite's `datetime('now')` text form (UTC, no milliseconds) for a comparison against occurred_at. */
+function _sqliteUtc(ms) {
+  return new Date(ms).toISOString().slice(0, 19).replace('T', ' ');
+}
+
+/**
+ * D-9: the watcher spend the cell's trailing window accrued, read from `model_usage_ledger` — the
+ * table the ticks already write (`feature='lead-wait-watch'`, WP-4a stores the watched worker's
+ * ctm_session_id as `session_id`, WP-1 stores the same id on every outcome row as `worker_id`).
+ * The window is the union of the rows' own created_at bounds plus WATCHER_USD_TAIL_MS.
+ * @returns {{usd:number, rows:number}|null} null when the window names no worker, or no ledger row matched
+ */
+function readWatcherUsd(d, outcomes) {
+  if (!d || typeof d.prepare !== 'function') return null;
+  const rows = Array.isArray(outcomes) ? outcomes : [];
+  const workerIds = [...new Set(rows.map((row) => (row && row.worker_id != null ? String(row.worker_id) : '')).filter(Boolean))];
+  if (!workerIds.length) return null;
+  const times = rows.map((row) => _toMs(row && row.created_at)).filter((ms) => ms !== null);
+  if (!times.length) return null;
+  try {
+    const placeholders = workerIds.map(() => '?').join(', ');
+    const row = d.prepare(`
+      SELECT SUM(cost_usd) AS usd, COUNT(*) AS n FROM model_usage_ledger
+       WHERE feature = ? AND session_id IN (${placeholders}) AND occurred_at >= ? AND occurred_at <= ?
+    `).get(WATCHER_LEDGER_FEATURE, ...workerIds, _sqliteUtc(Math.min(...times)), _sqliteUtc(Math.max(...times) + WATCHER_USD_TAIL_MS));
+    const matched = Number(row && row.n) || 0;
+    if (matched <= 0) return null;
+    return { usd: Number(row.usd) || 0, rows: matched };
+  } catch {
+    // expected: a brain predating model_usage_ledger has no watcher spend to read — the metric stays null
+    return null;
+  }
+}
+
+function _readKv(d, key) {
+  try {
+    const row = d.prepare('SELECT value FROM kv_store WHERE key = ?').get(String(key));
+    return row ? row.value : null;
+  } catch {
+    // expected: kv_store is absent on a bare test handle -- no watermark means "never relabelled"
+    return null;
+  }
+}
+
+function _writeKv(d, key, value) {
+  d.prepare(`
+    INSERT INTO kv_store (key, value, updated_at) VALUES (?, ?, datetime('now'))
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+  `).run(String(key), String(value));
+}
+
+/** The label version the one-time relabel/recovery pass has already run for (D-6); 0 when unknown. */
+function readRelabelledTo(d) {
+  const value = Number.parseInt(_readKv(d, RELABELLED_TO_KEY), 10);
+  return Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * D-7: how many of one cell's explore rows carry no measurement -- rows whose facts derive
+ * `unmeasured`, plus rows with no facts at all that are no longer open (a row that never
+ * produced observable inputs can never be a closed hand-off or fallback).
+ */
+function _unmeasuredCount(d, cellKey) {
+  const rows = d.prepare(`
+    SELECT decision, facts_json FROM helper_outcomes WHERE cell_key = ? AND kind = 'explore'
+  `).all(String(cellKey));
+  let count = 0;
+  for (const row of rows) {
+    const facts = _parseFacts(row.facts_json);
+    if (facts) {
+      if (labelFromFacts('explore', facts).decision === 'unmeasured') count += 1;
+    } else if (row.decision !== 'open') {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+// --- reads -------------------------------------------------------------------------
+
+/** `helper_rule_cells` row, or null. Never throws (a missing table is "no row"). */
+function readCell(d, cellKey) {
+  if (!d || typeof d.prepare !== 'function') return null;
+  try {
+    return d.prepare('SELECT * FROM helper_rule_cells WHERE cell_key = ?').get(String(cellKey)) || null;
+  } catch {
+    // expected: helper_rule_cells is absent until migration 100 runs — no row means 'on'
+    return null;
+  }
+}
+
+/**
+ * The one reader callers gate on. A missing table, a missing row, an unparsable state or any
+ * read error is 'on' (fail-open); a user veto is always 'off'.
+ * @returns {'on'|'off'|'probe'}
+ */
+function readCellState(d, cellKey) {
+  const row = readCell(d, cellKey);
+  if (!row) return 'on';
+  if (Number(row.user_veto) === 1) return 'off';
+  const state = typeof row.state === 'string' ? row.state.trim() : '';
+  return CELL_STATES.includes(state) ? state : 'on';
+}
+
+/** The trailing window of a cell's outcomes, most recent first. Never throws. */
+function readTrailingOutcomes(d, cellKey, limit = WINDOW) {
+  if (!d || typeof d.prepare !== 'function') return [];
+  const count = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.floor(Number(limit)) : WINDOW;
+  try {
+    return d.prepare('SELECT * FROM helper_outcomes WHERE cell_key = ? ORDER BY seq DESC LIMIT ?')
+      .all(String(cellKey), count) || [];
+  } catch {
+    // expected: helper_outcomes is absent until migration 100 runs — an empty window changes nothing
+    return [];
+  }
+}
+
+/** Every cell row (the panel and the daily tick enumerate from here). Never throws. */
+function listCells(d) {
+  if (!d || typeof d.prepare !== 'function') return [];
+  try {
+    return d.prepare('SELECT * FROM helper_rule_cells ORDER BY cell_key').all() || [];
+  } catch {
+    // expected: helper_rule_cells is absent until migration 100 runs — no cells yet
+    return [];
+  }
+}
+
+/** The WP-0 census measurement, falling back to the seeded value when the row is missing. */
+function readLeadBurstUsd(d) {
+  try {
+    const row = d.prepare("SELECT value FROM kv_store WHERE key = ?").get(LEAD_BURST_USD_KEY);
+    const value = Number.parseFloat(row?.value);
+    return Number.isFinite(value) ? value : DEFAULT_LEAD_BURST_USD;
+  } catch {
+    // expected: kv_store is absent on a bare test handle — the seeded default is the contract value
+    return DEFAULT_LEAD_BURST_USD;
+  }
+}
+
+// --- the evaluator seam ------------------------------------------------------------
+
+/**
+ * Evaluate one cell and persist the verdict. Writes `helper_rule_cells` (state, metrics,
+ * timestamps) and, ONLY when the state changed, one `helper_rule_events` row.
+ * @returns {{cell_key:string, state:string, changed:boolean}}
+ */
+function evaluateAndApply(d, cellKey) {
+  const key = String(cellKey);
+  const stored = readCell(d, key);
+  const cell = stored || { cell_key: key, kind: kindFromCellKey(key), state: 'on', user_veto: 0, state_changed_at: null };
+  const outcomes = readTrailingOutcomes(d, key, WINDOW);
+  const verdict = evaluateCell(cell, outcomes, { now: Date.now(), leadBurstUsd: readLeadBurstUsd(d), watcherUsd: readWatcherUsd(d, outcomes) });
+  const previousState = stored && typeof stored.state === 'string' && stored.state ? stored.state : 'on';
+  const changed = verdict.state !== previousState;
+  const metricsJson = JSON.stringify(verdict.metrics);
+
+  // One upsert for both cases: a changed state restamps state_changed_at (the probe timer's
+  // zero point); an unchanged one keeps it and only refreshes metrics/updated_at.
+  d.prepare(`
+    INSERT INTO helper_rule_cells (cell_key, kind, state, user_veto, metrics_json, state_changed_at, updated_at)
+    VALUES (@cell_key, @kind, @state, @user_veto, @metrics_json, datetime('now'), datetime('now'))
+    ON CONFLICT(cell_key) DO UPDATE SET
+      state = excluded.state,
+      metrics_json = excluded.metrics_json,
+      state_changed_at = CASE WHEN helper_rule_cells.state = excluded.state
+        THEN COALESCE(helper_rule_cells.state_changed_at, excluded.state_changed_at)
+        ELSE excluded.state_changed_at END,
+      updated_at = excluded.updated_at
+  `).run({
+    cell_key: key,
+    kind: cell.kind || kindFromCellKey(key),
+    state: verdict.state,
+    user_veto: Number(cell.user_veto) === 1 ? 1 : 0,
+    metrics_json: metricsJson,
+  });
+
+  if (changed) {
+    d.prepare('INSERT INTO helper_rule_events (cell_key, from_state, to_state, reason, evidence_json) VALUES (?, ?, ?, ?, ?)')
+      .run(key, previousState, verdict.state, verdict.reason || 'state_change', metricsJson);
+  }
+
+  return { cell_key: key, state: verdict.state, changed };
+}
+
+// --- owner-path writes (CUSTOM_BRAIN_CALLS) ----------------------------------------
+
+/**
+ * Record one watcher wake or exploration outcome. `seq` is per cell (re-labelling the same
+ * `id` replaces the row and keeps its place), then the cell is re-evaluated in the SAME
+ * transaction so the panel never sees an outcome the rules have not accounted for.
+ * @param {{id:string, cell_key:string, kind?:string, label?:string, decision?:string,
+ *          helper_usd?:number, lead_usd?:number, seconds_to_report?:number,
+ *          reread_rate?:number, report_rows?:number, grade_json?:string,
+ *          worker_id?:string, facts_json?:string|object, label_version?:number}} outcome
+ *          Round 2 (§6.4 S-13): `worker_id` makes the row addressable by worker (D-5),
+ *          `facts_json` keeps the observed inputs the label is re-derivable from (D-1), and
+ *          `label_version` defaults to LABEL_VERSION when facts are stored, 1 when they are not.
+ * @returns {{seq:number, cell:{cell_key:string, state:string, changed:boolean}}}
+ */
+function recordOutcome(d, outcome = {}) {
+  const cellKey = String(outcome.cell_key || '');
+  const id = String(outcome.id || '');
+  if (!cellKey) throw new TypeError('helperRulesRecordOutcome: cell_key is required');
+  if (!id) throw new TypeError('helperRulesRecordOutcome: id is required');
+  const factsJson = _factsJsonOf(outcome);
+  const labelVersion = Number.isInteger(outcome.label_version) ? outcome.label_version : (factsJson ? LABEL_VERSION : 1);
+  const run = d.transaction(() => {
+    const existing = d.prepare('SELECT seq FROM helper_outcomes WHERE id = ?').get(id);
+    const row = d.prepare('SELECT COALESCE(MAX(seq), 0) AS max_seq FROM helper_outcomes WHERE cell_key = ?').get(cellKey);
+    const seq = existing ? Number(existing.seq) : Number(row?.max_seq || 0) + 1;
+    d.prepare(`
+      INSERT OR REPLACE INTO helper_outcomes
+        (id, cell_key, kind, seq, label, decision, helper_usd, lead_usd, seconds_to_report, reread_rate, report_rows, grade_json, worker_id, facts_json, label_version, created_at)
+      VALUES
+        (@id, @cell_key, @kind, @seq, @label, @decision, @helper_usd, @lead_usd, @seconds_to_report, @reread_rate, @report_rows, @grade_json, @worker_id, @facts_json, @label_version, datetime('now'))
+    `).run({
+      id,
+      cell_key: cellKey,
+      kind: outcome.kind || kindFromCellKey(cellKey),
+      seq,
+      label: outcome.label ?? null,
+      decision: outcome.decision ?? null,
+      helper_usd: outcome.helper_usd ?? null,
+      lead_usd: outcome.lead_usd ?? null,
+      seconds_to_report: outcome.seconds_to_report ?? null,
+      reread_rate: outcome.reread_rate ?? null,
+      report_rows: outcome.report_rows ?? null,
+      grade_json: outcome.grade_json ?? null,
+      worker_id: outcome.worker_id ?? null,
+      facts_json: factsJson,
+      label_version: labelVersion,
+    });
+    return { seq, cell: evaluateAndApply(d, cellKey) };
+  });
+  return run.immediate();
+}
+
+/**
+ * Close an exploration row (explore cells only — the wait-watch rows are labelled at insert).
+ * A missing id is not an error: WP-5b's dispatch can race a row it never opened.
+ * `seq` is returned alongside the cell because it is the spot-check grader's sampling counter
+ * (WP-6: every 5th completed hand-off per cell), and the caller cannot read it otherwise.
+ * @returns {{closed:boolean, seq?:number, cell?:object}}
+ */
+function closeOutcome(d, id, patch = {}) {
+  const key = String(id || '');
+  if (!key) return { closed: false };
+  const run = d.transaction(() => {
+    const result = d.prepare(`
+      UPDATE helper_outcomes
+         SET decision = COALESCE(?, decision),
+             helper_usd = COALESCE(?, helper_usd),
+             seconds_to_report = COALESCE(?, seconds_to_report),
+             report_rows = COALESCE(?, report_rows)
+       WHERE id = ?
+    `).run(
+      patch.decision ?? null,
+      patch.helper_usd ?? null,
+      patch.seconds_to_report ?? null,
+      patch.report_rows ?? null,
+      key,
+    );
+    if (!result.changes) return { closed: false };
+    const row = d.prepare('SELECT cell_key, seq FROM helper_outcomes WHERE id = ?').get(key);
+    return { closed: true, seq: Number(row.seq), cell: evaluateAndApply(d, row.cell_key) };
+  });
+  return run.immediate();
+}
+
+/**
+ * D-5 (§6.4 S-13): close the open explore row for one worker, resolved here rather than by an
+ * in-memory id — a Wall-E restart, an evicted `openHandoffs` entry or a second process cannot
+ * orphan the row. The label is DERIVED (D-1): the caller hands over the terminal facts, the
+ * stored open-time facts fill every null, and `labelFromFacts` decides. A worker with no open
+ * row is not an error (the same race `closeOutcome` tolerates).
+ * @param {string} workerId the row's `worker_id` (the delegation's ctm_session_id)
+ * @param {{facts?:object}} [patch] the terminal facts (§6.2)
+ * @returns {{closed:boolean, id?:string, seq?:number, cell?:object, labelled?:object, facts?:object}}
+ */
+function closeOutcomeByWorker(d, workerId, { facts } = {}) {
+  const worker = String(workerId || '');
+  if (!worker) return { closed: false };
+  const run = d.transaction(() => {
+    const row = d.prepare(`
+      SELECT id, cell_key, seq, facts_json FROM helper_outcomes
+       WHERE worker_id = ? AND kind = 'explore' AND decision = 'open'
+       ORDER BY seq DESC LIMIT 1
+    `).get(worker);
+    if (!row) return { closed: false };
+    // The stored facts keep opened_at / brief_path / harness; the incoming ones fill every
+    // remaining field. A null in the incoming object never blanks a known stored value.
+    const merged = { ...(_parseFacts(row.facts_json) || {}), ..._nonNullEntries(facts) };
+    const labelled = labelFromFacts('explore', merged);
+    d.prepare(`
+      UPDATE helper_outcomes
+         SET decision = ?, helper_usd = ?, seconds_to_report = ?, report_rows = ?,
+             facts_json = ?, label_version = ?
+       WHERE id = ?
+    `).run(
+      labelled.decision,
+      labelled.helper_usd ?? null,
+      labelled.seconds_to_report ?? null,
+      labelled.report_rows ?? null,
+      JSON.stringify(merged),
+      LABEL_VERSION,
+      row.id,
+    );
+    return {
+      closed: true,
+      id: row.id,
+      seq: Number(row.seq),
+      cell: evaluateAndApply(d, row.cell_key),
+      labelled,
+      facts: merged,
+    };
+  });
+  return run.immediate();
+}
+
+// D-5: the recomputed columns of one explore row — everything except the stored inputs and the
+// version stamp. Compared field by field so `relabelled` counts the rows this pass actually FIXED
+// rather than the rows it merely visited.
+function _exploreDiffers(row, labelled) {
+  return row.decision !== labelled.decision
+    || (row.helper_usd ?? null) !== (labelled.helper_usd ?? null)
+    || (row.seconds_to_report ?? null) !== (labelled.seconds_to_report ?? null)
+    || (row.report_rows ?? null) !== (labelled.report_rows ?? null);
+}
+
+/**
+ * D-5/D-6 (§6.4 S-13): recompute every stored row whose facts exist and whose `label_version`
+ * is behind `to`, then run the one-time recovery pass. Idempotent by construction — a second run
+ * has no candidates and the kv watermark stops the recovery — so it is safe to call on every boot
+ * or from the daily tick.
+ *
+ * A row with `facts_json IS NULL` is NEVER touched (D-1): its inputs were not kept, so there is
+ * nothing to recompute from and it must not be silently rewritten.
+ * @param {{to?:number}} [options]
+ * @returns {{scanned:number, relabelled:number, unmeasured:number, cells_reset:string[]}}
+ */
+function relabel(d, { to = LABEL_VERSION } = {}) {
+  const target = Number.isFinite(Number(to)) ? Math.trunc(Number(to)) : LABEL_VERSION;
+  const run = d.transaction(() => {
+    const rows = d.prepare(`
+      SELECT id, cell_key, kind, decision, label, helper_usd, seconds_to_report, report_rows, facts_json
+        FROM helper_outcomes
+       WHERE facts_json IS NOT NULL AND facts_json <> '' AND label_version < ?
+       ORDER BY cell_key, seq
+    `).all(target);
+    const updateExplore = d.prepare(`
+      UPDATE helper_outcomes
+         SET decision = ?, helper_usd = ?, seconds_to_report = ?, report_rows = ?, label_version = ?
+       WHERE id = ?
+    `);
+    const updateWatch = d.prepare('UPDATE helper_outcomes SET label = ?, label_version = ? WHERE id = ?');
+    const changedByCell = new Map();
+    let relabelled = 0;
+    for (const row of rows) {
+      const facts = _parseFacts(row.facts_json);
+      if (!facts) continue; // HANDLE: unreadable facts are not inputs -- leave the row as stored
+      const labelled = labelFromFacts(row.kind, facts);
+      if (row.kind === 'explore') {
+        if (_exploreDiffers(row, labelled)) {
+          relabelled += 1;
+          changedByCell.set(row.cell_key, (changedByCell.get(row.cell_key) || 0) + 1);
+        }
+        updateExplore.run(
+          labelled.decision,
+          labelled.helper_usd ?? null,
+          labelled.seconds_to_report ?? null,
+          labelled.report_rows ?? null,
+          target,
+          row.id,
+        );
+      } else {
+        if (row.label !== labelled.label) {
+          relabelled += 1;
+          changedByCell.set(row.cell_key, (changedByCell.get(row.cell_key) || 0) + 1);
+        }
+        updateWatch.run(labelled.label, target, row.id);
+      }
+    }
+
+    let cellsReset = [];
+    if (readRelabelledTo(d) < target) {
+      cellsReset = _recoverDemotedCells(d, target, changedByCell);
+    }
+    _writeKv(d, RELABELLED_TO_KEY, target);
+    return {
+      scanned: rows.length,
+      relabelled,
+      unmeasured: _unmeasuredTotal(d, rows),
+      cells_reset: cellsReset,
+    };
+  });
+  return run.immediate();
+}
+
+/** The global D-7 unmeasured count over every explore row (all versions) of the touched cells. */
+function _unmeasuredTotal(d, rows) {
+  const cells = [...new Set(rows.map((row) => row.cell_key))];
+  let total = 0;
+  for (const cell of cells) {
+    if (String(cell).startsWith('explore|')) total += _unmeasuredCount(d, cell);
+  }
+  return total;
+}
+
+/**
+ * D-6: the one-time recovery. A cell the EVALUATOR demoted (its last event reason is one of the
+ * demotion reasons) was demoted on round-1 labels; those verdicts are void (P3), so the cell goes
+ * back to `on` with one audit event and is re-evaluated once — a cell that still fails on v2
+ * labels goes straight back off with a fresh, truthful reason. A vetoed cell and every wait-watch
+ * cell are never touched.
+ */
+function _recoverDemotedCells(d, target, changedByCell) {
+  const cells = d.prepare(`
+    SELECT cell_key, state FROM helper_rule_cells
+     WHERE cell_key LIKE 'explore|%' AND user_veto = 0 AND state IN ('off', 'probe')
+     ORDER BY cell_key
+  `).all();
+  const reset = [];
+  for (const cell of cells) {
+    const lastEvent = d.prepare('SELECT reason FROM helper_rule_events WHERE cell_key = ? ORDER BY id DESC LIMIT 1')
+      .get(cell.cell_key);
+    const previousReason = lastEvent && typeof lastEvent.reason === 'string' ? lastEvent.reason : null;
+    if (!previousReason || !EXPLORE_DEMOTION_REASONS.has(previousReason)) continue;
+    d.prepare(`
+      UPDATE helper_rule_cells SET state = 'on', state_changed_at = datetime('now'), updated_at = datetime('now')
+       WHERE cell_key = ?
+    `).run(cell.cell_key);
+    d.prepare('INSERT INTO helper_rule_events (cell_key, from_state, to_state, reason, evidence_json) VALUES (?, ?, ?, ?, ?)')
+      .run(cell.cell_key, cell.state, 'on', REASONS.LABEL_V2_RESET, JSON.stringify({
+        relabelled: changedByCell.get(cell.cell_key) || 0,
+        unmeasured: _unmeasuredCount(d, cell.cell_key),
+        previous_reason: previousReason,
+      }));
+    evaluateAndApply(d, cell.cell_key);
+    reset.push(cell.cell_key);
+  }
+  return reset;
+}
+
+/**
+ * D-10 (§6.4 S-13): an explore row still open after `ttlMs` was never closed by the hook — a
+ * Wall-E restart, a lead that stopped polling, or a worker that outlived its lead. It is closed
+ * as `abandoned` (excluded from `closed` by D-7) with `facts_json.abandoned_at`, so the panel can
+ * show it instead of an ever-growing "open" set.
+ * @param {{nowMs?:number, ttlMs?:number}} [options]
+ * @returns {{abandoned:number}}
+ */
+function sweepAbandoned(d, { nowMs = Date.now(), ttlMs = EXPLORE_OPEN_TTL_MS } = {}) {
+  const now = Number.isFinite(Number(nowMs)) ? Number(nowMs) : Date.now();
+  const ttl = Number.isFinite(Number(ttlMs)) ? Number(ttlMs) : EXPLORE_OPEN_TTL_MS;
+  const run = d.transaction(() => {
+    const rows = d.prepare(`
+      SELECT id, cell_key, seq, facts_json, created_at FROM helper_outcomes
+       WHERE kind = 'explore' AND decision = 'open'
+       ORDER BY cell_key, seq
+    `).all();
+    const update = d.prepare('UPDATE helper_outcomes SET decision = ?, facts_json = ?, label_version = ? WHERE id = ?');
+    const touched = new Set();
+    let abandoned = 0;
+    for (const row of rows) {
+      const facts = _parseFacts(row.facts_json) || {};
+      const openedAt = Number.isFinite(Number(facts.opened_at)) ? Number(facts.opened_at) : _toMs(row.created_at);
+      if (openedAt == null || now - openedAt <= ttl) continue;
+      update.run('abandoned', JSON.stringify({ ...facts, abandoned_at: now }), LABEL_VERSION, row.id);
+      touched.add(row.cell_key);
+      abandoned += 1;
+    }
+    for (const cellKey of touched) evaluateAndApply(d, cellKey);
+    return { abandoned };
+  });
+  return run.immediate();
+}
+
+/**
+ * WP-6: store the spot-check grader's verdict on one hand-off row, then re-evaluate its cell in
+ * the SAME transaction — the explore rule reads `grade_json.sufficient`, so the sufficient rate
+ * may never be a write behind the row it belongs to. A missing id is not an error (the grade
+ * arrives fire-and-forget and may race a purge).
+ * @param {string} id the `helper_outcomes` row (the delegation invocation id)
+ * @param {object} gradeJson `{sufficient, coverage, inaccuracies, why}` or `{unavailable:true, error}`
+ * @returns {{updated:boolean, cell?:object}}
+ */
+function setGrade(d, id, gradeJson) {
+  const key = String(id || '');
+  if (!key) return { updated: false };
+  const run = d.transaction(() => {
+    const result = d.prepare('UPDATE helper_outcomes SET grade_json = ? WHERE id = ?')
+      .run(JSON.stringify(gradeJson || {}), key);
+    if (!result.changes) return { updated: false };
+    const row = d.prepare('SELECT cell_key FROM helper_outcomes WHERE id = ?').get(key);
+    return { updated: true, cell: evaluateAndApply(d, row.cell_key) };
+  });
+  return run.immediate();
+}
+
+/**
+ * WP-7's veto/enable switch. Upserts the cell and always writes one event row
+ * (`from_state` = whatever was stored, null on the first write).
+ * @returns {object|null} the cell row as stored
+ */
+function setCellState(d, cellKey, { state, user_veto, reason, evidence } = {}) {
+  const key = String(cellKey || '');
+  if (!key) throw new TypeError('helperRulesSetCellState: cell_key is required');
+  const nextState = CELL_STATES.includes(state) ? state : 'on';
+  const veto = user_veto ? 1 : 0;
+  const run = d.transaction(() => {
+    const previous = readCell(d, key);
+    d.prepare(`
+      INSERT INTO helper_rule_cells (cell_key, kind, state, user_veto, state_changed_at, updated_at)
+      VALUES (@cell_key, @kind, @state, @user_veto, datetime('now'), datetime('now'))
+      ON CONFLICT(cell_key) DO UPDATE SET
+        state = excluded.state,
+        user_veto = excluded.user_veto,
+        state_changed_at = CASE WHEN helper_rule_cells.state = excluded.state
+          THEN COALESCE(helper_rule_cells.state_changed_at, excluded.state_changed_at)
+          ELSE excluded.state_changed_at END,
+        updated_at = excluded.updated_at
+    `).run({ cell_key: key, kind: kindFromCellKey(key), state: nextState, user_veto: veto });
+    d.prepare('INSERT INTO helper_rule_events (cell_key, from_state, to_state, reason, evidence_json) VALUES (?, ?, ?, ?, ?)')
+      .run(key, previous ? previous.state : null, nextState, String(reason || 'manual'), JSON.stringify(evidence || {}));
+    return readCell(d, key);
+  });
+  return run.immediate();
+}
+
+/**
+ * The daily timer the outcome stream cannot provide: `off → probe` needs elapsed time, not a
+ * new row. WP-5b's scheduler registration calls this through brainWrite; the rules are unchanged
+ * either way. Round 2 (§6.4 S-16) runs three steps, in this order:
+ *   1. `sweepAbandoned` — D-10's 4 h TTL, so a row no lead ever closed stops occupying the window;
+ *   2. `relabel` — D-5's recompute + D-6's one-time recovery (a no-op once the kv watermark is
+ *      current, which is why it can ride the daily tick at all);
+ *   3. the evaluator over every explore cell, as before — this is what advances `off → probe`.
+ * @returns {{cells: Array<{cell_key:string, state:string, changed:boolean}>, abandoned:number,
+ *            relabelled:number}}
+ */
+function dailyTick(d) {
+  const abandoned = sweepAbandoned(d, {});
+  const relabelled = relabel(d, {});
+  const keys = d.prepare("SELECT cell_key FROM helper_rule_cells WHERE kind = 'explore' OR cell_key LIKE 'explore|%'")
+    .all()
+    .map((row) => row.cell_key);
+  const run = d.transaction(() => keys.map((key) => evaluateAndApply(d, key)));
+  return {
+    cells: run.immediate(),
+    abandoned: abandoned.abandoned,
+    relabelled: relabelled.relabelled,
+  };
+}
+
+module.exports = {
+  CELL_STATES,
+  DEFAULT_LEAD_BURST_USD,
+  LEAD_BURST_USD_KEY,
+  closeOutcome,
+  closeOutcomeByWorker,
+  dailyTick,
+  evaluateAndApply,
+  kindFromCellKey,
+  listCells,
+  readCell,
+  readCellState,
+  readLeadBurstUsd,
+  readRelabelledTo,
+  readTrailingOutcomes,
+  readWatcherUsd,
+  recordOutcome,
+  relabel,
+  setCellState,
+  setGrade,
+  sweepAbandoned,
+};