bareloop 0.49.0 → 0.51.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/pagerules.js CHANGED
@@ -10,11 +10,11 @@ import { normLabel } from './labelscan.js';
10
10
 
11
11
  /**
12
12
  * @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
13
- * @typedef {{name: string, from?: string, shape: string, words?: string[], currency?: string[], unit?: string[], reading?: Reading}} MapFact the AI's map, one fact
13
+ * @typedef {{name: string, from?: string, shape: string, words?: string[], currency?: string[], unit?: string[], reading?: Reading, lang?: string, decimal?: string}} MapFact the AI's map, one fact
14
14
  * @typedef {{facts: MapFact[]}} PageMap
15
- * @typedef {{line: number, name: string, shape: string, from: string, words: string[], unit?: string[], currency?: string[], forRule?: number, reading?: Reading}} KeptFact
15
+ * @typedef {{line: number, name: string, shape: string, from: string, words: string[], unit?: string[], currency?: string[], forRule?: number, reading?: Reading, lang?: string, decimal?: string}} KeptFact
16
16
  * `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)
17
- * @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), the phrase it looked for (phrase-no-result)
17
+ * @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 box a sign listed twice was kept in (sign-twice: unit or currency), the fact it would have repeated (S1), the phrase it looked for (phrase-no-result)
18
18
  */
19
19
 
20
20
  /** @param {unknown} v @returns {v is Record<string, any>} */
@@ -75,6 +75,8 @@ const READ = {
75
75
  money: /^\s*[$€£]?\s*(\d[\d,]*(?:\.\d+)?)/,
76
76
  time: /^\s*(\d{1,2}:\d{2}[\s\u202f\u00a0]?[AaPp][Mm])/,
77
77
  number: /^\s*(\d[\d,]*(?:\.\d+)?)/,
78
+ // R1 same-value only: the date words right after a label, up to the 4-digit year (a day, a month name, a year; or ISO)
79
+ date: /^\s*(\d{4}-\d{2}-\d{2}|\S+(?:\s\S+){0,3}\s\d{4})(?!\d)/,
78
80
  };
79
81
 
80
82
  /**
@@ -123,6 +125,21 @@ export function numberAtEnd(s) {
123
125
  const p = firstDigit(e);
124
126
  return p === -1 ? undefined : s.slice(p, e);
125
127
  }
128
+ /** a number as a page writes it where the decimal mark is a comma: groups of three joined by "." or a space (or none), then an optional comma and decimals */
129
+ export const NUM_COMMA = '\\d{1,3}(?:[. ]\\d{3})+(?:,\\d+)?|\\d+(?:,\\d+)?';
130
+ /**
131
+ * {@link numberAtEnd} for a comma-decimal page: the number written at the very end of `s` (only whitespace after it), as the page writes it
132
+ * ("1.057,65", "1 089", "48,49"). Only the last 24 characters are read (no price is longer), so a long run of digits cannot cost more than that.
133
+ * @param {string} s @returns {string|undefined}
134
+ */
135
+ export function numberAtEndComma(s) {
136
+ const t = s.trimEnd();
137
+ const tail = t.slice(-24);
138
+ const m = new RegExp(`(?<![\\d,.])(?:${NUM_COMMA})$`).exec(tail);
139
+ // a match that starts the tail while the text goes on to the left of it may be the end of a longer run: not a number of its own
140
+ if (!m || (m.index === 0 && t.length > tail.length && /[\d,.]/.test(t[t.length - tail.length - 1]))) return undefined;
141
+ return m[0];
142
+ }
126
143
  const AFTER = new RegExp(`^\\s*(?:[$€£]\\s*)?(${NUM})`);
127
144
  const AFTER_CUR = new RegExp(`^\\s*(${NUM})`);
128
145
  const stripCommas = (/** @type {string} */ s) => s.replace(/,/g, '');
@@ -159,8 +176,123 @@ const ORDINALS = ['first', 'second', 'third', 'fourth', 'fifth', 'sixth', 'seven
159
176
 
160
177
  /** 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 */
161
178
  const CURRENCY_SYMBOLS = ['$', '€', '£'];
179
+
180
+ /**
181
+ * The page FORMS of a currency sign in `lines`: `glued` = right after a number ("29,99€"), `spaced` = after a number and one space ("29,99 €"),
182
+ * `before` = in front of a number it does not itself follow ("€399", "€ 399").
183
+ * @param {string[]} lines @param {string} sign @returns {{glued: boolean, spaced: boolean, before: boolean}}
184
+ */
185
+ function signForms(lines, sign) {
186
+ let glued = false; let spaced = false; let before = false;
187
+ for (const [l, i] of occs(lines, sign)) {
188
+ const head = l.slice(0, i);
189
+ if (/\d$/.test(head)) glued = true;
190
+ else if (/\d $/.test(head)) spaced = true;
191
+ else if (/^ ?\d/.test(l.slice(i + sign.length))) before = true;
192
+ }
193
+ return { glued, spaced, before };
194
+ }
195
+ /** the char codes of the digits and of the "." and "," a number is written with */
196
+ const isDigitCode = (/** @type {number} */ c) => c >= 48 && c <= 57;
197
+ const isMarkCode = (/** @type {number} */ c) => c === 46 || c === 44;
198
+ /**
199
+ * The number that ends a string: its last run of digits, "." and ",", from the run's first digit (undefined when the run holds no digit). One
200
+ * backward scan, the linear form of /\d[\d.,]*$/ (that one re-scans a long digit run from every digit).
201
+ * @param {string} s @returns {string | undefined}
202
+ */
203
+ function numberBefore(s) {
204
+ let j = s.length;
205
+ while (j > 0 && (isDigitCode(s.charCodeAt(j - 1)) || isMarkCode(s.charCodeAt(j - 1)))) j--;
206
+ while (j < s.length && isMarkCode(s.charCodeAt(j))) j++;
207
+ return j < s.length ? s.slice(j) : undefined;
208
+ }
209
+ /** a number without the "." and "," marks that end it; the linear form of .replace(/[.,]+$/, '') (that one is quadratic on a long run of marks before a digit) @param {string | undefined} n */
210
+ function trimMarks(n) {
211
+ if (n === undefined) return undefined;
212
+ let e = n.length;
213
+ while (e > 0 && isMarkCode(n.charCodeAt(e - 1))) e--;
214
+ return n.slice(0, e);
215
+ }
216
+ /**
217
+ * How the page writes the decimals of the amounts a money fact's signs touch (a sign right after a number, spaced or glued, or right before one).
218
+ * A CLEAR comma amount ends in a comma and exactly two digits ("1.058,47", "17,00"), a CLEAR dot amount in a dot and exactly two ("29.99"); a comma or
219
+ * dot and exactly three digits ("1,299", "1.299") is ambiguous and counts as neither. Only one kind seen = that mark; both or neither = undefined.
220
+ * @param {string[]} lines @param {string[]} signs @returns {',' | '.' | undefined}
221
+ */
222
+ function pageDecimal(lines, signs) {
223
+ let comma = false; let dot = false;
224
+ for (const sgn of signs) {
225
+ for (const [l, i] of occs(lines, sgn)) {
226
+ const before = numberBefore(l.slice(0, i).replace(/ $/, ''));
227
+ const after = trimMarks(/^ ?(\d[\d.,]*)/.exec(l.slice(i + sgn.length))?.[1]);
228
+ for (const n of [before, after]) {
229
+ if (n === undefined) continue;
230
+ if (/,\d{2}$/.test(n)) comma = true;
231
+ else if (/\.\d{2}$/.test(n)) dot = true;
232
+ }
233
+ }
234
+ }
235
+ return comma === dot ? undefined : comma ? ',' : '.';
236
+ }
162
237
  /** the shapes that read a value after a label */
163
- const VALUE_SHAPES = ['money', 'time', 'number'];
238
+ const VALUE_SHAPES = ['money', 'time', 'number', 'date'];
239
+
240
+ /** the full month names of each language a date may be signed in (bareguard 0.27 reads these and short forms; one full name on the page proves the language is the page's) */
241
+ const MONTHS_FULL = /** @type {Record<string, string[]>} */ ({
242
+ en: ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december'],
243
+ de: ['januar', 'februar', 'märz', 'april', 'mai', 'juni', 'juli', 'august', 'september', 'oktober', 'november', 'dezember'],
244
+ fr: ['janvier', 'février', 'mars', 'avril', 'mai', 'juin', 'juillet', 'août', 'septembre', 'octobre', 'novembre', 'décembre'],
245
+ es: ['enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio', 'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre'],
246
+ it: ['gennaio', 'febbraio', 'marzo', 'aprile', 'maggio', 'giugno', 'luglio', 'agosto', 'settembre', 'ottobre', 'novembre', 'dicembre'],
247
+ pt: ['janeiro', 'fevereiro', 'março', 'abril', 'maio', 'junho', 'julho', 'agosto', 'setembro', 'outubro', 'novembro', 'dezembro'],
248
+ nl: ['januari', 'februari', 'maart', 'april', 'mei', 'juni', 'juli', 'augustus', 'september', 'oktober', 'november', 'december'],
249
+ });
250
+ /**
251
+ * Does the text hold a comma-decimal amount: a number that stands alone (no digit, comma or point before or after it), its whole part one run of
252
+ * digits or groups of three joined by "." or a space, then a comma and one or two decimals. "133,330 chars" (a thousands-grouped count) is not one.
253
+ * The linear form of /(?<![\d,.])\d{1,3}(?:[. ]\d{3})*,\d{1,2}(?![\d,]|\.\d)|(?<![\d,.])\d+,\d{1,2}(?![\d,]|\.\d)/ (that one re-scans a long
254
+ * run of groups from every group). A start is a digit with no digit, comma or point before it; its digit run is the whole part, or the first group
255
+ * when the run is up to three digits and groups of three follow, and only the end of that chain can carry the comma.
256
+ * @param {string} s @returns {boolean}
257
+ */
258
+ function hasCommaDecimal(s) {
259
+ const n = s.length;
260
+ const digitsAt = (/** @type {number} */ q) => { let e = q; while (e < n && isDigitCode(s.charCodeAt(e))) e++; return e; };
261
+ const decimals = (/** @type {number} */ q) => {
262
+ if (s[q] !== ',') return false;
263
+ let e = q + 1;
264
+ while (e < q + 4 && isDigitCode(s.charCodeAt(e))) e++;
265
+ if (e - q - 1 < 1 || e - q - 1 > 2) return false;
266
+ return s[e] !== ',' && !(s[e] === '.' && isDigitCode(s.charCodeAt(e + 1)));
267
+ };
268
+ /** where the chain of ([. ]\d{3}) groups that starts at a position ends; each position is walked once @type {Map<number, number>} */
269
+ const chainEnd = new Map();
270
+ const endOf = (/** @type {number} */ from) => {
271
+ /** @type {number[]} */
272
+ const path = [];
273
+ let q = from; let end;
274
+ for (;;) {
275
+ const seen = chainEnd.get(q);
276
+ if (seen !== undefined) { end = seen; break; }
277
+ path.push(q);
278
+ if ((s[q] === '.' || s[q] === ' ') && isDigitCode(s.charCodeAt(q + 1)) && isDigitCode(s.charCodeAt(q + 2)) && isDigitCode(s.charCodeAt(q + 3))) q += 4;
279
+ else { end = q; break; }
280
+ }
281
+ for (const x of path) chainEnd.set(x, end);
282
+ return end;
283
+ };
284
+ for (let p = 0; p < n;) {
285
+ if (!isDigitCode(s.charCodeAt(p))) { p++; continue; }
286
+ const d = digitsAt(p);
287
+ const prev = p === 0 ? 0 : s.charCodeAt(p - 1);
288
+ if (p === 0 || !(isDigitCode(prev) || isMarkCode(prev))) {
289
+ if (decimals(d)) return true;
290
+ if (d - p <= 3 && decimals(endOf(d))) return true;
291
+ }
292
+ p = d;
293
+ }
294
+ return false;
295
+ }
164
296
 
165
297
  /**
166
298
  * 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.
@@ -180,13 +312,26 @@ export function applyPageRules(text, mapping, jobLines) {
180
312
  };
181
313
 
182
314
  // ---- S1, name part: a fact whose name counts results is refused before anything else reads it ----
183
- const list = all.filter((f) => {
184
- const hit = String(f.name ?? '').toLowerCase().split(/[^a-z]+/).find((w) => ORDINALS.includes(w));
315
+ const named = all.filter((f) => {
316
+ // "last" directly followed by a word ending in "ed" ("last updated", "last modified") names WHEN a thing changed, not which result: it is not a counting name
317
+ const hit = String(f.name ?? '').toLowerCase().split(/[^a-z]+/).find((w, i, ws) => ORDINALS.includes(w) && !(w === 'last' && /ed$/.test(ws[i + 1] ?? '')));
185
318
  if (hit === undefined) return true;
186
319
  drop(f, undefined, 's1-name');
187
320
  return false;
188
321
  });
189
322
 
323
+ // ---- a signed `lang` / `decimal` must really be on the page, else the whole fact is Not checked: a date in a language the page does not
324
+ // write, or a decimal comma on a page with no comma-decimal amount, could only ever read nothing (or the wrong thing). A field on a shape that
325
+ // does not take it (lang off a date, decimal off a number or money) is not carried; the rest of the fact stands. ----
326
+ const list = named.filter((f) => {
327
+ if (f.shape === 'date' && f.lang !== undefined) {
328
+ const months = Object.hasOwn(MONTHS_FULL, String(f.lang)) ? MONTHS_FULL[String(f.lang)] : [];
329
+ if (!months.some((m) => countPhrase(text, m) >= 1)) { drop(f, undefined, 'lang-not-on-page', String(f.lang)); return false; }
330
+ }
331
+ if ((f.shape === 'number' || f.shape === 'money') && f.decimal === ',' && !hasCommaDecimal(squash(text))) { drop(f, undefined, 'decimal-not-on-page', ','); return false; }
332
+ return true;
333
+ });
334
+
190
335
  // ---- found-on-page, then U1 and R1L for the facts that read an amount ----
191
336
  const lines = linesOf(text);
192
337
  /** @type {{f: MapFact, kept: string[], cur: string[], uni: string[], first?: string|null, anchorless?: boolean}[]} */
@@ -223,39 +368,68 @@ export function applyPageRules(text, mapping, jobLines) {
223
368
  /** @type {string[]} */ let uni = [];
224
369
  /** @type {string[]} */ let cur = [];
225
370
  if (f.shape === 'money') {
226
- // the forms: units first (the U1-moved words, then the AI's listed units), then currency signs. SORT, never drop for the box (money
227
- // build v2): the box is position only - a sign (before the number) is a currency, any other form (a word after it) is a unit - so every
228
- // form the AI listed in either box is pooled and moved to the box its own shape belongs to
371
+ // the forms: units first (the U1-moved words, then the AI's listed units), then currency signs. SORT, never drop for the box: the box is
372
+ // position only. A WORD is a unit. A currency SIGN is filed by how the PAGE writes it next to the number (bareguard 0.27, ruling #68): glued
373
+ // to the number, after it or before it, is a currency; spaced after it is a unit; both boxes when the page writes both. The box the AI
374
+ // listed it in does not matter, and a sign listed in both boxes whose page form needs only one is said once ('sign-twice').
229
375
  const listedCurrencies = (Array.isArray(f.currency) ? f.currency : []).map(String);
230
- // a currency SIGN listed in BOTH unit and currency is said once: the unit copy goes (fwd F71 drafts)
231
376
  // bareguard 0.26: two units equal after whitespace normalization are one form, so trim + collapse here and the twins collapse in the pool
232
- const listedUnits = (Array.isArray(f.unit) ? f.unit : []).map((u) => String(u).replace(/\s+/g, ' ').trim()).filter((u) => {
233
- if (!(CURRENCY_SYMBOLS.includes(u) && listedCurrencies.includes(u))) return true;
234
- drop(f, u, 'sign-twice');
235
- return false;
236
- });
377
+ const listedUnits = (Array.isArray(f.unit) ? f.unit : []).map((u) => String(u).replace(/\s+/g, ' ').trim());
378
+ const plainUnits = listedUnits.filter((u) => !CURRENCY_SYMBOLS.includes(u));
379
+ const plainCurrencies = listedCurrencies.filter((c) => !CURRENCY_SYMBOLS.includes(c));
380
+ // the lines that hold this fact's label are where its sign sits next to ITS number; with no label (U1 moved it, or none) the whole page
381
+ const scope = labels.length ? lines.filter((l) => labels.some((w) => l.includes(w))) : lines;
382
+ /** @type {string[]} */ const signCur = [];
383
+ /** @type {string[]} */ const signUni = [];
384
+ for (const sgn of new Set([...listedCurrencies, ...listedUnits].filter((x) => CURRENCY_SYMBOLS.includes(x)))) {
385
+ let fm = signForms(scope, sgn);
386
+ if (!fm.glued && !fm.spaced && !fm.before) fm = signForms(lines, sgn);
387
+ const asCur = fm.glued || fm.before;
388
+ const asUni = fm.spaced;
389
+ if (asCur || !asUni) signCur.push(sgn); // a sign with no number next to it stays a currency: the not-on-page / reads-no-result rules speak
390
+ if (asUni) signUni.push(sgn);
391
+ if (listedCurrencies.includes(sgn) && listedUnits.includes(sgn) && !(asCur && asUni)) drop(f, sgn, 'sign-twice', asUni ? 'unit' : 'currency');
392
+ }
237
393
  // a WORD listed in both boxes is one form, said once (a record of the double listing is kept, as R1L always said it)
238
- for (const w of new Set(listedCurrencies.filter((c) => !CURRENCY_SYMBOLS.includes(c) && listedUnits.includes(c)))) drop(f, w, 'r1l', w);
239
- const pool = [...moved, ...listedUnits, ...listedCurrencies];
240
- const units = [...new Set(pool.filter((w) => !CURRENCY_SYMBOLS.includes(w)))].filter((u) => {
241
- if (countPhrase(text, u) >= 1) return true;
394
+ for (const w of new Set(plainCurrencies.filter((c) => plainUnits.includes(c)))) drop(f, w, 'r1l', w);
395
+ const units = [...new Set([...moved, ...plainUnits, ...plainCurrencies, ...signUni])].filter((u) => {
396
+ if (CURRENCY_SYMBOLS.includes(u) ? countExact(text, u) >= 1 : countPhrase(text, u) >= 1) return true;
242
397
  drop(f, u, 'not-on-page');
243
398
  return false;
244
399
  });
245
- const curs = [...new Set(pool.filter((w) => CURRENCY_SYMBOLS.includes(w)))].filter((c) => {
400
+ const curs = [...new Set(signCur)].filter((c) => {
246
401
  if (countExact(text, c) >= 1) return true;
247
402
  drop(f, c, 'not-on-page');
248
403
  return false;
249
404
  });
250
405
  /** @type {{kind: 'unit'|'currency', w: string}[]} */
251
406
  const forms = [...units.map((u) => /** @type {const} */ ({ kind: 'unit', w: u })), ...curs.map((c) => /** @type {const} */ ({ kind: 'currency', w: c }))];
407
+ // A page read where the form is written (see R1L): a sign after its number reads the number before it, before its number the one after
408
+ const read = (/** @type {{kind: string, w: string}} */ x) => {
409
+ if (!CURRENCY_SYMBOLS.includes(x.w)) return x.kind === 'unit' ? unitSet(lines, x.w) : curSet(lines, x.w);
410
+ const fm = signForms(lines, x.w);
411
+ return x.kind === 'unit' || fm.glued || !fm.before ? unitSet(lines, x.w) : curSet(lines, x.w);
412
+ };
413
+ // a form that reads NO amount anywhere on the page ("ohne MwSt." alone on its own line) is dropped BEFORE R1L, so R1L never takes it as the
414
+ // reference and then drops the form that does read. When no form reads anything, nothing is dropped here and the later rules speak.
415
+ if (forms.some((x) => read(x).size > 0)) {
416
+ for (let i = forms.length - 1; i >= 0; i -= 1) {
417
+ if (read(forms[i]).size > 0) continue;
418
+ drop(f, forms[i].w, 'reads-no-amount');
419
+ forms.splice(i, 1);
420
+ }
421
+ }
252
422
  if (forms.length) {
253
- // R1L: every form reads the same set of numbers as the primary (the first form); one that reads more or fewer is dropped
254
- const read = (/** @type {{kind: string, w: string}} */ x) => (x.kind === 'unit' ? unitSet(lines, x.w) : curSet(lines, x.w));
423
+ // R1L: every form reads the same set of numbers as the primary (the first form that reads); one that reads more or fewer is dropped.
255
424
  const ps = read(forms[0]);
256
425
  const keep = [forms[0]];
257
- // 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)
258
- 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); }
426
+ // one SIGN filed in both boxes by its page forms is ONE symbol read in two forms (bareguard 0.27 counts the same amount as one price): it is
427
+ // never compared with itself
428
+ for (const x of forms.slice(1)) {
429
+ if (CURRENCY_SYMBOLS.includes(x.w) && x.w === forms[0].w) keep.push(x);
430
+ else if (x.w !== forms[0].w && sameSet(read(x), ps)) keep.push(x);
431
+ else drop(f, x.w, 'r1l', forms[0].w);
432
+ }
259
433
  uni = keep.filter((x) => x.kind === 'unit').map((x) => x.w);
260
434
  cur = keep.filter((x) => x.kind === 'currency').map((x) => x.w);
261
435
  }
@@ -309,6 +483,15 @@ export function applyPageRules(text, mapping, jobLines) {
309
483
  if (p.uni.length) out.unit = [...p.uni];
310
484
  if (p.cur.length) out.currency = [...p.cur];
311
485
  }
486
+ if (p.f.shape === 'date' && p.f.lang !== undefined) out.lang = String(p.f.lang);
487
+ if ((p.f.shape === 'number' || p.f.shape === 'money') && p.f.decimal !== undefined) out.decimal = String(p.f.decimal);
488
+ // CODE picks the decimal mark of a money fact from how the page writes the amounts its signs touch, over the AI's word when the page is clear
489
+ // (a "1.058,47 €" page read with "." would read wrong); both kinds or neither, the AI's word stands. A clear dot page keeps what was signed
490
+ // ("." is the reader's default, so no field is added).
491
+ if (p.f.shape === 'money') {
492
+ const mark = pageDecimal(lines, [...(out.currency ?? []), ...(out.unit ?? [])]);
493
+ if (mark === ',') out.decimal = ',';
494
+ }
312
495
  if (t.rule !== undefined) out.forRule = t.rule;
313
496
  if (validReading(out.shape, p.f.reading)) out.reading = /** @type {Reading} */ ({ ...p.f.reading });
314
497
  return out;
@@ -776,6 +776,8 @@ export function createSession(card, deps = {}) {
776
776
  if (RUBRIC_FILES) {
777
777
  const proved = await proveRubricInputs({ inputs: INPUTS, into, destination: card.destination, ...(deps.fetchUrl ? { fetchUrl: deps.fetchUrl } : {}) });
778
778
  prep = proved.ok ? proved.prep : { stop: proved.error, code: proved.code };
779
+ // what each header-only page read came back with (already secret-masked at capture), so the next live failure shows it
780
+ if (!proved.ok && proved.attempts?.length) appendDraftLog(outDir, { kind: 'page-fetch-attempts', no: Math.max(0, state.steps.length - 1), attempts: proved.attempts, at: new Date().toISOString() });
779
781
  } else {
780
782
  prep = await prepareSource({
781
783
  source: SOURCE, into, ...(isRepoLike || destIsDir ? { destination: card.destination } : {}),
@@ -118,6 +118,8 @@
118
118
  .topbar .version{flex:none;}
119
119
  @media (max-width: 600px){ .topbar .tagline{display:none;} }
120
120
  .topbar-right{display:flex;align-items:center;gap:10px;flex-wrap:wrap;}
121
+ #online-dot{font-size:12px;white-space:nowrap;flex:none;}
122
+ #online-dot.on{color:var(--green);} #online-dot.off{color:var(--red);}
121
123
 
122
124
  [hidden]{display:none !important;}
123
125
  .main{display:flex;flex:1;min-height:0;}
@@ -717,6 +719,7 @@
717
719
  </div>
718
720
  <div class="topbar-right">
719
721
  <span class="hint" id="host-line"></span>
722
+ <span id="online-dot" class="on" data-testid="online-dot" role="status">&#9679; online</span>
720
723
  <button class="btn small" type="button" id="btn-settings" data-testid="btn-settings">&#9881; Settings</button>
721
724
  <button class="theme-toggle" id="theme-toggle" type="button" aria-label="Toggle light/dark theme">&#9789;</button>
722
725
  </div>
@@ -1116,8 +1119,9 @@
1116
1119
  // ---- fetch helpers ----
1117
1120
  function getJSON(path){
1118
1121
  return fetch(path, { headers: { accept: "application/json" } }).then(function(r){
1119
- if(!r.ok) throw new Error(path + ": HTTP " + r.status);
1120
- return r.json();
1122
+ // `.status` marks "node answered": an HTTP error, or a 200 whose body would not parse — the online dot reads it (only a status-less failure is offline).
1123
+ if(!r.ok){ var err = new Error(path + ": HTTP " + r.status); err.status = r.status; throw err; }
1124
+ return r.json().catch(function(e){ e.status = r.status; throw e; });
1121
1125
  });
1122
1126
  }
1123
1127
 
@@ -4101,24 +4105,37 @@
4101
4105
  });
4102
4106
  }
4103
4107
 
4108
+ // The Runs list poll (every RUNS_LIST_POLL_MS) is the panel's heartbeat: ANY reply (even an HTTP error) = node answered = online; only a read that failed
4109
+ // with no HTTP status (the network, a dead panel) = offline. ONE painter writes the dot; the served page starts online.
4110
+ function paintOnline(isOnline){
4111
+ var el = document.getElementById("online-dot");
4112
+ el.className = isOnline ? "on" : "off";
4113
+ el.textContent = isOnline ? "\u25CF online" : "\u25CF offline";
4114
+ }
4115
+
4104
4116
  function refreshRunsList(force){
4105
4117
  var now = Date.now();
4106
4118
  if(!force && (now - lastRunsListRefreshAt) < RUNS_LIST_POLL_MS) return Promise.resolve();
4107
4119
  lastRunsListRefreshAt = now;
4108
4120
  return getJSON("/api/runs").then(function(result){
4109
4121
  pollFailStreak = 0;
4122
+ paintOnline(true);
4110
4123
  var runs = result.runs || [];
4111
4124
  var next = sig(result);
4112
4125
  if(next === lastRunsPayloadSig) return runs; // unchanged payload — never rebuild the DOM for nothing
4113
4126
  lastRunsPayloadSig = next;
4114
4127
  lastRunsSig = sig(runs);
4115
- withScrollPreserved(["left-pane-body"], function(){
4116
- // the painter re-runs the SAME filter/search state — a poll tick never resets it, and it writes a box only when its markup changed.
4117
- setRunsData(result);
4118
- runsFilterBar.refresh();
4119
- });
4128
+ // a render throw is a page bug, not the panel being down: log it here so it never reaches the status catch below (which would paint "offline")
4129
+ try {
4130
+ withScrollPreserved(["left-pane-body"], function(){
4131
+ // the painter re-runs the SAME filter/search state — a poll tick never resets it, and it writes a box only when its markup changed.
4132
+ setRunsData(result);
4133
+ runsFilterBar.refresh();
4134
+ });
4135
+ } catch(renderErr){ console.error("runs list render failed", renderErr); }
4120
4136
  return runs;
4121
- }).catch(function(){
4137
+ }).catch(function(err){
4138
+ paintOnline(!!(err && typeof err.status === "number"));
4122
4139
  pollFailStreak++;
4123
4140
  // Keep the last good render; a transient failure is invisible. Only a
4124
4141
  // PERSISTENT failure (3+ ticks, ~6s) gets a quiet, non-alarming note —
@@ -5248,8 +5265,8 @@
5248
5265
  fitCardBoxes();
5249
5266
  }
5250
5267
  msgInput.addEventListener("input", renderMain);
5251
- // P7 — the numbered boxes. A plain job line is numbered 1, 2, 3; a line starting `~` is a rule for the line above and has no
5252
- // number; Inputs numbers every line; empty lines have none. A hidden mirror (same font/width/padding) measures each logical
5268
+ // P7 — the numbered boxes. A plain job line is numbered 1, 2, 3; a line starting `~` is a rule for the line above: it shows `~` in
5269
+ // the gutter and takes no number; Inputs numbers every line; empty lines have none. A hidden mirror (same font/width/padding) measures each logical
5253
5270
  // line's wrapped height so every number stays level with its own line — the same rules src/jobblock.js parses by.
5254
5271
  var NUMBERED_IDS = ["jf-job", "jf-inputs"];
5255
5272
  var FIT_IDS = ["jf-job", "jf-inputs", "jf-dest"];
@@ -5261,7 +5278,8 @@
5261
5278
  var n = 0;
5262
5279
  var nums = lines.map(function(l){
5263
5280
  var t = l.trim();
5264
- if(t === "" || (isJob && t.charAt(0) === "~")) return "";
5281
+ if(t === "") return "";
5282
+ if(isJob && t.charAt(0) === "~") return "~";
5265
5283
  n += 1; return String(n);
5266
5284
  });
5267
5285
  mir.style.width = ta.clientWidth ? ta.clientWidth + "px" : "";
package/src/plan.js CHANGED
@@ -36,6 +36,10 @@ export const EXIT_TYPES = Object.freeze(['artifact-written', 'tree-changed', 'js
36
36
  /** decision 8: AND-only conjunction, bounded — no OR (a weak arm would
37
37
  * launder the exit), no NOT */
38
38
  export const MAX_EXITS_PER_STEP = 2;
39
+ /** a legal-example sentence for the exit menu — shown in the planner prompt and
40
+ * appended to the missing-required exit red, so a redraft sees a legal shape,
41
+ * not only the rule (F254: `exit` is required on EVERY step) */
42
+ export const EXIT_EXAMPLE = 'Legal exit examples: a step with no check uses [{"type":"artifact-written","path":"<its target>"},{"type":"tree-changed","scope":"<an offered scope>"}]; a step with a check uses [{"type":"tree-changed","scope":"<an offered scope>"},{"type":"check-passes","name":"<a check name>"}].';
39
43
  /** plan size bound — per-step rounds bound the spend, but an unbounded step
40
44
  * COUNT is still an unbounded claim on the wallet; same 8 as loop.maxIterations */
41
45
  export const MAX_PLAN_STEPS = 8;
@@ -519,7 +523,7 @@ export function validatePlan(input, { job, maxStepRounds = 40, scopes, seedRed,
519
523
  */
520
524
  function validateExit(s, at, red, { checkNames, fence, insideFence, writeStep, toolsParsed, scopeMenu, stepScope, overlapsStepScope, seedRedNames, isFinalWrite }) {
521
525
  if (!Array.isArray(s.exit) || s.exit.length === 0) {
522
- red('missing-required', `${at}.exit`, `non-empty array from the closed menu ${EXIT_TYPES.join('|')} — ALL listed exits must pass (AND-only); a step without an exit has no progress gate`);
526
+ red('missing-required', `${at}.exit`, `non-empty array from the closed menu ${EXIT_TYPES.join('|')} — ALL listed exits must pass (AND-only); a step without an exit has no progress gate — ${EXIT_EXAMPLE}`);
523
527
  return;
524
528
  }
525
529
  if (s.exit.length > MAX_EXITS_PER_STEP) {
package/src/planrun.js CHANGED
@@ -28,7 +28,7 @@ import { Gate } from 'bareguard';
28
28
  import { LiteCtx } from 'litectx';
29
29
  import { runClose, runStages, ralph, CLOSE_FAULTS, boundGap } from './ralph.js';
30
30
  import { validatePlan, legalScopes, closeStagesOf } from './plan.js';
31
- import { WRITE_VERBS, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, MAX_SCOPE_MENU, RETRIEVAL_PAIR } from './plan.js';
31
+ import { WRITE_VERBS, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, MAX_SCOPE_MENU, RETRIEVAL_PAIR, EXIT_EXAMPLE } from './plan.js';
32
32
  import { snapshotScope, evalExits, CHECK_GAP_MAX } from './exits.js';
33
33
  import { createRoot } from './root.js';
34
34
  import { createStallWatch, STALL_MS, MAX_STALLS } from './stall.js';
@@ -38,6 +38,7 @@ import { TOOL_MENU, STORE_VERBS, checkMenu } from './job.js';
38
38
  import { TOOL_BY_VERB, CTX_TOOLS, createCtxTools, toolAction, PERSONA_TOOLS, strategyFor } from './tools.js';
39
39
  import { anySuppressionWarning } from './authoring.js';
40
40
  import { createReadShim, readShimArm, readShimStrategy } from './readshim.js';
41
+ import { createHandoffStore, trackReads } from './handoff.js';
41
42
  import { globToPrefix, redactSecrets, SECRET_PATTERNS } from './validate.js';
42
43
  import { startAttemptDiff } from './attemptdiff.js';
43
44
  import { validateBridge, loadGate, newestEligibleVersion, reuseEligibility, quarantinesCredit, QUARANTINED_CODE } from './bridges.js';
@@ -699,7 +700,7 @@ strictly in array order. Each step (no other fields exist):
699
700
  inside it, and a "tree-changed" exit's scope must not be disjoint from it (one that
700
701
  CONTAINS it is fine) — otherwise every write the step could make is denied, or the
701
702
  exit can never pass, on every attempt.
702
- - "exit": 1..${MAX_EXITS_PER_STEP} form checks that ALL must pass (AND), each one of:
703
+ - "exit": REQUIRED on EVERY step — 1..${MAX_EXITS_PER_STEP} form checks that ALL must pass (AND), each one of:
703
704
  {"type":"artifact-written","path":"...","pattern":"optional regex"}
704
705
  {"type":"tree-changed","scope":"<copy one value from the offered scopes below>"}
705
706
  {"type":"json-valid","path":"..."}
@@ -708,6 +709,7 @@ strictly in array order. Each step (no other fields exist):
708
709
  it character for character. No other name exists, and you cannot add one.
709
710
  A check-passes on a write-granted step MUST be paired with a tree-changed exit
710
711
  (the repository starts green — a lone check would pass on the untouched tree).
712
+ ${EXIT_EXAMPLE}
711
713
  A check-passes may ONLY appear on a step whose tools include write or edit: a
712
714
  failing check is reported back to THAT step's worker for another attempt, so
713
715
  the step must be able to act on the report. Do not plan a separate read-only
@@ -1022,6 +1024,10 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
1022
1024
  // would be wrong and would look fine). Only the guard runs here; the flag itself
1023
1025
  // is still threaded onward as written.
1024
1026
  readShimArm(readShim);
1027
+ // THE HANDOFF NOTE (src/handoff.js): the paths earlier asks of THIS run read. In memory only, so a resumed leg starts empty.
1028
+ // The switch is the signed spec's `handoffNote` (absent = on, only `false` turns it off).
1029
+ const handoffOn = job.handoffNote !== false;
1030
+ const handoff = createHandoffStore({ workdir });
1025
1031
  // The scout switch's guard, same class and same door: a mis-typed value
1026
1032
  // coerced by truthiness would run the scout under an "off" label (or skip it
1027
1033
  // under an "on" one) and no reading of the results afterwards could recover
@@ -2567,6 +2573,26 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2567
2573
  // below anything a second/minute-scale timer can perceive. Store output is byte-identical.
2568
2574
  if (ctx.length) await lc.index({ yield: true });
2569
2575
  const toolDefs = [...shell, ...ctx];
2576
+ // The handoff note: record what each ask READS (the allowed read-class calls), hand the next step/fix ask the map.
2577
+ // Scout and drafter asks feed the store but are never given a note.
2578
+ /** @type {Set<string>} */
2579
+ let askReads = new Set();
2580
+ if (handoffOn) trackReads(toolDefs, [TOOL_BY_VERB.read, TOOL_BY_VERB.get], (a) => askReads.add(a), workdir);
2581
+ /** @param {(prompt: string, defs?: any) => Promise<any>} inner */
2582
+ const withHandoff = (inner) => (!handoffOn ? inner : async (/** @type {string} */ prompt, /** @type {any} */ defs) => {
2583
+ askReads = new Set();
2584
+ let p = prompt;
2585
+ if (phase === 'fix' || phase.startsWith('step:')) {
2586
+ // The index is incremental: refreshing it here is what keeps the symbol ranges true to the files as they now are.
2587
+ try { if (ctx.length) await lc.index({ yield: true }); } catch { /* the map falls back to line counts */ }
2588
+ const note = handoff.render({ getNode: (rel) => lc.getNode(rel) });
2589
+ if (note.text) {
2590
+ p = `${prompt}\n\n${note.text}`;
2591
+ emit('handoff-note', { phase, iteration: roundIteration, chars: note.text.length, paths: note.paths });
2592
+ }
2593
+ }
2594
+ try { return await inner(p, defs); } finally { handoff.absorb(askReads); }
2595
+ });
2570
2596
  // F19 per VERB (P, corrected 2026-07-31): a strategy SENTENCE rides only with
2571
2597
  // the verb it names. Gating per COMPONENT was close but over-reached — a
2572
2598
  // worker granted only `impact` must not be steered to tools it lacks, and the
@@ -2633,6 +2659,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2633
2659
  const askFrom = async () => null;
2634
2660
  const ask = async (prompt, defs = toolDefs) => {
2635
2661
  let r;
2662
+ shim.reset(); // each ask() is a fresh session: the model holds nothing earlier asks were handed
2636
2663
  try {
2637
2664
  r = await loop.run([{ role: 'user', content: prompt }], defs, { maxTokens: 32000 });
2638
2665
  } catch (e) {
@@ -2663,7 +2690,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2663
2690
  }
2664
2691
  return r;
2665
2692
  };
2666
- return { ask, askFrom, workerWrites, writeCount, setIteration, wasBounded: () => attemptBounded };
2693
+ return { ask: withHandoff(ask), askFrom, workerWrites, writeCount, setIteration, wasBounded: () => attemptBounded };
2667
2694
  }
2668
2695
 
2669
2696
  // ── LOOP path: the injected provider (anthropic-api and every other
@@ -2862,6 +2889,10 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2862
2889
  };
2863
2890
  const ask = async (prompt, defs = toolDefs) => {
2864
2891
  let r;
2892
+ // A fresh Loop = a fresh transcript: the read shim's delivered-ledger resets with it, or a
2893
+ // later attempt's re-read is answered with a pointer to bytes its model never saw (F252).
2894
+ // askFrom (a continuation of a prior transcript) deliberately does NOT reset.
2895
+ shim.reset();
2865
2896
  const thinkOpts = thinkingForCall();
2866
2897
  try {
2867
2898
  r = await stallWatch.watch((gen) => newLoop(gen).run([{ role: 'user', content: prompt }], defs, { cacheMessages: true, maxTokens: 32000, ...callBounds(), ...thinkOpts }));
@@ -2933,7 +2964,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2933
2964
  }
2934
2965
  return r;
2935
2966
  };
2936
- return { ask, askFrom, workerWrites, writeCount, setIteration, wasBounded: () => attemptBounded };
2967
+ return { ask: withHandoff(ask), askFrom, workerWrites, writeCount, setIteration, wasBounded: () => attemptBounded };
2937
2968
  }
2938
2969
 
2939
2970
  /** relay a throw from OUTSIDE ralph (scout/plan drafting/fix) as its honest
package/src/readshim.js CHANGED
@@ -555,7 +555,23 @@ export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL, onCount = n
555
555
  * the diff lever (L2) is a different response shape and is not counted here. */
556
556
  const summary = () => ({ pointered, capped, bytesWithheld });
557
557
 
558
- return { arm, cap, wrapRead, serveStale, summary };
558
+ /**
559
+ * A NEW ask() builds a fresh Loop with a fresh transcript — the model holds NONE of
560
+ * what earlier asks delivered — so the delivery ledger must forget with it. Left in
561
+ * place, attempt 2 re-reading a file attempt 1 fully received is answered "unchanged,
562
+ * you already hold all N bytes": untruthful, the one thing this module exists to
563
+ * prevent (FINDINGS F252). Over-delivery is the legal direction; a false pointer is not.
564
+ *
565
+ * It clears ONLY the ledger (what the model was handed). It does NOT touch the
566
+ * MEMORY-CACHE counters (`pointered`/`capped`/`bytesWithheld`, and the caller's run-level
567
+ * `onCount` sum): those are a record of bytes already withheld, not of what a model holds,
568
+ * and zeroing them would erase real savings from the readout. `serveStale` holds no ledger.
569
+ * Not called for a continuation (`askFrom` re-runs the SAME transcript — the model still
570
+ * holds everything, so its ledger stays true).
571
+ */
572
+ const reset = () => { ledger.clear(); };
573
+
574
+ return { arm, cap, wrapRead, serveStale, summary, reset };
559
575
  }
560
576
 
561
577
  /**