bareloop 0.42.0 → 0.44.0

package/src/inputlook.js

@@ -11,6 +11,7 @@
 import { scanLabels, labelOnList, renderLabelList, normLabel, LABEL_SHAPES } from './labelscan.js';
 import { FACT_SHAPES, FACT_OPS } from './facts.js';
 import { lineRules } from './rubricstep.js';
+import { dropRows, dropLine } from './pagedropwords.js';
 
 /** the name of the answer tool - the one place the AI's report enters */
 export const LOOK_REPORT_TOOL = 'report_look';
@@ -149,13 +150,31 @@ export function lookPrompt({ jobLines, labels, lists }) {
     + `Report only through ${LOOK_REPORT_TOOL}.`;
 }
 
-/** @typedef {{line: number, name: string, shape: string, source: string, label?: string, labelId?: string, value?: string, phrase?: string, example: string, rule?: any, aiProposal?: boolean, forRule?: number}} LookFact */
+/** @typedef {{line: number, name: string, shape: string, source: string, label?: string, labelId?: string, value?: string, phrase?: string, example: string, rule?: any, aiProposal?: boolean, forRule?: number, reading?: import('./pagerules.js').Reading,
+ *   words?: string[], labels?: string[], unit?: string[], currency?: string[]}} LookFact  `words` / `labels` / `unit` / `currency`: what the page-word map kept (idea A core) */
 /** @typedef {{line: number, rule?: number, words?: string, why: string}} LookNotFound */
-/** @typedef {{facts: LookFact[], prose: {line: number, text?: string}[], notFound: LookNotFound[]}} LookReport */
+/** @typedef {{facts: LookFact[], prose: {line: number, text?: string}[], notFound: LookNotFound[], dropped?: import('./pagerules.js').Dropped[]}} LookReport */
 
 /** @param {unknown} v @returns {v is Record<string, any>} */
 const isRec = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 
+/**
+ * A fact the page-word map kept (src/pagerules.js `KeptFact`), as the look report carries it: a phrase fact holds its alternative
+ * phrases; any other holds its labels (the first is the primary), and a money fact its units and currencies.
+ * @param {import('./pagerules.js').KeptFact} k @param {string} source @returns {LookFact}
+ */
+export function lookFactOf(k, source) {
+  /** @type {LookFact} */
+  const out = { line: k.line, name: k.name, shape: k.shape, source, example: '', words: [...k.words] };
+  if (k.shape === 'phrase') out.phrase = k.words[0];
+  else { out.labels = [...k.words]; if (k.words.length) out.label = k.words[0]; }
+  if (k.unit) out.unit = [...k.unit];
+  if (k.currency) out.currency = [...k.currency];
+  if (k.forRule !== undefined) out.forRule = k.forRule;
+  if (k.reading) out.reading = { ...k.reading };
+  return out;
+}
+
 /**
  * Turn the AI's raw report into a VERIFIED one, by code, at $0. A fact is carried only when: its shape is a real shape, its source is
  * a real input, and its label is ON THE LIST for that input and shape (an id is resolved to its exact words). Anything else is moved
@@ -225,7 +244,17 @@ export function renderLookReport(report) {
   const add = (/** @type {number} */ n, /** @type {string} */ s) => byLine.set(n, [...(byLine.get(n) ?? []), s]);
   for (const f of report.facts) {
     const bits = [`${f.name} - ${f.shape}`, `from "${f.source}"`];
-    if (f.phrase !== undefined) bits.push(`the quote must say ${JSON.stringify(f.phrase)}`);
+    if (Array.isArray(f.words)) {
+      // a fact the page-word map kept (idea A core): the words the page holds, each one proven by code; the first is the main one
+      const quote = (/** @type {string[]|undefined} */ a) => (a ?? []).map((w) => JSON.stringify(w)).join(' or ');
+      if (f.shape === 'phrase') bits.push(`the quote must say ${f.words.length > 1 ? 'ONE of these page words, copied exactly' : 'this page word'}: ${quote(f.words)}`);
+      else {
+        if (f.words.length) bits.push(`label ${quote(f.words)}${f.words.length > 1 ? ' (the first is the main one)' : ''}`);
+        else bits.push('no label (read by its unit or sign alone)');
+        if (f.unit?.length) bits.push(`unit ${quote(f.unit)}`);
+        if (f.currency?.length) bits.push(`currency ${quote(f.currency)}`);
+      }
+    } else if (f.phrase !== undefined) bits.push(`the quote must say ${JSON.stringify(f.phrase)}`);
     else if (f.label !== undefined) bits.push(`label ${JSON.stringify(f.label)} (id ${f.labelId})`);
     else bits.push('no label (the value as the quote writes it)');
     if (f.example) bits.push(`seen: ${JSON.stringify(f.example)}`);
@@ -234,6 +263,12 @@ export function renderLookReport(report) {
     if (f.forRule !== undefined) bits.push(`carries ~ rule ${f.forRule}`);
     add(f.line, `CAN CHECK: ${bits.join(', ')}`);
   }
+  // NO SILENT DROP: a word, fact or rule the page rules removed is said to the drafter too, so it is never written back as a check
+  for (const row of dropRows(report.dropped)) {
+    add(row.line, row.full
+      ? `NOT CHECKED${row.rule !== undefined ? ` (rule ${row.rule})` : ''}: "${row.fact}" - ${row.sentences.join(' ')}`
+      : `LEFT OUT of "${row.fact}" (the rest is still checked): ${row.sentences.join(' ')}`);
+  }
   for (const p of report.prose) add(p.line, 'WRITTEN TEXT (not looked up; keep its word/section counts)');
   for (const n of report.notFound) add(n.line, `NOT FOUND${n.rule ? ` (rule ${n.rule})` : ''}: ${n.words ? `${JSON.stringify(n.words)} - ` : ''}${n.why}`);
   const lines = [...byLine.keys()].sort((a, b) => a - b).map((n) => `line ${n}:\n${byLine.get(n).map((/** @type {string} */ s) => `  ${s}`).join('\n')}`);

package/src/interviewrun.js

@@ -690,7 +690,6 @@ export async function main(argv, deps = {}) {
     // endpoint on its own in that case (PRD item 28 ruling (d)).
     ...(baseUrlArg === null ? {} : { baseUrl: baseUrlArg }),
     ...(modelArg === null ? {} : { model: modelArg }),
-    cadence: { unit: 'day', every: 1 },
     budgetUsd,
     ...(wallMin === null ? {} : { maxWallMs: Math.round(wallMin * 60_000) }),
     // ABSENT for a plain folder (`writeScope === null`, D5/step S6) — never a

package/src/job.js

@@ -18,6 +18,8 @@ import { globToPrefix, scopeContained, isObj, isNonEmptyString, sweepSecretLiter
 import { validateCloseDecl, DECLARED_CLOSE_CLASSES } from './declaredclose.js';
 import { inputLabelsOf } from './rubricstep.js';
 import { CLOSE_TIMEOUT_FLOOR_MS } from './closetimeout.js';
+import { validateTrigger } from './trigger.js';
+import { resolveJobJudge } from './judged.js';
 
 // The menus below ARE the close-authoring hierarchy (PRD §7) and ship frozen:
 // they are read at call time, so a mutable export would let adopter code
@@ -168,7 +170,7 @@ export const CONDITION_KEYS = Object.freeze(['providerPath', 'closeVerbosity', '
 // `steps` stays in the field list ONLY so a retired spec reds by name
 // (`shape-retired`) instead of falling through to a generic unknown-field —
 // the operator gets told what happened, not just that something is wrong.
-const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'baseUrl', 'conditions', 'cadence', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'thinking', 'judge', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools', 'jobLines', 'inputs'];
+const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'baseUrl', 'conditions', 'cadence', 'trigger', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'thinking', 'judge', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools', 'jobLines', 'inputs'];
 /** the exact fields of a signed `judge` override — nested objects red unknown
  * keys too, because no smuggling level exists in a signed spec */
 const JUDGE_FIELDS = ['provider', 'model'];
@@ -278,15 +280,25 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
     }
   }
 
-  if (spec.cadence === undefined) red('missing-required', 'cadence');
-  else if (!isObj(spec.cadence)) red('invalid-value', 'cadence', 'object of {unit, every}');
-  else {
-    const cad = spec.cadence;
-    for (const key of Object.keys(cad)) {
-      if (key !== 'unit' && key !== 'every') red('unknown-field', `cadence.${key}`, 'nested objects red unknown keys too — no smuggling level exists in a signed spec');
+  // T (PRD v1.99): `cadence` is no longer required. A spec signed before triggers keeps its `cadence` (still validated
+  // when present, read as by hand, never rewritten, never re-hashed); a new spec carries none.
+  if (spec.cadence !== undefined) {
+    if (!isObj(spec.cadence)) red('invalid-value', 'cadence', 'object of {unit, every}');
+    else {
+      const cad = spec.cadence;
+      for (const key of Object.keys(cad)) {
+        if (key !== 'unit' && key !== 'every') red('unknown-field', `cadence.${key}`, 'nested objects red unknown keys too — no smuggling level exists in a signed spec');
+      }
+      if (!CADENCE_UNITS.includes(cad.unit)) red('invalid-value', 'cadence.unit', CADENCE_UNITS.join('|'));
+      if (!(Number.isInteger(cad.every) && cad.every >= 1 && cad.every <= 30)) red('bounds', 'cadence.every', '1..30');
     }
-    if (!CADENCE_UNITS.includes(cad.unit)) red('invalid-value', 'cadence.unit', CADENCE_UNITS.join('|'));
-    if (!(Number.isInteger(cad.every) && cad.every >= 1 && cad.every <= 30)) red('bounds', 'cadence.every', '1..30');
+  }
+
+  // T: the trigger the person signed (a typed object, never cron text). ABSENT = by hand. Set only by the panel's
+  // two-click schedule door; the agent never writes it (assembleSpec refuses a draft that carries it).
+  if (spec.trigger !== undefined) {
+    const tv = validateTrigger(spec.trigger);
+    if (!tv.ok) red(tv.code, tv.path, tv.say);
   }
 
   if (spec.budgetUsd === undefined) red('missing-required', 'budgetUsd');
@@ -333,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)');
   }
@@ -931,6 +943,13 @@ export function jobSpecHash(job) {
  */
 export const REUSE_OPEN_SPEC_FIELDS = Object.freeze(['source', 'destination', 'writeScope', 'budgetUsd', 'maxWallMs', 'inputs']);
 
+/**
+ * The signed spec's schedule fields: {@link workflowKey} ignores them too, so a scheduled spec keeps the workflow
+ * key of the green run it was scheduled from (else Reuse would refuse every scheduled spec). They stay inside
+ * {@link jobSpecHash}. Kept apart from {@link REUSE_OPEN_SPEC_FIELDS}, which names the Reuse boxes.
+ */
+export const SCHEDULE_SPEC_FIELDS = Object.freeze(['trigger']);
+
 /**
  * The worker-identity fields {@link workflowKey} ALSO ignores (hamr 2026-10-04: Model is open on a reuse; the Name
  * chosen in Settings carries its provider and baseUrl with it). They stay inside {@link jobSpecHash}, so what the person
@@ -945,7 +964,8 @@ export const WORKFLOW_KEY_IDENTITY_FIELDS = Object.freeze(['provider', 'baseUrl'
  * share a workflow key iff they ran the same goal, checks, guardrails and close — whatever source they ran on, wherever they wrote, whatever caps they had.
  * It is NOT a signature: {@link jobSpecHash} (which covers the caps and the fence) stays what the person signs, and
  * a reuse lands on a NEW jobSpecHash with the SAME workflowKey. Same never-throws contract as `jobSpecHash`, and
- * the same resolved-`tools` form, so an omitted-`tools` spec and its spelled-out menu share a key.
+ * the same resolved-`tools` form, so an omitted-`tools` spec and its spelled-out menu share a key. A soft-green spec keys on its
+ * RESOLVED judge identity (an absent `judge` is its worker's), so pinning the default judge never changes the key.
  * @param {object} job
  * @returns {string} sha256 hex
  */
@@ -954,7 +974,14 @@ export function workflowKey(job) {
   try {
     /** @type {any} */
     const rest = isObj(job) ? { ...job } : job;
-    if (isObj(rest)) for (const f of [...REUSE_OPEN_SPEC_FIELDS, ...WORKFLOW_KEY_IDENTITY_FIELDS]) delete rest[f];
+    // A RUBRIC job's judge defaults to its own worker. The worker identity is dropped below, so resolve the judge FIRST
+    // (the runner's one spelling) and key on that: a spec with no `judge` and the same spec with the judge pinned to
+    // its default (what a reuse/schedule signs) are one workflow; an explicitly different judge is another.
+    // Deterministic specs have no judge, so their key is untouched. An unresolvable judge leaves the spec as signed.
+    if (isObj(rest) && rest.verdictType === 'soft-green') {
+      try { rest.judge = resolveJobJudge(/** @type {any} */ (rest), /** @type {any} */ (rest.provider), resolveWorkerModel); } catch { /* validateJob reds it */ }
+    }
+    if (isObj(rest)) for (const f of [...REUSE_OPEN_SPEC_FIELDS, ...WORKFLOW_KEY_IDENTITY_FIELDS, ...SCHEDULE_SPEC_FIELDS]) delete rest[f];
     c = canon(resolveSpec(rest));
   } catch { c = '\u0000unhashable'; }
   return createHash('sha256').update(`workflow-key-v1\n${c}`).digest('hex');

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,64 @@
+// 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.`,
+  'currency-not-symbol': (d) => `"${d.word}" is not a currency sign ($, € or £); a word the page writes after the amount is read as a unit.`,
+  '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(' ')}`;
+}

package/src/pagemap.js

@@ -0,0 +1,264 @@
+// 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 { 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);
+    for (const f of kept.facts) facts.push(lookFactOf(f, label));
+    for (const d of kept.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}.`);
+}