bareloop 0.43.0 → 0.45.0

package/src/job.js

@@ -345,7 +345,7 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
     red('invalid-value', 'model', 'non-empty string — the exact model id of a line ticked in Settings > Providers');
   }
   // THINKING (P8) — the job's "Thinking on" tick, OPTIONAL: absent means off (and an old spec keeps the hash it always had); present it is
-  // signed like `model`. It covers DRAFTING and the rubric JUDGE only — the worker is never handed a thinking option. A boolean, nothing else.
+  // signed like `model`. It covers DRAFTING and the rubric JUDGE, and makes every WORKER call think (src/thinking.js `workerThinkingMode`; without it the worker's mode is decided from phase and attempt). A boolean, nothing else.
   if (spec.thinking !== undefined && typeof spec.thinking !== 'boolean') {
     red('invalid-value', 'thinking', 'true or false — the job\'s "Thinking on" tick (absent = off)');
   }

package/src/kinds.js

@@ -304,6 +304,7 @@ export function mechanicalStages(stages) {
  *   onJudgeCost?: (c: {stage: string|null, kind: string|null, path: string, attempt: number,
  *     label: string, model: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   callBounds?: () => {timeoutMs?: number, deadlineMs?: number},
+ *   onRubricEvidence?: (e: {step: number, evidence: any[], evidenceTotal?: number}) => void,
  *   onStage?: (row: {stage: string|null, kind: string|null, verdict: string, durationMs: number}) => void}} Ctx
  *   The arbiter's half of a stage run. Every field here is operator/runner
  *   territory: a declaration parameterises kinds, never the contracts.
@@ -1593,6 +1594,10 @@ async function runRubricStep(stage, ctx) {
   }
   const graded = await gradeStep({ params: p, bytes: notRegular ? null : bytes, outputBytes: notRegular ? null : bytes, inputs, factQuotes, factMissing }, inputShas);
   if (graded.verdict === 'stopped') return stop(`the rubric stopped: ${graded.fault}`, STOP_FAULTS.CRASHED);
+  // REPORT-ONLY: what each cited check read, handed to the runner's seam (the spine's `rubric-evidence`); nothing below reads it
+  if (graded.evidence && typeof ctx.onRubricEvidence === 'function') {
+    ctx.onRubricEvidence({ step, evidence: graded.evidence, ...(graded.evidenceTotal !== undefined ? { evidenceTotal: graded.evidenceTotal } : {}) });
+  }
   const gap = new Gap(ctx.gapKeep, ctx.gapCap);
   if (notRegular) gap.push(`${stage.name}: line ${step}: ${stepFileRel(step)} is not a regular file`);
   for (const l of graded.gapLines) gap.push(`${stage.name}: ${l}`);

package/src/pagedropwords.js

@@ -0,0 +1,110 @@
+// IDEA A CORE (docs/product/ITEM33-BUILD.md "Addendum 2026-10-18 — Idea A core: build spec", sections 4.6 and 7): NO SILENT DROP. The ONE place
+// that writes the sentence for a word, fact or rule that a page rule dropped. The plan card, the Job tab, the confirm card and the drafter's
+// block all read these words; no other file writes a drop reason (a test greps for it). Plain words, written by CODE from the drop's reason
+// code, never a raw code and never model-written. `<label>` is the page's own word.
+
+/** @typedef {import('./pagerules.js').Dropped} Dropped */
+
+/** reason code -> the plain sentence (`d.word` = the page's word, `d.fact` = the fact's name, `d.other` = what it was compared to) */
+const WORDS = /** @type {Record<string, (d: Dropped) => string>} */ ({
+  'not-on-page': (d) => `"${d.word}" is not written on the page.`,
+  'no-value': (d) => `The page never shows a number right after or right before "${d.word}".`,
+  'n2': (d) => `"${d.word}" is written more than once inside one line of the page, so one result cannot show it once.`,
+  'r1': (d) => `"${d.word}" does not show the same values as "${d.other}", so it was not used as a second way to read it.`,
+  'sign-twice': (d) => `"${d.word}" was listed twice, as a unit and as a currency; it is used once, as the currency.`,
+  'r1l': (d) => d.word === d.other
+    ? `"${d.word}" was listed twice, as a unit and as a currency; it is used once, as the first way to write the price.`
+    : `"${d.word}" does not show the same amounts as "${d.other}", so it was not used as a second way to write the price.`,
+  's1-name': () => 'One result is one record; ask for N results instead.',
+  's1': (d) => `"${d.fact}" would read the same value as "${d.other}". The page gives no second label for it.`,
+  'no-label': (d) => `No word on this page reads "${d.fact}" safely.`,
+  'limit-currency': (d) => `Only the first 3 currencies are used; "${d.word}" was left out.`,
+  'limit-unit': (d) => `Only the first 10 units are used; "${d.word}" was left out.`,
+  'unit-too-long': (d) => `"${d.word}" is longer than 100 characters, so it was not used.`,
+  'reads-no-result': () => "the price rule could not read a price in the page's results, so it is not checked.",
+  'phrase-no-result': (d) => `"${d.other}" is on the page but in none of its results, so it is not checked.`,
+  'person-left': () => 'You chose to leave it Not checked.',
+  'bad-shape': (d) => `The AI named a kind of value for "${d.fact}" that a check cannot read.`,
+});
+
+/** @param {Dropped} d @returns {string} the plain sentence for one drop */
+export function dropSentence(d) {
+  const f = WORDS[d.reason];
+  return f ? f(d) : `"${d.word ?? d.fact}" was left out.`;
+}
+
+/**
+ * One row per fact that lost something: the sentences (one per dropped word, then the fact's own), and whether the whole fact went.
+ * @param {Dropped[]|undefined|null} dropped
+ * @returns {{line: number, rule?: number, fact: string, full: boolean, sentences: string[]}[]}
+ */
+export function dropRows(dropped) {
+  /** @type {Map<string, {line: number, rule?: number, fact: string, full: boolean, sentences: string[]}>} */
+  const rows = new Map();
+  for (const d of Array.isArray(dropped) ? dropped : []) {
+    const key = `${d.line}\u0000${d.rule ?? ''}\u0000${d.fact}`;
+    let row = rows.get(key);
+    if (!row) { row = { line: d.line, ...(d.rule === undefined ? {} : { rule: d.rule }), fact: d.fact, full: false, sentences: [] }; rows.set(key, row); }
+    if (d.word === undefined) row.full = true;
+    const sentence = dropSentence(d);
+    if (!row.sentences.includes(sentence)) row.sentences.push(sentence);
+  }
+  // a fact's own sentence ("No word ... reads it safely") reads last, after the words that were lost
+  return [...rows.values()].map((r) => ({ ...r, sentences: [...r.sentences.filter((s) => !/^No word on this page reads /.test(s)), ...r.sentences.filter((s) => /^No word on this page reads /.test(s))] }));
+}
+
+/**
+ * A row as one Not-checked line, in the person's own words: `line N: "<the ~ rule as written, or the fact's name>" — <sentences>`.
+ * @param {{line: number, rule?: number, fact: string, sentences: string[]}} row @param {any[]|null|undefined} jobLines @param {(l: any) => string[]} rulesOf
+ * @returns {string}
+ */
+export function dropLine(row, jobLines, rulesOf) {
+  const jl = (jobLines ?? []).find((/** @type {any} */ l) => l && l.n === row.line);
+  const rule = row.rule === undefined || !jl ? undefined : rulesOf(jl)[row.rule - 1];
+  return `line ${row.line}: "${rule ?? row.fact}" — ${row.sentences.join(' ')}`;
+}
+
+// HOW THE PAGE WAS READ (run mvij7kuk, flight-c1): a drop of ONE WORD whose fact is still checked is a NOTE about the form code did not use, not
+// something left unchecked. The sentences for those reasons are WORD-level; every other sentence (a whole fact left out) keeps the line under
+// Not checked. Classified from the line's own words, so it holds for a signed spec already on disk.
+const WORD_REASONS = ['not-on-page', 'no-value', 'n2', 'r1', 'sign-twice', 'r1l', 'limit-currency', 'limit-unit', 'unit-too-long'];
+/** @param {string} s */
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const SENTENCE_RE = (() => {
+  const [W, O] = ['\u0001w\u0001', '\u0001o\u0001'];
+  /** @type {string[]} */
+  const alts = [];
+  for (const reason of WORD_REASONS) {
+    const probes = reason === 'r1l' ? [{ word: W, other: W }, { word: W, other: O }] : [{ word: W, other: O }];
+    for (const p of probes) alts.push(esc(WORDS[reason](/** @type {any} */ ({ ...p, reason, line: 0, fact: 'f' }))).split(esc(W)).join('[^"]+').split(esc(O)).join('[^"]+'));
+  }
+  return new RegExp(`^(?:(?:${alts.join('|')})(?: |$))+$`);
+})();
+
+/** the s1 sentence as a pattern whose one capture is the OTHER fact's name (the sentence is built from the one WORDS table) */
+const S1_RE = (() => {
+  const [F, O] = ['\u0001f\u0001', '\u0001o\u0001'];
+  return new RegExp(esc(WORDS['s1'](/** @type {any} */ ({ fact: F, other: O, reason: 's1', line: 0 }))).split(esc(F)).join('[^"]+').split(esc(O)).join('([^"]+)'), 'g');
+})();
+
+/**
+ * An `s1` drop (a second fact that would read the same value as one already kept) is a NOTE when that OTHER fact is still signed: the guardrail
+ * is checked by it. With the other fact not signed, or no signed list given, the sentence stays Not checked. Every sentence of a row must qualify.
+ * @param {string} text one Not-checked line @param {string[]|null|undefined} [signed] the names of the facts the plan signs
+ * @returns {boolean} true when the line only says which written forms of a still-checked fact were not used
+ */
+export function isReadNote(text, signed) {
+  const m = /^line \d+: "[^"]*" \u2014 (.+)$/s.exec(String(text));
+  if (m === null) return false;
+  const names = new Set(Array.isArray(signed) ? signed : []);
+  let found = 0;
+  const rest = m[1].replace(S1_RE, (all, other) => { if (!names.has(other)) return all; found += 1; return ''; }).replace(/\s+/g, ' ').trim();
+  return rest === '' ? found > 0 : SENTENCE_RE.test(rest);
+}
+
+/** @param {string[]|null|undefined} items @param {string[]|null|undefined} [signed] names of the signed facts (see isReadNote)
+ * @returns {{notChecked: string[], readNotes: string[]}} the lines split: what is left unchecked, and how the page was read */
+export function splitReadNotes(items, signed) {
+  const all = Array.isArray(items) ? items : [];
+  return { notChecked: all.filter((t) => !isReadNote(t, signed)), readNotes: all.filter((t) => isReadNote(t, signed)) };
+}

package/src/pagedry.js

@@ -0,0 +1,125 @@
+// MONEY BUILD v2 (docs/product/ITEM33-BUILD.md "Addendum 2026-10-21 — money build spec v2", part 2): "CAN IT READ". After the page rules, a $0 dry
+// read asks of each kept money fact whether the REAL run-time checker can read a price on the page's own result lines. For every result line it
+// grades an HONEST claim (quote = that line, value = the line's amount) with `gradeStep` (src/rubricstep.js), the one reader the run itself
+// uses - no copy of its logic here. A fact that reads no result line is dropped as `reads-no-result` and shows under Not checked.
+// No limits, no counts, no pass bar: only "can it read". Async (gradeStep is), so it sits beside applyPageRules, not inside it: the caller is
+// src/pagemap.js `runPageMap`. No I/O, no clock, no model.
+
+import { createHash } from 'node:crypto';
+import { gradeStep } from './rubricstep.js';
+import { linesOf } from './pagerules.js';
+
+/** @typedef {import('./pagerules.js').KeptFact} KeptFact @typedef {import('./pagerules.js').Dropped} Dropped */
+
+/** a number as the page writes it, thousands commas allowed */
+const NUM = '\\d[\\d,]*(?:\\.\\d+)?';
+const AFTER_LABEL = new RegExp(`^\\s*(?:[$€£]\\s*)?(${NUM})`);
+const BEFORE_UNIT = new RegExp(`(${NUM})\\s*$`);
+/** the label every dry-read claim is made under (the checker only needs one name; the fact's own is not read) */
+const CLAIM = 'price';
+const SOURCE = 'page';
+
+/**
+ * The result lines of a kept money fact: with a label, every page line where a kept label is followed by a number (one sign between allowed);
+ * with no label (U1 moved it to a unit, e.g. "€533 total"), every line where a number is followed by a kept unit.
+ * @param {string} text @param {KeptFact} k @returns {{quote: string, value: string}[]}
+ */
+export function moneyResultLines(text, k) {
+  const raw = text.split('\n');
+  const squashed = linesOf(text);
+  /** @type {{quote: string, value: string}[]} */
+  const out = [];
+  squashed.forEach((ln, i) => {
+    /** @type {string|undefined} */
+    let amount;
+    if (k.words.length) {
+      for (const w of k.words) {
+        for (let at = ln.indexOf(w); at !== -1 && amount === undefined; at = ln.indexOf(w, at + w.length)) amount = AFTER_LABEL.exec(ln.slice(at + w.length))?.[1];
+        if (amount !== undefined) break;
+      }
+    } else {
+      for (const u of k.unit ?? []) {
+        for (let at = ln.indexOf(u); at !== -1 && amount === undefined; at = ln.indexOf(u, at + u.length)) amount = BEFORE_UNIT.exec(ln.slice(0, at))?.[1];
+        if (amount !== undefined) break;
+      }
+    }
+    if (amount !== undefined) out.push({ quote: raw[i].trim(), value: amount.replace(/,/g, '') });
+  });
+  return out;
+}
+
+/**
+ * The fact as a run would sign it, for the dry read: the primary label is the anchor (none when U1 moved every label), then the kept units and currencies.
+ * @param {KeptFact} k @returns {Record<string, any>}
+ */
+const signedOf = (k) => ({ name: CLAIM, shape: 'money', ...(k.words.length ? { anchor: k.words[0] } : {}), ...(k.currency ? { currency: k.currency } : {}), ...(k.unit ? { unit: k.unit } : {}) });
+
+/**
+ * Dry-read every kept money fact; drop (as `reads-no-result`) the ones whose forms read no result line. Other facts pass through untouched.
+ * @param {string} text the frozen page text @param {KeptFact[]} facts what applyPageRules kept
+ * @returns {Promise<{facts: KeptFact[], dropped: Dropped[], reads: Record<string, number>, results: Record<string, number>}>}
+ *   `reads` / `results` = result lines the checker read / lines found, per fact name (for tests and reports; no verdict derives from the numbers)
+ */
+export async function dryReadMoney(text, facts) {
+  const sha = createHash('sha256').update(text).digest('hex');
+  /** @type {KeptFact[]} */
+  const kept = [];
+  /** @type {Dropped[]} */
+  const dropped = [];
+  /** @type {Record<string, number>} */
+  const reads = {};
+  /** @type {Record<string, number>} */
+  const results = {};
+  for (const k of facts) {
+    if (k.shape !== 'money') { kept.push(k); continue; }
+    const fact = signedOf(k);
+    const lines = moneyResultLines(text, k);
+    let n = 0;
+    for (const r of lines) {
+      const params = { step: 1, parts: [{ text: 'dry read', class: 'fact', source: SOURCE, covers: [1], facts: [fact] }] };
+      const g = await gradeStep({ params, bytes: JSON.stringify({ results: [{ quote: r.quote, values: { [CLAIM]: r.value } }] }), outputBytes: null, inputs: { [SOURCE]: text } }, { [SOURCE]: sha });
+      if (g.verdict === 'green') n += 1;
+    }
+    reads[k.name] = n;
+    results[k.name] = lines.length;
+    if (n > 0) { kept.push(k); continue; }
+    dropped.push({ line: k.line, ...(k.forRule === undefined ? {} : { rule: k.forRule }), fact: k.name, reason: 'reads-no-result' });
+  }
+  return { facts: kept, dropped, reads, results };
+}
+
+/**
+ * The same "can it read" for PHRASE facts (hamr ruled 3a, run m10-walk-flights-3: "Rome" was on the page only in "Track prices from Madrid to
+ * Rome" switches, in none of the 18 result lines, so no result could ever say it). A kept phrase fact is read against the page's RESULT LINES =
+ * the lines the job's kept money facts read (`moneyResultLines`), each graded as an honest claim by the real `gradeStep` (quote = that line;
+ * a phrase has no value to write). A phrase that reads no result line is dropped whole as `phrase-no-result` and shows under Not checked.
+ * With no kept money fact the result lines are unknown, so phrase facts pass through untouched (nothing is guessed about what a result is).
+ * @param {string} text the frozen page text @param {KeptFact[]} facts what the money dry read kept
+ * @returns {Promise<{facts: KeptFact[], dropped: Dropped[], reads: Record<string, number>}>} `reads` = result lines that said the phrase, per fact name
+ */
+export async function dryReadPhrases(text, facts) {
+  const sha = createHash('sha256').update(text).digest('hex');
+  /** @type {Map<string, true>} */
+  const quotes = new Map();
+  for (const k of facts) if (k.shape === 'money') for (const r of moneyResultLines(text, k)) quotes.set(r.quote, true);
+  /** @type {KeptFact[]} */
+  const kept = [];
+  /** @type {Dropped[]} */
+  const dropped = [];
+  /** @type {Record<string, number>} */
+  const reads = {};
+  for (const k of facts) {
+    if (k.shape !== 'phrase' || quotes.size === 0 || !k.words.length) { kept.push(k); continue; }
+    const fact = { name: k.name, shape: 'phrase', phrase: k.words[0] };
+    let n = 0;
+    for (const quote of quotes.keys()) {
+      const params = { step: 1, parts: [{ text: 'dry read', class: 'fact', source: SOURCE, covers: [1], facts: [fact] }] };
+      const g = await gradeStep({ params, bytes: JSON.stringify({ results: [{ quote, values: {} }] }), outputBytes: null, inputs: { [SOURCE]: text } }, { [SOURCE]: sha });
+      if (g.verdict === 'green') n += 1;
+    }
+    reads[k.name] = n;
+    if (n > 0) { kept.push(k); continue; }
+    dropped.push({ line: k.line, ...(k.forRule === undefined ? {} : { rule: k.forRule }), fact: k.name, other: k.words[0], reason: 'phrase-no-result' });
+  }
+  return { facts: kept, dropped, reads };
+}

package/src/pagemap.js

@@ -0,0 +1,269 @@
+// IDEA A CORE (docs/product/ITEM33-BUILD.md "Addendum 2026-10-18 — Idea A core: build spec", sections 4.1 and 5): THE MAP CALL.
+// ONE paid AI call per page input maps the person's job to the page's OWN words. The AI never grades and never invents: every word it
+// names is checked by plain code against the saved page (src/pagerules.js) before anything else sees the answer. This replaces the
+// search-and-read look (`runInputLook`, src/authorscout.js) as the default `lookFn`; it takes the same arguments and returns the same
+// envelope (`state`, `facts: {rubricFiles, inputs, look}`, `calls`, `raws`, `budgetStop`), so the phase line, the spend booking and
+// every downstream reader keep working. The prompt is ported from the POC call (.claude/scratch/idea-a-v2/mapcall.mjs, sha256 recorded
+// in commit 0bcc5fe).
+
+import { createRequire } from 'node:module';
+import { priceOf, scrubRaw, tallyCalls, capStop, callCasualty } from './text.js';
+import { redactSecrets } from './validate.js';
+import { isTransportFailure } from './transport.js';
+import { isRateLimited, rateLimitWaitMs } from './ratelimit.js';
+import { isOutputCutOff } from './authorflow.js';
+import { AUTHOR_CALL_TIMEOUT_MS, AUTHOR_SCOUT_MAX_TOKENS, SURVEY_CAUSES } from './authorscout.js';
+import { lineRules, boundInWords, wordsSaidOn } from './rubricstep.js';
+import { applyPageRules, validReading } from './pagerules.js';
+import { dryReadMoney, dryReadPhrases } from './pagedry.js';
+import { ruleWords } from './facts.js';
+import { lookFactOf } from './inputlook.js';
+
+const require = createRequire(import.meta.url);
+const { Loop } = require('bare-agent');
+
+/** the label of the one paid call, as the drafting book and the progress line see it */
+export const MAP_CALL_LABEL = 'page-map';
+/** the shapes the map may name; a `place` is read by code as a phrase */
+export const MAP_SHAPES = Object.freeze(['place', 'money', 'time', 'phrase']);
+
+export const MAP_SYSTEM = 'You map a person\'s job to the exact words of ONE saved web page. You never grade and never invent words: every string you return must be copied from the page text, character for character.';
+
+/**
+ * What the AI is told, for ONE page input. Ported from the POC prompt: the job, the `~` rules, "a result is one item", the answer form
+ * and the shape meanings.
+ * @param {{jobLines: {n: number, text: string, rule?: string, rules?: string[]}[], label: string, text: string}} o
+ * @returns {string}
+ */
+export function mapPrompt({ jobLines, label, text }) {
+  const job = jobLines.map((l) => `LINE ${l.n}: ${l.text}${lineRules(l).map((r, i) => `\n~ rule ${i + 1}: ${r}`).join('')}`).join('\n');
+  return `THE JOB (each ~ rule applies to the line above it):\n${job}\n\n`
+    + 'A "result" is one item the page lists (one flight, one stay, one row). For each job line and for each rule, say which fact(s) every result must carry, and give the PAGE\'S OWN WORDS for it.\n\n'
+    + 'Return ONLY a JSON object, no prose, no code fence:\n'
+    + '{"facts":[{"name":"<letters and spaces only>","from":"<line N | line N rule M>","shape":"place|money|time|phrase","words":["<page words>", ...],"currency":["<symbol>"],"unit":["<words after the amount>"],"reading":<optional, see below>}]}\n\n'
+    + 'shape meanings:\n'
+    + '- place: words = ways the page writes the place (a city, an airport name), copied from the page.\n'
+    + '- money: words = the label(s) written right BEFORE the amount, copied from the page. currency / unit = how the page writes the currency ("$") and/or the words after the amount ("US dollars"); give every spelling the page uses, as lists.\n'
+    + '- time: words = the label(s) written right BEFORE the time that is the one the rule is about, copied from the page.\n'
+    + '- phrase: words = fixed words a result\'s text must contain, copied from the page.\n'
+    + 'Several words in one list are alternatives for the same fact. Put the best one first.\n'
+    + 'reading (optional, only on a time or money fact): when a ~ rule is a limit on that fact that the page cannot hold in words (for example "not a red-eye" is a limit on the departure time), give your own best reading of the rule as that limit: {"op":"between","lo":<bound>,"hi":<bound>} or {"op":"lt|lte|gt|gte","value":<bound>}. A time bound is a "HH:MM" string on a 24-hour clock; a money bound is a number. Leave reading out when a page word already carries the rule.\n\n'
+    + `PAGE TEXT (the input "${label}"):\n${text}`;
+}
+
+/**
+ * Read the AI's answer: ONE JSON object of the answer form, and nothing else. No repair (hamr's ruling): text that is not JSON, JSON of
+ * another form, or a fact whose shape or lists are not of the form is a malformed answer.
+ * @param {unknown} text @returns {{ok: true, mapping: import('./pagerules.js').PageMap}|{ok: false}}
+ */
+export function parseMapAnswer(text) {
+  /** @type {any} */
+  let m;
+  try { m = JSON.parse(String(text ?? '').trim()); } catch { return { ok: false }; }
+  const strs = (/** @type {unknown} */ v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+  if (m === null || typeof m !== 'object' || Array.isArray(m) || !Array.isArray(m.facts)) return { ok: false };
+  for (const f of m.facts) {
+    if (f === null || typeof f !== 'object' || Array.isArray(f)) return { ok: false };
+    if (typeof f.name !== 'string' || !MAP_SHAPES.includes(f.shape) || !strs(f.words)) return { ok: false };
+    if (f.from !== undefined && typeof f.from !== 'string') return { ok: false };
+    for (const k of ['currency', 'unit']) if (f[k] !== undefined && !strs(f[k])) return { ok: false };
+    // PRD v1.107 Part 5b: a `reading` is a limit of the signed-rule shape on a time or money fact; any other is a malformed answer (no repair)
+    if (f.reading !== undefined && !validReading(f.shape, f.reading)) return { ok: false };
+  }
+  return { ok: true, mapping: m };
+}
+
+/** the default loop seam - one spelling of how this repo drives a model */
+const defaultLoop = (/** @type {any} */ { system, onLlmResult, provider, rates }) =>
+  new Loop({ provider, system, onLlmResult, ...(rates ? { rates } : {}) });
+
+/** the plain-word stop when the answer was not readable twice (no Resume: a draft is not a run) */
+export const MAP_UNREADABLE = 'The AI\'s answer about the page was not readable twice. Nothing was signed.';
+
+/**
+ * Run the map: one call per page input.
+ * @param {{texts: Record<string, string>, inputs: {n: number, label: string}[], jobLines: {n: number, text: string, rule?: string, rules?: string[]}[],
+ *   provider?: any, maxTokens?: number, ceilingUsd?: number|null, callTimeoutMs?: number,
+ *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number, thinkingStatus?: string, raw?: string}) => void,
+ *   createLoop?: (o: {system: string, onLlmResult: any, provider: any, rates?: {in: number, out: number}}) => any,
+ *   rates?: {in: number, out: number}|null, callOptions?: Record<string, any>, sleep?: (ms: number) => Promise<void>, prove?: Function}} o
+ * @returns {Promise<{state: 'PRESENT'|'ABSENT', facts: any, reason: string|null, cause: string|null, meta: any, raw: string,
+ *   raws: ReturnType<typeof scrubRaw>[], calls: {label: string, costUsd: number|null, unpricedRounds: number}[],
+ *   budgetStop: 'cap-halt'|'pricing-red'|null}>}
+ */
+export async function runPageMap({
+  texts, inputs, jobLines, provider = null, maxTokens = AUTHOR_SCOUT_MAX_TOKENS, ceilingUsd = null,
+  callTimeoutMs = AUTHOR_CALL_TIMEOUT_MS, onCall = () => {}, createLoop = defaultLoop, rates = null, callOptions = {},
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+}) {
+  const callTimeout = Number.isFinite(Number(callTimeoutMs)) && Number(callTimeoutMs) > 0
+    ? Math.min(Math.trunc(Number(callTimeoutMs)), AUTHOR_CALL_TIMEOUT_MS) : AUTHOR_CALL_TIMEOUT_MS;
+  const priced = rates ? { rates } : {};
+  /** @type {{label: string, costUsd: number|null, unpricedRounds: number}[]} */
+  const calls = [];
+  /** @type {ReturnType<typeof scrubRaw>[]} */
+  const raws = [];
+  let attempts = 0;
+  const record = (/** @type {any} */ r, /** @type {number} */ attempt) => {
+    const call = { label: MAP_CALL_LABEL, ...priceOf(r) };
+    calls.push(call);
+    const raw = scrubRaw({ label: MAP_CALL_LABEL, attempt, text: r?.text });
+    raws.push(raw);
+    // the scrubbed answer rides the call, so the session's drafting log (draft-log.jsonl) keeps the AI's map and a run can be replayed at $0
+    onCall({ ...call, raw: raw.text, ...(r?.thinkingStatus === undefined ? {} : { thinkingStatus: r.thinkingStatus }) });
+  };
+  const absent = (/** @type {string} */ reason, /** @type {string} */ cause, /** @type {'cap-halt'|'pricing-red'|null} */ budgetStop = null) => ({
+    state: /** @type {'ABSENT'} */ ('ABSENT'), facts: null, reason, cause, meta: { attempts }, raw: '', raws, calls, budgetStop,
+  });
+  const halted = () => capStop({ ceilingUsd, ...tallyCalls(calls) });
+  const labels = Object.keys(texts);
+  /** @type {any[]} */
+  const looks = [];
+  /** @type {any[]} */
+  const dropped = [];
+  /** @type {any[]} */
+  const facts = [];
+  /** @type {any[]} */
+  const maps = [];
+
+  for (const label of labels) {
+    const content = mapPrompt({ jobLines, label, text: texts[label] });
+    /** @type {any} */
+    let mapping = null;
+    let malformed = 0;
+    let transportRetried = false;
+    let rateRetried = false;
+    while (mapping === null) {
+      // the cap is checked BEFORE every call, never inside one
+      const halt = halted();
+      if (halt) return absent(halt === 'cap-halt' ? `the AI's look at the page was not made: the $${ceilingUsd} ceiling was already spent` : 'the AI\'s look at the page was not made: spend could not be priced, so the ceiling could not be enforced', SURVEY_CAUSES.NOT_FUNDED, halt);
+      attempts += 1;
+      const loop = createLoop({ system: MAP_SYSTEM, onLlmResult: undefined, provider, ...priced });
+      /** @type {any} */
+      let r;
+      try {
+        r = await loop.run([{ role: 'user', content }], [], { cacheMessages: true, maxTokens, timeoutMs: callTimeout, ...callOptions });
+      } catch (e) {
+        if (isRateLimited(e) && !rateRetried) {
+          // a 429 is a REFUSAL (nothing billed): wait the vendor's stated time once, then ask again
+          const wait = rateLimitWaitMs(e);
+          if (wait !== null) { rateRetried = true; await sleep(wait); continue; }
+        }
+        const casualty = callCasualty(e) ?? (isTransportFailure(e) ? String(/** @type {any} */ (e)?.message ?? e) : null);
+        if (casualty === null) throw e;
+        // the failed attempt may already be billed: it is booked UNPRICED, so the spend stays "not complete" (never a $0)
+        record({ error: casualty }, attempts);
+        if (!transportRetried) { transportRetried = true; continue; }
+        return absent(`the call about the page failed: ${redactSecrets(casualty)}`, SURVEY_CAUSES.CALL_FAILED);
+      }
+      record(r, attempts);
+      if (r?.error && !isOutputCutOff(r)) return absent(`the call about the page failed: ${redactSecrets(String(r.error))}`, SURVEY_CAUSES.CALL_FAILED);
+      // a truncated answer (max_tokens) is a malformed one
+      const parsed = isOutputCutOff(r) ? { ok: false } : parseMapAnswer(r?.text);
+      if (parsed.ok) { mapping = /** @type {any} */ (parsed).mapping; break; }
+      malformed += 1;
+      if (malformed >= 2) return absent(MAP_UNREADABLE, SURVEY_CAUSES.UNPARSEABLE);
+    }
+    const kept = applyPageRules(texts[label], mapping, jobLines);
+    // money build v2: "can it read" - a money fact whose forms read no result line of the page, by the run's own checker, is Not checked
+    const read = await dryReadMoney(texts[label], kept.facts);
+    // hamr 3a: a phrase fact is read against the same result lines (only when the job keeps a money fact)
+    const phr = await dryReadPhrases(texts[label], read.facts);
+    for (const f of phr.facts) facts.push(lookFactOf(f, label));
+    for (const d of [...kept.dropped, ...read.dropped, ...phr.dropped]) dropped.push({ ...d, source: label });
+    maps.push({ source: label, facts: mapping.facts.length });
+    looks.push(label);
+  }
+  return {
+    state: 'PRESENT', reason: null, cause: null, meta: { attempts, maps }, raw: '', raws, calls, budgetStop: null,
+    facts: { rubricFiles: true, inputs: inputs.map((i) => ({ n: i.n, label: i.label })), look: { facts, prose: [], notFound: [], dropped } },
+  };
+}
+
+/** the answer that drops a `~` rule the page cannot check: the person types it (any case, a closing full stop allowed) */
+export const DROP_IT = 'drop it';
+/** @param {unknown} text @returns {boolean} */
+export const isDropIt = (text) => String(text ?? '').trim().replace(/\.$/, '').toLowerCase() === DROP_IT;
+/** the answers that accept the code's reading of a rule; anything else the person types is their own reading */
+const AGREE_WORDS = ['agree', 'yes'];
+/** @param {unknown} text @returns {boolean} */
+export const isAgree = (text) => AGREE_WORDS.includes(String(text ?? '').trim().replace(/[.!]$/, '').toLowerCase());
+
+/** @typedef {{line: number, rule: number, source: 'look', question: string, ask: 'reading'|'cant-check', ruleText: string, reading?: string}} LookAsk
+ *   `reading` = the plain words an `agree` writes as a `~` rule (a reading ask only) */
+
+/** the words of a reading ask: the ONE spelling, and {@link readingOfQuestion} reads it back (the Result tab's "(you confirmed)") */
+const READING_HEAD = ' I read it as: ';
+const READING_TAIL = '. Agree? Answer "agree"';
+/** @param {number} n @param {string} rule @param {string} reading @returns {string} */
+const readingQuestion = (n, rule, reading) => `Your line ${n} says "${rule}".${READING_HEAD}${reading}${READING_TAIL}, or type your own reading (your answer is added as a new ~ rule on line ${n}).`;
+/** @param {unknown} q a recorded question @returns {string|null} the reading a reading ask proposed, or null when it was another kind of question */
+export function readingOfQuestion(q) {
+  const s = String(q ?? '');
+  const a = s.indexOf(READING_HEAD);
+  const b = s.indexOf(READING_TAIL);
+  return a >= 0 && b > a ? s.slice(a + READING_HEAD.length, b) : null;
+}
+
+/**
+ * PRD v1.107 Part 5b ("the look reads, code asks"): the early asks CODE forces before any paid drafting, from the look's own result. Every `~` rule is
+ * one of three kinds:
+ *   - PAGE: a kept page word carries it (a kept fact with `forRule` and no `reading`): no ask.
+ *   - READING: a kept fact carries it with a `reading` (a limit the page cannot hold, e.g. "not a red-eye" -> departure time between 06:00 and 21:00).
+ *     Asked only when a bound of the reading is NOT in the words the person wrote (the same test as `rubric-fact-unmarked`, `boundInWords`); a
+ *     bound they wrote themselves is theirs and nothing is asked. `agree` writes the reading as a `~` rule in plain words (the answer text is
+ *     `reading`), so the drafter is told it and the fact signs plain.
+ *   - CAN'T CHECK: no kept fact carries it (PRD v1.106 Part 5 Q3 T2). `drop it` leaves it Not checked.
+ * One ask per rule text on a line; readings first, then can't-check asks, each in line order. The caller applies the machine's cap and the answer gate.
+ * @param {{facts?: {line: number, forRule?: number, name?: string, shape?: string, unit?: string[], currency?: string[], reading?: import('./pagerules.js').Reading}[]}|null|undefined} look
+ * @param {{n: number, text?: string, rule?: string, rules?: string[]}[]|null|undefined} jobLines
+ * @returns {LookAsk[]}
+ */
+export function askableFromLook(look, jobLines) {
+  const facts = Array.isArray(look?.facts) ? look.facts : [];
+  /** @type {LookAsk[]} */
+  const readings = [];
+  /** @type {LookAsk[]} */
+  const cants = [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+  for (const l of Array.isArray(jobLines) ? jobLines : []) {
+    lineRules(l).forEach((rule, k) => {
+      const n = k + 1;
+      const key = `${l.n}\u0000${rule.trim().toLowerCase()}`;
+      const tied = facts.filter((f) => f.line === l.n && f.forRule === n);
+      if (tied.length > 0) {
+        const said = wordsSaidOn(l);
+        const f = tied.find((x) => x.reading && validReading(x.shape, x.reading) && ruleBounds(x.reading).some((b) => !boundInWords(b, said)));
+        if (f === undefined || seen.has(key)) return;
+        seen.add(key);
+        const reading = `${f.name} ${ruleWords({ shape: f.shape, unit: f.unit, currency: f.currency, rule: f.reading })}`;
+        readings.push({
+          line: l.n, rule: n, source: 'look', ask: 'reading', ruleText: rule, reading,
+          question: readingQuestion(l.n, rule, reading),
+        });
+        return;
+      }
+      if (seen.has(key)) return;
+      seen.add(key);
+      cants.push({
+        line: l.n, rule: n, source: 'look', ask: 'cant-check', ruleText: rule,
+        question: `Your line ${l.n} says "${rule}". I can't check this on the page. Drop it? Answer "${DROP_IT}", or type how to check it (your answer is added as a new ~ rule on line ${l.n}).`,
+      });
+    });
+  }
+  return [...readings, ...cants];
+}
+
+/** @param {import('./pagerules.js').Reading} r @returns {unknown[]} the bounds a reading holds */
+const ruleBounds = (r) => (r.op === 'between' ? [r.lo, r.hi] : [r.value]);
+
+/**
+ * PRD v1.107 Part 5b: more asks than the machine's cap means the job needs a rewrite, not a questionnaire. The code-owned stop words list EVERY ask and
+ * its reading as the suggestion (no extra paid call). A secret in a rule is masked.
+ * @param {LookAsk[]} asks @returns {string}
+ */
+export function tooManyAsksText(asks) {
+  const list = asks.map((a) => `line ${a.line} "${a.ruleText}" → ${a.reading ?? "I can't check this on the page"}`).join('; ');
+  return redactSecrets(`Your job has ${asks.length} rules I can't check or had to guess. Please rewrite it so each one says what to look for. My readings: ${list}.`);
+}