parseman 0.60.4 → 0.60.6

package/dist/table/ops.d.ts

@@ -210,6 +210,12 @@ export declare const OP_TOKEN = 29;
  * is why this restores the saved value rather than writing `false`.
  */
 export declare const OP_SCOPE_CAP = 30;
+/**
+ * `k` of a `SCOPE_CAP` row whose `parser({ captureTrivia: true })` names no trivia.
+ * It raises capture and leaves the trivia the scope was entered with in force,
+ * where `k = -1` clears it (`trivia: null`).
+ */
+export declare const SCOPE_INHERIT = -2;
 /**
  * `WITHCTX k c` — `withCtx(extra, c)`. `k >= 0` is `extra` in the const pool
  * (the replace form); `k < 0` is the derive form, `~k` indexing the author's

package/dist/table/ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../../src/table/ops.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../../src/table/ops.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -13,5 +13,5 @@
  * 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 declare const PARSEMAN_VERSION = "0.60.4";
+export declare const PARSEMAN_VERSION = "0.60.6";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parseman",
-  "version": "0.60.4",
+  "version": "0.60.6",
   "packageManager": "pnpm@10.15.1",
   "engines": {
     "node": "^20.19.0 || >=22.13.0"

package/src/analysis/commitment.ts

@@ -676,7 +676,9 @@ export function classifyRuleMap(
       let resolved: Combinator<unknown> | undefined
       try { resolved = def.thunk() } catch { resolved = undefined }
       if (resolved === undefined) {
-        if ((p as unknown as { _ruleName?: string })._ruleName) externalRefs.add(p)
+        // A `prior.X` placeholder is a hole too: the composition fills it by name.
+        const hole = p as unknown as { _ruleName?: string; _priorOf?: string }
+        if (hole._ruleName !== undefined || hole._priorOf !== undefined) externalRefs.add(p)
         return
       }
       scanExternal(resolved)

package/src/combinators/grammar.ts

@@ -215,7 +215,7 @@ export function parser<T>(opts: ParserOptions, root: Combinator<T>): ParsemanPar
         ctx.triviaKindLabels = undefined
       } else if (scopeTrivia !== undefined) {
         ctx.trivia = scopeTrivia
-        if (scopeLabels) ctx.triviaKindLabels = scopeLabels
+        ctx.triviaKindLabels = scopeLabels
       }
       if (forceCaptureTrivia || _ctx?.captureTrivia) ctx.captureTrivia = true
       // Kind-filter for per-node capture. Resolve against this scope's trivia

package/src/combinators/parser.ts

@@ -1,5 +1,7 @@
 import type { Combinator } from '../types.ts'
 import type { HostMode } from '../cst/host-mode.ts'
+import type { Runnable } from '../functional/run.ts'
+import { any } from './first-set.ts'
 import { ref } from './ref.ts'
 import { markUnusedValues } from '../compiler/value-usage.ts'
 import { parser as grammarParser } from './grammar.ts'
@@ -28,12 +30,20 @@ function isDefinableRef(v: unknown): v is DefinableRef {
     && typeof (v as { define?: unknown }).define === 'function'
 }
 
+/** The rule name a `prior.X` placeholder stands for (see `linkRules`), or `undefined`. */
+export function priorNameOf(r: Combinator<unknown>): string | undefined {
+  return (r as unknown as { _priorOf?: string })._priorOf
+}
+
 function ruleNameOf(r: Combinator<unknown>): string | undefined {
   return (r as unknown as { _ruleName?: string })._ruleName
 }
 
 function isNamedRuleRefForAnotherRule(r: Combinator<unknown>, key: string): boolean {
-  const name = r._def.tag === 'lazy' ? ruleNameOf(r) : undefined
+  if (r._def.tag !== 'lazy') return false
+  // A `prior.X` hole stands for an earlier piece's rule, never for this key.
+  if (priorNameOf(r) !== undefined) return true
+  const name = ruleNameOf(r)
   return name !== undefined && name !== key
 }
 
@@ -157,13 +167,58 @@ type RuleMapNodeTag<T extends Record<string, Combinator<unknown>>> = {
 type RulesResult<T extends Record<string, Combinator<unknown>>> =
   T & GrammarWithReflection<RuleMapNodeType<T>, RuleMapNodeTag<T>>
 
-export function rules<T extends Record<string, Combinator<unknown>>>(factory: (self: any) => T): RulesResult<T>
-export function rules<T extends Record<string, Combinator<unknown>>>(options: RulesOptions, factory: (self: any) => T): RulesResult<T>
-export function rules<T extends Record<string, Combinator<unknown>>>(
-  a: ((self: any) => T) | RulesOptions,
-  b?: (self: any) => T,
+/**
+ * The second parameter of a `rules((g, prior) => …)` factory. `prior.X` is the
+ * definition of `X` that the grammars composed BEFORE this one gave it, with a
+ * top-level `node()` unwrapped to its body, so a composing grammar can re-reduce,
+ * wrap or extend an inherited rule without re-spelling it:
+ *
+ *   rules((g, prior: PriorRules<typeof css>) => ({
+ *     Value: node('Value', prior.Value, reduceValue),
+ *   }))
+ *
+ * Naming the base grammar types `prior.X`, and a misspelled rule fails to compile.
+ *
+ * Its `g.X` references stay bound to the composition (open recursion). A rule's value
+ * is `unknown` here, because unwrapping a `node()` changes it. Unnamed, the parameter
+ * answers any string, which `noUncheckedIndexedAccess` reads as possibly undefined.
+ * See `docs/guide/extending.md`.
+ */
+export type PriorRules<Base = Record<string, Combinator<unknown>>> =
+  [KnownRuleNames<Base>] extends [never]
+    ? { readonly [name: string]: Combinator<unknown> }
+    : { readonly [K in KnownRuleNames<Base>]: Combinator<unknown> }
+
+/** The rule names a grammar's type spells out: not its index signature, if it has one. */
+export type KnownRuleNames<Base> = keyof {
+  [K in keyof Base as string extends K ? never : number extends K ? never : Base[K] extends Combinator<unknown> | Runnable ? K : never]: unknown
+} & string
+
+const priorUnfilled = (key: string): Error =>
+  new Error(`compose: prior.${key} is read, but no grammar composed before it defines "${key}"`)
+
+/** The placeholder for a `prior.X` no earlier piece has defined yet. Composition
+ * replaces it; running it, or analysing what it leads to, reports the name. */
+function priorHole(key: string): Combinator<unknown> {
+  const unfilled = priorUnfilled(key)
+  const fail = (): never => { throw unfilled }
+  return {
+    _tag: 'lazy',
+    _meta: { firstSet: any(), canMatchNewline: true, isTrivia: false },
+    _def: { tag: 'lazy', thunk: fail },
+    parse: fail,
+    _priorOf: key,
+  } as Combinator<unknown>
+}
+
+export function rules<T extends Record<string, Combinator<unknown>>, P extends object = PriorRules>(factory: (self: any, prior: P) => T): RulesResult<T>
+export function rules<T extends Record<string, Combinator<unknown>>, P extends object = PriorRules>(options: RulesOptions, factory: (self: any, prior: P) => T): RulesResult<T>
+export function rules<T extends Record<string, Combinator<unknown>>, P extends object = PriorRules>(
+  a: ((self: any, prior: P) => T) | RulesOptions,
+  b?: (self: any, prior: P) => T,
 ): RulesResult<T> {
-  const factory = (typeof a === 'function' ? a : b) as (self: any) => T
+  // The proxy answers every name, so it satisfies whatever rules `P` names.
+  const factory = (typeof a === 'function' ? a : b) as unknown as RulesRecipe['factory']
   const options = (typeof a === 'function' ? b : a) as RulesOptions | undefined
   const recipe: RulesRecipe = { factory, options }
   const map = linkRules([recipe])
@@ -180,7 +235,7 @@ export function rules<T extends Record<string, Combinator<unknown>>>(
  */
 export const RULES_RECIPE = Symbol.for('parseman.rulesRecipe')
 export type RulesRecipe = {
-  readonly factory: (self: Record<string, Combinator<unknown>>) => Record<string, Combinator<unknown>>
+  readonly factory: (self: Record<string, Combinator<unknown>>, prior: PriorRules) => Record<string, Combinator<unknown>>
   readonly options: RulesOptions | undefined
 }
 
@@ -234,8 +289,26 @@ export function linkRules(
   // before the rule's own parser is built — enabling forward references. A later
   // recipe's definition of a name WINS; the name keeps its first position.
   const winners = new Map<string, { parser: Combinator<unknown>; options: RulesOptions | undefined }>()
+  // `prior.X`: the winner for X BEFORE the running recipe, read while that recipe's
+  // factory runs (its own definitions join `winners` only after it returns). It is
+  // the earlier definition itself, inlined into the new rule's graph, so it costs no
+  // hop at parse time. A grammar not yet composed has no earlier piece: `prior.X` is
+  // then a placeholder the serializer writes back as `prior.X`, and a composition
+  // that still has no earlier X refuses it.
+  const priorHoles = new Map<string, Combinator<unknown>>()
+  const prior = new Proxy<PriorRules>({}, {
+    get(_target, key) {
+      if (typeof key !== 'string') return undefined
+      const earlier = winners.get(key)?.parser
+      if (earlier !== undefined) return earlier._def.tag === 'node' ? earlier._def.parser : earlier
+      if (link !== undefined) throw priorUnfilled(key)
+      let hole = priorHoles.get(key)
+      if (hole === undefined) priorHoles.set(key, hole = priorHole(key))
+      return hole
+    },
+  })
   for (const recipe of recipes) {
-    const definitions = recipe.factory(proxy)
+    const definitions = recipe.factory(proxy, prior)
     for (const key of Object.keys(definitions)) {
       winners.set(key, { parser: definitions[key]!, options: recipe.options })
     }

package/src/combinators/trivia-boundary.ts

@@ -20,9 +20,11 @@ const MAX_DEPTH = 12
  *
  * `lazy` is deliberately false and is never followed: a reference is the
  * delegation this question is about, so following it would both loop and answer
- * for a different rule. `grammar` is false because it declares its own scope, so
- * an outer install never reaches its body. `dispatch` is false because it is a
- * ROUTE: its arms re-enter from the routed token and spell their own padding.
+ * for a different rule. A `grammar` that names or clears trivia declares its own
+ * scope, so an outer install never reaches its body and the answer is false; one
+ * that does not (`parser({ trackLines: true }, …)`, which `rules({ trackLines })`
+ * wraps every rule in) inherits, so it is transparent. `dispatch` is false because
+ * it is a ROUTE: its arms re-enter from the routed token and spell their own padding.
  *
  * Structural and pure — callers resolve it ONCE, not per parse.
  */
@@ -35,6 +37,12 @@ export function hasOwnTriviaBoundary(p: Combinator<unknown>, depth: number = MAX
     // Multi-term forms: the gaps BETWEEN terms are the ambient-trivia positions.
     case 'sequence': return d.parsers.length > 1
     case 'many': case 'oneOrMore': case 'sepBy': return true
+    // A scope that names or clears trivia keeps an outer install out of its body.
+    // Any other inherits, so it falls through at no cost in depth: line tracking
+    // wraps every rule in one, and must not change what this walk sees.
+    case 'grammar':
+      if (d.triviaParser || d.clearTrivia) return false
+      depth++
     // Transparent wrappers — they add no position, so ask what they wrap.
     case 'node': case 'transform': case 'leaf': case 'label': case 'field':
     case 'token': case 'attempt': case 'optional': case 'expect': case 'withCtx':

package/src/compiler/compile-linkable-table.ts

@@ -4,6 +4,7 @@ import { childrenOf } from '../analysis/gating.ts'
 import { collectGrammarReflection, type GrammarReflection } from '../cst/reflection.ts'
 import { classifyRuleMap } from '../analysis/commitment.ts'
 import { serializeRuleMap } from './ir-serialize.ts'
+import { priorNameOf } from '../combinators/parser.ts'
 import { compileRuleMap, compileRuleMapRunnable, type TableRuleMapOptions } from '../table/compile-rule-map.ts'
 import type { TableProgram, TableRule } from '../table/program.ts'
 import { PARSEMAN_VERSION } from '../version.ts'
@@ -132,7 +133,9 @@ function externalNames(
       let resolved: Combinator<unknown> | undefined
       try { resolved = d.thunk() } catch { resolved = undefined }
       if (resolved === undefined) {
-        const name = (p as unknown as { _ruleName?: string })._ruleName
+        // A `prior.X` the composition fills from an earlier piece is a hole too.
+        const prior = priorNameOf(p)
+        const name = prior === undefined ? (p as unknown as { _ruleName?: string })._ruleName : `prior.${prior}`
         if (name !== undefined && !out.includes(name)) out.push(name)
         return
       }

package/src/compiler/ir-serialize.ts

@@ -18,7 +18,7 @@
  * source, or an unsupported construct) — the caller then keeps the lowered source.
  */
 import type { Combinator, DispatchMatcherCase, ParserDef } from '../types.ts'
-import { rules } from '../combinators/parser.ts'
+import { priorNameOf, rules } from '../combinators/parser.ts'
 import { ref } from '../combinators/ref.ts'
 import { regex } from '../combinators/regex.ts'
 import { literal } from '../combinators/literal.ts'
@@ -191,6 +191,8 @@ class Serializer {
   private localRuleNames = new Map<Comb, string>()
   private ruleMap: ReadonlyArray<readonly [string, Comb]>
   private scanSkip: readonly Comb[]
+  /** Whether any rule reads a `prior.X` hole, so the factory takes `(g, prior)`. */
+  private usesPrior = false
 
   private accessed: readonly string[]
   private referenced = new Set<string>()
@@ -214,7 +216,7 @@ class Serializer {
     if (seen.has(c)) return
     seen.add(c)
     if (c._def.tag === 'lazy') {
-      if (ruleNameOf(c) !== undefined) throw new Unserializable('scanSkip unit references a grammar rule')
+      if (ruleNameOf(c) !== undefined || priorNameOf(c) !== undefined) throw new Unserializable('scanSkip unit references a grammar rule')
       const target = lazyTarget(c)
       if (target) this.assertNoRuleRef(target, seen)
       return
@@ -307,9 +309,10 @@ class Serializer {
     }
     // Shared consts go INSIDE the factory: they can reference `g[name]` rule refs,
     // and `g` only exists in the factory scope.
+    const params = this.usesPrior ? '(g, prior)' : '(g)'
     const factory = innerDecls.length === 0
-      ? `(g) => ({\n${body}\n})`
-      : `(g) => {\n${innerDecls.map(d => '  ' + d).join('\n')}\n  return ({\n${body}\n})\n}`
+      ? `${params} => ({\n${body}\n})`
+      : `${params} => {\n${innerDecls.map(d => '  ' + d).join('\n')}\n  return ({\n${body}\n})\n}`
     const call = `rules(${optionsArg}${factory})`
     return outerDecls.length === 0
       ? call
@@ -321,6 +324,7 @@ class Serializer {
   private analyze(c: Comb, active: Set<Comb>): void {
     const def = c._def
     if (def.tag === 'lazy') {
+      if (priorNameOf(c) !== undefined) { this.usesPrior = true; return } // resolved by prior[name]
       if (ruleNameOf(c) !== undefined) return          // named rule ref — resolved by g[name]
       const target = lazyTarget(c)
       if (!target) throw new Unserializable('unresolved unnamed ref')
@@ -422,6 +426,8 @@ class Serializer {
     }
     switch (def.tag) {
       case 'lazy': {
+        const prior = priorNameOf(c)
+        if (prior !== undefined) return `prior[${JSON.stringify(prior)}]`
         const name = this.localRuleNames.get(c) ?? ruleNameOf(c)
         if (name !== undefined) { this.referenced.add(name); return `g[${JSON.stringify(name)}]` }
         const target = lazyTarget(c)!

package/src/compiler/linker.ts

@@ -16,7 +16,7 @@ import { borrowedRuleMessage, borrowedRuleReference } from './borrowed-rules.ts'
 import { FUSED_HOST_MODE, FUSED_HOST_ELIDED, type HostMode } from '../cst/host-mode.ts'
 import { compileLinkableTable, type LinkableTable } from './compile-linkable-table.ts'
 import { GRAMMAR_REFLECTION } from '../cst/reflection.ts'
-import { linkRules, RULE_ORDER, RULES_RECIPE, type LinkOptions, type RulesRecipe } from '../combinators/parser.ts'
+import { linkRules, RULE_ORDER, RULES_RECIPE, type KnownRuleNames, type LinkOptions, type RulesRecipe } from '../combinators/parser.ts'
 import type { BuildHost, Combinator, CstCollapsePredicate, ParseContext, ParseResult } from '../types.ts'
 import type { Runnable } from '../functional/run.ts'
 import { PlainNode, PlainTaggedNode } from '../cst/plain.js'
@@ -342,7 +342,7 @@ function recipesOf(item: LinkableTable | Record<string, unknown>): readonly Rule
  * `rules({ trivia }, …)` map's own, or a runtime composition's composing trivia.
  * Outermost wins over every linked rule, inherited ones included; `parser` /
  * `noTrivia` still override locally. */
-function composingTriviaOf(items: Array<LinkableTable | Record<string, unknown>>): Combinator<unknown> | undefined {
+function composingTriviaOf(items: ReadonlyArray<LinkableTable | Record<string, unknown>>): Combinator<unknown> | undefined {
   for (let i = items.length - 1; i >= 0; i--) {
     const item = items[i] as Record<symbol, unknown>
     if (item[LINKED] !== undefined) {
@@ -359,7 +359,7 @@ function composingTriviaOf(items: Array<LinkableTable | Record<string, unknown>>
 
 /** The rule names a linked composition defines, in first-declaration order —
  * known WITHOUT linking, from each item's own declaration order. */
-function declaredNamesOf(items: Array<LinkableTable | Record<string, unknown>>): string[] {
+function declaredNamesOf(items: ReadonlyArray<LinkableTable | Record<string, unknown>>): string[] {
   const names = new Set<string>()
   for (const item of items) {
     const linked = (item as Record<symbol, unknown>)[LINKED] !== undefined
@@ -419,6 +419,16 @@ function linkComposition(
   return map
 }
 
+/** The rules each item spells out. An item that spells out none, such as a plain
+ * `Record<string, …>`, could hold anything, so the whole result stays open. */
+type ItemRuleNames<Item> = Item extends unknown
+  ? [KnownRuleNames<Item>] extends [never] ? string : KnownRuleNames<Item>
+  : never
+
+/** A composition's rules: every name its items spell out, plus lookup by any string. */
+export type ComposedRules<Items extends readonly unknown[]> =
+  Record<string, Runnable> & { [K in ItemRuleNames<Items[number]>]: Runnable }
+
 /**
  * Compose grammars into ONE parser map — the only public composition entry point.
  * `compose([base, ext, …])`: a later entry's rule WINS by name, and because every
@@ -435,23 +445,23 @@ function linkComposition(
  * costs a walk of the items' declared names. For speed, `compile()` a rule of it;
  * `compile()` specialises when the environment allows and falls back under CSP.
  */
-export function compose(
-  items: Array<LinkableTable | Record<string, unknown>>,
+export function compose<const Items extends ReadonlyArray<LinkableTable | Record<string, unknown>>>(
+  items: Items,
   /**
    * Host mode for the composed grammar, same meaning as `compile(g, { hostMode })`.
    * The interpreter routes by host at parse time; this records `'cst'` on every rule
    * so `run()` can refuse a mismatched host instead of building the wrong tree.
    */
   opts?: { hostMode?: HostMode },
-): Record<string, Runnable> {
+): ComposedRules<Items> {
   if (items.some(item => (item as Record<symbol, unknown>)[LEAF_COMPOSED] === true)) {
     throw new Error('compose: a composeLeaf() result is terminal and cannot be composed again')
   }
-  return linkedMap(items, opts, false)
+  return linkedMap(items, opts, false) as ComposedRules<Items>
 }
 
 function linkedMap(
-  items: Array<LinkableTable | Record<string, unknown>>,
+  items: ReadonlyArray<LinkableTable | Record<string, unknown>>,
   opts: { hostMode?: HostMode } | undefined,
   leaf: boolean,
 ): Record<string, Runnable> {
@@ -485,10 +495,10 @@ function linkedMap(
  * At runtime it is the same lazy link as `compose()`, marked terminal. The bench and
  * differential harnesses import un-macro'd grammar modules and run this path.
  */
-export function composeLeaf(
-  items: Array<LinkableTable | Record<string, unknown>>,
-): Record<string, Runnable> {
-  return linkedMap(items, undefined, true)
+export function composeLeaf<const Items extends ReadonlyArray<LinkableTable | Record<string, unknown>>>(
+  items: Items,
+): ComposedRules<Items> {
+  return linkedMap(items, undefined, true) as ComposedRules<Items>
 }
 
 /** Whether `map` is a runtime composition (a combinator map) rather than a

package/src/index.ts

@@ -23,6 +23,7 @@ export type { AttemptOptions } from './combinators/attempt.ts'
 export { many, oneOrMore, optional, sepBy, oneOrMoreSep, keepSeparator } from './combinators/repeat.ts'
 export type { RepeatOptions, SepByOptions, TrailingSeparator, KeptSeparator } from './combinators/repeat.ts'
 export { rules } from './combinators/parser.ts'
+export type { PriorRules } from './combinators/parser.ts'
 export { ref } from './combinators/ref.ts'
 export { not } from './combinators/not.ts'
 export { peek } from './combinators/peek.ts'
@@ -140,7 +141,7 @@ export type {
 // back to `FusedRule`, `isInterpretedFuse` would have to be re-exported in the same
 // change — a dual shape with no way to detect it is the worse of the two.
 export { compose, composeLeaf, cstBuildHost } from './compiler/linker.ts'
-export type { CstBuildHostOptions, FusedRule } from './compiler/linker.ts'
+export type { ComposedRules, CstBuildHostOptions, FusedRule } from './compiler/linker.ts'
 
 export { buildLineIndex, createLineIndex, recordLineRange, normalizeLineIndex, offsetToLineCol, annotateSpan, annotateTreeSpans } from './line-index.ts'
 export type { LineIndex } from './line-index.ts'

package/src/plugin/evaluator.ts

@@ -16,7 +16,7 @@ import type {
 import type { Combinator } from '../types.ts'
 import type { DispatchArm } from '../combinators/dispatch.ts'
 import { ref } from '../combinators/ref.ts'
-import { rules, type RulesOptions } from '../combinators/parser.ts'
+import { rules, RULES_RECIPE, type PriorRules, type RulesOptions, type RulesRecipe } from '../combinators/parser.ts'
 import * as parseman from '../index.ts'
 import { confirmedBuildParamUnused } from '../compiler/build-arity.ts'
 import { directBuilderBindings } from './direct-builder-static.ts'
@@ -1478,11 +1478,17 @@ export function evaluateParserFactory(
 
   const factory = factoryNode as unknown as ArrowFunctionExpression | OxcFunction
   const params = factory.params
-  if (params.length !== 1) return null
-  const param = params[0] as unknown as { type: string; name?: string }
+  if (params.length !== 1 && params.length !== 2) return null
   // FormalParameter is { decorators? } & BindingPattern — BindingIdentifier has type "Identifier"
-  const proxyName = param.type === 'Identifier' ? param.name ?? null : null
+  const paramName = (param: unknown): string | null => {
+    const p = param as { type: string; name?: string }
+    return p.type === 'Identifier' ? p.name ?? null : null
+  }
+  const proxyName = paramName(params[0])
   if (!proxyName) return null
+  // `(g, prior)`: the second parameter is the `prior` handle (`PriorRules`).
+  const priorName = params.length === 2 ? paramName(params[1]) : undefined
+  if (priorName === null) return null
 
   const body = factory.body
   if (!body) return null
@@ -1566,11 +1572,12 @@ export function evaluateParserFactory(
   const ABORT = Symbol('parseman: factory not statically evaluable')
   let built: Record<string, Combinator<unknown>>
   try {
-    built = rules(options ?? {}, (g: Record<string, Combinator<unknown>>) => {
+    built = rules(options ?? {}, (g: Record<string, Combinator<unknown>>, prior: PriorRules) => {
       // Outer ScopeEntry values carry their mfSrcs and are replayed by scopeGet()
       // when body statements or return expressions reference them.
       const localScope: XScope = scope instanceof ModuleScope ? scope.fork() : new Map(scope as XScope)
       localScope.set(proxyName, g)
+      if (priorName !== undefined) localScope.set(priorName, prior)
 
       // ── Phase 1: the factory's own body statements ────────────────────────
       if (!evalBodyStatements(statements, localScope, code, out)) throw ABORT
@@ -1615,9 +1622,13 @@ export function evaluateParserFactory(
   for (const key of keys) map.set(key, built[key]!)
   const declared = new Set(keys)
   externalAccesses.set(map, Object.keys(built).filter(name => !declared.has(name)))
+  ruleMapRecipes.set(map, (built as unknown as Record<symbol, readonly RulesRecipe[]>)[RULES_RECIPE]!)
   return map
 }
 
+/** The recipe an evaluated rule map came from, for a composition that links it. */
+export const ruleMapRecipes = new WeakMap<ReadonlyMap<string, Combinator<unknown>>, readonly RulesRecipe[]>()
+
 /**
  * Every EXTERNAL name an evaluated factory read through `g`, keyed by the map
  * `evaluateParserFactory` returned. The map holds declared rules only, so a `g.X`