perf(benchmark): memoize the endurance comparator parse — blank-line-incremental, not full re-parse (#13032) (#13111)

Subject B (the main-thread comparator) re-parsed the full growing source each tick — O(n^2) over a session, conflating Neo's parser memoization with the worker-topology variable the benchmark exists to isolate. Resolve the naive-vs-best-practice fork to best practice: createIncrementalBlocks settles blocks before the last blank line once and re-parses only the open region per delta.

A blank line is the only boundary a forward-only stream can never un-merge (a partial list item still merges with the next once it arrives), so block-granularity settling is unsafe — caught by the every-prefix equivalence test. parseMarkdownBlocks output stays byte-identical (back-compat).

Verified: 9/9 unit green; benchmark e2e 4/4 green (comparator drives end-to-end; cross-subject delta runner intact).

Author: neo-opus-vega

ai/examples/harnessEndurance/comparator/comparator.mjs

@@ -1,5 +1,5 @@
-import parseMarkdownBlocks from './markdownBlocks.mjs';
-import {LoadProfile}       from '../shared/LoadProfile.mjs';
+import {createIncrementalBlocks} from './markdownBlocks.mjs';
+import {LoadProfile}             from '../shared/LoadProfile.mjs';
 
 /**
  * @summary Subject B — the honest single-main-thread comparator for the Harness Endurance Benchmark.
@@ -12,12 +12,11 @@ import {LoadProfile}       from '../shared/LoadProfile.mjs';
  * RENDER (best-practice shape): tail-incremental — settled blocks are written once then frozen, only
  * the open last block re-renders as it grows; NOT an O(n²) full-`innerHTML` rewrite.
  *
- * PARSE (honest caveat for the fairness fork): this re-parses the full growing source each tick — the
- * COMMON main-thread approach. Neo's parser memoizes settled blocks (re-parses only the open tail), so
- * the lag delta here includes Neo's memoization benefit ALONGSIDE the worker-topology effect; a
- * memoized comparator would isolate threading more tightly. Documented as the naive-vs-best-practice
- * refinement on the benchmark ticket — a defensible first comparator, biased if anything toward
- * realism (this is what typical main-thread streaming-markdown code does), reviewable.
+ * PARSE (best-practice shape): incremental — settled blocks (everything before the last blank line) are
+ * parsed ONCE and only the open region re-parses from each delta (`createIncrementalBlocks`), mirroring
+ * the off-thread Neo parser's memoization. So the lag delta isolates the worker-topology variable (WHERE
+ * the work runs) rather than conflating it with parse strategy — the benchmark's naive-vs-best-practice
+ * fork, resolved to best-practice.
  */
 
 const
@@ -64,17 +63,16 @@ function applyBlocks(blocks) {
 }
 
 /**
- * Drives the deterministic `LoadProfile` append stream, parsing + rendering each growing-source tick
- * synchronously on the main thread. A run token prevents overlapping runs.
+ * Drives the deterministic `LoadProfile` append stream, parsing the open block + rendering each delta
+ * synchronously on the main thread (settled blocks memoized). A run token prevents overlapping runs.
  * @param {Object} [config] forwarded to `LoadProfile` (seed, durationMs, cadences).
  * @returns {Promise<void>}
  */
 async function start(config = {}) {
     const
         profile = new LoadProfile(config),
-        token   = ++runToken;
-
-    let accumulated = '';
+        token   = ++runToken,
+        blocks  = createIncrementalBlocks();
 
     containers.forEach(container => container.remove());
     containers = [];
@@ -84,8 +82,7 @@ async function start(config = {}) {
             break
         }
 
-        accumulated += text;
-        applyBlocks(parseMarkdownBlocks(accumulated));
+        applyBlocks(blocks.push(text));
 
         await new Promise(resolve => setTimeout(resolve, profile.appendCadenceMs))
     }

ai/examples/harnessEndurance/comparator/markdownBlocks.mjs

@@ -1,18 +1,35 @@
 /**
  * @summary Competent single-main-thread markdown → block-HTML renderer for the benchmark comparator
- * (Subject B).
+ * (Subject B), with blank-line-incremental parsing.
  *
  * The honest comparator does the SAME class of work as Subject A's off-thread Neo parser — block
  * segmentation, inline marks, and HTML escaping (hostile input rendered inert) — but synchronously on
- * the MAIN thread. It returns per-block HTML so the app applies the stream tail-incrementally (append
- * new blocks, re-render only the open last block), never an O(n²) full-`innerHTML` rewrite.
+ * the MAIN thread. {@link parseMarkdownBlocks} parses a full string; the streaming driver
+ * {@link createIncrementalBlocks} MEMOIZES — it settles completed blocks once and re-parses only the
+ * open region from the deltas it is fed.
  *
- * Pure (string → string[]), dependency-free, unit-tested. Fairness posture (full rationale + the
- * naive-vs-best-practice fork on the benchmark ticket thread): this parser is competent but simpler than
- * Neo's full grammar, so it does LESS main-thread work — a CONSERVATIVE bias (a lighter parser makes
- * the comparator MORE responsive, shrinking any Neo advantage), which is the honest direction for a
- * falsifier. A real library (`marked`) is the documented alternative if reviewers want tighter
- * parse-work parity.
+ * Why blank-line granularity (not per-block): a blank line is the ONLY block boundary a forward-only
+ * token stream can never un-merge — a mid-stream `- a` followed by `-` parses as list + paragraph, yet
+ * becomes ONE list once `- b` arrives, so settling per-block would corrupt the output. Blocks before
+ * the last blank line are permanently separated; everything after it is the open region, re-parsed each
+ * delta. Per-`push` work is therefore bounded by the blank-line cadence of the stream (the benchmark's
+ * `LoadProfile` corpus emits `\n\n` separators regularly), NOT by the whole transcript — keeping the
+ * comparator's parse cost off the O(n²) full-re-parse path.
+ *
+ * Why incremental matters for the falsifier (the benchmark's naive-vs-best-practice fork → best practice): a full
+ * re-parse of the growing source each tick is O(n²) over a session AND conflates Neo's parser
+ * memoization with the worker-topology variable under test. Memoizing here leaves the lag delta
+ * measuring ONLY where the work runs (main thread vs worker) — the variable this benchmark isolates. No
+ * `innerHTML` O(n²) rewrite on render either (the app applies tail-incrementally).
+ *
+ * Fairness posture: this parser is competent but simpler than Neo's full grammar, so it does LESS
+ * main-thread work per block — a CONSERVATIVE bias (a lighter parser makes the comparator MORE
+ * responsive, shrinking any Neo advantage), the honest direction for a falsifier. Residual: a multi-block
+ * run with no blank line between (e.g. a heading immediately followed by a paragraph) re-parses together
+ * until the next blank line — a bounded, negligible over-count. A real library (`marked`) is the
+ * documented alternative if reviewers want tighter parse-work parity.
+ *
+ * Pure (no DOM / Neo / Playwright), dependency-free, unit-tested.
  */
 
 const ESCAPE = {'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'};
@@ -108,4 +125,63 @@ export function parseMarkdownBlocks(source) {
     return blocks
 }
 
+/**
+ * Index just after the LAST blank line in `source` — the highest offset before which every block is
+ * permanently settled (a forward-only append can never merge a block across a blank line). Returns 0
+ * when no blank line is present yet (nothing settled). A blank line is a newline, an optional run of
+ * spaces/tabs, then a newline.
+ * @param {String} source
+ * @returns {Number}
+ * @private
+ */
+function lastBlankBoundary(source) {
+    const re = /\n[ \t]*\n/g;
+    let boundary = 0, match;
+
+    while ((match = re.exec(source)) !== null) {
+        boundary    = match.index + match[0].length;
+        re.lastIndex = match.index + 1;   // step one char so consecutive blank-line runs keep advancing
+    }
+
+    return boundary
+}
+
+/**
+ * @summary A stateful, delta-fed incremental block parser — the memoizing front-end for streaming.
+ *
+ * Feed it appended deltas via {@link push}; it keeps only the OPEN source after the last blank line,
+ * settles the blocks before that boundary exactly once, and returns the current full block-HTML list
+ * each call. Per-`push` work is bounded by the open region (since the last blank line), NOT the whole
+ * transcript — the property that keeps the comparator's parse cost off the O(n²) full-re-parse path and
+ * isolates the worker-topology variable the benchmark measures.
+ *
+ * @returns {{push: (function(String): String[])}}
+ */
+export function createIncrementalBlocks() {
+    let settledHtml = [],
+        openSource  = '';
+
+    return {
+        /**
+         * Append a streamed delta and return the current block-HTML list (settled blocks + the open
+         * region's blocks). Pass the DELTA, not the accumulated source.
+         * @param {String} [textDelta='']
+         * @returns {String[]}
+         */
+        push(textDelta = '') {
+            openSource += textDelta;
+
+            const boundary = lastBlankBoundary(openSource);
+
+            if (boundary > 0) {
+                // Everything before the last blank line can never change → settle it once.
+                settledHtml.push(...parseMarkdownBlocks(openSource.slice(0, boundary)));
+                openSource = openSource.slice(boundary);
+            }
+
+            return [...settledHtml, ...parseMarkdownBlocks(openSource)]
+        }
+    };
+}
+
 export default parseMarkdownBlocks;

test/playwright/unit/ai/examples/harnessEndurance/comparator/markdownBlocks.spec.mjs

@@ -1,5 +1,5 @@
 import {test, expect}                       from '@playwright/test';
-import parseMarkdownBlocks, {parseMarkdownBlocks as named} from '../../../../../../../ai/examples/harnessEndurance/comparator/markdownBlocks.mjs';
+import parseMarkdownBlocks, {parseMarkdownBlocks as named, createIncrementalBlocks} from '../../../../../../../ai/examples/harnessEndurance/comparator/markdownBlocks.mjs';
 
 /**
  * @summary Coverage for ai/examples/harnessEndurance/comparator/markdownBlocks.mjs — the pure
@@ -53,4 +53,37 @@ test.describe('ai/examples/harnessEndurance/comparator/markdownBlocks', () => {
     test('default export equals the named export', () => {
         expect(parseMarkdownBlocks).toBe(named);
     });
+
+    test('createIncrementalBlocks streams to the SAME result as a full parse at every prefix', () => {
+        // The list (`- a\n- b`) is the regression guard: a forward-only stream transiently parses
+        // `- a\n-` as list+paragraph, so block-granularity settling would split it — blank-line
+        // settling must keep it ONE list once `- b` arrives.
+        const source = '# Title\n\npara one grows\n\n- a\n- b\n\n> quote here';
+        const parser = createIncrementalBlocks();
+        let acc = '', last = [];
+
+        for (let i = 0; i < source.length; i += 3) {
+            const chunk = source.slice(i, i + 3);
+            acc += chunk;
+            last  = parser.push(chunk);
+            // The memoized incremental output must equal a full re-parse of the same prefix — always.
+            expect(last).toEqual(parseMarkdownBlocks(acc));
+        }
+
+        expect(last).toEqual(parseMarkdownBlocks(source));
+        expect(last).toEqual(['<h1>Title</h1>', '<p>para one grows</p>', '<ul><li>a</li><li>b</li></ul>', '<blockquote>quote here</blockquote>']);
+    });
+
+    test('createIncrementalBlocks settles blocks at blank-line boundaries; the open region re-parses', () => {
+        const parser = createIncrementalBlocks();
+
+        expect(parser.push('a para'))     .toEqual(['<p>a para</p>']);                            // open region
+        expect(parser.push(' continues')) .toEqual(['<p>a para continues</p>']);                  // same open block grows
+        expect(parser.push('\n\n# Head')) .toEqual(['<p>a para continues</p>', '<h1>Head</h1>']); // blank line settles the paragraph
+        expect(parser.push('er'))         .toEqual(['<p>a para continues</p>', '<h1>Header</h1>']); // settled stays byte-stable
+    });
+
+    test('createIncrementalBlocks tolerates empty deltas', () => {
+        expect(createIncrementalBlocks().push('')).toEqual([]);
+    });
 });