bareloop 0.43.0 → 0.44.0

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}.`);
+}

package/src/pagerules.js

@@ -0,0 +1,319 @@
+// IDEA A CORE (docs/product/ITEM33-BUILD.md "Addendum 2026-10-18 — Idea A core: build spec", section 4.2): the plain code rules that
+// keep or drop each page word the AI's map named. The AI never grades: it names words, code keeps only what the saved page proves.
+// Pure - no I/O, no clock, no model. The rule bodies are PORTED from the frozen POC (.claude/scratch/idea-a-v2/rules.mjs and
+// rules-v3-candidate.mjs; sha256 recorded in commit 0bcc5fe), with the OUT branches (R2, R2a, R2b, R2c, R3, R3U, V4, pageClaims) deleted.
+
+import { lineRules } from './rubricstep.js';
+import { MAX_CURRENCIES, MAX_UNITS, MAX_UNIT_CHARS, FACT_OPS, boundOk } from './facts.js';
+import { countExact, countPhrase, squash } from './factwords.js';
+import { normLabel } from './labelscan.js';
+
+/**
+ * @typedef {{op: string, value?: string|number, lo?: string|number, hi?: string|number}} Reading what a `~` rule means as a limit (PRD v1.107 Part 5b): the same shape as a signed fact rule
+ * @typedef {{name: string, from?: string, shape: string, words?: string[], currency?: string[], unit?: string[], reading?: Reading}} MapFact the AI's map, one fact
+ * @typedef {{facts: MapFact[]}} PageMap
+ * @typedef {{line: number, name: string, shape: string, from: string, words: string[], unit?: string[], currency?: string[], forRule?: number, reading?: Reading}} KeptFact
+ *   `words` = what the page proves: the labels of a money/number/time fact, or the alternative phrases of a phrase fact (a place is a phrase)
+ * @typedef {{line: number, rule?: number, fact: string, word?: string, reason: string, other?: string}} Dropped  `other` = what the drop is compared to: the first label (R1), the primary form (R1L), the fact it would have repeated (S1)
+ */
+
+/** @param {unknown} v @returns {v is Record<string, any>} */
+const isRec = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * Which job line, and which `~` rule under it, a map fact carries out. The map writes `from` as "line N", "line N rule M", "rule M" or
+ * "job line"; anything else is the first job line.
+ * @param {unknown} from @param {{n: number, text?: string, rule?: string, rules?: string[]}[]} jobLines
+ * @returns {{line: number, rule?: number}}
+ */
+export function tieOf(from, jobLines) {
+  const s = String(from ?? '');
+  const lineM = /line\s*(\d+)/i.exec(s);
+  const ruleM = /rule\s*(\d+)/i.exec(s);
+  const first = jobLines[0]?.n ?? 1;
+  let line = lineM && jobLines.some((l) => l.n === Number(lineM[1])) ? Number(lineM[1]) : null;
+  const rule = ruleM ? Number(ruleM[1]) : undefined;
+  if (line === null && rule !== undefined) line = jobLines.find((l) => lineRules(l).length >= rule)?.n ?? null;
+  const out = { line: line ?? first };
+  if (rule !== undefined && lineRules(jobLines.find((l) => l.n === out.line)).length >= rule) return { ...out, rule };
+  return out;
+}
+
+/**
+ * Is this a legal `reading` for a fact of this shape? Only a time or money fact carries one, with the op set and the bound types of a signed
+ * fact rule (src/facts.js): no other key, no missing bound. A malformed one makes the whole map answer malformed (no repair).
+ * @param {unknown} shape @param {unknown} r @returns {boolean}
+ */
+export function validReading(shape, r) {
+  if (shape !== 'time' && shape !== 'money') return false;
+  if (!isRec(r) || !FACT_OPS.includes(r.op)) return false;
+  const keys = Object.keys(r).sort().join();
+  return r.op === 'between' ? keys === 'hi,lo,op' && boundOk(shape, r.lo) && boundOk(shape, r.hi) : keys === 'op,value' && boundOk(shape, r.value);
+}
+
+/** @param {string} text @returns {string[]} the page's lines, white space squashed (the unit every per-line rule counts in) */
+export const linesOf = (text) => text.split('\n').map(squash);
+
+/**
+ * How many times a label occurs inside ONE page line, at most (plain indexOf on squashed lines, non-overlapping): the N2 measure.
+ * @param {string[]} lines @param {string} phrase @returns {number}
+ */
+function maxPerLine(lines, phrase) {
+  const p = squash(phrase).trim();
+  if (!p) return 0;
+  let max = 0;
+  for (const ln of lines) {
+    let n = 0;
+    for (let i = ln.indexOf(p); i !== -1; i = ln.indexOf(p, i + p.length)) n += 1;
+    if (n > max) max = n;
+  }
+  return max;
+}
+
+/** the value each shape reads right after a label: a money or number is digits (a sign may come first), a time is h:mm and AM/PM */
+const READ = {
+  money: /^\s*[$€£]?\s*(\d[\d,]*(?:\.\d+)?)/,
+  time: /^\s*(\d{1,2}:\d{2}[\s\u202f\u00a0]?[AaPp][Mm])/,
+  number: /^\s*(\d[\d,]*(?:\.\d+)?)/,
+};
+
+/**
+ * R1 reader: the set of values of a fact's shape written right after each occurrence of a label on the page.
+ * @param {string[]} lines @param {string} label @param {'money'|'time'|'number'} shape @returns {Set<string>}
+ */
+function valueSet(lines, label, shape) {
+  /** @type {Set<string>} */
+  const s = new Set();
+  const p = squash(label).trim();
+  if (!p) return s;
+  for (const ln of lines) {
+    for (let i = ln.indexOf(p); i !== -1; i = ln.indexOf(p, i + p.length)) {
+      const m = READ[shape].exec(ln.slice(i + p.length));
+      if (m) s.add(m[1]);
+    }
+  }
+  return s;
+}
+/** @param {Set<string>} a @param {Set<string>} b @returns {boolean} */
+const sameSet = (a, b) => a.size === b.size && [...a].every((x) => b.has(x));
+
+/** a number as the page writes it: digits, thousands commas, optional decimals (a currency sign next to it is not part of it) */
+const NUM = '\\d[\\d,]*(?:\\.\\d+)?';
+const BEFORE = new RegExp(`(${NUM})\\s*$`);
+const AFTER = new RegExp(`^\\s*(?:[$€£]\\s*)?(${NUM})`);
+const AFTER_CUR = new RegExp(`^\\s*(${NUM})`);
+const stripCommas = (/** @type {string} */ s) => s.replace(/,/g, '');
+
+/** @param {string[]} lines @param {string} w @returns {[string, number][]} every occurrence of w as [its line, where it starts] */
+function occs(lines, w) {
+  /** @type {[string, number][]} */
+  const out = [];
+  for (const l of lines) for (let i = l.indexOf(w); i !== -1; i = l.indexOf(w, i + w.length)) out.push([l, i]);
+  return out;
+}
+
+/**
+ * U1: how many times a label has a number right BEFORE it (whitespace only between) and right AFTER it (whitespace and one currency sign
+ * between). A marker the page writes after the number ("490 total") has B > 0 and A = 0.
+ * @param {string[]} lines @param {string} label @returns {{B: number, A: number}}
+ */
+function beforeAfter(lines, label) {
+  let B = 0;
+  let A = 0;
+  for (const [l, i] of occs(lines, label)) {
+    if (BEFORE.test(l.slice(0, i))) B += 1;
+    if (AFTER.test(l.slice(i + label.length))) A += 1;
+  }
+  return { B, A };
+}
+/** R1L: the numbers a UNIT form reads - the one right before each occurrence @param {string[]} lines @param {string} u @returns {Set<string>} */
+const unitSet = (lines, u) => new Set(occs(lines, u).map(([l, i]) => BEFORE.exec(l.slice(0, i))?.[1]).filter((v) => typeof v === 'string').map((v) => stripCommas(/** @type {string} */ (v))));
+/** R1L: the numbers a CURRENCY form reads - the one right after each occurrence @param {string[]} lines @param {string} c @returns {Set<string>} */
+const curSet = (lines, c) => new Set(occs(lines, c).map(([l, i]) => AFTER_CUR.exec(l.slice(i + c.length))?.[1]).filter((v) => typeof v === 'string').map((v) => stripCommas(/** @type {string} */ (v))));
+
+/** S1: a fact name that counts results ("the second flight") cannot be checked per result - one result is one record, ask for N results instead */
+const ORDINALS = ['first', 'second', 'third', 'fourth', 'fifth', 'sixth', 'seventh', 'eighth', 'ninth', 'tenth', 'latest', 'earliest', 'newest', 'oldest', 'last', 'next', 'previous', 'final', 'nth'];
+
+/** the symbols a currency may be (src/facts.js); a code like "EUR" is a word read after the number, so it is a unit */
+const CURRENCY_SYMBOLS = ['$', '€', '£'];
+/** the shapes that read a value after a label */
+const VALUE_SHAPES = ['money', 'time', 'number'];
+
+/**
+ * Apply the rules to the AI's map over one saved page. Returns the kept facts and, for everything a rule removed, one `dropped` entry.
+ * The order of the rules is the POC's (apply-v3.mjs): found-on-page, then the rules that read the page. A place is read as a phrase.
+ * @param {string} text the frozen page text @param {PageMap} mapping @param {{n: number, text?: string, rule?: string, rules?: string[]}[]} jobLines
+ * @returns {{facts: KeptFact[], dropped: Dropped[]}}
+ */
+export function applyPageRules(text, mapping, jobLines) {
+  /** @type {Dropped[]} */
+  const dropped = [];
+  const all = Array.isArray(mapping?.facts) ? mapping.facts.filter(isRec) : [];
+  /** @type {Map<MapFact, {line: number, rule?: number}>} */
+  const ties = new Map(all.map((f) => [f, tieOf(f.from, jobLines)]));
+  const drop = (/** @type {MapFact} */ f, /** @type {string|undefined} */ word, /** @type {string} */ reason, /** @type {string|undefined} */ other = undefined) => {
+    const t = /** @type {{line: number, rule?: number}} */ (ties.get(f));
+    dropped.push({ line: t.line, ...(t.rule === undefined ? {} : { rule: t.rule }), fact: String(f.name ?? ''), ...(word === undefined ? {} : { word }), reason, ...(other === undefined ? {} : { other }) });
+  };
+
+  // ---- S1, name part: a fact whose name counts results is refused before anything else reads it ----
+  const list = all.filter((f) => {
+    const hit = String(f.name ?? '').toLowerCase().split(/[^a-z]+/).find((w) => ORDINALS.includes(w));
+    if (hit === undefined) return true;
+    drop(f, undefined, 's1-name');
+    return false;
+  });
+
+  // ---- found-on-page, then U1 and R1L for the facts that read an amount ----
+  const lines = linesOf(text);
+  /** @type {{f: MapFact, kept: string[], cur: string[], uni: string[], first?: string|null, anchorless?: boolean}[]} */
+  const pending = [];
+  for (const f of list) {
+    const words = (Array.isArray(f.words) ? f.words : []).map((w) => String(w)).filter((w) => w.trim() !== '');
+    if (f.shape === 'place' || f.shape === 'phrase') {
+      const kept = [];
+      for (const w of words) {
+        const n = f.shape === 'phrase' ? countPhrase(text, w) : countExact(text, w);
+        if (n >= 1) kept.push(w); else drop(f, w, 'not-on-page');
+      }
+      pending.push({ f, kept, cur: [], uni: [] });
+    } else if (VALUE_SHAPES.includes(String(f.shape))) {
+      const amount = f.shape === 'money' || f.shape === 'number';
+      /** labels the page holds (and, for an amount, that have a number right after them) */
+      const labels = [];
+      /** the AI's labels as U1 leaves them, a word the page does not hold included: the first of these is R1's reference */
+      const asListed = [];
+      /** U1: labels the page writes after the number */
+      const moved = [];
+      for (const w0 of words) {
+        const w = normLabel(w0);
+        if (!w) continue;
+        if (countExact(text, w) < 1) { asListed.push(w0); drop(f, w0, 'not-on-page'); continue; }
+        if (amount) {
+          const { B, A } = beforeAfter(lines, w);
+          if (A === 0 && B > 0) { moved.push(w); continue; }
+          if (A === 0 && B === 0) { drop(f, w, 'no-value'); continue; }
+        }
+        asListed.push(w0);
+        labels.push(w);
+      }
+      /** @type {string[]} */ let uni = [];
+      /** @type {string[]} */ let cur = [];
+      if (f.shape === 'money') {
+        // the forms: units first (the U1-moved words, then the AI's listed units), then currency signs
+        const listedCurrencies = (Array.isArray(f.currency) ? f.currency : []).map(String);
+        // a currency SIGN listed in BOTH unit and currency is said once: the unit copy goes (fwd F71 drafts)
+        const listedUnits = (Array.isArray(f.unit) ? f.unit : []).map(String).filter((u) => {
+          if (!(CURRENCY_SYMBOLS.includes(u) && listedCurrencies.includes(u))) return true;
+          drop(f, u, 'sign-twice');
+          return false;
+        });
+        const units = [...new Set([...moved, ...listedUnits])].filter((u) => {
+          if (countPhrase(text, u) >= 1) return true;
+          drop(f, u, 'not-on-page');
+          return false;
+        });
+        const curs = listedCurrencies.filter((c) => {
+          if (countExact(text, c) >= 1) return true;
+          drop(f, c, 'not-on-page');
+          return false;
+        });
+        /** @type {{kind: 'unit'|'currency', w: string}[]} */
+        const forms = [...units.map((u) => /** @type {const} */ ({ kind: 'unit', w: u })), ...curs.map((c) => /** @type {const} */ ({ kind: 'currency', w: c }))];
+        if (forms.length) {
+          // R1L: every form reads the same set of numbers as the primary (the first form); one that reads more or fewer is dropped
+          const read = (/** @type {{kind: string, w: string}} */ x) => (x.kind === 'unit' ? unitSet(lines, x.w) : curSet(lines, x.w));
+          const ps = read(forms[0]);
+          const keep = [forms[0]];
+          // the same word listed as both a unit and a currency is ONE form: it is never compared with itself, only said (the unit, listed first, stays)
+          for (const x of forms.slice(1)) { if (x.w !== forms[0].w && sameSet(read(x), ps)) keep.push(x); else drop(f, x.w, 'r1l', forms[0].w); }
+          uni = keep.filter((x) => x.kind === 'unit').map((x) => x.w);
+          cur = keep.filter((x) => x.kind === 'currency').map((x) => x.w);
+        }
+        // a currency that is a word ("US dollars") is read after the number, so it is a unit, never a currency sign
+        cur = cur.filter((c) => {
+          if (CURRENCY_SYMBOLS.includes(c)) return true;
+          drop(f, c, 'currency-not-symbol');
+          return false;
+        });
+        // the guard's list limits (src/facts.js), applied here so a longer list is cut by code and SAID, never refused later: the first forms stay
+        uni = uni.filter((u, i) => {
+          if (u.length > MAX_UNIT_CHARS) { drop(f, u, 'unit-too-long'); return false; }
+          if (i >= MAX_UNITS) { drop(f, u, 'limit-unit'); return false; }
+          return true;
+        });
+        cur = cur.filter((c, i) => {
+          if (i < MAX_CURRENCIES) return true;
+          drop(f, c, 'limit-currency');
+          return false;
+        });
+      }
+      pending.push({ f, kept: labels, cur, uni, first: asListed.length ? normLabel(asListed[0]) : null, anchorless: amount && asListed.length === 0 });
+    } else drop(f, undefined, 'bad-shape');
+  }
+
+  // ---- R1, same-value: the labels after the AI's FIRST listed one are kept only if they read the same set of values as it does ----
+  for (const p of pending) {
+    if (!VALUE_SHAPES.includes(String(p.f.shape))) continue;
+    const shape = /** @type {'money'|'time'|'number'} */ (p.f.shape);
+    const ref = p.first ? valueSet(lines, p.first, shape) : new Set();
+    p.kept = p.kept.filter((w) => {
+      if (w === p.first) return true;
+      if (sameSet(valueSet(lines, w, shape), ref)) return true;
+      drop(p.f, w, 'r1', p.first ?? undefined);
+      return false;
+    });
+  }
+
+  // ---- N2, per line: a label written 2+ times inside one page line cannot say which value is meant, so it is unusable. (R2 grow-left is OUT.) ----
+  for (const p of pending) {
+    if (!VALUE_SHAPES.includes(String(p.f.shape))) continue;
+    p.kept = p.kept.filter((w) => {
+      if (maxPerLine(lines, w) <= 1) return true;
+      drop(p.f, w, 'n2');
+      return false;
+    });
+  }
+
+  // ---- the kept facts, in the POC's order: places, phrases, then values ----
+  /** @type {KeptFact[]} */
+  const signed = [];
+  const make = (/** @type {{f: MapFact, kept: string[], cur: string[], uni: string[]}} */ p) => {
+    const t = /** @type {{line: number, rule?: number}} */ (ties.get(p.f));
+    /** @type {KeptFact} */
+    const out = { line: t.line, name: String(p.f.name), shape: p.f.shape === 'place' ? 'phrase' : String(p.f.shape), from: String(p.f.from ?? ''), words: [...p.kept] };
+    if (p.f.shape === 'money') {
+      if (p.uni.length) out.unit = [...p.uni];
+      if (p.cur.length) out.currency = [...p.cur];
+    }
+    if (t.rule !== undefined) out.forRule = t.rule;
+    if (validReading(out.shape, p.f.reading)) out.reading = /** @type {Reading} */ ({ ...p.f.reading });
+    return out;
+  };
+  for (const kind of ['place', 'phrase', 'value']) {
+    for (const p of pending) {
+      const isValue = VALUE_SHAPES.includes(String(p.f.shape));
+      if (kind === 'value' ? !isValue : p.f.shape !== kind) continue;
+      // a fact left with no label is dropped, unless U1 moved every label to a unit/currency form of a money fact (it then reads that form
+      // alone); a money fact also needs a currency or a unit the page holds
+      const forms = p.cur.length + p.uni.length;
+      const ok = p.f.shape === 'money' ? forms > 0 && (p.kept.length > 0 || p.anchorless === true) : p.kept.length > 0;
+      if (!ok) { drop(p.f, undefined, 'no-label'); continue; }
+      signed.push(make(p));
+    }
+  }
+  // ---- S1, shape and label part: two facts of one result may not share a shape AND a label (they would read the same value and can never differ).
+  // The first one stays; a fact with no label is keyed by its first unit or currency, so two different amounts are never confused. ----
+  /** @type {Map<string, string>} */
+  const seen = new Map();
+  const kept = signed.filter((k) => {
+    const key = `${k.shape}\u0000${k.words[0] ?? k.unit?.[0] ?? k.currency?.[0] ?? ''}`;
+    const first = seen.get(key);
+    if (first === undefined) { seen.set(key, k.name); return true; }
+    const f = /** @type {MapFact} */ (all.find((x) => String(x.name) === k.name));
+    drop(f, undefined, 's1', first);
+    return false;
+  });
+  const order = list.map((f) => String(f.name));
+  return { facts: kept.sort((a, b) => order.findIndex((n) => a.name.startsWith(n)) - order.findIndex((n) => b.name.startsWith(n))), dropped };
+}