bareloop 0.48.0 → 0.50.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/launcher.js CHANGED
@@ -29,6 +29,8 @@ const WAIT_DEADLINE_MS = 10_000;
29
29
  /** how long `start` keeps asking a TAKEN port that stays silent before it refuses to open another panel next to it */
30
30
  const SILENT_PORT_WAIT_MS = 10_000;
31
31
  const POLL_MS = 100;
32
+ /** not in the signed text: how long `npm install -g` may run before its own child is killed */
33
+ const NPM_DEADLINE_MS = 300_000;
32
34
  const MIN_NODE_MAJOR = 22;
33
35
  const RULE_WIDTH = 56;
34
36
 
@@ -49,6 +51,10 @@ const RULE_WIDTH = 56;
49
51
  * @property {number} [silentWaitMs] how long start keeps asking a taken, silent port (default 10 s)
50
52
  * @property {string} [nodeVersion] default process.versions.node
51
53
  * @property {typeof fetch} [fetchImpl]
54
+ * @property {(cmd: string, args: string[], o: object) => any} [npmSpawn] runs `npm install -g bareloop@latest` for `update` (default node:child_process spawn, no shell)
55
+ * @property {number} [npmDeadlineMs] how long `update`'s npm install may run before its child is killed (default 300 s)
56
+ * @property {boolean} [terminal] false = no person at a terminal (piped / redirected stdin): `update` then never installs, it prints the command (absent = ask)
57
+ * @property {typeof fetch} [npmFetch] the registry check of `update` only (default the global fetch); nothing else ever goes online
52
58
  * @property {(cmd: string, args: string[], o: object) => any} [spawnFn] default node:child_process spawn
53
59
  * @property {(pid: number, sig: string|number) => void} [kill] default process.kill
54
60
  * @property {((target: string) => Promise<boolean>)} [open] default the shared OS opener
@@ -266,7 +272,7 @@ export async function installCmd(io, d, shown) {
266
272
  return 1;
267
273
  }
268
274
  }
269
- if (made.length === 0) { io.out('Already installed, nothing to do.'); return 0; }
275
+ if (made.length === 0) { io.out('Already set up. This does not update bareloop. Pick 6 update for that.'); return 0; }
270
276
  io.out('Installed. Created:');
271
277
  for (const m of made) io.out(` ${m}`);
272
278
  return 0;
@@ -291,6 +297,69 @@ export async function statusCmd(io, d, shown) {
291
297
  return 0;
292
298
  }
293
299
 
300
+ /** @param {string} v @returns {number[]|null} major, minor, patch of `1.2.3` (a `-pre` tail is ignored); null when it is not that shape */
301
+ function parseVersion(v) {
302
+ const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
303
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
304
+ }
305
+
306
+ /** @param {number[]} a @param {number[]} b @returns {boolean} a is newer than b */
307
+ const isNewer = (a, b) => ((a[0] - b[0]) || (a[1] - b[1]) || (a[2] - b[2])) > 0;
308
+
309
+ /**
310
+ * `bareloop update` — the only launcher command that goes online, and only when pressed: reads the newest published version from the npm
311
+ * registry (5 s deadline) and says whether there is a newer one. It installs nothing; it tells the person the command.
312
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown]
313
+ * @returns {Promise<number>}
314
+ */
315
+ export async function updateCmd(io, d, shown) {
316
+ await headerOnce(io, d, shown);
317
+ const mine = d.version ?? packageVersion();
318
+ /** @type {number[]|null} */
319
+ let latest = null;
320
+ /** @type {string} */
321
+ let latestText = '';
322
+ try {
323
+ const res = await (d.npmFetch ?? fetch)('https://registry.npmjs.org/bareloop/latest', { signal: AbortSignal.timeout(5000) });
324
+ if (res.ok) {
325
+ const j = /** @type {{version?: unknown}} */ (await res.json());
326
+ latestText = typeof j?.version === 'string' ? j.version : '';
327
+ latest = parseVersion(latestText);
328
+ }
329
+ } catch { /* offline, timeout, bad JSON: the one plain line below */ }
330
+ const have = parseVersion(mine);
331
+ if (!latest || !have) {
332
+ fail(io, d, 'Could not reach npm to check. Try again later.');
333
+ return 1;
334
+ }
335
+ if (!isNewer(latest, have)) { io.out(`You have the newest bareloop (${mine}).`); return 0; }
336
+ const manual = 'npm install -g bareloop@latest';
337
+ io.out(`bareloop ${latestText} is out. You have ${mine}.`);
338
+ if (!d.ask || d.terminal === false) { io.out(`To update: ${manual}`); return 0; }
339
+ // an empty Enter or other text asks once more; a second one ends as "no"
340
+ let yes = false;
341
+ for (let i = 0; i < 2; i += 1) {
342
+ const a = (await d.ask('Update now? (y/n) ')).trim().toLowerCase();
343
+ if (a === 'y' || a === 'yes') { yes = true; break; }
344
+ if (a === 'n' || a === 'no' || a === 'q') break;
345
+ }
346
+ if (!yes) { io.out(`Not updated. To update later: ${manual}`); return 0; }
347
+ const ok = await new Promise((resolve) => {
348
+ let timer;
349
+ const end = (/** @type {boolean} */ v) => { clearTimeout(timer); resolve(v); };
350
+ try {
351
+ const child = (d.npmSpawn ?? realSpawn)('npm', ['install', '-g', 'bareloop@latest'], { stdio: 'inherit' });
352
+ // not in the signed text: npm may run this long, then its own child is ended (aligned with fwdloop)
353
+ timer = setTimeout(() => { try { child.kill('SIGTERM'); } catch { /* already gone */ } end(false); }, d.npmDeadlineMs ?? NPM_DEADLINE_MS);
354
+ child.once('error', () => end(false));
355
+ child.once('close', (code) => end(code === 0));
356
+ } catch { end(false); }
357
+ });
358
+ if (!ok) { fail(io, d, `The update did not finish. Run it yourself: ${manual}`); return 1; }
359
+ io.out(`Updated to ${latestText}. Then ${shown ? 'pick 3 restart' : 'run bareloop restart'}.`); // the menu door (shown) has the menu; the subcommand door has none
360
+ return 0;
361
+ }
362
+
294
363
  /**
295
364
  * Wait until `port` stops (gone=true) or starts (gone=false) answering whoami as bareloop.
296
365
  * @param {LauncherDeps} d @param {number} port @param {boolean} gone
@@ -484,8 +553,8 @@ export async function restartCmd(args, io, d, shown) {
484
553
  }
485
554
 
486
555
  /**
487
- * The bare `bareloop` menu (PRD v1.114, one menu): the panel's four choices, the four job commands, one question. Runs the chosen command
488
- * and returns its exit code. The job commands (6 export, 7 run, 8 resume, 9 history) are `d.jobs`, supplied by the CLI: each prompts for
556
+ * The bare `bareloop` menu (PRD v1.114, one menu): the panel's six choices, the four job commands, one question. Runs the chosen command
557
+ * and returns its exit code. The job commands (7 export, 8 run, 9 resume, 10 history) are `d.jobs`, supplied by the CLI: each prompts for
489
558
  * what it needs on the same asker this menu uses.
490
559
  * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string, jobs?: {export: () => Promise<number>, run: () => Promise<number>, resume: () => Promise<number>, history: () => Promise<number>}}} d
491
560
  * @returns {Promise<number>}
@@ -498,8 +567,8 @@ export async function menuCmd(io, d) {
498
567
  if (!P.on) io.out('');
499
568
  const n = (/** @type {string} */ k) => P.boldCyan(k);
500
569
  const ind = P.on ? ' ' : '';
501
- io.out(`${ind}panel: ${n('1')} start ${n('2')} stop ${n('3')} restart ${n('4')} status ${n('5')} install`);
502
- io.out(`${ind}jobs: ${n('6')} export ${n('7')} run ${n('8')} resume ${n('9')} history`);
570
+ io.out(`${ind}panel: ${n('1')} start ${n('2')} stop ${n('3')} restart ${n('4')} status ${n('5')} install ${n('6')} update`);
571
+ io.out(`${ind}jobs: ${n('7')} export ${n('8')} run ${n('9')} resume ${n('10')} history`);
503
572
  io.out(`${ind}${n('q')} quit`);
504
573
  const choice = ask ? (await ask(`${P.cyan('>')} `)).trim().toLowerCase() : 'q';
505
574
  // the header is already on screen: the chosen command reuses it instead of printing it a second time
@@ -508,10 +577,11 @@ export async function menuCmd(io, d) {
508
577
  if (choice === '3' || choice === 'restart') return restartCmd([], io, d, h);
509
578
  if (choice === '4' || choice === 'status') return statusCmd(io, d, h);
510
579
  if (choice === '5' || choice === 'install') return installCmd(io, d, h);
511
- const jobChoices = { 6: 'export', export: 'export', 7: 'run', run: 'run', 8: 'resume', resume: 'resume', 9: 'history', history: 'history' };
580
+ if (choice === '6' || choice === 'update') return updateCmd(io, d, h);
581
+ const jobChoices = { 7: 'export', export: 'export', 8: 'run', run: 'run', 9: 'resume', resume: 'resume', 10: 'history', history: 'history' };
512
582
  const job = Object.hasOwn(jobChoices, choice) ? jobChoices[choice] : undefined; // never `constructor` / `__proto__`
513
583
  if (job !== undefined && d.jobs) return d.jobs[/** @type {'export'|'run'|'resume'|'history'} */ (job)]();
514
584
  if (choice === '' || choice === 'q' || choice === 'quit') return 0;
515
- fail(io, d, `unknown choice ${JSON.stringify(choice)} — one of: 1, 2, 3, 4, 5, 6, 7, 8, 9, q`);
585
+ fail(io, d, `unknown choice ${JSON.stringify(choice)} — one of: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, q`);
516
586
  return 1;
517
587
  }
@@ -3,15 +3,18 @@
3
3
  // 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
4
4
  // code, never a raw code and never model-written. `<label>` is the page's own word.
5
5
 
6
+ import { FACT_LANGS } from './facts.js';
7
+
6
8
  /** @typedef {import('./pagerules.js').Dropped} Dropped */
7
9
 
8
10
  /** reason code -> the plain sentence (`d.word` = the page's word, `d.fact` = the fact's name, `d.other` = what it was compared to) */
9
11
  const WORDS = /** @type {Record<string, (d: Dropped) => string>} */ ({
10
12
  'not-on-page': (d) => `"${d.word}" is not written on the page.`,
11
13
  'no-value': (d) => `The page never shows a number right after or right before "${d.word}".`,
14
+ 'reads-no-amount': (d) => `The page never shows an amount next to "${d.word}", so it was not used to write the price.`,
12
15
  'n2': (d) => `"${d.word}" is written more than once inside one line of the page, so one result cannot show it once.`,
13
16
  '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.`,
14
- 'sign-twice': (d) => `"${d.word}" was listed twice, as a unit and as a currency; it is used once, as the currency.`,
17
+ 'sign-twice': (d) => `"${d.word}" was listed twice, as a unit and as a currency; it is used once, as the ${d.other === 'unit' ? 'unit' : 'currency'}.`,
15
18
  'r1l': (d) => d.word === d.other
16
19
  ? `"${d.word}" was listed twice, as a unit and as a currency; it is used once, as the first way to write the price.`
17
20
  : `"${d.word}" does not show the same amounts as "${d.other}", so it was not used as a second way to write the price.`,
@@ -22,6 +25,9 @@ const WORDS = /** @type {Record<string, (d: Dropped) => string>} */ ({
22
25
  'limit-unit': (d) => `Only the first 10 units are used; "${d.word}" was left out.`,
23
26
  'unit-too-long': (d) => `"${d.word}" is longer than 100 characters, so it was not used.`,
24
27
  'reads-no-result': () => "the price rule could not read a price in the page's results, so it is not checked.",
28
+ 'reads-no-time': (d) => `the page never shows a time right after "${d.other}", so it is not checked.`,
29
+ 'lang-not-on-page': (d) => `the page shows no month name in ${FACT_LANGS[/** @type {keyof typeof FACT_LANGS} */ (d.other ?? '')] ?? d.other}, so the date is not checked.`,
30
+ 'decimal-not-on-page': () => 'the page shows no amount written with a comma before the decimals, so it is not checked.',
25
31
  'phrase-no-result': (d) => `"${d.other}" is on the page but in none of its results, so it is not checked.`,
26
32
  'person-left': () => 'You chose to leave it Not checked.',
27
33
  'bad-shape': (d) => `The AI named a kind of value for "${d.fact}" that a check cannot read.`,
@@ -67,7 +73,7 @@ export function dropLine(row, jobLines, rulesOf) {
67
73
  // HOW THE PAGE WAS READ (run mvij7kuk, flight-c1): a drop of ONE WORD whose fact is still checked is a NOTE about the form code did not use, not
68
74
  // something left unchecked. The sentences for those reasons are WORD-level; every other sentence (a whole fact left out) keeps the line under
69
75
  // Not checked. Classified from the line's own words, so it holds for a signed spec already on disk.
70
- const WORD_REASONS = ['not-on-page', 'no-value', 'n2', 'r1', 'sign-twice', 'r1l', 'limit-currency', 'limit-unit', 'unit-too-long'];
76
+ const WORD_REASONS = ['not-on-page', 'no-value', 'reads-no-amount', 'n2', 'r1', 'sign-twice', 'r1l', 'limit-currency', 'limit-unit', 'unit-too-long'];
71
77
  /** @param {string} s */
72
78
  const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
73
79
  const SENTENCE_RE = (() => {
@@ -75,7 +81,7 @@ const SENTENCE_RE = (() => {
75
81
  /** @type {string[]} */
76
82
  const alts = [];
77
83
  for (const reason of WORD_REASONS) {
78
- const probes = reason === 'r1l' ? [{ word: W, other: W }, { word: W, other: O }] : [{ word: W, other: O }];
84
+ const probes = reason === 'r1l' ? [{ word: W, other: W }, { word: W, other: O }] : reason === 'sign-twice' ? [{ word: W, other: 'currency' }, { word: W, other: 'unit' }] : [{ word: W, other: O }];
79
85
  for (const p of probes) alts.push(esc(WORDS[reason](/** @type {any} */ ({ ...p, reason, line: 0, fact: 'f' }))).split(esc(W)).join('[^"]+').split(esc(O)).join('[^"]+'));
80
86
  }
81
87
  return new RegExp(`^(?:(?:${alts.join('|')})(?: |$))+$`);
package/src/pagedry.js CHANGED
@@ -4,28 +4,57 @@
4
4
  // uses - no copy of its logic here. A fact that reads no result line is dropped as `reads-no-result` and shows under Not checked.
5
5
  // No limits, no counts, no pass bar: only "can it read". Async (gradeStep is), so it sits beside applyPageRules, not inside it: the caller is
6
6
  // src/pagemap.js `runPageMap`. No I/O, no clock, no model.
7
+ // TIME DRY READ (docs/logs/time-dryread-poc-PREREG.md, F236/F237): the same "can it read" for TIME facts - `dryReadTimes` below.
7
8
 
8
9
  import { createHash } from 'node:crypto';
9
10
  import { gradeStep } from './rubricstep.js';
10
- import { linesOf, numberAtEnd } from './pagerules.js';
11
+ import { linesOf, numberAtEnd, numberAtEndComma, NUM_COMMA } from './pagerules.js';
11
12
 
12
13
  /** @typedef {import('./pagerules.js').KeptFact} KeptFact @typedef {import('./pagerules.js').Dropped} Dropped */
13
14
 
14
15
  /** a number as the page writes it, thousands commas allowed */
15
16
  const NUM = '\\d[\\d,]*(?:\\.\\d+)?';
16
17
  const AFTER_LABEL = new RegExp(`^\\s*(?:[$€£]\\s*)?(${NUM})`);
18
+ const AFTER_LABEL_COMMA = new RegExp(`^\\s*(?:[$€£]\\s*)?(${NUM_COMMA})`);
19
+ /** the symbols a currency may be; one right before a number reads the number after it */
20
+ const SIGNS = ['$', '€', '£'];
17
21
  /** the label every dry-read claim is made under (the checker only needs one name; the fact's own is not read) */
18
22
  const CLAIM = 'price';
19
23
  const SOURCE = 'page';
24
+ const CLAIM_TIME = 'time';
25
+
26
+ /**
27
+ * How many of `lines` the run's real checker reads green as an honest claim of `fact`: each line is graded alone by `gradeStep` (quote = the line,
28
+ * the claim named `claim` carrying the line's value). The one grading call money and time dry reads share.
29
+ * @param {string} text the frozen page text @param {string} sha its sha256 @param {object} fact the signed fact @param {string} claim the claim name inside `fact`
30
+ * @param {{quote: string, value: string}[]} lines @returns {Promise<number>}
31
+ */
32
+ async function greenLines(text, sha, fact, claim, lines) {
33
+ let n = 0;
34
+ for (const r of lines) {
35
+ const params = { step: 1, parts: [{ text: 'dry read', class: 'fact', source: SOURCE, covers: [1], facts: [fact] }] };
36
+ const g = await gradeStep({ params, bytes: JSON.stringify({ results: [{ quote: r.quote, values: { [claim]: r.value } }] }), outputBytes: null, inputs: { [SOURCE]: text } }, { [SOURCE]: sha });
37
+ if (g.verdict === 'green') n += 1;
38
+ }
39
+ return n;
40
+ }
20
41
 
21
42
  /**
22
43
  * The result lines of a kept money fact: with a label, every page line where a kept label is followed by a number (one sign between allowed);
23
- * with no label (U1 moved it to a unit, e.g. "€533 total"), every line where a number is followed by a kept unit.
44
+ * with no label (U1 moved it to a unit, e.g. "€533 total", or a sign alone, e.g. "48,49€"), every line where a number sits right before a kept
45
+ * unit or sign, or right after a kept sign. A fact that signs `decimal: ","` is read in that form: groups of three joined by "." or a space, a comma
46
+ * before the decimals. The value is always the CANONICAL amount ("1057.65"): the typed value a claim carries, never the page's spelling.
47
+ * A LOOSE finder (it only collects): whether the run's checker can read the line is `gradeStep`'s to say.
24
48
  * @param {string} text @param {KeptFact} k @returns {{quote: string, value: string}[]}
25
49
  */
26
50
  export function moneyResultLines(text, k) {
27
51
  const raw = text.split('\n');
28
52
  const squashed = linesOf(text);
53
+ const comma = k.decimal === ',';
54
+ const afterLabel = comma ? AFTER_LABEL_COMMA : AFTER_LABEL;
55
+ const endNumber = comma ? numberAtEndComma : numberAtEnd;
56
+ /** the page's amount as a canonical decimal string */
57
+ const canon = (/** @type {string} */ a) => (comma ? a.replace(/[. ]/g, '').replace(',', '.') : a.replace(/,/g, ''));
29
58
  /** @type {{quote: string, value: string}[]} */
30
59
  const out = [];
31
60
  squashed.forEach((ln, i) => {
@@ -33,16 +62,19 @@ export function moneyResultLines(text, k) {
33
62
  let amount;
34
63
  if (k.words.length) {
35
64
  for (const w of k.words) {
36
- for (let at = ln.indexOf(w); at !== -1 && amount === undefined; at = ln.indexOf(w, at + w.length)) amount = AFTER_LABEL.exec(ln.slice(at + w.length))?.[1];
65
+ for (let at = ln.indexOf(w); at !== -1 && amount === undefined; at = ln.indexOf(w, at + w.length)) amount = afterLabel.exec(ln.slice(at + w.length))?.[1];
37
66
  if (amount !== undefined) break;
38
67
  }
39
68
  } else {
40
- for (const u of k.unit ?? []) {
41
- for (let at = ln.indexOf(u); at !== -1 && amount === undefined; at = ln.indexOf(u, at + u.length)) amount = numberAtEnd(ln.slice(0, at));
69
+ for (const u of [...(k.unit ?? []), ...(k.currency ?? [])]) {
70
+ for (let at = ln.indexOf(u); at !== -1 && amount === undefined; at = ln.indexOf(u, at + u.length)) {
71
+ amount = endNumber(ln.slice(0, at));
72
+ if (amount === undefined && SIGNS.includes(u)) amount = afterLabel.exec(ln.slice(at + u.length))?.[1];
73
+ }
42
74
  if (amount !== undefined) break;
43
75
  }
44
76
  }
45
- if (amount !== undefined) out.push({ quote: raw[i].trim(), value: amount.replace(/,/g, '') });
77
+ if (amount !== undefined) out.push({ quote: raw[i].trim(), value: canon(amount) });
46
78
  });
47
79
  return out;
48
80
  }
@@ -51,7 +83,7 @@ export function moneyResultLines(text, k) {
51
83
  * The fact as a run would sign it, for the dry read: the primary label is the anchor (none when U1 moved every label), then the kept units and currencies.
52
84
  * @param {KeptFact} k @returns {Record<string, any>}
53
85
  */
54
- const signedOf = (k) => ({ name: CLAIM, shape: 'money', ...(k.words.length ? { anchor: k.words[0] } : {}), ...(k.currency ? { currency: k.currency } : {}), ...(k.unit ? { unit: k.unit } : {}) });
86
+ const signedOf = (k) => ({ name: CLAIM, shape: 'money', ...(k.words.length ? { anchor: k.words[0] } : {}), ...(k.currency ? { currency: k.currency } : {}), ...(k.unit ? { unit: k.unit } : {}), ...(k.decimal === undefined ? {} : { decimal: k.decimal }) });
55
87
 
56
88
  /**
57
89
  * Dry-read every kept money fact; drop (as `reads-no-result`) the ones whose forms read no result line. Other facts pass through untouched.
@@ -73,12 +105,7 @@ export async function dryReadMoney(text, facts) {
73
105
  if (k.shape !== 'money') { kept.push(k); continue; }
74
106
  const fact = signedOf(k);
75
107
  const lines = moneyResultLines(text, k);
76
- let n = 0;
77
- for (const r of lines) {
78
- const params = { step: 1, parts: [{ text: 'dry read', class: 'fact', source: SOURCE, covers: [1], facts: [fact] }] };
79
- const g = await gradeStep({ params, bytes: JSON.stringify({ results: [{ quote: r.quote, values: { [CLAIM]: r.value } }] }), outputBytes: null, inputs: { [SOURCE]: text } }, { [SOURCE]: sha });
80
- if (g.verdict === 'green') n += 1;
81
- }
108
+ const n = await greenLines(text, sha, fact, CLAIM, lines);
82
109
  reads[k.name] = n;
83
110
  results[k.name] = lines.length;
84
111
  if (n > 0) { kept.push(k); continue; }
@@ -122,3 +149,61 @@ export async function dryReadPhrases(text, facts) {
122
149
  }
123
150
  return { facts: kept, dropped, reads };
124
151
  }
152
+
153
+ /** a clock time as the page writes it: H:MM or HH:MM, then an optional AM/PM (any case, a space between allowed) */
154
+ const CLOCK = /\d{1,2}:\d{2}(?:\s?[AaPp][Mm])?/;
155
+
156
+ /**
157
+ * The candidate lines of a kept time fact: a LOOSE finder (it only collects). Every page line where a kept label word has a clock time anywhere
158
+ * after it; the value is that line's first time after the label. Whether the run's checker can read it is not decided here.
159
+ * @param {string} text @param {KeptFact} k @returns {{quote: string, value: string}[]}
160
+ */
161
+ export function timeCandidateLines(text, k) {
162
+ const raw = text.split('\n');
163
+ const squashed = linesOf(text);
164
+ /** @type {{quote: string, value: string}[]} */
165
+ const out = [];
166
+ squashed.forEach((ln, i) => {
167
+ for (const w of k.words) {
168
+ for (let at = ln.indexOf(w); at !== -1; at = ln.indexOf(w, at + w.length)) {
169
+ const m = CLOCK.exec(ln.slice(at + w.length));
170
+ if (m) { out.push({ quote: raw[i].trim(), value: m[0] }); return; }
171
+ }
172
+ }
173
+ });
174
+ return out;
175
+ }
176
+
177
+ /**
178
+ * The same "can it read" for TIME facts (F236: the label "Departure time" sat on a page that writes "Departure time:", the colon right after it, so
179
+ * no time could ever be read after the label, and the fact was signed anyway). Each candidate line of a kept time fact is graded as an HONEST claim
180
+ * (quote = that line, value = its first time after the label) by the real `gradeStep`, signed like a run would sign it (name, shape, anchor = the
181
+ * primary label; no window, as dryReadMoney leaves the limits out). A fact with no green line is dropped whole as `reads-no-time`.
182
+ * No counts, no pass bar. A time fact with no label word has nothing to anchor a read to (a run could not sign it either), so it passes through untouched.
183
+ * Facts of other shapes pass through untouched. It catches an IMPOSSIBLE label only: a label that reads a WRONG time is kept (left to the person at Accept).
184
+ * @param {string} text the frozen page text @param {KeptFact[]} facts what the money dry read kept
185
+ * @returns {Promise<{facts: KeptFact[], dropped: Dropped[], reads: Record<string, number>, results: Record<string, number>}>}
186
+ * `reads` / `results` = candidate lines the checker read / found, per fact name (for tests and reports; no verdict derives from the numbers)
187
+ */
188
+ export async function dryReadTimes(text, facts) {
189
+ const sha = createHash('sha256').update(text).digest('hex');
190
+ /** @type {KeptFact[]} */
191
+ const kept = [];
192
+ /** @type {Dropped[]} */
193
+ const dropped = [];
194
+ /** @type {Record<string, number>} */
195
+ const reads = {};
196
+ /** @type {Record<string, number>} */
197
+ const results = {};
198
+ for (const k of facts) {
199
+ if (k.shape !== 'time' || !k.words.length) { kept.push(k); continue; }
200
+ const fact = { name: CLAIM_TIME, shape: 'time', anchor: k.words[0] };
201
+ const lines = timeCandidateLines(text, k);
202
+ const n = await greenLines(text, sha, fact, CLAIM_TIME, lines);
203
+ reads[k.name] = n;
204
+ results[k.name] = lines.length;
205
+ if (n > 0) { kept.push(k); continue; }
206
+ dropped.push({ line: k.line, ...(k.forRule === undefined ? {} : { rule: k.forRule }), fact: k.name, other: k.words[0], reason: 'reads-no-time' });
207
+ }
208
+ return { facts: kept, dropped, reads, results };
209
+ }
package/src/pagefetch.js CHANGED
@@ -9,7 +9,7 @@
9
9
  // proven in step 0 ('read' and 'full' returned almost nothing from a results page). The text that comes back is the input. An empty
10
10
  // fetch is a plain-words stop, never a silent empty input. Nothing here touches a model.
11
11
 
12
- import { SECRET_PATTERNS } from './validate.js';
12
+ import { SECRET_PATTERNS, redactSecrets } from './validate.js';
13
13
  import { TAG } from './labelscan.js';
14
14
 
15
15
  /** the session options (incognito: no auth ever enters; blockPrivateNetwork: SSRF guard); ONE frozen object so a test can pin them */
@@ -30,7 +30,18 @@ export const MIN_PAGE_CHARS = 200;
30
30
  export const MIN_CONTENT_CHARS = 100;
31
31
  /** 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 */
32
32
  const CHROME_ROLES = new Set(['banner', 'navigation', 'contentinfo']);
33
- /** 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) */
33
+ /** how many times one fetch is tried when it comes back header-only or times out (a real Dell page was header-only on one try and whole on the next) */
34
+ export const FETCH_ATTEMPTS = 3;
35
+ /** the pause between attempts (ms) */
36
+ export const RETRY_WAIT_MS = 3000;
37
+ /** a header-only snapshot is re-taken (same open page) every this many ms until content shows up (live: Dell de-de gave header-only 3 times in ~5 s
38
+ * each, while its content arrived ~18-35 s after load; a fast refetch hits the same unsettled page) */
39
+ export const SETTLE_INTERVAL_MS = 2000;
40
+ /** the most one attempt keeps re-reading a header-only page (ms) before it counts as header-only; the per-attempt deadline below still bounds the whole attempt */
41
+ export const SETTLE_BUDGET_MS = 20_000;
42
+ /** how many characters of a header-only page's content (after the snapshot header) the failure record keeps */
43
+ export const HEAD_KEEP_CHARS = 300;
44
+ /** our own deadline around ONE attempt (a fetch that retries can take up to FETCH_ATTEMPTS of these, plus the pauses); a hung browser leaves no trace, this is the only thing that fires on the absence of an answer */
34
45
  export const PAGE_FETCH_TIMEOUT_MS = 90_000;
35
46
 
36
47
  /** @param {unknown} v @returns {boolean} an http(s) address (the one spelling of "this Inputs value is a web address") */
@@ -70,13 +81,18 @@ export function pageContentChars(text) {
70
81
  * snapshot: (o?: {mode?: string}) => Promise<string>, close: () => Promise<void>}} FetchPage the part of barebrowse's page handle the fetch uses
71
82
  */
72
83
 
84
+ /** @typedef {{chars: number, ms: number, head: string}} AttemptRecord what a header-only attempt saw: content characters, elapsed ms, the first characters of the content (secret-masked) */
85
+
73
86
  /**
74
87
  * Fetch one page's text. `connect` is injected (a test never reaches the network); the default is barebrowse's own `connect`.
88
+ * The whole fetch (own browser, own page, closed each time) is tried up to FETCH_ATTEMPTS times, but ONLY when an attempt ends header-only (the page
89
+ * loaded its menus and not its content) or times out (our deadline, or the page load's own timeout). A bot challenge, a refused or private address, any
90
+ * other load error, a near-empty page and a non-text answer are final on the first attempt.
75
91
  * @param {string} url
76
- * @param {{connect?: (opts: Record<string, any>) => Promise<FetchPage>, timeoutMs?: number, idleMs?: number, idleTimeoutMs?: number, closeWaitMs?: number}} [o]
77
- * @returns {Promise<{ok: true, text: string, url: string}|{ok: false, error: string}>} `error` is plain words, without a spend line
92
+ * @param {{connect?: (opts: Record<string, any>) => Promise<FetchPage>, timeoutMs?: number, idleMs?: number, idleTimeoutMs?: number, closeWaitMs?: number, retryWaitMs?: number, settleMs?: number, settleIntervalMs?: number}} [o] `retryWaitMs` - the pause between attempts (a test passes 0); `settleMs`/`settleIntervalMs` - the in-attempt re-read budget and pace for a header-only page
93
+ * @returns {Promise<{ok: true, text: string, url: string}|{ok: false, error: string, attempts?: AttemptRecord[]}>} `error` is plain words, without a spend line
78
94
  */
79
- export async function fetchPageText(url, { connect, timeoutMs = PAGE_FETCH_TIMEOUT_MS, idleMs = NETWORK_IDLE_MS, idleTimeoutMs = NETWORK_IDLE_TIMEOUT_MS, closeWaitMs = 3000 } = {}) {
95
+ export async function fetchPageText(url, { connect, timeoutMs = PAGE_FETCH_TIMEOUT_MS, idleMs = NETWORK_IDLE_MS, idleTimeoutMs = NETWORK_IDLE_TIMEOUT_MS, closeWaitMs = 3000, retryWaitMs = RETRY_WAIT_MS, settleMs = SETTLE_BUDGET_MS, settleIntervalMs = SETTLE_INTERVAL_MS } = {}) {
80
96
  let u;
81
97
  try { u = new URL(url.trim()); } catch { return { ok: false, error: `${url} is not a web address bareloop can read` }; }
82
98
  if (u.protocol !== 'http:' && u.protocol !== 'https:') return { ok: false, error: `${url} is not an http or https address` };
@@ -88,6 +104,30 @@ export async function fetchPageText(url, { connect, timeoutMs = PAGE_FETCH_TIMEO
88
104
  else {
89
105
  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}` }; }
90
106
  }
107
+ /** @type {{ok: false, error: string}} */
108
+ let last = { ok: false, error: '' };
109
+ /** @type {AttemptRecord[]} */
110
+ const attempts = [];
111
+ for (let attempt = 1; attempt <= FETCH_ATTEMPTS; attempt += 1) {
112
+ const r = await attemptOnce(u, open, { timeoutMs, idleMs, idleTimeoutMs, closeWaitMs, settleMs, settleIntervalMs });
113
+ if (r.ok) return r;
114
+ if (!r.retry) return { ok: false, error: r.error, ...(attempts.length || r.record ? { attempts: r.record ? [...attempts, r.record] : attempts } : {}) };
115
+ if (r.record) attempts.push(r.record);
116
+ last = { ok: false, error: r.error };
117
+ if (attempt < FETCH_ATTEMPTS && retryWaitMs > 0) await new Promise((res) => setTimeout(res, retryWaitMs));
118
+ }
119
+ return { ok: false, error: `${last.error} (tried ${FETCH_ATTEMPTS} times)`, ...(attempts.length ? { attempts } : {}) };
120
+ }
121
+
122
+ /**
123
+ * ONE attempt: opens its own browser and page and always closes them. `retry: true` marks the two endings worth another go (header-only, timeout).
124
+ * @param {URL} u @param {(opts: Record<string, any>) => Promise<FetchPage>} open
125
+ * @param {{timeoutMs: number, idleMs: number, idleTimeoutMs: number, closeWaitMs: number, settleMs: number, settleIntervalMs: number}} o
126
+ * @returns {Promise<{ok: true, text: string, url: string}|{ok: false, error: string, retry: boolean, record?: AttemptRecord}>}
127
+ */
128
+ async function attemptOnce(u, open, { timeoutMs, idleMs, idleTimeoutMs, closeWaitMs, settleMs, settleIntervalMs }) {
129
+ const t0 = Date.now();
130
+ let stopped = false;
91
131
  /** @type {NodeJS.Timeout|undefined} */
92
132
  let timer;
93
133
  /** @type {Promise<FetchPage>|undefined} */
@@ -101,19 +141,31 @@ export async function fetchPageText(url, { connect, timeoutMs = PAGE_FETCH_TIMEO
101
141
  await p.goto(u.href, GOTO_TIMEOUT_MS);
102
142
  // bounded: a page that never goes quiet (polling, streaming) is read as it stands - the wait is for a page that is still filling
103
143
  try { await p.waitForNetworkIdle({ idle: idleMs, timeout: idleTimeoutMs }); } catch { /* read what is there */ }
104
- return p.snapshot({ ...SNAPSHOT_OPTIONS });
144
+ let snap = await p.snapshot({ ...SNAPSHOT_OPTIONS });
145
+ // header-only: the page's scripts may still be filling it (network idle came early). Keep the page open and re-read it, up to settleMs;
146
+ // only then does this attempt count as header-only. The attempt's own deadline still bounds all of it.
147
+ const settleEnd = Date.now() + settleMs;
148
+ while (!stopped && Date.now() < settleEnd && isHeaderOnly(snap)) {
149
+ await new Promise((res) => setTimeout(res, Math.min(settleIntervalMs, Math.max(0, settleEnd - Date.now()))));
150
+ if (stopped) break;
151
+ snap = await p.snapshot({ ...SNAPSHOT_OPTIONS });
152
+ }
153
+ return snap;
105
154
  })(),
106
- new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`no answer inside ${Math.round(timeoutMs / 1000)} seconds`)), timeoutMs); }),
155
+ new Promise((_, reject) => { timer = setTimeout(() => reject(Object.assign(new Error(`no answer inside ${Math.round(timeoutMs / 1000)} seconds`), { deadline: true })), timeoutMs); }),
107
156
  ]);
108
- if (typeof text !== 'string') return { ok: false, error: `${u.href} did not come back as text` };
109
- 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` };
157
+ if (typeof text !== 'string') return { ok: false, retry: false, error: `${u.href} did not come back as text` };
158
+ if (/\[BOT CHALLENGE DETECTED\]/.test(text)) return { ok: false, retry: false, error: `${u.href} asked for a human check (a bot challenge), so the page could not be read` };
110
159
  const size = text.trim().length;
111
- 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` };
112
- 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` };
160
+ if (size < MIN_PAGE_CHARS) return { ok: false, retry: 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` };
161
+ if (pageContentChars(text) < MIN_CONTENT_CHARS) return { ok: false, retry: true, 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`, record: headerRecord(text, Date.now() - t0) };
113
162
  return { ok: true, text, url: u.href };
114
163
  } catch (e) {
115
- return { ok: false, error: `${u.href} could not be read: ${/** @type {Error} */ (e)?.message ?? String(e)}` };
164
+ const msg = /** @type {Error} */ (e)?.message ?? String(e);
165
+ const timedOut = /** @type {any} */ (e)?.deadline === true || /time[d ]?-?out/i.test(msg);
166
+ return { ok: false, retry: timedOut, error: `${u.href} could not be read: ${msg}` };
116
167
  } finally {
168
+ stopped = true;
117
169
  if (timer !== undefined) clearTimeout(timer);
118
170
  // always close the browser, also when the deadline fired while it was still starting or loading
119
171
  if (opening) {
@@ -124,3 +176,14 @@ export async function fetchPageText(url, { connect, timeoutMs = PAGE_FETCH_TIMEO
124
176
  }
125
177
  }
126
178
  }
179
+
180
+ /** @param {unknown} text @returns {boolean} text long enough to pass the near-empty floor, yet with no content outside the site's own chrome (the one case worth re-reading) */
181
+ function isHeaderOnly(text) {
182
+ return typeof text === 'string' && !/\[BOT CHALLENGE DETECTED\]/.test(text) && text.trim().length >= MIN_PAGE_CHARS && pageContentChars(text) < MIN_CONTENT_CHARS;
183
+ }
184
+
185
+ /** the short failure record of a header-only attempt; the head is secret-masked (the log is append-only) @param {string} text @param {number} ms @returns {AttemptRecord} */
186
+ function headerRecord(text, ms) {
187
+ const body = text.split('\n').filter((l) => !/^url: /.test(l) && !/^[\d,]+ chars → /.test(l) && !/^hint: /.test(l)).join(' ').replace(/\s+/g, ' ').trim();
188
+ return { chars: pageContentChars(text), ms, head: redactSecrets(body.slice(0, HEAD_KEEP_CHARS)) };
189
+ }
package/src/pagemap.js CHANGED
@@ -15,8 +15,8 @@ import { isOutputCutOff } from './authorflow.js';
15
15
  import { AUTHOR_CALL_TIMEOUT_MS, AUTHOR_SCOUT_MAX_TOKENS, SURVEY_CAUSES } from './authorscout.js';
16
16
  import { lineRules, boundInWords, wordsSaidOn } from './rubricstep.js';
17
17
  import { applyPageRules, validReading } from './pagerules.js';
18
- import { dryReadMoney, dryReadPhrases } from './pagedry.js';
19
- import { ruleWords } from './facts.js';
18
+ import { dryReadMoney, dryReadTimes, dryReadPhrases } from './pagedry.js';
19
+ import { ruleWords, FACT_LANGS } from './facts.js';
20
20
  import { lookFactOf } from './inputlook.js';
21
21
 
22
22
  const require = createRequire(import.meta.url);
@@ -25,7 +25,9 @@ const { Loop } = require('bare-agent');
25
25
  /** the label of the one paid call, as the drafting book and the progress line see it */
26
26
  export const MAP_CALL_LABEL = 'page-map';
27
27
  /** the shapes the map may name; a `place` is read by code as a phrase */
28
- export const MAP_SHAPES = Object.freeze(['place', 'money', 'time', 'phrase']);
28
+ export const MAP_SHAPES = Object.freeze(['place', 'money', 'time', 'date', 'number', 'phrase']);
29
+ /** the languages a date's month names may be signed in (one list with src/facts.js) */
30
+ const MAP_LANGS = Object.keys(FACT_LANGS);
29
31
 
30
32
  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.';
31
33
 
@@ -40,12 +42,15 @@ export function mapPrompt({ jobLines, label, text }) {
40
42
  return `THE JOB (each ~ rule applies to the line above it):\n${job}\n\n`
41
43
  + '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'
42
44
  + 'Return ONLY a JSON object, no prose, no code fence:\n'
43
- + '{"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'
45
+ + `{"facts":[{"name":"<letters and spaces only>","from":"<line N | line N rule M>","shape":"place|money|time|date|number|phrase","words":["<page words>", ...],"currency":["<symbol>"],"unit":["<words after the amount>"],"lang":"<${MAP_LANGS.join("|")}>","decimal":"<. or ,>","reading":<optional, see below>}]}\n\n`
44
46
  + 'shape meanings:\n'
45
47
  + '- place: words = ways the page writes the place (a city, an airport name), copied from the page.\n'
46
48
  + '- 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'
47
49
  + '- time: words = the label(s) written right BEFORE the time that is the one the rule is about, copied from the page.\n'
50
+ + `- date: words = the label(s) written right BEFORE the date that is the one the rule is about, copied from the page. lang = the language the page writes the month name in (${MAP_LANGS.join(' ')}); leave lang out when the date is written 2026-10-26.\n`
51
+ + '- number: words = the label(s) written right BEFORE a plain number (a rating, a count), copied from the page. decimal = the mark the page writes before the decimals: "." or ",". Give decimal on a money fact too when the page writes a comma before the decimals.\n'
48
52
  + '- phrase: words = fixed words a result\'s text must contain, copied from the page.\n'
53
+ + 'A label must appear ONCE on its page line and sit right before the value; when the value stands alone on its line, give no label.\n'
49
54
  + 'Several words in one list are alternatives for the same fact. Put the best one first.\n'
50
55
  + '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'
51
56
  + `PAGE TEXT (the input "${label}"):\n${text}`;
@@ -60,6 +65,7 @@ export function parseMapAnswer(text) {
60
65
  /** @type {any} */
61
66
  let m;
62
67
  try { m = JSON.parse(String(text ?? '').trim()); } catch { return { ok: false }; }
68
+ const notBlank = (/** @type {string} */ w) => w.trim() !== '';
63
69
  const strs = (/** @type {unknown} */ v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
64
70
  if (m === null || typeof m !== 'object' || Array.isArray(m) || !Array.isArray(m.facts)) return { ok: false };
65
71
  for (const f of m.facts) {
@@ -67,6 +73,12 @@ export function parseMapAnswer(text) {
67
73
  if (typeof f.name !== 'string' || !MAP_SHAPES.includes(f.shape) || !strs(f.words)) return { ok: false };
68
74
  if (f.from !== undefined && typeof f.from !== 'string') return { ok: false };
69
75
  for (const k of ['currency', 'unit']) if (f[k] !== undefined && !strs(f[k])) return { ok: false };
76
+ if (f.lang !== undefined && !(typeof f.lang === 'string' && MAP_LANGS.includes(f.lang))) return { ok: false };
77
+ if (f.decimal !== undefined && !(f.decimal === '.' || f.decimal === ',')) return { ok: false };
78
+ // a blank entry (empty or only spaces) names nothing: it is left out here, with no note, and the rest of the fact stands. This is not a JSON
79
+ // repair - the answer was well-formed; a list left empty is absent (words stays a list, `[]`: the fact then reads by its signs alone)
80
+ f.words = f.words.filter(notBlank);
81
+ for (const k of ['currency', 'unit']) if (f[k] !== undefined) { f[k] = f[k].filter(notBlank); if (f[k].length === 0) delete f[k]; }
70
82
  // 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)
71
83
  if (f.reading !== undefined && !validReading(f.shape, f.reading)) return { ok: false };
72
84
  }
@@ -167,10 +179,12 @@ export async function runPageMap({
167
179
  const kept = applyPageRules(texts[label], mapping, jobLines);
168
180
  // money build v2: "can it read" - a money fact whose forms read no result line of the page, by the run's own checker, is Not checked
169
181
  const read = await dryReadMoney(texts[label], kept.facts);
182
+ // time dry read (F236/F237): a time fact whose label has no time the run's checker can read after it is Not checked
183
+ const tim = await dryReadTimes(texts[label], read.facts);
170
184
  // hamr 3a: a phrase fact is read against the same result lines (only when the job keeps a money fact)
171
- const phr = await dryReadPhrases(texts[label], read.facts);
185
+ const phr = await dryReadPhrases(texts[label], tim.facts);
172
186
  for (const f of phr.facts) facts.push(lookFactOf(f, label));
173
- for (const d of [...kept.dropped, ...read.dropped, ...phr.dropped]) dropped.push({ ...d, source: label });
187
+ for (const d of [...kept.dropped, ...read.dropped, ...tim.dropped, ...phr.dropped]) dropped.push({ ...d, source: label });
174
188
  maps.push({ source: label, facts: mapping.facts.length });
175
189
  looks.push(label);
176
190
  }
@@ -188,6 +202,18 @@ export const isDropIt = (text) => String(text ?? '').trim().replace(/\.$/, '').t
188
202
  const AGREE_WORDS = ['agree', 'yes'];
189
203
  /** @param {unknown} text @returns {boolean} */
190
204
  export const isAgree = (text) => AGREE_WORDS.includes(String(text ?? '').trim().replace(/[.!]$/, '').toLowerCase());
205
+ /**
206
+ * F240: an answer that opens with an agree word IMMEDIATELY followed by a comma or a colon (spaces allowed only after it) and more text
207
+ * ("yes, check it as ...", "agree: the outbound flight") is the person's own reading with a courtesy word in front: the word and the
208
+ * comma/colon go, the rest stays word for word. No hyphen or dash of any kind and no bare space counts, so "yes-no questions only",
209
+ * "agree-ment on price", "yes - departs", "yes departs" and "yesterday, ..." are kept whole. A bare "yes"/"agree" (isAgree) and a text that
210
+ * only contains the word later are returned untouched.
211
+ * @param {string} text @returns {string}
212
+ */
213
+ export const stripAgreeLead = (text) => {
214
+ const m = String(text ?? '').match(new RegExp(`^(?:${AGREE_WORDS.join('|')})[,:]\\s*(\\S[\\s\\S]*)$`, 'i'));
215
+ return m ? m[1].trim() : String(text ?? '');
216
+ };
191
217
 
192
218
  /** @typedef {{line: number, rule: number, source: 'look', question: string, ask: 'reading'|'cant-check', ruleText: string, reading?: string}} LookAsk
193
219
  * `reading` = the plain words an `agree` writes as a `~` rule (a reading ask only) */