bareloop 0.41.0 → 0.43.0

package/src/kinds.js

@@ -61,13 +61,14 @@
 
 import { spawn } from 'node:child_process';
 import { realpathSync } from 'node:fs';
-import { readFile, stat, mkdtemp, rm, symlink } from 'node:fs/promises';
+import { readFile, stat, lstat, mkdtemp, rm, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, sep } from 'node:path';
+import { join, sep, dirname } from 'node:path';
 import { globToPrefix, isNonEmptyString } from './validate.js';
 import { CLOSE_ENV_DENY } from './ralph.js';
 import { runLocate, decide, validateCard, LOCATE_AXES, LOCATE_LABEL } from './judged.js';
 import { rateSourceFields } from './text.js';
+import { gradeStep, stepFileRel, STEP_MAX_BYTES, citedLabels, sha256Of } from './rubricstep.js';
 
 /** the close's two judgment exits — a stage's verdict, in the shape the
  * hand-written closes already spoke (exit code is truth) */
@@ -140,7 +141,7 @@ export const SIGNS = Object.freeze([1, -1]);
  * executor runs that the catalogue never names is a capability nothing can
  * reach. `judged-floor` joined at softgreen module 2 — the runner and the
  * catalogue unlock in ONE commit for exactly that reason. */
-export const LIVE_KINDS = Object.freeze(['command-exit', 'count-not-worse', 'pattern-absent-in-diff', 'files-changed', 'human-confirms', 'judged-floor']);
+export const LIVE_KINDS = Object.freeze(['command-exit', 'count-not-worse', 'pattern-absent-in-diff', 'files-changed', 'human-confirms', 'judged-floor', 'rubric-step']);
 /**
  * The judged stage's ladder: ONE attempt plus ONE retry, and no more.
  *
@@ -1526,6 +1527,85 @@ async function runFilesChanged(stage, ctx) {
   });
 }
 
+/**
+ * PART 1a — the `rubric-step` kind: grade ONE job line's step file (output/steps/N.json) with bareguard's rubric primitive.
+ * It spawns nothing and buys nothing. The inputs a step cites are read from the frozen tree (`input/...`) and held to the
+ * sha256 the SOURCE DOOR recorded in `<into>/source.json` (`inputs: [{label, rel, sha256}]`), so an input that changed after
+ * the freeze is a stopped instrument, never a green. The rubric is built here, at every run, from the stage's own parameters
+ * (the inputs belong to the run, not to the signed job). A step file that is missing, cut off, or not a JSON object is a RED
+ * (the worker has not finished the line); an instrument that cannot read what it must is a STOP (97), never a red.
+ * @param {any} stage @param {Ctx} ctx @returns {Promise<StageResult>}
+ */
+async function runRubricStep(stage, ctx) {
+  const p = stage.params;
+  const step = p.step;
+  const stop = (/** @type {string} */ why, /** @type {string} */ fault = STOP_FAULTS.FAILED) => stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}": ${why}`, { step }, fault);
+  // the source door's record of what was frozen: beside the tree, one level up (`<into>/source.json`, `<into>/tree`)
+  /** @type {any} */
+  let manifest;
+  try { manifest = JSON.parse(await readFile(join(dirname(ctx.workdir), 'source.json'), 'utf8')); } catch (e) {
+    return stop(`the source record (source.json beside the job's tree) could not be read: ${/** @type {Error} */ (e).message}`);
+  }
+  const recorded = Array.isArray(manifest?.inputs) ? manifest.inputs : [];
+  /** @type {Record<string, string>} */
+  const inputShas = {};
+  /** @type {Record<string, string>} */
+  const inputs = {};
+  for (const label of citedLabels(p)) {
+    const row = recorded.find((/** @type {any} */ r) => r && r.label === label);
+    if (!row || typeof row.rel !== 'string' || typeof row.sha256 !== 'string') return stop(`the step cites "${label}", but the source record has no input with that label`);
+    let buf;
+    try { buf = await readFile(join(ctx.workdir, row.rel)); } catch (e) { return stop(`input "${label}" (${row.rel}) could not be read: ${/** @type {Error} */ (e).message}`); }
+    if (sha256Of(buf) !== row.sha256) return stop(`input "${label}" (${row.rel}) no longer matches the bytes frozen at the source door`);
+    inputShas[label] = row.sha256;
+    inputs[label] = buf.toString('utf8');
+  }
+  // the step file: a regular file, read once, bounded
+  const abs = join(ctx.workdir, stepFileRel(step));
+  /** @type {string|null} */
+  let bytes = null;
+  let notRegular = false;
+  try {
+    const ls = await lstat(abs);
+    if (!ls.isFile()) notRegular = true;
+    else if (ls.size > STEP_MAX_BYTES) return stop(`${stepFileRel(step)} is over the ${STEP_MAX_BYTES} byte limit the rubric reads`);
+    else bytes = (await readFile(abs)).toString('utf8');
+  } catch (e) {
+    if (/** @type {any} */ (e)?.code !== 'ENOENT') return stop(`${stepFileRel(step)} could not be read: ${/** @type {Error} */ (e).message}`);
+  }
+  // PART 1b: a prose step's numbers are tied to the quotes the earlier fact lines' step files hold (those stages ran, and were
+  // green, before this one: the close is first-red-wins in stage order, which the validator pins). Unreadable = a stopped instrument.
+  /** @type {Record<number, string[]>} */
+  const factQuotes = {};
+  /** @type {number[]} */
+  const factMissing = [];
+  const tie = Array.isArray(p.parts) ? p.parts.find((/** @type {any} */ x) => x && x.class === 'countable' && x.check === 'numbersFromFacts') : null;
+  for (const n of tie ? tie.from : []) {
+    try {
+      const parsedFacts = JSON.parse(await readFile(join(ctx.workdir, stepFileRel(n)), 'utf8'));
+      const results = Array.isArray(parsedFacts?.results) ? parsedFacts.results : [];
+      factQuotes[n] = results.map((/** @type {any} */ r) => (r && typeof r.quote === 'string' ? r.quote : ''));
+    } catch (e) {
+      // M2: an earlier line's file that is not there (the seed read, before any worker wrote) is a normal red, never an instrument fault
+      if (/** @type {any} */ (e)?.code === 'ENOENT') { factMissing.push(n); continue; }
+      return stop(`the checked facts of line ${n} (${stepFileRel(n)}) could not be read for the number tie: ${/** @type {Error} */ (e).message}`);
+    }
+  }
+  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);
+  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}`);
+  const red = graded.verdict === 'red' || notRegular;
+  return result(stage, {
+    verdict: red ? 'red' : 'green',
+    exitCode: red ? EXIT_RED : EXIT_GREEN,
+    gapLines: gap.render(),
+    // the trend number (`trendValueOf`, src/declaredclose.js, reads `detail.redCount` for a stage with no measurement)
+    detail: { ...graded.detail, ...(notRegular ? { redCount: 1 } : {}) },
+  });
+}
+
 /**
  * THE SIGNER'S ANSWER, normalised at the seam that accepts it — the library half
  * of the three-button gate (2026-08-12 §1).
@@ -1954,6 +2034,7 @@ const RUNNERS = {
   'files-changed': runFilesChanged,
   'human-confirms': runHumanConfirms,
   'judged-floor': runJudgedFloor,
+  'rubric-step': runRubricStep,
 };
 
 /**

package/src/labelscan.js

@@ -0,0 +1,170 @@
+// THE LABEL LIST (PART 1c, docs/product/ITEM33-BUILD.md "3. The look", "LABELS ARE PICKED, NEVER TYPED"): before the look, code scans a
+// source at $0 and lists, per shape (money, number, date, time, text), the words that sit right before a value of that shape,
+// with how often each occurs. The look and the drafter pick a label ONLY from this list (by id or exact text); a label that is not on
+// it is a $0 red naming it. ONE generic scan for every page or file - there is no per-site table here and never will be.
+//
+// How a label is found (all of it plain string work, no model):
+//   - each line is cleaned (any run of white space, U+202F / U+00A0 included, becomes one space; bracketed tags like `[ref=549]` that a
+//     page reader adds are dropped);
+//   - values are found in a fixed order of shapes: date, time, money, number, and last `text` = any other token that holds a digit
+//     (a version like 0.41.0, an id). A value is only a place to look BEFORE: bareguard reads the real value at run time;
+//   - the words before a value are the text between the previous value on the line and this one, cut to its last one or two
+//     tokens (and the whole gap when it is short); a label holds no digit;
+//   - text facts also get the words before each REPEATED capitalised phrase (an airport, a city, a name): `Leaves` before one phrase,
+//     `arrives at` before another.
+// A label is listed when it occurs at least MIN_COUNT times. Nothing here decides what a label MEANS.
+
+/** the shapes a list is made for */
+export const LABEL_SHAPES = Object.freeze(['money', 'number', 'date', 'time', 'text']);
+/** a label must occur at least this often to be listed (1: a one-page document with one total still has its label; the list is cut to the highest counts) */
+export const MIN_COUNT = 1;
+/** how many labels one shape's list holds at most (the highest counts first) */
+export const MAX_PER_SHAPE = 40;
+/** the longest label, in characters */
+const MAX_LABEL = 40;
+/** the longest whole gap taken as a label when it is short */
+const MAX_GAP_LABEL = 24;
+/** a phrase must repeat this often to be a repeated phrase */
+const MIN_PHRASE = 3;
+/** how many repeated phrases are looked behind */
+const MAX_PHRASES = 20;
+/** a line is scanned up to this many characters, and for this many values (a minified page is one huge line; the bound keeps the scan linear) */
+const MAX_LINE = 20000;
+const MAX_VALUES_PER_LINE = 400;
+/** only this much of a source is scanned (a source over it is scanned up to a line end) */
+export const SCAN_MAX_CHARS = 2_000_000;
+
+const WS = /[\s   ]+/g;
+const TAG = /\[[A-Za-z]+=[^\]\s]*\]/g;
+const MONTH = '(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|Sep(?:t(?:ember)?)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)';
+/** value finders in priority order: an earlier shape owns a span a later one would also match */
+const FINDERS = /** @type {[string, RegExp][]} */ ([
+  ['date', new RegExp(`\\b\\d{4}-\\d{2}-\\d{2}\\b|\\b\\d{1,2}/\\d{1,2}/\\d{2,4}\\b|\\b${MONTH}\\.? \\d{1,2}(?:, \\d{4})?\\b|\\b\\d{1,2} ${MONTH}\\.? \\d{4}\\b`, 'g')],
+  ['time', /\b\d{1,2}:\d{2}(?: ?[AaPp]\.?[Mm]\.?)?(?![\w:])/g],
+  ['money', /[$€£] ?\d[\d,]*(?:\.\d+)?|\b\d[\d,]*(?:\.\d+)? ?(?:US dollars?|dollars?|USD|euros?|EUR|pounds?|GBP)\b/g],
+  ['number', /(?<![\w.,])\d[\d,]*(?:\.\d+)?(?![\w]|\.\d)/g],
+  ['text', /[A-Za-z]*\d[\w.\-]*/g],
+]);
+const PHRASE = /\b[A-Z][a-z]+(?: [A-Z][a-z]+)+\b/g;
+
+/** @typedef {{id: string, label: string, count: number, example: string}} LabelEntry */
+/** @typedef {Record<'money'|'number'|'date'|'time'|'text', LabelEntry[]>} LabelScan */
+
+/** @param {string} t @returns {string} white space made one space, quote marks at the edges dropped, trimmed - how a label is compared */
+export function normLabel(t) {
+  return String(t ?? '').replace(WS, ' ').trim().replace(/^["'“”]+|["'“”]+$/g, '').trim();
+}
+
+/** @param {string} gap @returns {string[]} the labels a gap of text before a value offers */
+function candidates(gap) {
+  const g = normLabel(gap);
+  if (g === '') return [];
+  const tokens = g.split(' ');
+  /** @type {Set<string>} */
+  const out = new Set();
+  out.add(normLabel(tokens.at(-1) ?? ''));
+  if (tokens.length >= 2) out.add(normLabel(tokens.slice(-2).join(' ')));
+  if (g.length <= MAX_GAP_LABEL) out.add(g);
+  return [...out].filter((c) => c !== '' && c.length <= MAX_LABEL && !/\d/.test(c) && !/ref=/.test(c));
+}
+
+/**
+ * Scan one source text for the labels that sit before values, per shape.
+ * @param {string} text
+ * @returns {LabelScan}
+ */
+export function scanLabels(text) {
+  let src = String(text ?? '');
+  if (src.length > SCAN_MAX_CHARS) { const nl = src.lastIndexOf('\n', SCAN_MAX_CHARS); src = src.slice(0, nl > 0 ? nl : SCAN_MAX_CHARS); }
+  /** @type {Record<string, Map<string, {count: number, example: string}>>} */
+  const seen = Object.fromEntries(LABEL_SHAPES.map((s) => [s, new Map()]));
+  const bump = (/** @type {string} */ shape, /** @type {string} */ label, /** @type {string} */ example) => {
+    const m = seen[shape];
+    const cur = m.get(label);
+    if (cur) cur.count += 1; else m.set(label, { count: 1, example });
+  };
+  /** @type {Map<string, number>} */
+  const phraseCount = new Map();
+  /** @type {string[]} */
+  const lines = [];
+  /** @type {{line: string, at: number, phrase: string}[]} */
+  const variants = [];
+  for (const raw of src.split('\n')) {
+    const line = raw.slice(0, MAX_LINE).replace(TAG, ' ').replace(WS, ' ').trim();
+    if (line === '') continue;
+    lines.push(line);
+    for (const m of line.matchAll(PHRASE)) {
+      // a capitalised run may start with a sentence-initial word ("Leaves San Francisco ..."): the run is also read without its first word
+      const words = m[0].split(' ');
+      let off = m.index ?? 0;
+      for (let j = 0; j <= 1 && words.length - j >= 2; j += 1) {
+        const phrase = words.slice(j).join(' ');
+        phraseCount.set(phrase, (phraseCount.get(phrase) ?? 0) + 1);
+        variants.push({ line, at: off, phrase });
+        off += words[j].length + 1;
+      }
+    }
+  }
+  for (const line of lines) {
+    /** @type {{shape: string, s: number, e: number, v: string}[]} */
+    const found = [];
+    for (const [shape, re] of FINDERS) {
+      for (const m of line.matchAll(re)) {
+        const s = m.index ?? 0;
+        const e = s + m[0].length;
+        if (found.length >= MAX_VALUES_PER_LINE) break;
+        if (found.some((f) => s < f.e && e > f.s)) continue;
+        found.push({ shape, s, e, v: m[0] });
+      }
+    }
+    found.sort((a, b) => a.s - b.s);
+    let prevEnd = 0;
+    for (const f of found) {
+      for (const c of candidates(line.slice(prevEnd, f.s))) bump(f.shape, c, f.v);
+      prevEnd = f.e;
+    }
+  }
+  // the words before each REPEATED capitalised phrase (a place, a name): text facts
+  const phrases = new Set([...phraseCount].filter(([, n]) => n >= MIN_PHRASE).sort((a, b) => b[1] - a[1]).slice(0, MAX_PHRASES).map(([p]) => p));
+  for (const v of variants) {
+    if (!phrases.has(v.phrase)) continue;
+    for (const c of candidates(v.line.slice(0, v.at))) bump('text', c, v.phrase);
+  }
+  /** @type {Record<string, string>} */
+  const prefix = { money: 'm', number: 'n', date: 'd', time: 't', text: 'x' };
+  return /** @type {LabelScan} */ (Object.fromEntries(LABEL_SHAPES.map((shape) => {
+    const rows = [...seen[shape]].filter(([, v]) => v.count >= MIN_COUNT)
+      .sort((a, b) => b[1].count - a[1].count || a[0].length - b[0].length || (a[0] < b[0] ? -1 : 1))
+      .slice(0, MAX_PER_SHAPE)
+      .map(([label, v], i) => ({ id: `${prefix[shape]}${i + 1}`, label, count: v.count, example: v.example }));
+    return [shape, rows];
+  })));
+}
+
+/**
+ * Is this label on the list for this shape? Compared the way a label is read: white space of any kind is one space, quote marks at the
+ * edges are dropped. `idOrText` may be a list id (`t1`) or the exact words.
+ * @param {LabelScan} scan @param {string} shape @param {unknown} idOrText
+ * @returns {LabelEntry|null}
+ */
+export function labelOnList(scan, shape, idOrText) {
+  const rows = scan[/** @type {'money'} */ (shape)];
+  if (!rows || typeof idOrText !== 'string') return null;
+  const asId = rows.find((r) => r.id === idOrText.trim());
+  if (asId) return asId;
+  const want = normLabel(idOrText);
+  return rows.find((r) => r.label === want) ?? null;
+}
+
+/**
+ * The list as the look and the drafter are shown it, one block per shape that has any label.
+ * @param {string} inputLabel the input the list belongs to @param {LabelScan} scan
+ * @returns {string}
+ */
+export function renderLabelList(inputLabel, scan) {
+  const blocks = LABEL_SHAPES.filter((s) => scan[/** @type {'money'} */ (s)].length > 0).map((s) => {
+    const rows = scan[/** @type {'money'} */ (s)].map((r) => `  ${r.id}  ${JSON.stringify(r.label)}  x${r.count}  e.g. ${JSON.stringify(r.example)}`);
+    return `${s} (the words right before a ${s === 'text' ? 'repeated phrase or an id/version' : s}):\n${rows.join('\n')}`;
+  });
+  return `LABELS IN THE INPUT "${inputLabel}" - pick a label ONLY from this list (by its id or its exact words); a label that is not here is refused:\n\n${blocks.length ? blocks.join('\n\n') : '(no repeated label was found before a value)'}`;
+}

package/src/pagefetch.js

@@ -0,0 +1,125 @@
+// URL inputs (PART 1c, docs/product/ITEM33-BUILD.md "4. URL inputs" + live fix L1, PRD item 33 RF21/RF22): an Inputs line may be a web
+// address the person pastes (a results page). bareloop fetches it with barebrowse, READ ONLY, headless and incognito, as published:
+//
+//     page = await connect({ incognito: true, blockPrivateNetwork: true })
+//     await page.goto(url); await page.waitForNetworkIdle({ idle, timeout }); await page.snapshot({ mode: 'act' })
+//
+// L1: one-shot `browse()` snapshots at load, before the page's own scripts fill a results list (the same URL gave 77,951 / 8,801 / 719
+// chars). So we wait for the network to go quiet (bounded) before the snapshot. Generic: no site selector. The snapshot mode is the one
+// proven in step 0 ('read' and 'full' returned almost nothing from a results page). The text that comes back is the input. An empty
+// fetch is a plain-words stop, never a silent empty input. Nothing here touches a model.
+
+import { SECRET_PATTERNS } from './validate.js';
+
+/** the session options (incognito: no auth ever enters; blockPrivateNetwork: SSRF guard); ONE frozen object so a test can pin them */
+export const CONNECT_OPTIONS = Object.freeze({ incognito: true, blockPrivateNetwork: true });
+/** the snapshot options step 0 proved */
+export const SNAPSHOT_OPTIONS = Object.freeze({ mode: 'act' });
+/** the page's network must be quiet this long (ms) before we read it: long enough to span the gap between a page's first load and the
+ *  script requests that fill the results, short enough not to stretch a plain page */
+export const NETWORK_IDLE_MS = 1500;
+/** the most we wait for the network to go quiet (ms); a page that never settles (polling, streaming) is read as it stands after this */
+export const NETWORK_IDLE_TIMEOUT_MS = 20_000;
+/** the most we wait for the page to load at all (ms) */
+export const GOTO_TIMEOUT_MS = 30_000;
+/** a page that comes back with fewer characters than this (after trimming) is treated as "nothing came back" */
+export const MIN_PAGE_CHARS = 200;
+/** the page text left after the site's own header, menus and footer are taken out must hold at least this many characters, or the page is
+ *  "only site chrome" (L2: a 719-character fetch of Google's header and sign-in passed the 200-character floor) */
+export const MIN_CONTENT_CHARS = 100;
+/** the page reader's landmark roles for a site's own chrome (the ARIA names of header, menu and footer); everything under one is not the page's content */
+const CHROME_ROLES = new Set(['banner', 'navigation', 'contentinfo']);
+/** our own deadline around one whole fetch (a hung browser leaves no trace; this is the only thing that fires on the absence of an answer) */
+export const PAGE_FETCH_TIMEOUT_MS = 90_000;
+
+/** @param {unknown} v @returns {boolean} an http(s) address (the one spelling of "this Inputs value is a web address") */
+export function isWebUrl(v) {
+  return typeof v === 'string' && /^https?:\/\//i.test(v.trim());
+}
+
+/**
+ * How much of a fetched page is the page's own content: the snapshot's header lines (url, size note, hint) and every part of the tree
+ * under a banner / navigation / contentinfo landmark are taken out, the page reader's bracketed tags are removed, and what is left is
+ * counted. Generic - no site names, only the ARIA landmark roles. Text that is not a snapshot tree (a plain file) has no landmark, so it
+ * counts whole.
+ * @param {string} text @returns {number}
+ */
+export function pageContentChars(text) {
+  const lines = String(text ?? '').split('\n');
+  let skipIndent = -1;
+  let n = 0;
+  let head = true;
+  for (const raw of lines) {
+    if (head && (/^url: /.test(raw) || /^[\d,]+ chars → /.test(raw) || /^hint: /.test(raw))) continue;
+    head = false;
+    const m = /^(\s*)- ([A-Za-z_]+)\b/.exec(raw);
+    const indent = m ? m[1].length : raw.length - raw.trimStart().length;
+    if (skipIndent >= 0) {
+      if (raw.trim() === '' || indent > skipIndent) continue;
+      skipIndent = -1;
+    }
+    if (m && CHROME_ROLES.has(m[2])) { skipIndent = indent; continue; }
+    n += raw.replace(/\[[A-Za-z]+=[^\]\s]*\]/g, ' ').replace(/^\s*-\s*/, '').replace(/\s+/g, ' ').trim().length;
+  }
+  return n;
+}
+
+/**
+ * @typedef {{goto: (url: string, timeout?: number) => Promise<void>, waitForNetworkIdle: (o?: {idle?: number, timeout?: number}) => Promise<void>,
+ *   snapshot: (o?: {mode?: string}) => Promise<string>, close: () => Promise<void>}} FetchPage the part of barebrowse's page handle the fetch uses
+ */
+
+/**
+ * Fetch one page's text. `connect` is injected (a test never reaches the network); the default is barebrowse's own `connect`.
+ * @param {string} url
+ * @param {{connect?: (opts: Record<string, any>) => Promise<FetchPage>, timeoutMs?: number, idleMs?: number, idleTimeoutMs?: number, closeWaitMs?: number}} [o]
+ * @returns {Promise<{ok: true, text: string, url: string}|{ok: false, error: string}>} `error` is plain words, without a spend line
+ */
+export async function fetchPageText(url, { connect, timeoutMs = PAGE_FETCH_TIMEOUT_MS, idleMs = NETWORK_IDLE_MS, idleTimeoutMs = NETWORK_IDLE_TIMEOUT_MS, closeWaitMs = 3000 } = {}) {
+  let u;
+  try { u = new URL(url.trim()); } catch { return { ok: false, error: `${url} is not a web address bareloop can read` }; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return { ok: false, error: `${url} is not an http or https address` };
+  if (u.username !== '' || u.password !== '') return { ok: false, error: 'a web address with a user name or password in it is refused - bareloop reads a page with no credentials at all' };
+  if (SECRET_PATTERNS.some((re) => re.test(u.href))) return { ok: false, error: 'the web address carries a known secret shape - secrets never enter a job' };
+  /** @type {(opts: Record<string, any>) => Promise<FetchPage>} */
+  let open;
+  if (connect) open = connect;
+  else {
+    try { open = /** @type {any} */ ((await import('barebrowse')).connect); } catch (e) { return { ok: false, error: `the page reader (barebrowse) could not be loaded: ${/** @type {Error} */ (e).message}` }; }
+  }
+  /** @type {NodeJS.Timeout|undefined} */
+  let timer;
+  /** @type {Promise<FetchPage>|undefined} */
+  let opening;
+  try {
+    opening = open({ ...CONNECT_OPTIONS });
+    const page = opening;
+    const text = await Promise.race([
+      (async () => {
+        const p = await page;
+        await p.goto(u.href, GOTO_TIMEOUT_MS);
+        // bounded: a page that never goes quiet (polling, streaming) is read as it stands - the wait is for a page that is still filling
+        try { await p.waitForNetworkIdle({ idle: idleMs, timeout: idleTimeoutMs }); } catch { /* read what is there */ }
+        return p.snapshot({ ...SNAPSHOT_OPTIONS });
+      })(),
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`no answer inside ${Math.round(timeoutMs / 1000)} seconds`)), timeoutMs); }),
+    ]);
+    if (typeof text !== 'string') return { ok: false, error: `${u.href} did not come back as text` };
+    if (/\[BOT CHALLENGE DETECTED\]/.test(text)) return { ok: false, error: `${u.href} asked for a human check (a bot challenge), so the page could not be read` };
+    const size = text.trim().length;
+    if (size < MIN_PAGE_CHARS) return { ok: false, error: `${u.href} came back with ${size === 0 ? 'no text' : `only ${size} characters of text`} (less than ${MIN_PAGE_CHARS}) - the page did not load, or holds nothing to read` };
+    if (pageContentChars(text) < MIN_CONTENT_CHARS) return { ok: false, error: `${u.href} came back with only the site's own header and menus - the page did not load its content, so there is nothing to read` };
+    return { ok: true, text, url: u.href };
+  } catch (e) {
+    return { ok: false, error: `${u.href} could not be read: ${/** @type {Error} */ (e)?.message ?? String(e)}` };
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    // always close the browser, also when the deadline fired while it was still starting or loading
+    if (opening) {
+      /** @type {NodeJS.Timeout|undefined} */
+      let w;
+      await Promise.race([opening.then((p) => p.close()).catch(() => {}), new Promise((r) => { w = setTimeout(r, closeWaitMs); })]);
+      if (w !== undefined) clearTimeout(w);
+    }
+  }
+}