parseman 0.58.3 → 0.59.1

package/src/compiler/token-dispatch.ts

@@ -1,83 +1,12 @@
 /**
- * Derived tokenization, part 3: token-KEYED dispatch.
+ * Packing and case-fold helpers for the dormant token scanner (`token-scanner.ts`).
  *
- * A `dispatch()` used to emit, per case, a chained condition that re-derived the
- * key from the selector's STRING one character at a time:
- *
- *   if (_dkey.length === 6 && _dkey.charCodeAt(0) === 64 && (_dkey.charCodeAt(1) | 32) === 108 && ...)
- *   else if (_dkey.length === 15 && ...)
- *
- * Measured on the built css artifact: 40,269 B of 3,336,650 B was exactly these
- * chains, 10,499 B of it inside `_r_StylesheetAtRule` alone.
- *
- * Instead the selector's matched span is walked to a small integer case id, and
- * the cases select on the integer. Every id strategy below is BUILT, not
- * reasoned about — `PARSEMAN_DISPATCH=<id>:<sel>` picks one so they can be
- * measured on the shipped artifact rather than in a microbenchmark, which
- * already misled us once: a standalone "table" looked slow because that
- * implementation sliced and lowercased and hashed, not because table dispatch
- * is slow.
- *
- * Every strategy is "compute a candidate case cheaply, then VERIFY against the
- * packed key text", except `trie`, whose walk is already exact.
- */
-
-/** One dispatch case's keys, in emission order. Case ids are 1-based; 0 = no match. */
-export type DispatchKeySet = { keys: readonly string[]; caseInsensitive: boolean }
-
-export type IdStrategy = 'trie' | 'lenswitch' | 'firstchar' | 'phash'
-export type ArmSelection = 'ifchain' | 'switch'
-
-export type DispatchConfig = { id: IdStrategy | 'auto'; sel: ArmSelection }
-
-/**
- * `PARSEMAN_DISPATCH=<id>:<sel>`. The default is the MEASURED winner on the
- * shipped css artifact, not a preference. All five configurations were built
- * into this emitter and compared on the real artifact with the trees diffed for
- * equality, interleaved in one process (medians of 31 rounds):
- *
- *   config          ms/parse   rel     raw B      gzip B
- *   chain            6.092    1.000   3,336,650   426,247
- *   trie:ifchain     5.967    0.979   3,311,657   424,465   <- default
- *   trie:switch      5.945    0.976   3,333,421   424,895
- *   phash:switch     6.011    0.987   3,331,361   424,637
- *
- * `firstchar` and `lenswitch` BUILD but are inapplicable to css's at-keyword
- * sets — every key starts with `@`, and the lengths collide — so they fall back
- * and emit the chain. `phash` finds an injective hash (the search works) but
- * costs more table bytes than the trie saves. `switch` arm selection is within
- * noise of the chain of integer compares at 3 sites x 8 cases; its larger raw
- * size is the downstream formatter indenting case bodies, which is why gzip is
- * the metric that decides here.
- *
- * The speed spread across ALL configurations is 2.4% — dispatch keying is not
- * where css parse time goes.
+ * This module once also emitted token-keyed `dispatch()` id strategies (trie,
+ * length switch, first char, perfect hash) for the source lowering deleted in
+ * 0.47.0. Those strategies, their `PARSEMAN_DISPATCH` selector and their
+ * measurements were removed with nothing left calling them; they last existed at
+ * `4a5d0341`. What remains is what `token-scanner.ts` imports.
  */
-export function dispatchConfigFromEnv(env: Record<string, string | undefined>): DispatchConfig {
-  const raw = env.PARSEMAN_DISPATCH
-  if (raw === undefined || raw === '') return { id: 'trie', sel: 'ifchain' }
-  const [idPart, selPart] = raw.split(':')
-  const id = (['trie', 'lenswitch', 'firstchar', 'phash', 'auto'] as const).find(s => s === idPart) ?? 'auto'
-  const sel: ArmSelection = selPart === 'ifchain' ? 'ifchain' : 'switch'
-  return { id, sel }
-}
-
-/** Flattened (key, caseIndex) pairs, folded when the case is case-insensitive. */
-type FlatKey = { text: string; caseIndex: number }
-
-function flatten(cases: ReadonlyArray<DispatchKeySet>): FlatKey[] | null {
-  const out: FlatKey[] = []
-  for (const [i, c] of cases.entries()) {
-    for (const key of c.keys) {
-      if (key.length === 0) return null
-      // A case-SENSITIVE key containing an ASCII letter cannot share a folded
-      // comparison with the rest; refuse rather than accept the wrong case.
-      if (!c.caseInsensitive && /[a-zA-Z]/.test(key)) return null
-      out.push({ text: foldText(key), caseIndex: i + 1 })
-    }
-  }
-  return out.length === 0 ? null : out
-}
 
 /**
  * ASCII letter-only case fold. Used IDENTICALLY when building the tables and
@@ -88,11 +17,6 @@ function flatten(cases: ReadonlyArray<DispatchKeySet>): FlatKey[] | null {
  */
 export const foldExpr = (c: string): string => `(${c} >= 65 && ${c} <= 90 ? ${c} + 32 : ${c})`
 export function foldCode(c: number): number { return c >= 65 && c <= 90 ? c + 32 : c }
-function foldText(t: string): string {
-  let out = ''
-  for (let i = 0; i < t.length; i++) out += String.fromCharCode(foldCode(t.charCodeAt(i)))
-  return out
-}
 
 /**
  * Pack a non-negative int array into a two-chars-per-value string literal.
@@ -103,7 +27,7 @@ function foldText(t: string): string {
  * this is the ONLY implementation: a second copy in token-scanner.ts had the same
  * encoding and the same missing check, which is how one defect became two.
  */
-export const PACK_MAX = 4095
+const PACK_MAX = 4095
 export function packInts(values: readonly number[]): string {
   let s = ''
   for (const v of values) {
@@ -118,236 +42,9 @@ export function packInts(values: readonly number[]): string {
   return JSON.stringify(s)
 }
 
-/* ------------------------------------------------------------------ *
- * Shared runtime helpers, emitted ONCE per artifact however many sites
- * use them. That is what lets tables shrink the artifact instead of
- * growing it: only the small per-site data is duplicated.
- * ------------------------------------------------------------------ */
-
-export type SharedHelper = 'unpack' | 'verify' | 'trie' | 'lenswitch' | 'firstchar' | 'phash'
-
-export function sharedHelperDecl(kind: SharedHelper, n: (h: SharedHelper) => string): string {
-  switch (kind) {
-    case 'unpack':
-      return `const ${n('unpack')} = s => { const o = new Int32Array(s.length >> 1); for (let i = 0; i < o.length; i++) o[i] = (s.charCodeAt(i * 2) - 35) | ((s.charCodeAt(i * 2 + 1) - 35) << 6); return o }`
-    case 'verify':
-      return [
-        `function ${n('verify')}(input, from, to, keys, ko, kl) {`,
-        `  if (to - from !== kl) return false`,
-        `  for (let i = 0; i < kl; i++) { const c = input.charCodeAt(from + i); if (${foldExpr('c')} !== keys.charCodeAt(ko + i)) return false }`,
-        `  return true`,
-        `}`,
-      ].join('\n')
-    case 'trie':
-      return [
-        `function ${n('trie')}(input, from, to, ch, st, nx, ac) {`,
-        `  let node = 0`,
-        `  for (let i = from; i < to; i++) {`,
-        `    const c0 = input.charCodeAt(i), c = ${foldExpr('c0')}`,
-        `    let t = -1`,
-        `    for (let e = st[node], z = st[node + 1]; e < z; e++) if (ch.charCodeAt(e) === c) { t = nx[e]; break }`,
-        `    if (t < 0) return 0`,
-        `    node = t`,
-        `  }`,
-        `  return ac[node]`,
-        `}`,
-      ].join('\n')
-    case 'lenswitch':
-      return [
-        `function ${n('lenswitch')}(input, from, to, lens, cix, keys, kos, kls) {`,
-        `  const len = to - from`,
-        `  for (let i = 0; i < lens.length; i++) {`,
-        `    if (lens[i] !== len) continue`,
-        `    if (${n('verify')}(input, from, to, keys, kos[i], kls[i])) return cix[i]`,
-        `  }`,
-        `  return 0`,
-        `}`,
-      ].join('\n')
-    case 'firstchar':
-      return [
-        `function ${n('firstchar')}(input, from, to, tab, cix, keys, kos, kls) {`,
-        `  const c0 = input.charCodeAt(from), c = ${foldExpr('c0')}`,
-        `  if (c > 127) return 0`,
-        `  let i = tab[c]`,
-        `  if (i === 0) return 0`,
-        `  i--`,
-        `  return ${n('verify')}(input, from, to, keys, kos[i], kls[i]) ? cix[i] : 0`,
-        `}`,
-      ].join('\n')
-    case 'phash':
-      return [
-        `function ${n('phash')}(input, from, to, p1, p2, mul, mod, tab, cix, keys, kos, kls) {`,
-        `  const len = to - from`,
-        `  let a = 0, b = 0`,
-        `  if (p1 < len) { const c = input.charCodeAt(from + p1); a = ${foldExpr('c')} }`,
-        `  if (p2 < len) { const c = input.charCodeAt(from + p2); b = ${foldExpr('c')} }`,
-        `  let i = tab[(len * mul + a * 31 + b) % mod]`,
-        `  if (i === 0) return 0`,
-        `  i--`,
-        `  return ${n('verify')}(input, from, to, keys, kos[i], kls[i]) ? cix[i] : 0`,
-        `}`,
-      ].join('\n')
-  }
-}
-
-/** Per-site emission: declarations to hoist plus the call expression. */
-export type SiteEmission = {
-  strategy: IdStrategy
-  decls: string[]
-  callExpr: string
-  helpers: SharedHelper[]
-}
-
-/** Packed key text plus offset/length/case tables, shared by every verify strategy. */
-function packKeys(prefix: string, unpack: string, flat: FlatKey[]): {
-  decls: string[]; kos: string; kls: string; cix: string; keys: string
-} {
-  let text = ''
-  const kos: number[] = []
-  const kls: number[] = []
-  const cix: number[] = []
-  for (const f of flat) {
-    kos.push(text.length)
-    kls.push(f.text.length)
-    cix.push(f.caseIndex)
-    text += f.text
-  }
-  return {
-    decls: [
-      `const ${prefix}k = ${JSON.stringify(text)}`,
-      `const ${prefix}o = ${unpack}(${packInts(kos)})`,
-      `const ${prefix}l = ${unpack}(${packInts(kls)})`,
-      `const ${prefix}x = ${unpack}(${packInts(cix)})`,
-    ],
-    keys: `${prefix}k`, kos: `${prefix}o`, kls: `${prefix}l`, cix: `${prefix}x`,
-  }
-}
-
-function emitTrie(prefix: string, unpack: string, helper: string, flat: FlatKey[], pos: string, end: string): SiteEmission | null {
-  type Node = { edges: Map<number, number>; accept: number }
-  const nodes: Node[] = [{ edges: new Map(), accept: 0 }]
-  for (const f of flat) {
-    let n = 0
-    for (let i = 0; i < f.text.length; i++) {
-      const code = f.text.charCodeAt(i)
-      let t = nodes[n]!.edges.get(code)
-      if (t === undefined) { t = nodes.length; nodes.push({ edges: new Map(), accept: 0 }); nodes[n]!.edges.set(code, t) }
-      n = t
-    }
-    if (nodes[n]!.accept !== 0 && nodes[n]!.accept !== f.caseIndex) return null
-    nodes[n]!.accept = f.caseIndex
-  }
-  const start: number[] = [0]; const char: number[] = []; const next: number[] = []; const accept: number[] = []
-  for (const nd of nodes) {
-    for (const [c, t] of [...nd.edges.entries()].sort((a, b) => a[0] - b[0])) { char.push(c); next.push(t) }
-    start.push(char.length); accept.push(nd.accept)
-  }
-  return {
-    strategy: 'trie',
-    decls: [
-      `const ${prefix}c = ${JSON.stringify(char.map(c => String.fromCharCode(c)).join(''))}`,
-      `const ${prefix}s = ${unpack}(${packInts(start)})`,
-      `const ${prefix}n = ${unpack}(${packInts(next)})`,
-      `const ${prefix}a = ${unpack}(${packInts(accept)})`,
-    ],
-    callExpr: `${helper}(input, ${pos}, ${end}, ${prefix}c, ${prefix}s, ${prefix}n, ${prefix}a)`,
-    helpers: ['unpack', 'trie'],
-  }
-}
-
-function emitLenSwitch(prefix: string, unpack: string, helper: string, flat: FlatKey[], pos: string, end: string): SiteEmission | null {
-  // Only worth it when length is close to decisive: at most one collision bucket.
-  const byLen = new Map<number, number>()
-  for (const f of flat) byLen.set(f.text.length, (byLen.get(f.text.length) ?? 0) + 1)
-  if ([...byLen.values()].filter(v => v > 1).length > 1) return null
-  const packed = packKeys(prefix, unpack, flat)
-  return {
-    strategy: 'lenswitch',
-    decls: [...packed.decls, `const ${prefix}n = ${unpack}(${packInts(flat.map(f => f.text.length))})`],
-    callExpr: `${helper}(input, ${pos}, ${end}, ${prefix}n, ${packed.cix}, ${packed.keys}, ${packed.kos}, ${packed.kls})`,
-    helpers: ['unpack', 'verify', 'lenswitch'],
-  }
-}
-
-function emitFirstChar(prefix: string, unpack: string, helper: string, flat: FlatKey[], pos: string, end: string): SiteEmission | null {
-  const tab = new Array<number>(128).fill(0)
-  for (const [i, f] of flat.entries()) {
-    const c = f.text.charCodeAt(0)
-    // Requires the key set to SEPARATE on char 0 — that is the whole premise.
-    if (c > 127 || tab[c] !== 0) return null
-    tab[c] = i + 1
-  }
-  const packed = packKeys(prefix, unpack, flat)
-  return {
-    strategy: 'firstchar',
-    decls: [...packed.decls, `const ${prefix}t = ${unpack}(${packInts(tab)})`],
-    callExpr: `${helper}(input, ${pos}, ${end}, ${prefix}t, ${packed.cix}, ${packed.keys}, ${packed.kos}, ${packed.kls})`,
-    helpers: ['unpack', 'verify', 'firstchar'],
-  }
-}
-
-/**
- * gperf-style SEARCH for an injective hash over the ACTUAL key set. A FIXED
- * discriminator provably fails — `(len,c1,c2)` collides on
- * `@counter-style`/`@color-profile` and `@font-feature-values`/
- * `@font-palette-values` — but that says nothing about a SEARCHED one, which is
- * what this does: try every character-position pair against a set of
- * multipliers and moduli and keep the first combination with no collisions.
- */
-function emitPHash(prefix: string, unpack: string, helper: string, flat: FlatKey[], pos: string, end: string): SiteEmission | null {
-  const maxLen = Math.max(...flat.map(f => f.text.length))
-  const at = (f: FlatKey, p: number): number => (p < f.text.length ? f.text.charCodeAt(p) : 0)
-  for (let p1 = 0; p1 < maxLen; p1++) {
-    for (let p2 = p1; p2 < maxLen; p2++) {
-      for (const mul of [1, 3, 7, 11, 17, 31, 53]) {
-        for (let mod = flat.length; mod <= flat.length * 6 + 16; mod++) {
-          const slots = new Array<number>(mod).fill(0)
-          let ok = true
-          for (const [i, f] of flat.entries()) {
-            const h = (f.text.length * mul + at(f, p1) * 31 + at(f, p2)) % mod
-            if (slots[h] !== 0) { ok = false; break }
-            slots[h] = i + 1
-          }
-          if (!ok) continue
-          const packed = packKeys(prefix, unpack, flat)
-          return {
-            strategy: 'phash',
-            decls: [...packed.decls, `const ${prefix}t = ${unpack}(${packInts(slots)})`],
-            callExpr: `${helper}(input, ${pos}, ${end}, ${p1}, ${p2}, ${mul}, ${mod}, ${prefix}t, ${packed.cix}, ${packed.keys}, ${packed.kos}, ${packed.kls})`,
-            helpers: ['unpack', 'verify', 'phash'],
-          }
-        }
-      }
-    }
-  }
-  return null
-}
-
 /**
- * Emit the id computation for one site. `auto` picks by KEY-SET SHAPE measured
- * at macro time rather than applying one strategy everywhere: separation on
- * char 0 is the cheapest test there is, a searched perfect hash next, then
- * length, with the trie as the always-applicable fallback.
+ * The decoder for `packInts`, emitted once per artifact under `name`.
  */
-export function emitDispatchId(
-  cases: ReadonlyArray<DispatchKeySet>,
-  cfg: DispatchConfig,
-  prefix: string,
-  helperName: (h: SharedHelper) => string,
-  pos: string,
-  end: string,
-): SiteEmission | null {
-  const flat = flatten(cases)
-  if (flat === null) return null
-  const unpack = helperName('unpack')
-  const order: IdStrategy[] = cfg.id === 'auto' ? ['firstchar', 'phash', 'lenswitch', 'trie'] : [cfg.id]
-  for (const s of order) {
-    const built =
-      s === 'trie' ? emitTrie(prefix, unpack, helperName('trie'), flat, pos, end)
-      : s === 'lenswitch' ? emitLenSwitch(prefix, unpack, helperName('lenswitch'), flat, pos, end)
-      : s === 'firstchar' ? emitFirstChar(prefix, unpack, helperName('firstchar'), flat, pos, end)
-      : emitPHash(prefix, unpack, helperName('phash'), flat, pos, end)
-    if (built !== null) return built
-  }
-  return null
+export function unpackHelperDecl(name: string): string {
+  return `const ${name} = s => { const o = new Int32Array(s.length >> 1); for (let i = 0; i < o.length; i++) o[i] = (s.charCodeAt(i * 2) - 35) | ((s.charCodeAt(i * 2 + 1) - 35) << 6); return o }`
 }

package/src/compiler/token-scanner.ts

@@ -35,7 +35,7 @@
 import type { Alphabet } from './token-alphabet.ts'
 import { TOK_EOF, TOK_UNKNOWN, TOK_WS } from './token-alphabet.ts'
 import { firstSetFromRegex } from '../regex/first-set.ts'
-import { packInts, sharedHelperDecl } from './token-dispatch.ts'
+import { packInts, unpackHelperDecl } from './token-dispatch.ts'
 import { foldCode, foldExpr } from './token-dispatch.ts'
 
 /**
@@ -193,7 +193,7 @@ export function emitScanner(alphabet: Alphabet, ns: string): ScannerEmission {
   // two halves of one encoding still lived in two files. They agree today — the
   // point is that widening the encoding (which the `RangeError` tells you to do)
   // must not be able to change one half and miss the other.
-  decls.push(sharedHelperDecl('unpack', () => p('_tkUnpack')))
+  decls.push(unpackHelperDecl(p('_tkUnpack')))
   decls.push(`const ${p('_tkNext_')} = ${p('_tkUnpack')}(${packInts(NEXT)})`)
   decls.push(`const ${p('_tkStart')} = ${p('_tkUnpack')}(${packInts(START)})`)
   decls.push(`const ${p('_tkAccept')} = ${p('_tkUnpack')}(${packInts(ACCEPT)})`)

package/src/cst/capture-buffer.ts

@@ -1,5 +1,6 @@
 import type { ParseContext, Span } from '../types.ts'
-import { annotateSpanFromLineContext } from '../line-index.ts'
+import { annotateSpanFromLineContext, lineSpanFromContext } from '../line-index.ts'
+import { PlainBuf, PlainLeaf } from './plain.js'
 
 /** Lazy per-node capture state — arrays materialized on first push. */
 export type CstCaptureBuf = {
@@ -42,7 +43,7 @@ export function beginCstNodeCapture(ctx: ParseContext): CstNodeCaptureSaved {
     cap: ctx.captureTrivia,
     buf: ctx._cstBuf,
   }
-  ctx._cstBuf = {}
+  ctx._cstBuf = new PlainBuf(undefined, undefined, 0)
   ctx._cstChildren = undefined
   ctx._cstLeaves = undefined
   ctx._cstRawChildren = undefined
@@ -79,14 +80,21 @@ export function endCstNodeCapture(
   return materialized
 }
 
+/** Every caller passes a leaf `{ _tag, value, span }` (parseman's own terminals; this is not public API). */
+function isLeaf(v: unknown): v is { _tag: 'leaf'; value: unknown; span: Span } {
+  return typeof v === 'object' && v !== null && (v as { _tag?: unknown })._tag === 'leaf'
+}
+
 export function pushCstLeaf(ctx: ParseContext, leaf: unknown): void {
   if (!ctx.trackLines) {
     pushCstChild(ctx, leaf, leaf)
     return
   }
-  const annotated = leaf && typeof leaf === 'object' && (leaf as { span?: unknown }).span
-    ? { ...(leaf as Record<string, unknown>), span: annotateSpanFromLineContext((leaf as { span: Span }).span, ctx) }
-    : leaf
+  const annotated = isLeaf(leaf)
+    ? new PlainLeaf(leaf.value, lineSpanFromContext(leaf.span, ctx))
+    : leaf && typeof leaf === 'object' && (leaf as { span?: unknown }).span
+      ? { ...(leaf as Record<string, unknown>), span: annotateSpanFromLineContext((leaf as { span: Span }).span, ctx) }
+      : leaf
   pushCstChild(ctx, annotated, annotated)
 }
 

package/src/cst/plain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The objects a parse keeps until it ends — spans, leaves, default nodes, field
+ * captures, capture buffers — built by `new` calls instead of object literals.
+ *
+ * WHY. V8 keeps an allocation site per object literal and decides, per site, whether to
+ * allocate straight into old space (pretenuring). The decision is taken during warm-up
+ * from where scavenges happen to fall, so identical processes split into a fast and a
+ * slow mode, and any change in bundle layout re-rolls it: on Node 26 a pretenured
+ * process ran 34–61 mark-compacts per run where a fast one ran 1. A `new` call has no
+ * allocation site, so these objects are never pretenured. Each constructor's
+ * `prototype` is `Object.prototype`, so what it builds is a plain object: same
+ * prototype, same `constructor`, same keys in the same order as the literal it replaces.
+ *
+ * ONE MODULE. Every constructor defines its own hidden class, so two copies of this
+ * module build two maps for the same shape, and every site that reads both turns
+ * polymorphic. The build therefore emits it once (`dist/cst/plain.js`) and every public
+ * entry imports that file (`scripts/build.mjs`). The emitted engine receives the same
+ * functions as factory parameters (`EMITTED_PARAMS`).
+ */
+import type { Span } from '../types.ts'
+import type { CstCaptureBuf } from './capture-buffer.ts'
+
+export type PlainLeafObject = { _tag: 'leaf'; value: unknown; span: Span }
+export type PlainNodeObject = { _tag: 'node'; type: string; span: Span; state: unknown; children: unknown[] }
+export type PlainFieldObject = { name: string; value: unknown; span: Span }
+
+export declare const PlainSpan: new (start: number, end: number) => Span
+export declare const PlainLeaf: new (value: unknown, span: Span) => PlainLeafObject
+export type PlainLineSpanObject = { start: number; end: number; startLine: number; startColumn: number; endLine: number; endColumn: number }
+export declare const PlainLineSpan: new (start: number, end: number, startLine: number, startColumn: number, endLine: number, endColumn: number) => PlainLineSpanObject
+export declare const PlainTaggedNode: new (type: string, tags: readonly string[], span: Span, state: unknown, children: unknown[]) => { _tag: 'node'; type: string; tags: readonly string[]; span: Span; state: unknown; children: unknown[] }
+export declare const PlainTriviaField: new (name: string, value: unknown, span: Span, leading: string, trailing: string) => { name: string; value: unknown; span: Span; leading: string; trailing: string }
+export declare const PlainNode: new (type: string, span: Span, state: unknown, children: unknown[]) => PlainNodeObject
+export declare const PlainField: new (name: string, value: unknown, span: Span) => PlainFieldObject
+export declare const PlainBuf: new (rawOnly: true | undefined, noRaw: true | undefined, rawLen: number) => CstCaptureBuf

package/src/cst/plain.js

@@ -0,0 +1,74 @@
+// Constructors for the objects a parse keeps until it ends. Plain JavaScript on
+// purpose: a function constructor whose `prototype` is `Object.prototype` is the only
+// spelling that builds a plain object with a `new` call, and TypeScript cannot declare
+// one in a `.ts` file without a cast. `plain.d.ts` types them. Why constructors at all,
+// and why this is ONE module shared by every bundle: see `plain.d.ts`.
+
+export function PlainSpan(start, end) {
+  this.start = start
+  this.end = end
+}
+
+export function PlainLeaf(value, span) {
+  this._tag = 'leaf'
+  this.value = value
+  this.span = span
+}
+
+export function PlainLineSpan(start, end, startLine, startColumn, endLine, endColumn) {
+  this.start = start
+  this.end = end
+  this.startLine = startLine
+  this.startColumn = startColumn
+  this.endLine = endLine
+  this.endColumn = endColumn
+}
+
+export function PlainNode(type, span, state, children) {
+  this._tag = 'node'
+  this.type = type
+  this.span = span
+  this.state = state
+  this.children = children
+}
+
+export function PlainTaggedNode(type, tags, span, state, children) {
+  this._tag = 'node'
+  this.type = type
+  this.tags = tags
+  this.span = span
+  this.state = state
+  this.children = children
+}
+
+export function PlainField(name, value, span) {
+  this.name = name
+  this.value = value
+  this.span = span
+}
+
+export function PlainTriviaField(name, value, span, leading, trailing) {
+  this.name = name
+  this.value = value
+  this.span = span
+  this.leading = leading
+  this.trailing = trailing
+}
+
+// Every field assigned, so the three buffer kinds share one shape. `rawLen` is always a
+// count: a field that held `undefined` in most buffers and a number in some would
+// generalize and deoptimize the pushes that read it.
+export function PlainBuf(rawOnly, noRaw, rawLen) {
+  this.rawOnly = rawOnly
+  this.noRaw = noRaw
+  this.rawLen = rawLen
+  this.single = undefined
+  this.ch = undefined
+  this.rawSingle = undefined
+  this.raw = undefined
+  this.tl = undefined
+}
+
+for (const f of [PlainSpan, PlainLineSpan, PlainLeaf, PlainNode, PlainTaggedNode, PlainField, PlainTriviaField, PlainBuf]) {
+  f.prototype = Object.prototype
+}

package/src/cst/root-trivia-scope.ts

@@ -14,7 +14,7 @@
 
 /** The message `parser()` raises for an unclassified local scope. Exported so the
  *  three engines cannot drift a word apart. */
-export const ROOT_TRIVIA_SCOPE_REFUSAL
+const ROOT_TRIVIA_SCOPE_REFUSAL
   = 'parser(): selected root trivia requires classifiedTrivia() for every local trivia scope, or rootCapture: \'opaque\'.'
 
 /**

package/src/cst/trivia-entries.ts

@@ -61,7 +61,7 @@ export type RootTriviaIndex = {
 const EMPTY_INDICES: readonly number[] = Object.freeze([])
 const EMPTY_GAPS: readonly RootTriviaGap[] = Object.freeze([])
 /** Number of packed fields in one selected-root trivia row. */
-export const SELECTED_ROOT_STRIDE = 5
+const SELECTED_ROOT_STRIDE = 5
 
 type RootTriviaMaps = {
   before: Map<number, number[]>

package/src/cst/trivia-kinds.ts

@@ -60,7 +60,7 @@ function unwrapTrivia(p: Combinator<unknown>): Combinator<unknown> {
 }
 
 /** Strip `label()` wrapper; returns inner parser for matching. */
-export function peelLabel(p: Combinator<unknown>): { label: string; parser: Combinator<unknown> } | null {
+function peelLabel(p: Combinator<unknown>): { label: string; parser: Combinator<unknown> } | null {
   if (p._def.tag === 'label') return { label: p._def.label, parser: p._def.parser }
   return null
 }

package/src/line-index.ts

@@ -1,4 +1,5 @@
 import type { Span } from './types.ts'
+import { PlainLineSpan, PlainSpan } from './cst/plain.js'
 
 /**
  * Precomputed index of newline positions for O(log n) offset->line/col lookup.
@@ -98,6 +99,42 @@ export function annotateSpan(span: Span, index: LineIndex): Span {
   }
 }
 
+const SPAN_KEYS = ['start', 'end', 'startLine', 'startColumn', 'endLine', 'endColumn'] as const
+
+/**
+ * A copy of a span, exactly as given: the same keys in the same order. The two shapes
+ * parseman builds itself, `{ start, end }` and the six-key line span, are rebuilt by their
+ * constructors (`src/cst/plain.d.ts`); any other shape a caller passes (an extra key, a
+ * different order, a partial line span) is spread, as before.
+ */
+export function copySpan(span: Span): Span {
+  // `for…in` walks the keys in order without allocating a key list.
+  let n = 0
+  for (const key in span) {
+    if (key !== SPAN_KEYS[n]) return { ...span }
+    n++
+  }
+  if (n === 2) return new PlainSpan(span.start, span.end)
+  if (n === 6 && span.startLine !== undefined && span.startColumn !== undefined && span.endLine !== undefined && span.endColumn !== undefined) {
+    return new PlainLineSpan(span.start, span.end, span.startLine, span.startColumn, span.endLine, span.endColumn)
+  }
+  return { ...span }
+}
+
+/**
+ * `annotateSpanFromLineContext` for a span parseman built itself (`{ start, end }` only),
+ * returning a constructor-built line span (`src/cst/plain.d.ts`). The public form keeps
+ * any extra keys a caller's span carries, so it spreads.
+ */
+export function lineSpanFromContext(span: Span, ctx: LineTrackingContext): Span {
+  if (!ctx.trackLines) return span
+  const index = ctx._lineIndex ?? (ctx._lineStarts ? { lineStarts: ctx._lineStarts } : undefined)
+  if (!index) return span
+  const s = offsetToLineCol(index, span.start)
+  const e = offsetToLineCol(index, span.end)
+  return new PlainLineSpan(span.start, span.end, s.line, s.col, e.line, e.col)
+}
+
 export function annotateSpanFromLineContext(
   span: Span,
   ctx: LineTrackingContext,

package/src/plugin/entry-supercompiler.ts

@@ -12,6 +12,7 @@ import { OP_ATTEMPT, OP_NODE, OP_NODE_TRACK, OP_REPV, OP_SCAN } from '../table/o
 import { emitAssemblySource, type EmitResult } from '../table/emit-assembly.ts'
 import { defaultAssemblyCfgs } from '../table/emit.ts'
 import { assemblyExtraIps, resolveTable, type TableProgram } from '../table/program.ts'
+import { FACTORY_ARITY_GUARD } from '../table/emit.ts'
 
 type Ast = { type: string; start?: number; end?: number; [key: string]: unknown }
 
@@ -271,8 +272,8 @@ export function supercompileRuleMapReplacement(
   if (typeof body.start !== 'number' || typeof body.end !== 'number') return replacement
   const start = body.start - prefix.length + 1
   const end = body.end - prefix.length - 1
-  if (replacement.slice(start, end) !== canonical.source + '\n') return replacement
-  const transformed = replacement.slice(0, start) + candidate.source + '\n' + replacement.slice(end)
+  if (replacement.slice(start, end) !== FACTORY_ARITY_GUARD + canonical.source + '\n') return replacement
+  const transformed = replacement.slice(0, start) + FACTORY_ARITY_GUARD + candidate.source + '\n' + replacement.slice(end)
   const checked = parseSync('parseman-entry-supercompile-replacement-result.js', prefix + transformed)
   return checked.errors.length === 0 ? transformed : replacement
 }

package/src/recovery/scan.ts

@@ -2,6 +2,7 @@ import type { Combinator, FirstSet, ParseContext, ParseError, ParseResult, Recov
 import { cstCaptureActive, pushCstChild } from '../cst/capture-buffer.ts'
 import { rangesHaveLead } from '../lead-ranges.ts'
 import { annotateSpanFromLineContext, recordLineRangeFromContext } from '../line-index.ts'
+import { PlainSpan } from '../cst/plain.js'
 
 /**
  * Recovery MECHANISM — sync-source-agnostic. These primitives implement "scan
@@ -112,7 +113,7 @@ export function recoverScan(
 ): { error: ParseError; end: number } {
   let scanPos = from
   while (scanPos < input.length && !probeAt(sync, input, scanPos, ctx)) scanPos++
-  const span = { start: from, end: scanPos }
+  const span = new PlainSpan(from, scanPos)
   if (ctx.trackLines) recordLineRangeFromContext(ctx, input, from, scanPos)
   const error: ParseError = { _tag: 'parseError', span: ctx.trackLines ? annotateSpanFromLineContext(span, ctx) : span, expected }
   ctx._errors?.push(error)

package/src/spec/model.ts

@@ -247,7 +247,7 @@ function fixedString(alt: string): string | undefined {
  * boundary (`word()` / `keywords()` and every hand-written copy of them), and a
  * `\b…\b`-anchored word.
  */
-export function fixedStringsOfRegex(source: string): string[] | undefined {
+function fixedStringsOfRegex(source: string): string[] | undefined {
   let src = source
   // `\b` anchors assert a boundary, exactly like the `(?![…])` guard.
   if (src.startsWith('\\b')) src = src.slice(2)