parseman 0.48.1 → 0.50.0

package/src/table/emit.ts

@@ -208,7 +208,7 @@ function emitAssemblies(prog: TableProgram, cfgs: readonly RunCfg[]): string[] {
     seen.add(key)
     let em
     try {
-      em = emitAssemblySource(t, prog, cfg, extraIps)
+      em = emitAssemblySource(t, prog, cfg, extraIps, true)
     } catch (e) {
       if (e instanceof Unemittable) continue
       throw e

package/src/table/encode.ts

@@ -1,6 +1,7 @@
 import type { AutoNotCheck, Combinator, FirstSet, ParserDef } from '../types.ts'
-import { classifyFinalChoice, firstSetOf, matchesEmpty, union, type RefResolver } from '../combinators/first-set.ts'
+import { classifyFinalChoice, firstSetOf, intersects, matchesEmpty, union, type RefResolver } from '../combinators/first-set.ts'
 import { childrenOf } from '../analysis/gating.ts'
+import { capturesLeaf, mayCommitFailure, mayLeavePartialCapture } from '../analysis/commitment.ts'
 import { getCoreLiteralValue } from '../combinators/choice.ts'
 import { deriveExpected } from '../combinators/expect.ts'
 import { assertionFailureExpected, directTerminalFailureExpected } from '../combinators/expected.ts'
@@ -33,7 +34,7 @@ import { covKindCode, encodeClassSpec, ownTableProgram } from './program.ts'
 import type { GrammarCoveragePlan } from '../compiler/grammar-coverage-ids.ts'
 import { directArrayProjection } from '../compiler/direct-projection.ts'
 import {
-  assertLexicalCapabilityClosure, collectLexicalCapabilities, winnerWrapsReference,
+  collectLexicalCapabilities, winnerWrapsReference,
 } from '../compiler/token-capability.ts'
 import { directExecutableTokenBody, type ExecutableLexNode } from '../compiler/token-alphabet.ts'
 
@@ -141,6 +142,9 @@ class Encoder {
   private lexIndex = new Map<string, number>()
   lexPrograms: LexProgramSpec[] = []
   private lexProgramIndex = new Map<string, number>()
+  private choiceRollbackMasks = new Map<number, number>()
+  private nonCommittingChoiceSites = new Set<number>()
+  private failureRollbackCleanSites = new Set<number>()
   labels: readonly string[] | undefined = undefined
   /** Trivia table in scope at the row being encoded — codegen's `ctx.activeTrivia`. */
   activeTrivia: Combinator<unknown> | undefined = undefined
@@ -611,6 +615,77 @@ class Encoder {
     return w === undefined ? undefined : (name: string) => w[name]
   }
 
+  /**
+   * Whether a failed ordered-choice arm can leave state that the enclosing
+   * choice must restore before trying its successor.
+   *
+   * `mayLeavePartialCapture` is the existing sound CST/trivia proof. The extra
+   * writer census covers the side sinks that proof deliberately does not model:
+   * fields, recovered errors, and interpreted scanners. Strict assemblies do
+   * not run repeat recovery, but these rows can still publish through a caller's
+   * context. Cycles are safe to stop: revisiting the same combinator cannot
+   * discover a writer the first traversal did not already reach.
+   */
+  private failureNeedsRollback(
+    p: Combinator<unknown>,
+    autoNot: readonly AutoNotCheck[] | null | undefined,
+  ): boolean {
+    const refName = (p as unknown as { _ruleName?: string })._ruleName
+    const winner = refName === undefined ? undefined : this.winners?.[refName]
+    const root = winner !== undefined && !winnerWrapsReference(winner, p) ? winner : p
+    const sideWriterMemo = new Map<Combinator<unknown>, boolean>()
+    const hasSideWriter = (
+      current: Combinator<unknown>,
+      seen = new Set<Combinator<unknown>>(),
+    ): { found: boolean; complete: boolean } => {
+      const cached = sideWriterMemo.get(current)
+      if (cached !== undefined) return { found: cached, complete: true }
+      if (seen.has(current)) return { found: false, complete: false }
+      const next = new Set(seen)
+      next.add(current)
+      const def = current._def
+      let result: { found: boolean; complete: boolean }
+      switch (def.tag) {
+        case 'field':
+        case 'expect':
+        case 'recover':
+        case 'scanTo':
+        case 'unknown':
+          result = { found: true, complete: true }
+          break
+        case 'lazy': {
+          const name = (current as unknown as { _ruleName?: string })._ruleName
+          const resolvedWinner = name === undefined ? undefined : this.winners?.[name]
+          if (resolvedWinner !== undefined && !winnerWrapsReference(resolvedWinner, current)) {
+            result = hasSideWriter(resolvedWinner, next)
+            break
+          }
+          try { result = hasSideWriter(def.thunk(), next) }
+          catch { result = { found: true, complete: true } }
+          break
+        }
+        default: {
+          let complete = true
+          result = { found: false, complete: true }
+          for (const child of childrenOf(def)) {
+            const childResult = hasSideWriter(child, next)
+            if (childResult.found) {
+              result = { found: true, complete: true }
+              break
+            }
+            complete &&= childResult.complete
+          }
+          if (!result.found) result = { found: false, complete }
+        }
+      }
+      if (result.found || result.complete) sideWriterMemo.set(current, result.found)
+      return result
+    }
+    return mayLeavePartialCapture(root, new Set(), true)
+      || hasSideWriter(root).found
+      || ((autoNot?.length ?? 0) > 0 && capturesLeaf(root))
+  }
+
   /** A first set becomes a char class string, or −1 for `any`. */
   private charClass(fs: FirstSet): number {
     if (fs.kind !== 'ranges' || fs.ranges.length === 0) return -1
@@ -1074,14 +1149,53 @@ class Encoder {
         // Arm ORDER is preserved on both, which is what makes this a PEG-safe
         // change rather than a reordering.
         const finalChoice = classifyFinalChoice(arms, rr)
-        const classes = arms.map((_, i) => finalChoice.nullable[i]
-          ? -1 : this.charClass(finalChoice.firstSets[i]!))
+        // attempt() preserves its child's success language, but the broad
+        // classifier deliberately treats the transaction as nullable/unknown so
+        // it can never by itself authorize exclusive one-arm selection. Recover
+        // only the narrower fact needed by an ORDERED choice: a non-nullable
+        // child can receive an individual rejection gate. Keep that authority
+        // out if it would make an otherwise open site fully disjoint, preserving
+        // the transaction's standing exclusion from exclusive dispatch.
+        const transactionalFirst = arms.map((arm, i): FirstSet | undefined => {
+          if (!finalChoice.nullable[i]) return undefined
+          const def = arm._def as ParserDef
+          if (def.tag !== 'attempt' || matchesEmpty(def.parser, new Set(), rr)) return undefined
+          return firstSetOf(def.parser, new Set(), rr)
+        })
+        const gateFirst = finalChoice.firstSets.map((first, i) => transactionalFirst[i] ?? first)
+        const classes = gateFirst.map((first, i) => finalChoice.nullable[i] && transactionalFirst[i] === undefined
+          ? -1 : this.charClass(first))
+        if (transactionalFirst.some(first => first !== undefined) && classes.every(cls => cls >= 0)) {
+          let overlap = false
+          for (let i = 0; i < gateFirst.length && !overlap; i++) {
+            for (let j = i + 1; j < gateFirst.length; j++) {
+              if (intersects(gateFirst[i]!, gateFirst[j]!)) { overlap = true; break }
+            }
+          }
+          if (!overlap) for (let i = 0; i < classes.length; i++) {
+            if (transactionalFirst[i] !== undefined) classes[i] = -1
+          }
+        }
         const dispIdx = this.disp.length
         this.disp.push(classes)
         // PER-ARM EXPECTED SETS RIDE ALONG, after the arm offsets. While the best
         // failure remains at the choice position, an arm declined by the driver's
         // char gate contributes the static opener set the interpreter would get by
         // entering it. A deeper dynamic arm failure discards those shallower sets.
+        // One compiler-only bit mask records which failed arms can actually
+        // dirty a rollback sink. It is consumed while printing emitted strict
+        // assemblies and never serialized; tolerant assemblies retain the
+        // universal rollback because repeat recovery can publish an error from
+        // inside any arm. Arity >31 falls back to -1 rather than truncating.
+        let rollbackMask = kids.length > 31 ? -1 : 0
+        if (rollbackMask === 0) {
+          for (let i = 0; i < arms.length; i++) {
+            const src = order[i]!
+            if (this.failureNeedsRollback(arms[i]!, d.autoNot[src])) {
+              rollbackMask |= 1 << i
+            }
+          }
+        }
         const head = this.emitHead(OP_CHOICE, 3 + 2 * kids.length)
         this.code[head + 1] = dispIdx
         this.code[head + 2] = kids.length
@@ -1093,6 +1207,10 @@ class Encoder {
           this.code[head + 4 + i] = kids[i]!
           this.code[head + 4 + kids.length + i] = this.expected(deriveExpected(arms[i]!))
         }
+        this.choiceRollbackMasks.set(head, rollbackMask)
+        if (arms.every(arm => !mayCommitFailure(arm, new Set(), rr))) {
+          this.nonCommittingChoiceSites.add(head)
+        }
         return head
       }
       case 'many':
@@ -1143,8 +1261,11 @@ class Encoder {
           ? this.emit(OP_REP, child, d.min, d.max ?? -1, sep, flags, this.expected(deriveExpected(d.parser)))
           : this.emit(OP_REP, child, d.min, d.max ?? -1, sep, flags)
       }
-      case 'optional':
-        return this.emit(OP_OPT, this.node(d.parser).ip)
+      case 'optional': {
+        const head = this.emit(OP_OPT, this.node(d.parser).ip)
+        if (!this.failureNeedsRollback(d.parser, undefined)) this.failureRollbackCleanSites.add(head)
+        return head
+      }
       case 'transform': {
         // Declared on the def and not lowered here. Refuse rather than assume it is
         // inert: a recognition-only transform suppresses its value, and a table that
@@ -1444,6 +1565,7 @@ class Encoder {
       // lowering was correct only for a choice arm.
       case 'attempt': {
         const inner = this.emit(OP_ATTEMPT, this.node(d.parser).ip)
+        if (!this.failureNeedsRollback(d.parser, undefined)) this.failureRollbackCleanSites.add(inner)
         // THE FIRST-SET FAIL-FAST GUARD, lowered as the `OP_GATE` row the `node()`
         // case already uses — it is the same guard, written twice in the
         // interpreter (`attempt.ts:22`, `node.ts:239`). It is NOT merely an
@@ -1652,6 +1774,10 @@ class Encoder {
       ...(this.rec ? { rec: 1 as const } : {}),
       ...(this.cov === undefined ? {} : { cov: this.cov }),
       lines: this.track ? 1 : 0,
+    }, undefined, {
+      choiceRollbackMasks: this.choiceRollbackMasks,
+      failureRollbackCleanSites: this.failureRollbackCleanSites,
+      nonCommittingChoiceSites: this.nonCommittingChoiceSites,
     })
   }
 }
@@ -1748,7 +1874,6 @@ export function encodeTableProgram(
   const lexicalRoots = [...names].sort().map(name => ruleMap[name]!)
   const resolveLexical = (name: string): Combinator<unknown> | undefined => ruleMap[name]
   const capabilities = collectLexicalCapabilities(lexicalRoots, resolveLexical)
-  assertLexicalCapabilityClosure(lexicalRoots, capabilities, resolveLexical)
   const enc = new Encoder(resolvedSettings, capabilities.capabilityComplete)
   enc.winners = ruleMap
   for (const name of names) enc.encodeRule(name, ruleMap[name]!)

package/src/table/ops.ts

@@ -27,8 +27,9 @@ export const OP_SEQ = 3
 /** `SEQV n c1 … cn` — `SEQ` with `valueUnused`: terms run, no tuple is built. */
 export const OP_SEQV = 4
 /**
- * `CHOICE d n fx c1 … cn` — `d` indexes a dispatch table (or −1 for ordered
- * try); `fx` indexes the choice's OWN expected set.
+ * `CHOICE d n fx c1 … cn e1 … en` — `d` indexes a dispatch table (or −1 for
+ * ordered try); `fx` indexes the choice's OWN expected set and each `e` is one
+ * arm's set. Compiler-only rollback authority is deliberately not on the wire.
  *
  * Ordered failure keeps the expected sets at the deepest arm offset, merging
  * exact ties in source order. Exclusive dispatch propagates its sole selected

package/src/table/program.ts

@@ -490,12 +490,53 @@ export type ResolvedTable = {
  */
 const TABLE_RUNTIME = Symbol('parseman.tableRuntime')
 type RuntimeTableProgram = TableProgram & {
-  readonly [TABLE_RUNTIME]?: { resolved: ResolvedTable | undefined }
+  readonly [TABLE_RUNTIME]?: {
+    resolved: ResolvedTable | undefined
+    readonly choiceRollbackMasks?: ReadonlyMap<number, number>
+    readonly nonCommittingChoiceSites?: ReadonlySet<number>
+    readonly failureRollbackCleanSites?: ReadonlySet<number>
+  }
 }
 
 /** Give an internally-created program its fixed-shape runtime owner. */
-export function ownTableProgram(prog: TableProgram, resolved?: ResolvedTable): TableProgram {
-  return { ...prog, [TABLE_RUNTIME]: { resolved } } as RuntimeTableProgram
+export function ownTableProgram(
+  prog: TableProgram,
+  resolved?: ResolvedTable,
+  caches: {
+    readonly choiceRollbackMasks?: ReadonlyMap<number, number>
+    readonly failureRollbackCleanSites?: ReadonlySet<number>
+    readonly nonCommittingChoiceSites?: ReadonlySet<number>
+  } = {},
+): TableProgram {
+  const runtime = (prog as RuntimeTableProgram)[TABLE_RUNTIME]
+  return {
+    ...prog,
+    [TABLE_RUNTIME]: {
+      resolved,
+      choiceRollbackMasks: caches.choiceRollbackMasks ?? runtime?.choiceRollbackMasks,
+      nonCommittingChoiceSites: caches.nonCommittingChoiceSites ?? runtime?.nonCommittingChoiceSites,
+      failureRollbackCleanSites: caches.failureRollbackCleanSites ?? runtime?.failureRollbackCleanSites,
+    },
+  } as RuntimeTableProgram
+}
+
+/** Compiler-only choice rollback authority, consumed while printing a static
+ * assembly and never serialized into the shipped table. */
+export function choiceRollbackMask(prog: TableProgram, ip: number): number | undefined {
+  return (prog as RuntimeTableProgram)[TABLE_RUNTIME]?.choiceRollbackMasks?.get(ip)
+}
+
+/** Compiler-only proof that no arm at this choice can raise a committed
+ * failure. Static assembly may defer its diagnostic merge until total failure. */
+export function choiceCannotCommit(prog: TableProgram, ip: number): boolean {
+  return (prog as RuntimeTableProgram)[TABLE_RUNTIME]?.nonCommittingChoiceSites?.has(ip) === true
+}
+
+/** Compiler-only authority that a failed transactional child cannot leak any
+ * capture, trivia, field, or error sink. Static assembly consumes it to omit the
+ * enclosing mark and rollback; it is never serialized into the shipped table. */
+export function failureRollbackClean(prog: TableProgram, ip: number): boolean {
+  return (prog as RuntimeTableProgram)[TABLE_RUNTIME]?.failureRollbackCleanSites?.has(ip) === true
 }
 
 /** A compiled entry, shaped exactly like a codegen rule function. */

package/src/table/scalar-terminal.ts

@@ -1,4 +1,8 @@
-import { OP_LIT, OP_NOT, OP_RX } from './ops.ts'
+import {
+  OP_ATTEMPT, OP_CHOICE, OP_FIELD, OP_GATE, OP_LABEL, OP_LEAF, OP_LIT, OP_NODE, OP_NOT,
+  OP_PEEK, OP_RULE, OP_RX, OP_SCOPE, OP_SCOPE_CAP, OP_SCOPE_PLAIN, OP_SEQ, OP_SEQV,
+  OP_SEQX, OP_TOKEN, OP_XFORM,
+} from './ops.ts'
 
 /** Pure recognition only. Consumption owns value, CST, line, failure and cursor effects. */
 export type ScalarRecognizer = (input: string, pos: number, seed?: number) => number
@@ -49,3 +53,211 @@ export function scalarTerminalNotChild(code: ArrayLike<number>, ip: number): num
   const op = code[child]
   return op === OP_RX || op === OP_LIT ? child : -1
 }
+
+/**
+ * A direct scalar terminal that every successful execution of `ip` must match
+ * first, through wrappers that cannot consume or select before their child.
+ * Returns only after `minDepth` edges so a caller never duplicates recognition
+ * merely to avoid one already-cheap terminal call.
+ */
+export function leadingScalarTerminal(
+  code: ArrayLike<number>, ip: number, minDepth = 2, throughAttempt = true, throughPeek = false,
+): number {
+  const seen = new Set<number>()
+  let at = ip
+  let depth = 0
+  while (!seen.has(at)) {
+    seen.add(at)
+    const op = code[at]
+    if (op === OP_LIT || op === OP_RX) return depth >= minDepth ? at : -1
+    if (op === OP_RULE || op === OP_LABEL || op === OP_TOKEN || (throughAttempt && op === OP_ATTEMPT)) {
+      at = code[at + 1]!
+      depth++
+      continue
+    }
+    // A positive lookahead has exactly its child's success language and no
+    // effects on success. Choice predecisions may therefore execute a scalar
+    // child to reject the enclosing arm early. This is opt-in because callers
+    // that require a CONSUMING opener (notably exact start-failure diagnostics)
+    // must continue to treat peek() as zero-width.
+    if (throughPeek && op === OP_PEEK) {
+      at = code[at + 1]!
+      depth++
+      continue
+    }
+    if (op === OP_GATE || op === OP_SCOPE || op === OP_SCOPE_CAP || op === OP_SCOPE_PLAIN
+      || op === OP_XFORM || op === OP_NODE || op === OP_FIELD || op === OP_LEAF) {
+      at = code[at + 2]!
+      depth++
+      continue
+    }
+    if (op === OP_SEQ || op === OP_SEQV) {
+      if (code[at + 1]! < 1) return -1
+      at = code[at + 2]!
+      depth++
+      continue
+    }
+    if (op === OP_SEQX) {
+      if (code[at + 2]! < 1) return -1
+      at = code[at + 3]!
+      depth++
+      continue
+    }
+    return -1
+  }
+  return -1
+}
+
+export type LeadingScalarSequence = {
+  readonly terminals: readonly number[]
+  /** The explicit ambient trivia slot between terms; -1 means no trivia. */
+  readonly trivia: number
+}
+
+/**
+ * The first three complete scalar terms of a sequence under an explicit trivia
+ * scope. Unlike `leadingScalarTerminal`, each returned terminal is the WHOLE
+ * corresponding sequence term: recognizing it therefore identifies the exact
+ * position at which the enclosing sequence would scan trivia for the next one.
+ *
+ * This is rejection authority only. Gates, attempts, transforms and builders
+ * may still make the arm fail after the prefix matched, so callers must enter
+ * the ordinary arm on a positive result and may only skip it on a miss.
+ */
+export function leadingScalarSequence(
+  code: ArrayLike<number>, ip: number,
+): LeadingScalarSequence | undefined {
+  const wholeScalar = (start: number): number => {
+    const seen = new Set<number>()
+    let at = start
+    while (!seen.has(at)) {
+      seen.add(at)
+      const op = code[at]
+      if (op === OP_LIT || op === OP_RX) return at
+      if (op === OP_RULE || op === OP_TOKEN || op === OP_ATTEMPT) {
+        at = code[at + 1]!
+        continue
+      }
+      if (op === OP_GATE || op === OP_SCOPE_PLAIN
+        || op === OP_XFORM || op === OP_NODE || op === OP_FIELD || op === OP_LEAF) {
+        at = code[at + 2]!
+        continue
+      }
+      if (op === OP_SEQ || op === OP_SEQV) {
+        if (code[at + 1] !== 1) return -1
+        at = code[at + 2]!
+        continue
+      }
+      if (op === OP_SEQX) {
+        if (code[at + 2] !== 1) return -1
+        at = code[at + 3]!
+        continue
+      }
+      return -1
+    }
+    return -1
+  }
+
+  const seen = new Set<number>()
+  let at = ip
+  let ambientTrivia: number | undefined
+  while (!seen.has(at)) {
+    seen.add(at)
+    const op = code[at]
+    if (op === OP_RULE) {
+      at = code[at + 1]!
+      continue
+    }
+    if (op === OP_SCOPE_PLAIN) {
+      ambientTrivia = code[at + 1]!
+      at = code[at + 2]!
+      continue
+    }
+    if (op === OP_GATE || op === OP_XFORM || op === OP_NODE || op === OP_FIELD || op === OP_LEAF) {
+      at = code[at + 2]!
+      continue
+    }
+
+    const n = op === OP_SEQ || op === OP_SEQV
+      ? code[at + 1]!
+      : op === OP_SEQX ? code[at + 2]! : 0
+    if (n < 3 || ambientTrivia === undefined) return undefined
+    const base = op === OP_SEQX ? at + 3 : at + 2
+    const terminals = [
+      wholeScalar(code[base]!),
+      wholeScalar(code[base + 1]!),
+      wholeScalar(code[base + 2]!),
+    ]
+    return terminals.every(terminal => terminal >= 0)
+      ? { terminals, trivia: ambientTrivia }
+      : undefined
+  }
+  return undefined
+}
+
+/**
+ * A bounded union of literal prefixes that every successful execution of `ip`
+ * must enter through. Unlike `leadingScalarTerminal`, this may cross nested
+ * choices, but only when EVERY arm yields literal authority. Longer literals
+ * covered by a shorter prefix are removed (`@{-}` is already covered by `@{`).
+ */
+export function leadingLiteralFamily(
+  code: ArrayLike<number>, constants: readonly unknown[], ip: number,
+  minDepth = 2, limit = 4,
+): readonly number[] | undefined {
+  const active = new Set<number>()
+
+  const walk = (at: number, depth: number): number[] | undefined => {
+    if (active.has(at)) return undefined
+    active.add(at)
+    try {
+      const op = code[at]
+      if (op === OP_LIT) {
+        const value = constants[code[at + 1]!]
+        return depth >= minDepth && typeof value === 'string' && value.length > 0 ? [at] : undefined
+      }
+      if (op === OP_RULE || op === OP_LABEL || op === OP_TOKEN || op === OP_ATTEMPT || op === OP_PEEK) {
+        return walk(code[at + 1]!, depth + 1)
+      }
+      if (op === OP_GATE || op === OP_SCOPE || op === OP_SCOPE_CAP || op === OP_SCOPE_PLAIN
+        || op === OP_XFORM || op === OP_NODE || op === OP_FIELD || op === OP_LEAF) {
+        return walk(code[at + 2]!, depth + 1)
+      }
+      if (op === OP_SEQ || op === OP_SEQV) {
+        return code[at + 1]! < 1 ? undefined : walk(code[at + 2]!, depth + 1)
+      }
+      if (op === OP_SEQX) {
+        return code[at + 2]! < 1 ? undefined : walk(code[at + 3]!, depth + 1)
+      }
+      if (op !== OP_CHOICE) return undefined
+
+      const n = code[at + 2]!
+      if (n < 1) return undefined
+      const out: number[] = []
+      for (let i = 0; i < n; i++) {
+        const branch = walk(code[at + 4 + i]!, depth + 1)
+        if (branch === undefined) return undefined
+        for (const terminal of branch) {
+          const value = constants[code[terminal + 1]!] as string
+          let covered = false
+          for (let j = 0; j < out.length; j++) {
+            const prior = constants[code[out[j]! + 1]!] as string
+            if (value.startsWith(prior)) { covered = true; break }
+          }
+          if (covered) continue
+          for (let j = out.length - 1; j >= 0; j--) {
+            const prior = constants[code[out[j]! + 1]!] as string
+            if (prior.startsWith(value)) out.splice(j, 1)
+          }
+          out.push(terminal)
+          if (out.length > limit) return undefined
+        }
+      }
+      return out
+    } finally {
+      active.delete(at)
+    }
+  }
+
+  return walk(ip, 0)
+}

package/src/table/site-labels.ts

@@ -79,6 +79,13 @@ export const CAP_OFF = 1
 /** `ctx.captureTrivia === true` is guaranteed here. */
 export const CAP_ON = 2
 
+/** Buffer raw-entry mode is not provable at this site. */
+export const RAW_UNKNOWN = 0
+/** Buffer retains raw entry values. */
+export const RAW_CAPTURE = 1
+/** Buffer retains only a raw source-order count. */
+export const RAW_OMIT = 2
+
 export type SiteLabel = {
   /** `TRI_UNKNOWN`, `TRI_NONE`, or the trivia slot the enclosing scope installed. */
   readonly tri: number
@@ -87,19 +94,22 @@ export type SiteLabel = {
    * asymmetry note in this file's header. Never read as "guaranteed absent".
    */
   readonly buf: boolean
+  /** `RAW_UNKNOWN` / `RAW_CAPTURE` / `RAW_OMIT`. */
+  readonly raw: number
   /** `CAP_UNKNOWN` / `CAP_OFF` / `CAP_ON`. */
   readonly cap: number
 }
 
 /** The lattice's top: every entry point starts here. */
-export const TOP: SiteLabel = { tri: TRI_UNKNOWN, buf: false, cap: CAP_UNKNOWN }
+export const TOP: SiteLabel = { tri: TRI_UNKNOWN, buf: false, raw: RAW_UNKNOWN, cap: CAP_UNKNOWN }
 
 function meet(a: SiteLabel, b: SiteLabel): SiteLabel {
   const tri = a.tri === b.tri ? a.tri : TRI_UNKNOWN
   const buf = a.buf && b.buf
+  const raw = a.raw === b.raw ? a.raw : RAW_UNKNOWN
   const cap = a.cap === b.cap ? a.cap : CAP_UNKNOWN
-  if (tri === a.tri && buf === a.buf && cap === a.cap) return a
-  return { tri, buf, cap }
+  if (tri === a.tri && buf === a.buf && raw === a.raw && cap === a.cap) return a
+  return { tri, buf, raw, cap }
 }
 
 /**
@@ -145,7 +155,7 @@ function transfer(code: Int32Array, ip: number, at: SiteLabel, hostCst: boolean)
     // (`encode.ts:1153-1158`), so it can only ever raise `cap` to `CAP_ON`.
     const cap = op === OP_SCOPE_CAP ? CAP_ON : at.cap
     if (tri === at.tri && cap === at.cap) return at
-    return { tri, buf: at.buf, cap }
+    return { tri, buf: at.buf, raw: at.raw, cap }
   }
   if (op === OP_NODE || op === OP_NODE_TRACK) {
     const flags = code[ip + 3]!
@@ -156,14 +166,17 @@ function transfer(code: Int32Array, ip: number, at: SiteLabel, hostCst: boolean)
       // arrays instead of a CstCaptureBuf. Descendants still capture, but they
       // must take the generic collector branch rather than dereference `_cstBuf`.
       // False means UNKNOWN in this lattice, which is exactly the safe answer.
-      return { tri: at.tri, buf: false, cap: CAP_OFF }
+      return { tri: at.tri, buf: false, raw: RAW_UNKNOWN, cap: CAP_OFF }
     }
     // `ctx._cstBuf = buf` and `ctx.captureTrivia = <literal>`, both unconditional
     // — `emit-assembly.ts`'s `OP_NODE` body opens the buffer before it descends
     // and closes it after, whatever the host mode is.
     const cap = ((flags & 4) !== 0 || hostCst) ? CAP_ON : CAP_OFF
-    if (at.buf && cap === at.cap) return at
-    return { tri: at.tri, buf: true, cap }
+    const raw = !hostCst && code[ip + 1]! >= 0 && code[ip + 4]! < 0 && (flags & 2) !== 0
+      ? RAW_OMIT
+      : RAW_CAPTURE
+    if (at.buf && raw === at.raw && cap === at.cap) return at
+    return { tri: at.tri, buf: true, raw, cap }
   }
   // THE TWO BOUNDARIES clear every capture sink for their child and contribute
   // ONE leaf for the whole match; `token()` clears `ctx.trivia` as well. So a
@@ -178,11 +191,11 @@ function transfer(code: Int32Array, ip: number, at: SiteLabel, hostCst: boolean)
   // an option.
   if (op === OP_TOKEN) {
     if (at.tri === TRI_NONE && !at.buf) return at
-    return { tri: TRI_NONE, buf: false, cap: at.cap }
+    return { tri: TRI_NONE, buf: false, raw: RAW_UNKNOWN, cap: at.cap }
   }
   if (op === OP_LEAF) {
     if (!at.buf) return at
-    return { tri: at.tri, buf: false, cap: at.cap }
+    return { tri: at.tri, buf: false, raw: RAW_UNKNOWN, cap: at.cap }
   }
   return at
 }

package/src/types.ts

@@ -89,7 +89,7 @@ export type ParserDef =
   // it requires, so it carries `parser`'s first-set and a leading `peek()` gates
   // its choice arm (see `isPositiveLookahead` / `sequenceFirstSet`).
   | { tag: 'peek';    parser: Combinator<unknown> }
-  | { tag: 'node';     type?: string; parser: Combinator<unknown>; build?: ((children: ReadonlyArray<unknown>, fields: FieldMap | undefined, span: { start: number; end: number }, rawChildren: ReadonlyArray<unknown>, triviaLog: readonly number[], state: unknown) => unknown) | undefined; buildSrc?: string; /** The IDENTIFIER the type argument was written as at the `node()` call site, when it was a plain identifier rather than a literal — ANALYSIS ONLY, never emitted. Lets the inline-`mk` matcher recognise `node(t, …, (…) => mk(t, …))` from a factory, where the two `t`s are provably one binding. */ typeSrc?: string; /** Resolved source of a NAMED `buildSrc` — ANALYSIS ONLY, never emitted. See `buildAnalysisSrc`. */ buildSigSrc?: string; /** Declared positional arity of `build`: author-declared via `node(..., { buildArity })`, or resolved from the reducer's declaration. Wins over source inspection. */ buildArity?: number; /** Why arity could not be resolved, for the diagnostic. */ buildArityUnresolved?: string; buildStaticError?: readonly string[]; unwrap?: boolean; collapse?: boolean; project?: number; captureTrivia?: boolean; trailingTrivia?: boolean; tags?: readonly string[] }
+  | { tag: 'node';     type?: string; parser: Combinator<unknown>; build?: ((children: ReadonlyArray<unknown>, fields: FieldMap | undefined, span: { start: number; end: number }, rawChildren: ReadonlyArray<unknown>, triviaLog: readonly number[], state: unknown) => unknown) | undefined; buildSrc?: string; /** The IDENTIFIER the type argument was written as at the `node()` call site, when it was a plain identifier rather than a literal — ANALYSIS ONLY, never emitted. Lets the inline-`mk` matcher recognise `node(t, …, (…) => mk(t, …))` from a factory, where the two `t`s are provably one binding. */ typeSrc?: string; /** Resolved source of a NAMED `buildSrc` — ANALYSIS ONLY, never emitted. See `buildAnalysisSrc`. */ buildSigSrc?: string; /** Macro analysis proved the fourth formal (`rawChildren`) unreferenced. Never inferred from an author-declared `buildArity`; carried through composed IR. */ buildRawUnused?: true; /** Declared positional arity of `build`: author-declared via `node(..., { buildArity })`, or resolved from the reducer's declaration. Wins over source inspection. */ buildArity?: number; /** Why arity could not be resolved, for the diagnostic. */ buildArityUnresolved?: string; buildStaticError?: readonly string[]; /** Import provenance for a direct builder's free names — each `{ local, source, imported }` lets a downstream compose() re-emit `import { imported as local } from source` so the inlined builder source can bind. Carried through the IR round-trip. */ buildImports?: ReadonlyArray<{ local: string; source: string; imported: string }>; unwrap?: boolean; collapse?: boolean; project?: number; captureTrivia?: boolean; trailingTrivia?: boolean; tags?: readonly string[] }
   // `predSrc`/`extraSrc` (set by the macro evaluator): SOURCE TEXT of the guard
   // predicate / the withCtx `extra` value, so codegen inlines them into `_mf`
   // rather than pushing a `null` source. Absent under runtime compile() (the real

package/src/version.ts

@@ -13,4 +13,4 @@
  * Kept in sync with `package.json` by `test/unit/version-sync.test.ts`, which fails
  * the build if this constant drifts from the published version.
  */
-export const PARSEMAN_VERSION = '0.48.1'
+export const PARSEMAN_VERSION = '0.50.0'