@limaformat/lima 0.3.0 → 0.4.0

package/dist/reference-tokens2.d.ts

@@ -1,12 +1,43 @@
 /** Reference tokens recorded while the annotated Core tree is being built. */
-import type { StringSourceSpan } from './builder.js';
 export type ReferenceToken2 = {
     token: string;
+    /**
+     * Index of the token within the decoded scalar value — the splice point
+     * for interpolation. A UTF-16 offset (JS `String.slice` units); stays
+     * implementation-local, unlike `line`/`offset`.
+     */
     index: number;
-    offset: number;
+    /** Physical 1-based source line of the token (References 2.0 §2.4). */
     line: number;
+    /**
+     * 0-based **codepoint** offset of the token within its source line — the
+     * `column - 1` a diagnostic reports, and the tie-break key for §5 error
+     * ordering. Identical across implementations.
+     */
+    offset: number;
     documentPath?: string;
     partialPath?: string;
 };
+/**
+ * Where a scalar begins in the source: physical 1-based `line` and 0-based
+ * codepoint column `col` of its first character. A token's position is this
+ * anchor plus its codepoint offset within the value.
+ *
+ * `raw` is the value text a token's position is *read from*, before comment
+ * stripping and `\#` collapse (so `x: a\#b ${t}` reports `${t}` at its real
+ * column) — for a block scalar it is the original body lines joined with
+ * `\n` (§2.4 forbids reconstructing a token's line from the `^^`-merged
+ * string). Omitted only when it equals the decoded value.
+ *
+ * `tabAdjust[i]` is the column count Core §3 added to physical line
+ * `line + i` by leading-tab expansion; it is subtracted so the reported
+ * column is the *original*-source column (§2.4).
+ */
+export type ReferenceSource = {
+    raw?: string;
+    line: number;
+    col: number;
+    tabAdjust?: number[];
+};
 export declare const PURE_REFERENCE_2: RegExp;
-export declare const scanReferenceTokens2: (value: string, firstLine: number, sourceSpans?: StringSourceSpan[]) => ReferenceToken2[];
+export declare const scanReferenceTokens2: (value: string, source: ReferenceSource | undefined) => ReferenceToken2[];

package/dist/reference-tokens2.js

@@ -1,3 +1,4 @@
+/** Reference tokens recorded while the annotated Core tree is being built. */
 const SEGMENT = '[a-zA-Z0-9_][a-zA-Z0-9_:-]*';
 const DOC_PATH = `${SEGMENT}(?:\\.${SEGMENT})*`;
 const PARTIAL_NAME = '[a-zA-Z0-9_][a-zA-Z0-9_:/-]*';
@@ -5,33 +6,65 @@ const PARTIAL_PATH = `${PARTIAL_NAME}(?:\\.${SEGMENT})*`;
 export const PURE_REFERENCE_2 = new RegExp(`^(?:\\$\\{(${DOC_PATH})\\}|\\$\\((${PARTIAL_PATH})\\))$`);
 const REFERENCE_2 = new RegExp(`\\$\\{(${DOC_PATH})\\}|\\$\\((${PARTIAL_PATH})\\)`, 'g');
 const NO_TOKENS = [];
-export const scanReferenceTokens2 = (value, firstLine, sourceSpans) => {
-    if (!value.includes('${') && !value.includes('$('))
-        return NO_TOKENS;
+/** Codepoint length of the UTF-16 slice `[a, b)` of `s`. */
+const codepointLen = (s, a, b) => {
+    let n = 0;
+    for (let i = a; i < b;) {
+        i += s.codePointAt(i) > 0xffff ? 2 : 1;
+        n++;
+    }
+    return n;
+};
+/** Splice points (decoded value order): token text, UTF-16 index, path. */
+const scanDecoded = (value) => {
     REFERENCE_2.lastIndex = 0;
-    const result = [];
-    let line = firstLine;
-    let lineStart = 0;
+    const out = [];
+    for (const m of value.matchAll(REFERENCE_2)) {
+        out.push({
+            token: m[0], index: m.index ?? 0,
+            ...(m[1] !== undefined ? { documentPath: m[1] } : { partialPath: m[2] }),
+        });
+    }
+    return out;
+};
+/** Physical `(line, offset)` of each token, in source order, from the raw text. */
+const scanPhysical = (raw, firstLine, firstCol, tabAdjust) => {
+    REFERENCE_2.lastIndex = 0;
+    const out = [];
     let scanned = 0;
-    let spanIndex = 0;
-    for (const match of value.matchAll(REFERENCE_2)) {
-        const index = match.index ?? 0;
-        while (scanned < index) {
-            if (value.charCodeAt(scanned) === 10) {
+    let line = firstLine;
+    let col = firstCol;
+    let lineIndex = 0;
+    for (const m of raw.matchAll(REFERENCE_2)) {
+        const idx = m.index ?? 0;
+        while (scanned < idx) {
+            const cp = raw.codePointAt(scanned);
+            if (cp === 10) {
                 line++;
-                lineStart = scanned + 1;
+                col = 0;
+                lineIndex++;
             }
-            scanned++;
+            else
+                col++;
+            scanned += cp > 0xffff ? 2 : 1;
         }
-        while (sourceSpans && spanIndex + 1 < sourceSpans.length && sourceSpans[spanIndex + 1].start <= index)
-            spanIndex++;
-        const source = sourceSpans?.[spanIndex];
-        result.push({
-            token: match[0], index,
-            line: source?.line ?? line,
-            offset: source ? source.sourceOffset + index - source.start : index - lineStart,
-            ...(match[1] !== undefined ? { documentPath: match[1] } : { partialPath: match[2] }),
-        });
+        out.push({ line, offset: col - (tabAdjust?.[lineIndex] ?? 0) });
+    }
+    return out;
+};
+export const scanReferenceTokens2 = (value, source) => {
+    if (!value.includes('${') && !value.includes('$('))
+        return NO_TOKENS;
+    const decoded = scanDecoded(value);
+    if (decoded.length === 0)
+        return NO_TOKENS;
+    // The raw and decoded scans see the same tokens in the same order —
+    // `\#` collapse and `^^` merge never add or remove a `${…}` / `$(…)`.
+    const physical = source === undefined
+        ? scanPhysical(value, 1, 0)
+        : scanPhysical(source.raw ?? value, source.line, source.col, source.tabAdjust);
+    if (physical.length !== decoded.length) {
+        throw new Error(`Lima internal: reference token count mismatch (raw ${physical.length}, decoded ${decoded.length})`);
     }
-    return result;
+    return decoded.map((d, i) => ({ ...d, line: physical[i].line, offset: physical[i].offset }));
 };

package/dist/references.d.ts

@@ -20,71 +20,8 @@
  * There is no module-level mutable state: diagnostics are collected in a
  * `ResolutionContext` created fresh per call and threaded explicitly.
  */
-import { type LimaValue } from './value.js';
-import { type PositionedValue, type Diagnostic, type InsertedAt, type NativeValue } from './core.js';
+import { type Diagnostic } from './core.js';
 type Meta = Record<string, unknown>;
-/**
- * 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 (lowest-line) participant, 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 type ReferencesOptions = {
     /** Named values available via `(%key)` references. */
     partials?: Meta;

package/dist/references.js

@@ -21,9 +21,9 @@
  * `ResolutionContext` created fresh per call and threaded explicitly.
  */
 import { countNodes, canonicalString, codepointLength, ingestPartialValue, PARTIAL_COUNT_LIMIT, PARTIAL_NAME_LENGTH_LIMIT, PARTIAL_NODE_LIMIT, RESULT_NODE_LIMIT, SCALAR_LENGTH_LIMIT, } from './value.js';
-import { parseCoreWithPositions, toPlainValue, toNativeFromPositioned, NESTING_DEPTH_LIMIT, } from './core.js';
+import { parseCoreWithPositions, toPlainValue, NESTING_DEPTH_LIMIT, } from './core.js';
 import { LimaError } from './errors.js';
-const emptyMapping = () => Object.create(null);
+import { collectAllParticipants, deepCopyPositioned, earliestParticipant, emptyMapping, finalizePositioned, partialToPositioned, } from './positioned-tree.js';
 // References §2.1/§2.2/Appendix B grammar, per sigil.
 const DOC_SEGMENT = '[a-zA-Z0-9_][a-zA-Z0-9_:-]*';
 const DOC_PATH = `${DOC_SEGMENT}(?:\\.${DOC_SEGMENT})*`;
@@ -102,53 +102,6 @@ const isReferenceFreeP = (v) => {
     referenceFreeCache.set(v, result);
     return result;
 };
-/**
- * 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 };
-        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 };
-        }
-        case 'instant': return { kind: 'instant', value: new Date(v.value.getTime()), line: v.line, insertedAt: v.insertedAt };
-        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 };
-        }
-    }
-};
 /**
  * Recursively resolves reference-shaped string leaves in `node` against
  * `lookup` — the single function both resolution phases share (§4.1's live
@@ -282,70 +235,6 @@ const resolveTree = (node, lookup, partials, ctx) => {
     }
     return node; // null/bool/int/float/instant — nothing to resolve
 };
-export const finalizePositioned = (v) => {
-    const own = v.insertedAt ? [v.insertedAt] : [];
-    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 (lowest-line) participant, 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 : 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.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);
-};
 export const parseReferences = (frontMatter, options) => {
     const strict = options?.strict ?? false;
     const rawPartials = options?.partials ?? {};

package/dist/references2.d.ts

@@ -8,6 +8,8 @@ export type ParseOptions = {
     onWarning?: (diagnostic: Diagnostic) => void;
 };
 export declare const parse: <T extends Record<string, unknown> = Meta>(frontMatter: string, options?: ParseOptions) => T;
+/** Test oracle: exercises the resolver without its dependency-result cache. */
+export declare const __parseWithoutResolveCacheForTest: <T extends Record<string, unknown> = Meta>(frontMatter: string, options?: ParseOptions) => T;
 /** @deprecated Use parse(). */
 export declare const parseReferences: typeof parse;
 export {};

package/dist/references2.js

@@ -3,11 +3,19 @@ import { canonicalString, codepointLength, countNodes, ingestPartialValue, PARTI
 import { NESTING_DEPTH_LIMIT, parseCore, parseCoreWithPositions, toPlainValue, } from './core.js';
 import { hasActiveReferences2 } from './scalars.js';
 import { LimaError } from './errors.js';
-import { collectAllParticipants, deepCopyPositioned, earliestParticipant, finalizePositioned, partialToPositioned, } from './references.js';
-const emptyMapping = () => Object.create(null);
+import { collectAllParticipants, deepCopyPositioned, earliestParticipant, emptyMapping, finalizePositioned, partialToPositioned, } from './positioned-tree.js';
 const PARTIAL_NAME = '[a-zA-Z0-9_][a-zA-Z0-9_:/-]*';
 const PARTIAL_NAME_RE = new RegExp(`^${PARTIAL_NAME}$`);
 const MAX_EDGES = 3;
+/** Copies a pure-reference target and stamps the new insertion without
+ * discarding provenance already attached to the copied root (R-112). */
+const copyWithInsertion = (target, insertedAt) => {
+    const copy = deepCopyPositioned(target);
+    const priorInsertions = copy.insertedAt === undefined
+        ? copy.priorInsertions
+        : [...(copy.priorInsertions ?? []), copy.insertedAt];
+    return { ...copy, insertedAt, priorInsertions };
+};
 const addDiagnostic = (ctx, diagnostic, offset = 0) => {
     ctx.diagnostics.push({ ...diagnostic, offset });
 };
@@ -23,8 +31,18 @@ const lookupPath = (root, segments) => {
 };
 const documentTarget = (root, path) => {
     const segments = path.split('.');
-    const value = root.get(segments[0]);
-    return value === undefined ? undefined : { root: value, tail: segments.slice(1) };
+    let value = root.get(segments[0]);
+    if (value === undefined)
+        return undefined;
+    let index = 1;
+    while (index < segments.length && value.kind === 'mapping') {
+        const child = value.entries.get(segments[index]);
+        if (child === undefined)
+            return undefined;
+        value = child;
+        index++;
+    }
+    return { root: value, tail: segments.slice(index) };
 };
 const lookupPartial = (partials, path) => {
     const dot = path.indexOf('.');
@@ -65,9 +83,9 @@ const resolveNodeUncached = (node, document, partials, ctx, remainingEdges, stac
                 const match = tokenMatches(item)[0];
                 const token = match?.token ?? item.value;
                 addDiagnostic(ctx, {
-                    code: 'INVALID_REFERENCE_SHAPE', line: item.line, token,
-                    message: `Lima: reference "${token}" resolves to an array, which cannot be inserted as a sequence item at line ${item.line}`,
-                });
+                    code: 'INVALID_REFERENCE_SHAPE', line: match?.line ?? item.line, token,
+                    message: `Lima: reference "${token}" resolves to an array, which cannot be inserted as a sequence item at line ${match?.line ?? item.line}`,
+                }, match?.offset ?? 0);
                 return item;
             }
             return result.value;
@@ -110,8 +128,10 @@ const resolveNodeUncached = (node, document, partials, ctx, remainingEdges, stac
         if (target === undefined || stack.has(target))
             return { value: node, complete: false };
         if (pure.partialPath !== undefined) {
+            // `partialToPositioned` never annotates partial targets: partials are
+            // inert and have no source token before this document insertion.
             return {
-                value: { ...deepCopyPositioned(target), insertedAt: { line: pure.line, token: pure.token } },
+                value: copyWithInsertion(target, { line: pure.line, offset: pure.offset, token: pure.token }),
                 complete: true,
             };
         }
@@ -124,7 +144,9 @@ const resolveNodeUncached = (node, document, partials, ctx, remainingEdges, stac
         if (selected === undefined)
             return { value: node, complete: false };
         return {
-            value: { ...deepCopyPositioned(selected), insertedAt: { line: pure.line, token: pure.token } },
+            // `selected` may itself be the root inserted by an earlier reference;
+            // both it and this outer copy participate in final-structure errors.
+            value: copyWithInsertion(selected, { line: pure.line, offset: pure.offset, token: pure.token }),
             complete: true,
         };
     }
@@ -172,13 +194,24 @@ const resolveNodeUncached = (node, document, partials, ctx, remainingEdges, stac
     }
     return { value: { ...node, value: output, references2: unresolvedTokens }, complete };
 };
-/** Successful and failed dependency results are immutable and budget-specific. */
+/**
+ * The cache key is complete without `stack`: for a fixed node and edge
+ * budget, its outgoing targets and traversal order are fixed by the parsed
+ * document. If one of those targets is already on the current stack, that
+ * target is on a dependency cycle reachable from this node; entering from a
+ * different ancestor cannot make the cycle complete, and the monotonically
+ * decreasing edge budget fixes where an overlong path becomes unresolved.
+ * Thus `stack` only detects an already-inevitable incomplete dependency; it
+ * does not select a different successful value. Top-level calls are excluded
+ * (`stack.size > 1`) and cached Resolution trees are immutable, so sharing a
+ * successful or incomplete result at the same remaining budget is safe.
+ */
 const resolveNode = (node, document, partials, ctx, remainingEdges, stack) => {
-    const cacheable = stack.size > 1 && (node.kind === 'array' || node.kind === 'mapping' ||
-        (isActiveString(node) && tokenMatches(node).length > 0));
-    if (!cacheable)
+    const cache = ctx.cache;
+    if (cache === undefined || stack.size <= 1 || !(node.kind === 'array' || node.kind === 'mapping' ||
+        (isActiveString(node) && tokenMatches(node).length > 0)))
         return resolveNodeUncached(node, document, partials, ctx, remainingEdges, stack);
-    const byBudget = ctx.cache.get(node);
+    const byBudget = cache.get(node);
     const cached = byBudget?.get(remainingEdges);
     if (cached !== undefined)
         return cached;
@@ -186,7 +219,7 @@ const resolveNode = (node, document, partials, ctx, remainingEdges, stack) => {
     if (byBudget !== undefined)
         byBudget.set(remainingEdges, result);
     else
-        ctx.cache.set(node, new Map([[remainingEdges, result]]));
+        cache.set(node, new Map([[remainingEdges, result]]));
     return result;
 };
 const validatePartials = (raw) => {
@@ -233,7 +266,7 @@ const scanUnresolved = (node, ctx) => {
         for (const child of node.entries.values())
             scanUnresolved(child, ctx);
 };
-export const parse = (frontMatter, options) => {
+const parseInternal = (frontMatter, options, useResolveCache) => {
     if (options?.mode !== undefined && options.mode !== 'core' && options.mode !== 'references') {
         throw new TypeError(`Lima: invalid parse mode "${String(options.mode)}"`);
     }
@@ -250,7 +283,7 @@ export const parse = (frontMatter, options) => {
         return parseCore(frontMatter, options);
     }
     const document = parseCoreWithPositions(frontMatter, { strict: options?.strict ?? false, onWarning: options?.onWarning });
-    const ctx = { diagnostics: [], cache: new WeakMap() };
+    const ctx = { diagnostics: [], ...(useResolveCache ? { cache: new WeakMap() } : {}) };
     const resolved = new Map();
     for (const [key, value] of document) {
         const stack = new Set([value]);
@@ -261,7 +294,10 @@ export const parse = (frontMatter, options) => {
             scanUnresolved(value, ctx);
     if (ctx.diagnostics.length > 0) {
         ctx.diagnostics.sort((a, b) => a.line - b.line || a.offset - b.offset);
-        throw new LimaError(ctx.diagnostics[0]);
+        const winner = ctx.diagnostics[0];
+        // §2.4: expose the token's physical position (1-based) — Rust and Go
+        // already do; `offset` was internal-only here.
+        throw new LimaError({ ...winner, column: winner.offset + 1 });
     }
     const finalized = [...resolved].map(([key, value]) => [key, finalizePositioned(value)]);
     const depth = finalized.length === 0 ? 0 : Math.max(...finalized.map(([, value]) => value.depth));
@@ -270,6 +306,7 @@ export const parse = (frontMatter, options) => {
         const winner = earliestParticipant(participants);
         throw new LimaError({
             code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
+            ...(winner?.offset !== undefined ? { column: winner.offset + 1 } : {}),
             message: `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line ${winner?.line ?? 1}`,
         });
     }
@@ -283,6 +320,7 @@ export const parse = (frontMatter, options) => {
         const winner = earliestParticipant(participants);
         throw new LimaError({
             code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
+            ...(winner?.offset !== undefined ? { column: winner.offset + 1 } : {}),
             message: `Lima: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line ${winner?.line ?? 1}`,
         });
     }
@@ -291,5 +329,8 @@ export const parse = (frontMatter, options) => {
         out[key] = value.native;
     return out;
 };
+export const parse = (frontMatter, options) => parseInternal(frontMatter, options, true);
+/** Test oracle: exercises the resolver without its dependency-result cache. */
+export const __parseWithoutResolveCacheForTest = (frontMatter, options) => parseInternal(frontMatter, options, false);
 /** @deprecated Use parse(). */
 export const parseReferences = parse;