@limaformat/lima 0.3.1 → 0.4.0

package/dist/core.js

@@ -18,11 +18,11 @@
  * `flow.ts` (`[...]`/`{...}`), and `block.ts` (indentation-based sequences
  * and mappings) — this file is the orchestrator that ties them together.
  */
-import { LString } from './value.js';
-import { checkKeyLength, checkScalarLimit, byteLength, DOCUMENT_SIZE_LIMIT, TOP_LEVEL_KEY_LIMIT, NESTING_DEPTH_LIMIT, } from './normalize.js';
-import { unescapeDQ, stripComment, positionedBuilder, NO_SPAN_VALUE, parseSimpleScalarSpan, } from './scalars.js';
+import { checkKeyLength, byteLength, DOCUMENT_SIZE_LIMIT, TOP_LEVEL_KEY_LIMIT, NESTING_DEPTH_LIMIT, } from './normalize.js';
+import { unescapeDQ, stripComment, stripCommentKeepEscapes, positionedBuilder, NO_SPAN_VALUE, parseSimpleScalarSpan, } from './scalars.js';
 import { parseFlowOrScalarValue } from './flow.js';
 import { parseBlockRange } from './block.js';
+import { buildBlockScalar } from './block-scalar.js';
 import { LimaError } from './errors.js';
 import { KeyCursor, scanKeys } from './scanner.js';
 export { NESTING_DEPTH_LIMIT, SCALAR_LENGTH_LIMIT } from './normalize.js';
@@ -68,19 +68,6 @@ const depthOfNative = (v) => {
     return 0;
 };
 const SPACE_BEFORE_COLON_RE = /^(?:'[^']*'|"(?:[^"\\]|\\.)*")[ \t]+:/;
-const leadingSpaces = (line) => {
-    let i = 0;
-    while (i < line.length && line.charCodeAt(i) === 32)
-        i++;
-    return i;
-};
-/** Index right after the last non-space character — the `trimEnd()` boundary, without allocating. */
-const trailingSpaceEnd = (line) => {
-    let i = line.length;
-    while (i > 0 && line.charCodeAt(i - 1) === 32)
-        i--;
-    return i;
-};
 const lineAt = (s, pos) => {
     let n = 1;
     for (let i = 0; i < pos; i++)
@@ -136,7 +123,14 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
     if (frontMatter.includes('\r'))
         frontMatter = frontMatter.replace(/\r\n|\r/g, '\n');
     if (frontMatter.includes('\t')) {
-        frontMatter = frontMatter.replace(/^([ \t]*)/gm, (leading) => (leading.includes('\t') ? leading.replace(/\t/g, '  ') : leading));
+        // Record how many columns each line's leading whitespace grew, so a
+        // References 2.0 token can be reported at its *original* column (§2.4).
+        ctx.tabAdjust = [];
+        frontMatter = frontMatter.replace(/^([ \t]*)/gm, (leading) => {
+            const expanded = leading.includes('\t') ? leading.replace(/\t/g, '  ') : leading;
+            ctx.tabAdjust.push(expanded.length - leading.length);
+            return expanded;
+        });
     }
     if (frontMatter.includes(' \n') || frontMatter.endsWith(' ')) {
         // Capture-and-reinsert instead of a lookahead: `( +)(\n|$)` replaced
@@ -163,7 +157,7 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
         }
     }
     const parseEntry = (key, line, rawStart, isBlock, inlineEnd, nextStart) => {
-        checkKeyLength(key, () => line);
+        checkKeyLength(key, line);
         if ((strict || ctx.onWarning !== undefined) && builder.hasMappingKey(root, key)) {
             const diagnostic = {
                 code: 'DUPLICATE_KEY', line, key,
@@ -178,6 +172,14 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
         }
         const firstNewline = inlineEnd ?? frontMatter.indexOf('\n', rawStart);
         const newlineInRange = firstNewline < nextStart;
+        // Physical codepoint column of the value's first character in its
+        // source line — the anchor for References 2.0 token positions (§2.4).
+        // References 2.0 token positions (§2.4): only build the source anchor
+        // for the annotated builder; `parseCore` (native) discards it.
+        const wantSource = builder === positionedBuilder;
+        const valueLineStart = wantSource ? frontMatter.lastIndexOf('\n', rawStart - 1) + 1 : 0;
+        const valueCol = wantSource ? [...frontMatter.slice(valueLineStart, rawStart)].length : 0;
+        const lineTabAdjust = wantSource && ctx.tabAdjust ? [ctx.tabAdjust[line - 1] ?? 0] : undefined;
         // Typical frontmatter uses one inline scalar per key. Avoid building
         // and filling a temporary lines array for that overwhelmingly common
         // case; the scanner-delimited raw slice contains at most its terminal
@@ -190,8 +192,15 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
                 return;
             }
             const val = frontMatter.slice(rawStart, valueEnd);
-            const uncommented = val.includes('#') ? stripComment(val) : val;
-            builder.setMapping(root, key, parseFlowOrScalarValue(uncommented, ctx, line, builder));
+            const hasHash = val.includes('#');
+            const uncommented = hasHash ? stripComment(val) : val;
+            // The physical anchor keeps `\#` but drops a real comment, so a
+            // `${…}`-shaped token inside a trailing comment is not scanned (§2.4).
+            const source = wantSource ? {
+                raw: hasHash ? stripCommentKeepEscapes(val) : val,
+                line, col: valueCol, tabAdjust: lineTabAdjust,
+            } : undefined;
+            builder.setMapping(root, key, parseFlowOrScalarValue(uncommented, ctx, line, builder, source));
             return;
         }
         if (isBlock) {
@@ -217,77 +226,22 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
             const line0Trimmed = lines[0].trim();
             if (lines.length === 1 || line0Trimmed !== '|') {
                 const line0 = lines[0];
-                const val = line0.includes('#') ? stripComment(line0) : line0;
-                builder.setMapping(root, key, parseFlowOrScalarValue(val, ctx, line, builder));
+                const hasHash = line0.includes('#');
+                const val = hasHash ? stripComment(line0) : line0;
+                const source = wantSource ? {
+                    raw: hasHash ? stripCommentKeepEscapes(line0) : line0,
+                    line, col: valueCol, tabAdjust: lineTabAdjust,
+                } : undefined;
+                builder.setMapping(root, key, parseFlowOrScalarValue(val, ctx, line, builder, source));
                 return;
             }
-            // Multi-line string (`|` literal block scalar).
+            // Multi-line string (`|` literal block scalar). The introducing key
+            // is at column 0 here; `buildBlockScalar` finds the scalar's own
+            // extent within the range (which runs to the next top-level key),
+            // so a dedented comment or dedented freetext before that key ends
+            // the scalar rather than being absorbed into it.
             const bodyLines = raw.slice(raw.indexOf('\n') + 1).split('\n');
-            // Avoids trim()/trimStart()/trimEnd() — each allocates a whole new
-            // string just to measure or strip whitespace. leadingSpaces/
-            // trailingSpaceEnd compute the same boundaries by scanning char
-            // codes, and dedent+continuation-strip+trailing-trim collapse
-            // into a single final slice() per line instead of up to three.
-            let minIndent = Infinity;
-            for (const bodyLine of bodyLines) {
-                const indent = leadingSpaces(bodyLine);
-                if (indent === bodyLine.length)
-                    continue; // blank (all spaces, or empty)
-                if (indent < minIndent)
-                    minIndent = indent;
-            }
-            minIndent = Math.min(minIndent, key.length + 2);
-            const trimAmt = minIndent > 1 && isFinite(minIndent) ? minIndent : 0;
-            const mergedLines = [];
-            const mergedLineSpans = builder.tracksStringSourcePositions ? [] : undefined;
-            for (let bodyIndex = 0; bodyIndex < bodyLines.length; bodyIndex++) {
-                const bodyLine = bodyLines[bodyIndex];
-                const lineLen = bodyLine.length;
-                let start = trimAmt < lineLen ? trimAmt : lineLen;
-                const isContinuation = bodyLine.charCodeAt(start) === 94 && bodyLine.charCodeAt(start + 1) === 94; // ^^
-                if (isContinuation)
-                    start += 2;
-                let end = trailingSpaceEnd(bodyLine);
-                if (end < start)
-                    end = start;
-                const content = bodyLine.slice(start, end);
-                if (isContinuation) {
-                    if (mergedLines.length > 0) {
-                        if (content) {
-                            const outputStart = mergedLines[mergedLines.length - 1].length + 1;
-                            mergedLines[mergedLines.length - 1] += ' ' + content;
-                            mergedLineSpans?.[mergedLineSpans.length - 1].push({
-                                start: outputStart, line: line + 1 + bodyIndex, sourceOffset: start,
-                            });
-                        }
-                    }
-                    else {
-                        mergedLines.push(content);
-                        mergedLineSpans?.push(content ? [{ start: 0, line: line + 1 + bodyIndex, sourceOffset: start }] : []);
-                    }
-                }
-                else {
-                    mergedLines.push(content);
-                    mergedLineSpans?.push(content ? [{ start: 0, line: line + 1 + bodyIndex, sourceOffset: start }] : []);
-                }
-            }
-            while (mergedLines.length > 0 && mergedLines[mergedLines.length - 1] === '') {
-                mergedLines.pop();
-                mergedLineSpans?.pop();
-            }
-            const joined = mergedLines.join('\n');
-            let sourceSpans;
-            if (mergedLineSpans) {
-                sourceSpans = [];
-                let outputStart = 0;
-                for (let i = 0; i < mergedLines.length; i++) {
-                    for (const span of mergedLineSpans[i])
-                        sourceSpans.push({ ...span, start: outputStart + span.start });
-                    outputStart += mergedLines[i].length + 1;
-                }
-            }
-            checkScalarLimit(LString(joined), line);
-            builder.setMapping(root, key, builder.string(joined, line + 1, false, sourceSpans));
+            builder.setMapping(root, key, buildBlockScalar(bodyLines, 0, line, ctx, builder).value);
         }
     };
     // A recognised top-level entry needs at least one UTF-16 unit of key text,
@@ -336,7 +290,7 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
         for (let i = 0; i < keyCount; i++) {
             const m = matches[i];
             const rawDQ = m.doubleQuotedRaw;
-            const key = m.unquoted ?? m.singleQuoted ?? (rawDQ !== undefined ? unescapeDQ(rawDQ) : undefined);
+            const key = m.unquoted ?? m.singleQuoted ?? (rawDQ !== undefined ? unescapeDQ(rawDQ, strict, m.line) : undefined);
             if (key !== undefined)
                 parseEntry(key, m.line, m.rawStart, m.isBlock, m.inlineEnd, i + 1 < keyCount ? matches[i + 1].matchStart : frontMatter.length);
         }

package/dist/flow.d.ts

@@ -1,7 +1,8 @@
 /** Core §15.8 flow collections: `[...]` sequences and `{...}` mappings. */
 import { type ParseContext } from './normalize.js';
 import type { ValueBuilder } from './builder.js';
-export declare const parseFlowSequence: <V, M>(val: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>) => V[] | null;
-export declare const parseFlowMapping: <V, M>(val: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>) => V | null;
+import type { ReferenceSource } from './reference-tokens2.js';
+export declare const parseFlowSequence: <V, M>(val: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>, source?: ReferenceSource) => V[] | null;
+export declare const parseFlowMapping: <V, M>(val: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>, source?: ReferenceSource) => V | null;
 /** Parses a value that may be a flow collection, without probing both flow parsers for ordinary scalars. */
-export declare const parseFlowOrScalarValue: <V, M>(raw: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>) => V;
+export declare const parseFlowOrScalarValue: <V, M>(raw: string, ctx: ParseContext, line: number, builder: ValueBuilder<V, M>, source?: ReferenceSource) => V;

package/dist/flow.js

@@ -1,8 +1,65 @@
 /** Core §15.8 flow collections: `[...]` sequences and `{...}` mappings. */
 import { checkKeyLength, checkDuplicateKey } from './normalize.js';
-import { parseQuotedOrTyped, parseScalarValue, stripKeyQuotes } from './scalars.js';
+import { parseQuotedOrTyped, parseScalarValue, stripKeyQuotes, closingQuoteIndex, isValidKey } from './scalars.js';
 import { LimaError } from './errors.js';
 import { isTrimWhitespace } from './chars.js';
+/**
+ * Maps a UTF-16 offset in the decoded container `val` to the corresponding
+ * offset in the physical container `raw`. The two differ only by `\#` → `#`
+ * collapses outside quoted strings (FR-5 keeps `\#` inside quotes), so every
+ * `#` in `val` outside a quote is one such collapse — `raw` has `\#` there.
+ * Brackets, commas, quotes and quoted content are identical in both.
+ */
+const rawOffsetOf = (raw, val, valOffset) => {
+    let ri = 0;
+    let vi = 0;
+    let quote = 0;
+    while (vi < valOffset) {
+        const vc = val.charCodeAt(vi);
+        if (quote) {
+            if (vc === 92) {
+                vi += 2;
+                ri += 2;
+                continue;
+            } // escaped pair, identical in both
+            if (vc === quote)
+                quote = 0;
+        }
+        else if (vc === 34 || vc === 39) {
+            quote = vc;
+        }
+        else if (vc === 35) {
+            vi += 1;
+            ri += 2;
+            continue; // '#' in the decoded container ⇐ '\#' in raw
+        }
+        vi += 1;
+        ri += 1;
+    }
+    return ri;
+};
+/**
+ * The `ReferenceSource` for a flow element spanning UTF-16 `[start, end)` in
+ * the decoded container `val`. The element's physical column is the
+ * container's column plus the *codepoint* distance to the element's start in
+ * the physical text, and its `raw` is the physical element slice — so a
+ * token's reported position (References §2.4) and §5 left-to-right ordering
+ * are correct even when an earlier `\#` widened the source. `source.raw` is
+ * the physical container (equal to `val` when the value carried no `\#`).
+ */
+const elementSource = (source, val, start, end) => {
+    if (source === undefined)
+        return undefined;
+    const raw = source.raw ?? val;
+    const rs = rawOffsetOf(raw, val, start);
+    const re = rawOffsetOf(raw, val, end);
+    return {
+        line: source.line,
+        col: source.col + [...raw.slice(0, rs)].length,
+        raw: raw.slice(rs, re),
+        tabAdjust: source.tabAdjust,
+    };
+};
 const trimStart = (source, start, end) => {
     while (start < end && isTrimWhitespace(source.charCodeAt(start)))
         start++;
@@ -61,7 +118,7 @@ class FlowCursor {
 }
 const isNestedFlowConstruct = (item) => (item.charCodeAt(0) === 91 && item.charCodeAt(item.length - 1) === 93) ||
     (item.charCodeAt(0) === 123 && item.charCodeAt(item.length - 1) === 125);
-export const parseFlowSequence = (val, ctx, line, builder) => {
+export const parseFlowSequence = (val, ctx, line, builder, source) => {
     if (val.charCodeAt(0) !== 91 || val.charCodeAt(val.length - 1) !== 93)
         return null;
     const innerStart = trimStart(val, 1, val.length - 1);
@@ -90,17 +147,34 @@ export const parseFlowSequence = (val, ctx, line, builder) => {
             });
         }
         if (item.charCodeAt(0) === 123 && item.charCodeAt(item.length - 1) === 125) {
-            const nested = parseFlowMapping(item, ctx, line, builder);
+            const nested = parseFlowMapping(item, ctx, line, builder, elementSource(source, val, start, end));
             if (nested !== null) {
                 items.push(nested);
                 continue;
             }
         }
-        items.push(parseQuotedOrTyped(item, ctx, line, false, builder));
+        items.push(parseQuotedOrTyped(item, ctx, line, builder, elementSource(source, val, start, end)));
     }
     return items;
 };
-export const parseFlowMapping = (val, ctx, line, builder) => {
+/**
+ * Index of the key/value `: ` separator within a flow-mapping item — the
+ * first `: ` that is not inside a quoted key (§5.1). Returns -1 when the
+ * item has no separator.
+ */
+const flowItemSeparator = (val, start, end) => {
+    let scan = start;
+    if (val.charCodeAt(start) === 34 || val.charCodeAt(start) === 39) {
+        // §5.2: a single-quoted key is literal, so its first `'` closes.
+        const close = closingQuoteIndex(val.slice(start, end), false);
+        if (close === -1)
+            return -1;
+        scan = start + close + 1;
+    }
+    const sep = val.indexOf(': ', scan);
+    return sep === -1 || sep >= end ? -1 : sep;
+};
+export const parseFlowMapping = (val, ctx, line, builder, source) => {
     if (val.charCodeAt(0) !== 123 || val.charCodeAt(val.length - 1) !== 125)
         return null;
     const innerStart = trimStart(val, 1, val.length - 1);
@@ -117,8 +191,8 @@ export const parseFlowMapping = (val, ctx, line, builder) => {
                 throw new LimaError({ code: 'INVALID_FLOW_SYNTAX', line, message: `Lima: empty element in flow mapping at line ${line}` });
             continue;
         }
-        const colonPos = val.indexOf(': ', itemStart);
-        if (colonPos === -1 || colonPos >= itemEnd) {
+        const colonPos = flowItemSeparator(val, itemStart, itemEnd);
+        if (colonPos === -1) {
             if (ctx.strict)
                 throw new LimaError({
                     code: 'INVALID_FLOW_SYNTAX', line,
@@ -128,8 +202,15 @@ export const parseFlowMapping = (val, ctx, line, builder) => {
         }
         const keyStart = trimStart(val, itemStart, colonPos);
         const keyEnd = trimEnd(val, keyStart, colonPos);
-        const key = stripKeyQuotes(val.slice(keyStart, keyEnd));
-        checkKeyLength(key, () => line);
+        const keyRaw = val.slice(keyStart, keyEnd);
+        if (!isValidKey(keyRaw)) {
+            // §5.1: an unquoted key with a space/dot, or a malformed quoted
+            // key, is not a key. Skip the item in both modes (§10's strict
+            // list is closed and does not cover this — same as the top level).
+            continue;
+        }
+        const key = stripKeyQuotes(keyRaw, ctx.strict, line);
+        checkKeyLength(key, line);
         if (ctx.strict || ctx.onWarning !== undefined) {
             checkDuplicateKey(builder.hasMappingKey(entries, key), key, line, ctx);
         }
@@ -139,24 +220,24 @@ export const parseFlowMapping = (val, ctx, line, builder) => {
         if (isNestedFlowConstruct(rawVal)) {
             throw new LimaError({ code: 'INVALID_FLOW_SYNTAX', line, message: `Lima: invalid flow nesting at line ${line}: "${rawVal}"` });
         }
-        builder.setMapping(entries, key, parseQuotedOrTyped(rawVal, ctx, line, false, builder));
+        builder.setMapping(entries, key, parseQuotedOrTyped(rawVal, ctx, line, builder, elementSource(source, val, valueStart, valueEnd)));
     }
     return builder.mapping(entries, line);
 };
 /** Parses a value that may be a flow collection, without probing both flow parsers for ordinary scalars. */
-export const parseFlowOrScalarValue = (raw, ctx, line, builder) => {
+export const parseFlowOrScalarValue = (raw, ctx, line, builder, source) => {
     const first = raw.charCodeAt(0);
     if (first === 91) {
-        const sequence = parseFlowSequence(raw, ctx, line, builder);
+        const sequence = parseFlowSequence(raw, ctx, line, builder, source);
         if (sequence !== null)
             return builder.array(sequence, line);
-        return parseScalarValue(raw, ctx, line, builder);
+        return parseScalarValue(raw, ctx, line, builder, source);
     }
     else if (first === 123) {
-        const mapping = parseFlowMapping(raw, ctx, line, builder);
+        const mapping = parseFlowMapping(raw, ctx, line, builder, source);
         if (mapping !== null)
             return mapping;
-        return parseScalarValue(raw, ctx, line, builder);
+        return parseScalarValue(raw, ctx, line, builder, source);
     }
-    return parseQuotedOrTyped(raw, ctx, line, true, builder);
+    return parseQuotedOrTyped(raw, ctx, line, builder, source);
 };

package/dist/normalize.d.ts

@@ -20,6 +20,13 @@ export type Diagnostic = {
 export type ParseContext = {
     strict: boolean;
     onWarning?: (diagnostic: Diagnostic) => void;
+    /**
+     * Per-line (0-based) count of columns added by Core §3 leading-tab
+     * expansion — subtracted from a References 2.0 token's column so it
+     * reports its position in the *original* source (§2.4), not the
+     * tab-expanded one. Absent when the document had no tabs.
+     */
+    tabAdjust?: number[];
 };
 export declare const DOCUMENT_SIZE_LIMIT = 65536;
 export declare const KEY_LENGTH_LIMIT = 128;
@@ -28,14 +35,6 @@ export declare const NESTING_DEPTH_LIMIT = 16;
 export declare const byteLength: (s: string) => number;
 export declare const checkStringLimit: (value: string, line: number) => void;
 export declare const checkScalarLimit: (v: LimaValue, line: number) => void;
-/**
- * `line` is a thunk, not a plain number: computing a top-level key's line
- * can trigger an O(document length) scan (see `keyLine` in core.ts) the very
- * first time it's called, and this check runs for every key in the
- * document. Evaluating it eagerly would pay that cost on every parse, even
- * though the overwhelming majority of keys never violate the limit — the
- * thunk defers it to the one branch that actually needs a line number.
- */
-export declare const checkKeyLength: (key: string, line: () => number) => void;
+export declare const checkKeyLength: (key: string, line: number) => void;
 export declare const checkDuplicateKey: (exists: boolean, key: string, line: number, ctx: ParseContext) => void;
 export declare const checkDuplicateKeyMap: (entries: Map<string, unknown>, key: string, line: number, ctx: ParseContext) => void;

package/dist/normalize.js

@@ -28,20 +28,11 @@ export const checkScalarLimit = (v, line) => {
     if (v.kind === 'string')
         checkStringLimit(v.value, line);
 };
-/**
- * `line` is a thunk, not a plain number: computing a top-level key's line
- * can trigger an O(document length) scan (see `keyLine` in core.ts) the very
- * first time it's called, and this check runs for every key in the
- * document. Evaluating it eagerly would pay that cost on every parse, even
- * though the overwhelming majority of keys never violate the limit — the
- * thunk defers it to the one branch that actually needs a line number.
- */
 export const checkKeyLength = (key, line) => {
     if (key.length > KEY_LENGTH_LIMIT && codepointLength(key) > KEY_LENGTH_LIMIT) {
-        const l = line();
         throw new LimaError({
-            code: 'RESOURCE_LIMIT', line: l,
-            message: `Lima: key "${key}" exceeds maximum length of ${KEY_LENGTH_LIMIT} code points at line ${l}`,
+            code: 'RESOURCE_LIMIT', line,
+            message: `Lima: key "${key}" exceeds maximum length of ${KEY_LENGTH_LIMIT} code points at line ${line}`,
         });
     }
 };

package/dist/positioned-tree.d.ts

@@ -0,0 +1,73 @@
+/** Position-annotated tree helpers shared by frozen References 1.0 and active References 2.0; contains no reference grammar or resolution logic. */
+import { type InsertedAt, type NativeValue, type PositionedValue } from './core.js';
+import { type LimaValue } from './value.js';
+type Meta = Record<string, unknown>;
+/** Every Lima mapping result must be a prototype-free object. */
+export declare const emptyMapping: () => Meta;
+/**
+ * Structural deep copy for document-derived targets — preserves each leaf's
+ * own line/quoted (§4.2/R-104: still eligible for further resolution) and
+ * any existing `insertedAt` provenance from an earlier, nested resolution
+ * (R-112: a reference copied wholesale into a new position can itself
+ * already contain the result of an inner reference that resolved first —
+ * both insertion sites remain identifiable participants after the copy).
+ */
+export declare const deepCopyPositioned: (v: PositionedValue) => PositionedValue;
+/**
+ * Wraps a partial's ingested value into the annotated representation, with
+ * every string leaf marked permanently inert (§3.8: "no traversal into
+ * partial values" — the resolution phases must never rediscover a
+ * reference-like substring inside partial content). Called once per partial
+ * name at ingestion (see the call site), producing the one canonical tree
+ * every pure reference to that partial retrieves — deep-copying it on every
+ * such reference (§3.1) is the resolveTree call site's job, not this one.
+ */
+export declare const partialToPositioned: (v: LimaValue, line: number) => PositionedValue;
+/**
+ * References §5/R-112 (nesting depth), §6.2 (node count), and the public
+ * result shape (native conversion) computed together in one recursive pass
+ * over the final, post-substitution tree — instead of three independent
+ * full-tree walks (a depth-only pass, a count-only pass, then
+ * `toNativeFromPositioned`), each of which would otherwise revisit every
+ * node of what can be a large, reference-expanded result. Depth attribution
+ * needs more than a depth number: it needs to know which reference
+ * insertions lie on the actual deepest path, so the earliest of those (by
+ * line) can be blamed if the limit is exceeded — ties for "deepest child"
+ * all count, since a violation can be reached via more than one
+ * maximal-depth branch. `native` is still built unconditionally even
+ * though a depth/node-count violation elsewhere in the document means it
+ * will be discarded and never returned — cheaper than adding a second
+ * conditional branch to every call site, and the discarded case is the
+ * rare (error) path, not the one this pass exists to speed up.
+ *
+ * Each array/mapping branch tracks a running max depth and its participant
+ * list in a single loop over its children, instead of first materializing a
+ * full array of child results and then doing separate `.map()`/`Math.max`/
+ * `.filter().flatMap()` passes over it — for a wide sibling group (many
+ * children at the same depth, the common shape for flat documents with many
+ * top-level references) that would mean an extra full pass per level on top
+ * of the traversal itself. A running accumulator only ever copies-on-write:
+ * `.slice()` when a strictly greater depth replaces the running set, plain
+ * `.push()` onto that fresh copy for a tie at the current max — never a
+ * mutation of a child's own returned array. Reusing a child's array in
+ * place would currently be safe (each node is visited exactly once, no
+ * aliasing left after the pure-reference deep-copy fix), but relying on
+ * that invariant here has no upside worth the risk in a file that has
+ * already had one real aliasing bug.
+ */
+export type FinalizedValue = {
+    native: NativeValue;
+    nodeCount: number;
+    depth: number;
+    deepestParticipants: InsertedAt[];
+};
+export declare const finalizePositioned: (v: PositionedValue) => FinalizedValue;
+/**
+ * Earliest participant by source position — lowest line, then lowest
+ * character offset (References §5) — or null when none exist (R-113's
+ * "line 1" fallback applies then).
+ */
+export declare const earliestParticipant: (participants: InsertedAt[]) => InsertedAt | null;
+/** Node-count attribution for the RESOURCE_LIMIT error path: every reference insertion anywhere in the tree contributes to the total. */
+export declare const collectAllParticipants: (v: PositionedValue, acc: InsertedAt[]) => void;
+export {};

package/dist/positioned-tree.js

@@ -0,0 +1,123 @@
+/** Position-annotated tree helpers shared by frozen References 1.0 and active References 2.0; contains no reference grammar or resolution logic. */
+import { toNativeFromPositioned, } from './core.js';
+/** Every Lima mapping result must be a prototype-free object. */
+export const emptyMapping = () => Object.create(null);
+/**
+ * Structural deep copy for document-derived targets — preserves each leaf's
+ * own line/quoted (§4.2/R-104: still eligible for further resolution) and
+ * any existing `insertedAt` provenance from an earlier, nested resolution
+ * (R-112: a reference copied wholesale into a new position can itself
+ * already contain the result of an inner reference that resolved first —
+ * both insertion sites remain identifiable participants after the copy).
+ */
+export const deepCopyPositioned = (v) => {
+    switch (v.kind) {
+        case 'array': return { kind: 'array', items: v.items.map(deepCopyPositioned), line: v.line, references2Active: v.references2Active, insertedAt: v.insertedAt, priorInsertions: v.priorInsertions };
+        case 'mapping': {
+            const entries = new Map();
+            for (const [k, c] of v.entries)
+                entries.set(k, deepCopyPositioned(c));
+            return { kind: 'mapping', entries, line: v.line, references2Active: v.references2Active, insertedAt: v.insertedAt, priorInsertions: v.priorInsertions };
+        }
+        case 'instant': return { kind: 'instant', value: new Date(v.value.getTime()), line: v.line, insertedAt: v.insertedAt, priorInsertions: v.priorInsertions };
+        default: return v;
+    }
+};
+/**
+ * Wraps a partial's ingested value into the annotated representation, with
+ * every string leaf marked permanently inert (§3.8: "no traversal into
+ * partial values" — the resolution phases must never rediscover a
+ * reference-like substring inside partial content). Called once per partial
+ * name at ingestion (see the call site), producing the one canonical tree
+ * every pure reference to that partial retrieves — deep-copying it on every
+ * such reference (§3.1) is the resolveTree call site's job, not this one.
+ */
+export const partialToPositioned = (v, line) => {
+    switch (v.kind) {
+        case 'null': return { kind: 'null', line };
+        case 'bool': return { kind: 'bool', value: v.value, line };
+        case 'int': return { kind: 'int', value: v.value, line };
+        case 'float': return { kind: 'float', value: v.value, line };
+        case 'string': return { kind: 'string', value: v.value, line, quoted: true };
+        case 'instant': return { kind: 'instant', value: v.value, line };
+        case 'array': return { kind: 'array', items: v.items.map((i) => partialToPositioned(i, line)), line };
+        case 'mapping': {
+            const entries = new Map();
+            for (const [k, c] of v.entries)
+                entries.set(k, partialToPositioned(c, line));
+            return { kind: 'mapping', entries, line };
+        }
+    }
+};
+export const finalizePositioned = (v) => {
+    const own = v.insertedAt ? [...(v.priorInsertions ?? []), v.insertedAt] : (v.priorInsertions ?? []);
+    if (v.kind === 'array') {
+        if (v.items.length === 0)
+            return { native: [], nodeCount: 1, depth: 1, deepestParticipants: own };
+        const native = new Array(v.items.length);
+        let nodeCount = 1;
+        let maxDepth = -1;
+        let childParticipants = [];
+        for (let i = 0; i < v.items.length; i++) {
+            const r = finalizePositioned(v.items[i]);
+            native[i] = r.native;
+            nodeCount += r.nodeCount;
+            if (r.depth > maxDepth) {
+                maxDepth = r.depth;
+                childParticipants = r.deepestParticipants.slice();
+            }
+            else if (r.depth === maxDepth) {
+                for (const p of r.deepestParticipants)
+                    childParticipants.push(p);
+            }
+        }
+        return { native, nodeCount, depth: 1 + maxDepth, deepestParticipants: own.length ? own.concat(childParticipants) : childParticipants };
+    }
+    if (v.kind === 'mapping') {
+        if (v.entries.size === 0)
+            return { native: emptyMapping(), nodeCount: 1, depth: 1, deepestParticipants: own };
+        const native = emptyMapping();
+        let nodeCount = 1;
+        let maxDepth = -1;
+        let childParticipants = [];
+        for (const [k, c] of v.entries) {
+            const r = finalizePositioned(c);
+            native[k] = r.native;
+            nodeCount += r.nodeCount;
+            if (r.depth > maxDepth) {
+                maxDepth = r.depth;
+                childParticipants = r.deepestParticipants.slice();
+            }
+            else if (r.depth === maxDepth) {
+                for (const p of r.deepestParticipants)
+                    childParticipants.push(p);
+            }
+        }
+        return { native: native, nodeCount, depth: 1 + maxDepth, deepestParticipants: own.length ? own.concat(childParticipants) : childParticipants };
+    }
+    // Scalar leaf: null/bool/int/float/string/instant. No further recursion,
+    // so plain toNativeFromPositioned is exactly the single-node conversion
+    // needed here — reused rather than duplicated.
+    return { native: toNativeFromPositioned(v), nodeCount: 1, depth: 0, deepestParticipants: own };
+};
+/**
+ * Earliest participant by source position — lowest line, then lowest
+ * character offset (References §5) — or null when none exist (R-113's
+ * "line 1" fallback applies then).
+ */
+export const earliestParticipant = (participants) => participants.length === 0
+    ? null
+    : participants.reduce((a, b) => b.line < a.line || (b.line === a.line && (b.offset ?? 0) < (a.offset ?? 0)) ? b : a);
+/** Node-count attribution for the RESOURCE_LIMIT error path: every reference insertion anywhere in the tree contributes to the total. */
+export const collectAllParticipants = (v, acc) => {
+    if (v.priorInsertions)
+        acc.push(...v.priorInsertions);
+    if (v.insertedAt)
+        acc.push(v.insertedAt);
+    if (v.kind === 'array')
+        for (const item of v.items)
+            collectAllParticipants(item, acc);
+    if (v.kind === 'mapping')
+        for (const c of v.entries.values())
+            collectAllParticipants(c, acc);
+};