@limaformat/lima 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -10,7 +10,31 @@ and [Lima References
 1.0](https://github.com/limaformat/lima/blob/main/docs/lima-references-1.0-spec.md)
 are both frozen regardless of what this file shows.
 
-## [0.1.0] — Unreleased
+## [Unreleased]
+
+## [0.2.0] — 2026-08-11
+
+### Changed
+
+- **Breaking:** `parse(input, options?)` now implements Lima References 2.0.
+  Document references use `$(key)` instead of `($key)`, and partial
+  references use `$(:key)` instead of `(%key)`. References 1.0 tokens are
+  literal text through the public 2.0 API.
+- `parseReferences(input, options?)` is now a deprecated compatibility alias
+  for `parse` with identical References 2.0 results and diagnostics. It is not
+  a References 1.0 mode.
+- `ParseOptions.mode` selects `"references"` (the default) or `"core"`.
+  Core mode uses the same reference-unaware path as `parseCore`; supplying
+  `partials` in Core mode is invalid. `parseCore` itself is unchanged.
+- References 2.0 adds bounded transitive resolution (at most three reference
+  edges), partial mapping traversal, and `$(:namespace/name.path)` partials.
+- Error message prefix `LIMA:` → `Lima:` throughout (e.g. `LIMA: duplicate
+  key "a" at line 3` → `Lima: duplicate key "a" at line 3`), plus internal
+  code comments — naming-consistency fix, no functional change. `.code`
+  (the stable, documented field for programmatic error handling) is
+  unaffected; message text was never a documented stable API surface.
+
+## [0.1.0] — 2026-08-05
 
 Initial release.
 

package/README.md

@@ -1,5 +1,7 @@
 # @limaformat/lima
 
+[![npm version](https://img.shields.io/npm/v/%40limaformat%2Flima.svg)](https://www.npmjs.com/package/@limaformat/lima)
+
 **LIMA Is Metadata Annotation** — a small, predictable frontmatter format.
 A deliberate, focused subset of YAML: the part frontmatter actually needs,
 with well-defined types, no surprises, and zero runtime dependencies.
@@ -33,30 +35,33 @@ tags:
 `parse` accepts the raw content **between** the frontmatter delimiters
 (`---`) — stripping them is the caller's job.
 
-Two functions are exported:
+Three functions are exported:
 
 - `parseCore(input, options?)` — the base format only.
-- `parse(input, options?)` (alias for `parseReferences`) — adds
-  `($key)` document references and `(%key)` external partials.
+- `parse(input, options?)` — the primary References 2.0 parser; adds
+  `$(key)` document references and `$(:key)` external partials.
+- `parseReferences(input, options?)` — deprecated compatibility alias for
+  `parse` with the same References 2.0 semantics.
 
 ```ts
 parse(frontmatter, { strict: true })
 parse(frontmatter, { partials: { author: 'Alice' } })
+parse(frontmatter, { mode: 'core' }) // same reference-unaware path as parseCore
 ```
 
-Full syntax reference, the References extension, resource limits, strict
-mode, and the complete API:
-**[docs/guide.md](https://github.com/limaformat/lima/blob/main/docs/guide.md)**.
+The **[guide](https://github.com/limaformat/lima/blob/main/docs/guide.md)**
+covers Core and References 2.0 syntax, resource limits, strict mode, and the
+public API. The normative rules are defined in the
+**[References 2.0 specification](https://github.com/limaformat/lima/blob/main/docs/lima-references-2.0-spec.md)**.
 
 Why Lima exists, the case against YAML, and security rationale:
 **[repository README](https://github.com/limaformat/lima#readme)**.
 
 The [Lima Core 1.0](https://github.com/limaformat/lima/blob/main/docs/lima-core-1.0-spec.md)
-and [Lima References 1.0](https://github.com/limaformat/lima/blob/main/docs/lima-references-1.0-spec.md)
-specifications are the normative source of truth — this package implements
-them exactly, verified against a
-[250-case conformance corpus](https://github.com/limaformat/lima/tree/main/corpus)
-(count pinned by a test) shared with any other Lima implementation.
+and [Lima References 2.0](https://github.com/limaformat/lima/blob/main/docs/lima-references-2.0-spec.md)
+specifications are the source of truth for these public entry points. The
+frozen References 1.0 implementation remains available internally to run its
+independent conformance suite.
 
 Migrating existing YAML frontmatter:
 [docs/migrating-from-yaml.md](https://github.com/limaformat/lima/blob/main/docs/migrating-from-yaml.md).

package/dist/block.js

@@ -108,14 +108,14 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
                 else {
                     if (ctx.strict)
                         throw new LimaError({ code: 'INVALID_INDENTATION', line,
-                            message: `LIMA: unexpected syntax in array item continuation at line ${line}: "${trimmed}"` });
+                            message: `Lima: unexpected syntax in array item continuation at line ${line}: "${trimmed}"` });
                     cursor.next();
                 }
             }
             else {
                 if (ctx.strict)
                     throw new LimaError({ code: 'INVALID_INDENTATION', line,
-                        message: `LIMA: unexpected indentation at line ${line}: "${trimmed}"` });
+                        message: `Lima: unexpected indentation at line ${line}: "${trimmed}"` });
                 cursor.next();
             }
             continue;
@@ -130,7 +130,7 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
             if (entries !== null) {
                 if (ctx.strict)
                     throw new LimaError({ code: 'INVALID_INDENTATION', line,
-                        message: `LIMA: mixed array and map entries for the same key at line ${line}` });
+                        message: `Lima: mixed array and map entries for the same key at line ${line}` });
                 cursor.next();
                 continue;
             }
@@ -153,7 +153,7 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
             else if (afterDash === '-' || DASH_PREFIX_RE.test(afterDash)) {
                 if (ctx.strict)
                     throw new LimaError({ code: 'INVALID_INDENTATION', line,
-                        message: `LIMA: nested block sequence at line ${line}: "${cursorContent(cursor)}"` });
+                        message: `Lima: nested block sequence at line ${line}: "${cursorContent(cursor)}"` });
                 items.push(builder.null(line));
                 cursor.next();
                 while (cursor.valid) {
@@ -237,7 +237,7 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
             if (items !== null) {
                 if (ctx.strict)
                     throw new LimaError({ code: 'INVALID_INDENTATION', line,
-                        message: `LIMA: mixed map and array entries for the same key at line ${line}` });
+                        message: `Lima: mixed map and array entries for the same key at line ${line}` });
                 cursor.next();
                 continue;
             }
@@ -275,7 +275,7 @@ const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
             else {
                 if (ctx.strict)
                     throw new LimaError({ code: 'INVALID_INDENTATION', line,
-                        message: `LIMA: indented freetext without a block scalar marker at line ${line}: "${trimmed}"` });
+                        message: `Lima: indented freetext without a block scalar marker at line ${line}: "${trimmed}"` });
                 cursor.next();
             }
         }

package/dist/builder.d.ts

@@ -25,11 +25,13 @@
  * therefore performance — is identical either way, verified by benchmark.
  */
 export interface ValueBuilder<V, M = Map<string, V>> {
+    /** Opt-in for References' annotated builder; native Core avoids source-map work. */
+    readonly tracksStringSourcePositions?: boolean;
     null(line: number): V;
     bool(value: boolean, line: number): V;
     int(value: number, line: number): V;
     float(value: number, line: number): V;
-    string(value: string, line: number, quoted: boolean): V;
+    string(value: string, line: number, quoted: boolean, sourceSpans?: StringSourceSpan[]): V;
     instant(value: Date, line: number): V;
     array(items: V[], line: number): V;
     createMapping(): M;
@@ -39,3 +41,9 @@ export interface ValueBuilder<V, M = Map<string, V>> {
     mappingMaxDepth(entries: M, depthOf: (value: V) => number): number;
     mapping(entries: M, line: number): V;
 }
+/** Maps a span in a decoded scalar back to its physical source line/column. */
+export type StringSourceSpan = {
+    start: number;
+    line: number;
+    sourceOffset: number;
+};

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 /**
- * LIMA Core 1.0 parser — reference-unaware by construction (Appendix B:
+ * Lima Core 1.0 parser — reference-unaware by construction (Appendix B:
  * reference resolution is exclusively the concern of the optional
  * References extension). `($key)`/`(%key)`-shaped text is never
  * recognised or coerced here; it simply falls through as an ordinary
@@ -33,7 +33,7 @@ export type CoreOptions = {
     onWarning?: (diagnostic: Diagnostic) => void;
 };
 /**
- * Parses LIMA Core 1.0 syntax into the internal annotated value tree —
+ * Parses Lima Core 1.0 syntax into the internal annotated value tree —
  * every node carrying its source line, string leaves additionally carrying
  * whether they came from quoted syntax. `($key)`/`(%key)` text is left
  * exactly as written; nothing here ever inspects or resolves it. The

package/dist/core.js

@@ -1,5 +1,5 @@
 /**
- * LIMA Core 1.0 parser — reference-unaware by construction (Appendix B:
+ * Lima Core 1.0 parser — reference-unaware by construction (Appendix B:
  * reference resolution is exclusively the concern of the optional
  * References extension). `($key)`/`(%key)`-shaped text is never
  * recognised or coerced here; it simply falls through as an ordinary
@@ -89,7 +89,7 @@ const lineAt = (s, pos) => {
     return n;
 };
 /**
- * Parses LIMA Core 1.0 syntax, generic over the output representation
+ * Parses Lima Core 1.0 syntax, generic over the output representation
  * (`builder` — see `builder.ts`): References needs the annotated
  * `PositionedValue` tree (`parseCoreWithPositions` below fixes `V` to
  * that), while `parseCore` fixes `V` to the public native shape directly,
@@ -111,7 +111,7 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
         byteLength(frontMatter) > DOCUMENT_SIZE_LIMIT) {
         throw new LimaError({
             code: 'RESOURCE_LIMIT', line: 1,
-            message: `LIMA: document exceeds maximum size of ${DOCUMENT_SIZE_LIMIT} bytes at line 1`,
+            message: `Lima: document exceeds maximum size of ${DOCUMENT_SIZE_LIMIT} bytes at line 1`,
         });
     }
     const root = builder.createMapping();
@@ -154,7 +154,7 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
             if (SPACE_BEFORE_COLON_RE.test(line)) {
                 throw new LimaError({
                     code: 'INVALID_QUOTE', line: lineAt(frontMatter, searchFrom),
-                    message: `LIMA: space between closing quote and colon at line ${lineAt(frontMatter, searchFrom)}`,
+                    message: `Lima: space between closing quote and colon at line ${lineAt(frontMatter, searchFrom)}`,
                 });
             }
             if (lineEnd === -1)
@@ -167,7 +167,7 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
         if ((strict || ctx.onWarning !== undefined) && builder.hasMappingKey(root, key)) {
             const diagnostic = {
                 code: 'DUPLICATE_KEY', line, key,
-                message: `LIMA: duplicate key "${key}" at line ${line} — last value wins`,
+                message: `Lima: duplicate key "${key}" at line ${line} — last value wins`,
             };
             if (strict)
                 throw new LimaError(diagnostic);
@@ -239,7 +239,9 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
             minIndent = Math.min(minIndent, key.length + 2);
             const trimAmt = minIndent > 1 && isFinite(minIndent) ? minIndent : 0;
             const mergedLines = [];
-            for (const bodyLine of bodyLines) {
+            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; // ^^
@@ -251,22 +253,41 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
                 const content = bodyLine.slice(start, end);
                 if (isContinuation) {
                     if (mergedLines.length > 0) {
-                        if (content)
+                        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] === '')
+            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, false));
+            builder.setMapping(root, key, builder.string(joined, line + 1, false, sourceSpans));
         }
     };
     // A recognised top-level entry needs at least one UTF-16 unit of key text,
@@ -309,7 +330,7 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
         if (keyCount > TOP_LEVEL_KEY_LIMIT) {
             throw new LimaError({
                 code: 'RESOURCE_LIMIT', line: 1,
-                message: `LIMA: too many top-level key entries (max ${TOP_LEVEL_KEY_LIMIT}) at line 1`,
+                message: `Lima: too many top-level key entries (max ${TOP_LEVEL_KEY_LIMIT}) at line 1`,
             });
         }
         for (let i = 0; i < keyCount; i++) {
@@ -327,13 +348,13 @@ const parseCoreGeneric = (frontMatter, ctx, builder, computeDepth) => {
     if (blockDepthRisk.mayExceed && builder.mappingMaxDepth(root, computeDepth) > NESTING_DEPTH_LIMIT) {
         throw new LimaError({
             code: 'RESOURCE_LIMIT', line: 1,
-            message: `LIMA: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line 1`,
+            message: `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line 1`,
         });
     }
     return root;
 };
 /**
- * Parses LIMA Core 1.0 syntax into the internal annotated value tree —
+ * Parses Lima Core 1.0 syntax into the internal annotated value tree —
  * every node carrying its source line, string leaves additionally carrying
  * whether they came from quoted syntax. `($key)`/`(%key)` text is left
  * exactly as written; nothing here ever inspects or resolves it. The

package/dist/flow.js

@@ -79,14 +79,14 @@ export const parseFlowSequence = (val, ctx, line, builder) => {
         const item = val.slice(start, end);
         if (!item) {
             if (ctx.strict)
-                throw new LimaError({ code: 'INVALID_FLOW_SYNTAX', line, message: `LIMA: empty element in flow sequence at line ${line}` });
+                throw new LimaError({ code: 'INVALID_FLOW_SYNTAX', line, message: `Lima: empty element in flow sequence at line ${line}` });
             items.push(builder.null(line));
             continue;
         }
         if (item.charCodeAt(0) === 91 && item.charCodeAt(item.length - 1) === 93) {
             throw new LimaError({
                 code: 'INVALID_FLOW_SYNTAX', line,
-                message: `LIMA: nested flow sequence not permitted at line ${line}: "${item}"`,
+                message: `Lima: nested flow sequence not permitted at line ${line}: "${item}"`,
             });
         }
         if (item.charCodeAt(0) === 123 && item.charCodeAt(item.length - 1) === 125) {
@@ -114,7 +114,7 @@ export const parseFlowMapping = (val, ctx, line, builder) => {
         const item = val.slice(itemStart, itemEnd);
         if (!item) {
             if (ctx.strict)
-                throw new LimaError({ code: 'INVALID_FLOW_SYNTAX', line, message: `LIMA: empty element in flow mapping at line ${line}` });
+                throw new LimaError({ code: 'INVALID_FLOW_SYNTAX', line, message: `Lima: empty element in flow mapping at line ${line}` });
             continue;
         }
         const colonPos = val.indexOf(': ', itemStart);
@@ -122,7 +122,7 @@ export const parseFlowMapping = (val, ctx, line, builder) => {
             if (ctx.strict)
                 throw new LimaError({
                     code: 'INVALID_FLOW_SYNTAX', line,
-                    message: `LIMA: invalid flow mapping item (missing ": ") at line ${line}: "${item}"`,
+                    message: `Lima: invalid flow mapping item (missing ": ") at line ${line}: "${item}"`,
                 });
             return null;
         }
@@ -137,7 +137,7 @@ export const parseFlowMapping = (val, ctx, line, builder) => {
         const valueEnd = trimEnd(val, valueStart, itemEnd);
         const rawVal = val.slice(valueStart, valueEnd);
         if (isNestedFlowConstruct(rawVal)) {
-            throw new LimaError({ code: 'INVALID_FLOW_SYNTAX', line, message: `LIMA: invalid flow nesting at line ${line}: "${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));
     }

package/dist/index.d.ts

@@ -1,15 +1,16 @@
 /**
- * LIMA Parser — LIMA Is Metadata Annotation
+ * Lima Parser — LIMA Is Metadata Annotation
  *
  * Public entry point. The implementation is split per Appendix B's own
  * layering:
- *   - `core.ts`       — LIMA Core 1.0, reference-unaware by construction.
- *   - `references.ts` — the optional References 1.0 extension, layered on
- *                        top of Core's internal annotated value tree.
+ *   - `core.ts`       — Lima Core 1.0, reference-unaware by construction.
+ *   - `references2.ts` — the References 2.0 extension layered on Core.
+ *   - `references.ts`  — the frozen internal References 1.0 implementation.
  *   - `value.ts`       — the shared Lima Value Model both build on.
  *
- * `parse` (the historical default export) resolves references — it is
- * `parseReferences` under a name kept for backward compatibility.
+ * `parse` is the primary References 2.0 entry point. `parseReferences` is
+ * retained as its deprecated compatibility alias.
  */
 export { parseCore, type CoreOptions, type Diagnostic } from './core.js';
-export { parseReferences, parse, type ReferencesOptions, type ParseOptions } from './references.js';
+export { parseReferences, parse, type ParseMode, type ParseOptions } from './references2.js';
+export type ReferencesOptions = import('./references2.js').ParseOptions;

package/dist/index.js

@@ -1,15 +1,15 @@
 /**
- * LIMA Parser — LIMA Is Metadata Annotation
+ * Lima Parser — LIMA Is Metadata Annotation
  *
  * Public entry point. The implementation is split per Appendix B's own
  * layering:
- *   - `core.ts`       — LIMA Core 1.0, reference-unaware by construction.
- *   - `references.ts` — the optional References 1.0 extension, layered on
- *                        top of Core's internal annotated value tree.
+ *   - `core.ts`       — Lima Core 1.0, reference-unaware by construction.
+ *   - `references2.ts` — the References 2.0 extension layered on Core.
+ *   - `references.ts`  — the frozen internal References 1.0 implementation.
  *   - `value.ts`       — the shared Lima Value Model both build on.
  *
- * `parse` (the historical default export) resolves references — it is
- * `parseReferences` under a name kept for backward compatibility.
+ * `parse` is the primary References 2.0 entry point. `parseReferences` is
+ * retained as its deprecated compatibility alias.
  */
 export { parseCore } from './core.js';
-export { parseReferences, parse } from './references.js';
+export { parseReferences, parse } from './references2.js';

package/dist/normalize.js

@@ -20,7 +20,7 @@ export const checkStringLimit = (value, line) => {
     if (value.length > SCALAR_LENGTH_LIMIT && codepointLength(value) > SCALAR_LENGTH_LIMIT) {
         throw new LimaError({
             code: 'RESOURCE_LIMIT', line,
-            message: `LIMA: scalar exceeds maximum length of ${SCALAR_LENGTH_LIMIT} code points at line ${line}`,
+            message: `Lima: scalar exceeds maximum length of ${SCALAR_LENGTH_LIMIT} code points at line ${line}`,
         });
     }
 };
@@ -41,7 +41,7 @@ export const checkKeyLength = (key, line) => {
         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}`,
+            message: `Lima: key "${key}" exceeds maximum length of ${KEY_LENGTH_LIMIT} code points at line ${l}`,
         });
     }
 };
@@ -50,7 +50,7 @@ export const checkDuplicateKey = (exists, key, line, ctx) => {
         return;
     const diagnostic = {
         code: 'DUPLICATE_KEY', line, key,
-        message: `LIMA: duplicate key "${key}" at line ${line} — last value wins`,
+        message: `Lima: duplicate key "${key}" at line ${line} — last value wins`,
     };
     if (ctx.strict)
         throw new LimaError(diagnostic);

package/dist/reference-tokens2.d.ts

@@ -0,0 +1,12 @@
+/** Reference tokens recorded while the annotated Core tree is being built. */
+import type { StringSourceSpan } from './builder.js';
+export type ReferenceToken2 = {
+    token: string;
+    index: number;
+    offset: number;
+    line: number;
+    documentPath?: string;
+    partialPath?: string;
+};
+export declare const PURE_REFERENCE_2: RegExp;
+export declare const scanReferenceTokens2: (value: string, firstLine: number, sourceSpans?: StringSourceSpan[]) => ReferenceToken2[];

package/dist/reference-tokens2.js

@@ -0,0 +1,37 @@
+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_:/-]*';
+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('$('))
+        return NO_TOKENS;
+    REFERENCE_2.lastIndex = 0;
+    const result = [];
+    let line = firstLine;
+    let lineStart = 0;
+    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) {
+                line++;
+                lineStart = scanned + 1;
+            }
+            scanned++;
+        }
+        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] }),
+        });
+    }
+    return result;
+};

package/dist/references.d.ts

@@ -1,5 +1,5 @@
 /**
- * LIMA References 1.0 — layered strictly on top of `core.ts` (Appendix B:
+ * Lima References 1.0 — layered strictly on top of `core.ts` (Appendix B:
  * reference resolution is exclusively this extension's concern; Core never
  * sees it). Reads the annotated `PositionedValue` tree Core produces and
  * performs the two-phase resolution the spec describes (§4), keeping every
@@ -20,8 +20,71 @@
  * There is no module-level mutable state: diagnostics are collected in a
  * `ResolutionContext` created fresh per call and threaded explicitly.
  */
-import { type Diagnostic } from './core.js';
+import { type LimaValue } from './value.js';
+import { type PositionedValue, type Diagnostic, type InsertedAt, type NativeValue } 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;
@@ -33,4 +96,6 @@ export declare const parseReferences: <T extends Record<string, unknown> = Meta>
 /** Backward-compatible primary entry point — References layered on Core. */
 export declare const parse: typeof parseReferences;
 export type ParseOptions = ReferencesOptions;
+/** Internal conformance entry point for the frozen References 1.0 suite. */
+export declare const parseReferencesV1: typeof parseReferences;
 export {};

package/dist/references.js

@@ -1,5 +1,5 @@
 /**
- * LIMA References 1.0 — layered strictly on top of `core.ts` (Appendix B:
+ * Lima References 1.0 — layered strictly on top of `core.ts` (Appendix B:
  * reference resolution is exclusively this extension's concern; Core never
  * sees it). Reads the annotated `PositionedValue` tree Core produces and
  * performs the two-phase resolution the spec describes (§4), keeping every
@@ -110,14 +110,14 @@ const isReferenceFreeP = (v) => {
  * already contain the result of an inner reference that resolved first —
  * both insertion sites remain identifiable participants after the copy).
  */
-const deepCopyPositioned = (v) => {
+export const deepCopyPositioned = (v) => {
     switch (v.kind) {
-        case 'array': return { kind: 'array', items: v.items.map(deepCopyPositioned), line: v.line, insertedAt: v.insertedAt };
+        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, insertedAt: v.insertedAt };
+            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;
@@ -132,7 +132,7 @@ const deepCopyPositioned = (v) => {
  * 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.
  */
-const partialToPositioned = (v, line) => {
+export const partialToPositioned = (v, line) => {
     switch (v.kind) {
         case 'null': return { kind: 'null', line };
         case 'bool': return { kind: 'bool', value: v.value, line };
@@ -216,7 +216,7 @@ const resolveTree = (node, lookup, partials, ctx) => {
                 if (target.kind === 'mapping') {
                     reportDiagnostic(ctx, {
                         code: 'INVALID_INTERPOLATION', line: node.line, token: match,
-                        message: `LIMA: invalid interpolation of "${match}" at line ${node.line}: mapping cannot be interpolated into a string`,
+                        message: `Lima: invalid interpolation of "${match}" at line ${node.line}: mapping cannot be interpolated into a string`,
                     });
                     return match;
                 }
@@ -224,7 +224,7 @@ const resolveTree = (node, lookup, partials, ctx) => {
                     if (target.items.some((item) => item.kind === 'array' || item.kind === 'mapping')) {
                         reportDiagnostic(ctx, {
                             code: 'INVALID_INTERPOLATION', line: node.line, token: match,
-                            message: `LIMA: invalid interpolation of "${match}" at line ${node.line}: array contains a nested array or mapping`,
+                            message: `Lima: invalid interpolation of "${match}" at line ${node.line}: array contains a nested array or mapping`,
                         });
                         return match;
                     }
@@ -240,7 +240,7 @@ const resolveTree = (node, lookup, partials, ctx) => {
             if (codepointLength(replaced) > SCALAR_LENGTH_LIMIT) {
                 throw new LimaError({
                     code: 'RESOURCE_LIMIT', line: node.line,
-                    message: `LIMA: scalar exceeds maximum length of ${SCALAR_LENGTH_LIMIT} code points at line ${node.line}`,
+                    message: `Lima: scalar exceeds maximum length of ${SCALAR_LENGTH_LIMIT} code points at line ${node.line}`,
                 });
             }
             return { kind: 'string', value: replaced, line: node.line, quoted: false };
@@ -266,7 +266,7 @@ const resolveTree = (node, lookup, partials, ctx) => {
                     // throws in BOTH modes (R-036/R-143).
                     reportDiagnostic(ctx, {
                         code: 'INVALID_REFERENCE_SHAPE', line: item.line, token: item.value,
-                        message: `LIMA: reference "${item.value}" resolves to an array, which cannot be inserted as a sequence item at line ${item.line}`,
+                        message: `Lima: reference "${item.value}" resolves to an array, which cannot be inserted as a sequence item at line ${item.line}`,
                     });
                     return item;
                 }
@@ -282,7 +282,7 @@ const resolveTree = (node, lookup, partials, ctx) => {
     }
     return node; // null/bool/int/float/instant — nothing to resolve
 };
-const finalizePositioned = (v) => {
+export const finalizePositioned = (v) => {
     const own = v.insertedAt ? [v.insertedAt] : [];
     if (v.kind === 'array') {
         if (v.items.length === 0)
@@ -334,9 +334,9 @@ const finalizePositioned = (v) => {
     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. */
-const earliestParticipant = (participants) => participants.length === 0 ? null : participants.reduce((a, b) => (b.line < a.line ? b : a));
+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. */
-const collectAllParticipants = (v, acc) => {
+export const collectAllParticipants = (v, acc) => {
     if (v.insertedAt)
         acc.push(v.insertedAt);
     if (v.kind === 'array')
@@ -356,13 +356,13 @@ export const parseReferences = (frontMatter, options) => {
     // diagnostics collected below.
     const partialNames = Object.keys(rawPartials);
     if (partialNames.length > PARTIAL_COUNT_LIMIT) {
-        throw new LimaError({ code: 'INVALID_PARTIAL', message: `LIMA: too many partials (max ${PARTIAL_COUNT_LIMIT})` });
+        throw new LimaError({ code: 'INVALID_PARTIAL', message: `Lima: too many partials (max ${PARTIAL_COUNT_LIMIT})` });
     }
     for (const name of partialNames) {
         if (codepointLength(name) > PARTIAL_NAME_LENGTH_LIMIT) {
             throw new LimaError({
                 code: 'INVALID_PARTIAL', partial: name, path: name,
-                message: `LIMA: invalid partial "${name}" at path "${name}": name exceeds maximum length of ${PARTIAL_NAME_LENGTH_LIMIT} code points`,
+                message: `Lima: invalid partial "${name}" at path "${name}": name exceeds maximum length of ${PARTIAL_NAME_LENGTH_LIMIT} code points`,
             });
         }
     }
@@ -376,7 +376,7 @@ export const parseReferences = (frontMatter, options) => {
     if (totalPartialNodes > PARTIAL_NODE_LIMIT) {
         throw new LimaError({
             code: 'INVALID_PARTIAL',
-            message: `LIMA: partials exceed the combined maximum of ${PARTIAL_NODE_LIMIT} value nodes`,
+            message: `Lima: partials exceed the combined maximum of ${PARTIAL_NODE_LIMIT} value nodes`,
         });
     }
     // Converted to the annotated representation once per partial, not once
@@ -446,7 +446,7 @@ export const parseReferences = (frontMatter, options) => {
                     if (m) {
                         reportDiagnostic(ctx, {
                             code: 'UNRESOLVED_REFERENCE', line: v.line, token: `(${m[1]}${m[2]})`,
-                            message: `LIMA: unresolved reference "(${m[1]}${m[2]})" at line ${v.line}`,
+                            message: `Lima: unresolved reference "(${m[1]}${m[2]})" at line ${v.line}`,
                         });
                     }
                 }
@@ -491,8 +491,8 @@ export const parseReferences = (frontMatter, options) => {
         throw new LimaError({
             code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
             message: winner
-                ? `LIMA: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line ${winner.line}: "${winner.token}"`
-                : `LIMA: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line 1`,
+                ? `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line ${winner.line}: "${winner.token}"`
+                : `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line 1`,
         });
     }
     // §6.2: total node count of the final result tree, both modes. Same
@@ -509,8 +509,8 @@ export const parseReferences = (frontMatter, options) => {
         throw new LimaError({
             code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
             message: winner
-                ? `LIMA: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line ${winner.line}: "${winner.token}"`
-                : `LIMA: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line 1`,
+                ? `Lima: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line ${winner.line}: "${winner.token}"`
+                : `Lima: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line 1`,
         });
     }
     const out = emptyMapping();
@@ -520,3 +520,5 @@ export const parseReferences = (frontMatter, options) => {
 };
 /** Backward-compatible primary entry point — References layered on Core. */
 export const parse = parseReferences;
+/** Internal conformance entry point for the frozen References 1.0 suite. */
+export const parseReferencesV1 = parseReferences;

package/dist/references2.d.ts

@@ -0,0 +1,13 @@
+import { type Diagnostic } from './core.js';
+type Meta = Record<string, unknown>;
+export type ParseMode = 'references' | 'core';
+export type ParseOptions = {
+    mode?: ParseMode;
+    partials?: Meta;
+    strict?: boolean;
+    onWarning?: (diagnostic: Diagnostic) => void;
+};
+export declare const parse: <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

@@ -0,0 +1,295 @@
+/** Lima References 2.0 resolver. References 1.0 remains isolated in references.ts. */
+import { canonicalString, codepointLength, countNodes, ingestPartialValue, PARTIAL_COUNT_LIMIT, PARTIAL_NAME_LENGTH_LIMIT, PARTIAL_NODE_LIMIT, RESULT_NODE_LIMIT, SCALAR_LENGTH_LIMIT, } from './value.js';
+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);
+const PARTIAL_NAME = '[a-zA-Z0-9_][a-zA-Z0-9_:/-]*';
+const PARTIAL_NAME_RE = new RegExp(`^${PARTIAL_NAME}$`);
+const MAX_EDGES = 3;
+const addDiagnostic = (ctx, diagnostic, offset = 0) => {
+    ctx.diagnostics.push({ ...diagnostic, offset });
+};
+const tokenMatches = (node) => node.references2 ?? [];
+const lookupPath = (root, segments) => {
+    let current = root;
+    for (const segment of segments) {
+        if (current?.kind !== 'mapping')
+            return undefined;
+        current = current.entries.get(segment);
+    }
+    return current;
+};
+const documentTarget = (root, path) => {
+    const segments = path.split('.');
+    const value = root.get(segments[0]);
+    return value === undefined ? undefined : { root: value, tail: segments.slice(1) };
+};
+const lookupPartial = (partials, path) => {
+    const dot = path.indexOf('.');
+    if (dot < 0)
+        return partials.get(path);
+    return lookupPath(partials.get(path.slice(0, dot)), path.slice(dot + 1).split('.'));
+};
+const isActiveString = (node) => node.kind === 'string' && !node.quoted;
+const scalarText = (value, token, line, offset, ctx) => {
+    if (value.kind === 'mapping') {
+        addDiagnostic(ctx, {
+            code: 'INVALID_INTERPOLATION', line, token,
+            message: `Lima: invalid interpolation of "${token}" at line ${line}: mapping cannot be interpolated into a string`,
+        }, offset);
+        return null;
+    }
+    if (value.kind === 'array') {
+        if (value.items.some((item) => item.kind === 'array' || item.kind === 'mapping')) {
+            addDiagnostic(ctx, {
+                code: 'INVALID_INTERPOLATION', line, token,
+                message: `Lima: invalid interpolation of "${token}" at line ${line}: array contains a nested array or mapping`,
+            }, offset);
+            return null;
+        }
+        return value.items.map((item) => canonicalString(toPlainValue(item))).join(', ');
+    }
+    return canonicalString(toPlainValue(value));
+};
+const resolveNodeUncached = (node, document, partials, ctx, remainingEdges, stack) => {
+    if (node.kind === 'array') {
+        if (!hasActiveReferences2(node))
+            return { value: node, complete: true };
+        let complete = true;
+        const items = node.items.map((item) => {
+            const result = resolveNode(item, document, partials, ctx, remainingEdges, stack);
+            complete &&= result.complete;
+            if (isActiveString(item) && result.value.kind === 'array') {
+                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}`,
+                });
+                return item;
+            }
+            return result.value;
+        });
+        return {
+            value: { ...node, items, references2Active: items.some(hasActiveReferences2) || undefined },
+            complete,
+        };
+    }
+    if (node.kind === 'mapping') {
+        if (!hasActiveReferences2(node))
+            return { value: node, complete: true };
+        let complete = true;
+        const entries = new Map();
+        for (const [key, child] of node.entries) {
+            const result = resolveNode(child, document, partials, ctx, remainingEdges, stack);
+            complete &&= result.complete;
+            entries.set(key, result.value);
+        }
+        let references2Active = false;
+        for (const value of entries.values()) {
+            if (hasActiveReferences2(value)) {
+                references2Active = true;
+                break;
+            }
+        }
+        return { value: { ...node, entries, references2Active: references2Active || undefined }, complete };
+    }
+    if (!isActiveString(node))
+        return { value: node, complete: true };
+    const recorded = tokenMatches(node);
+    const pure = recorded.length === 1 && recorded[0].index === 0 && recorded[0].token.length === node.value.length
+        ? recorded[0]
+        : undefined;
+    if (pure) {
+        if (remainingEdges === 0)
+            return { value: node, complete: false };
+        const documentLookup = pure.documentPath !== undefined ? documentTarget(document, pure.documentPath) : undefined;
+        const target = pure.documentPath !== undefined ? documentLookup?.root : lookupPartial(partials, pure.partialPath);
+        if (target === undefined || stack.has(target))
+            return { value: node, complete: false };
+        if (pure.partialPath !== undefined) {
+            return {
+                value: { ...deepCopyPositioned(target), insertedAt: { line: pure.line, token: pure.token } },
+                complete: true,
+            };
+        }
+        stack.add(target);
+        const result = resolveNode(target, document, partials, ctx, remainingEdges - 1, stack);
+        stack.delete(target);
+        if (!result.complete)
+            return { value: node, complete: false };
+        const selected = lookupPath(result.value, documentLookup?.tail ?? []);
+        if (selected === undefined)
+            return { value: node, complete: false };
+        return {
+            value: { ...deepCopyPositioned(selected), insertedAt: { line: pure.line, token: pure.token } },
+            complete: true,
+        };
+    }
+    const matches = recorded;
+    if (matches.length === 0)
+        return { value: node, complete: true };
+    let complete = true;
+    let cursor = 0;
+    let output = '';
+    const unresolvedTokens = [];
+    for (const match of matches) {
+        const offset = match.index;
+        output += node.value.slice(cursor, offset);
+        const documentLookup = match.documentPath !== undefined ? documentTarget(document, match.documentPath) : undefined;
+        const target = match.documentPath !== undefined ? documentLookup?.root : lookupPartial(partials, match.partialPath);
+        let replacement = null;
+        if (remainingEdges > 0 && target !== undefined && !stack.has(target)) {
+            if (match.partialPath !== undefined)
+                replacement = scalarText(target, match.token, match.line, match.offset, ctx);
+            else {
+                stack.add(target);
+                const result = resolveNode(target, document, partials, ctx, remainingEdges - 1, stack);
+                stack.delete(target);
+                const selected = result.complete ? lookupPath(result.value, documentLookup?.tail ?? []) : undefined;
+                if (selected !== undefined)
+                    replacement = scalarText(selected, match.token, match.line, match.offset, ctx);
+            }
+        }
+        if (replacement === null) {
+            complete = false;
+            unresolvedTokens.push({ ...match, index: output.length });
+            output += match.token;
+        }
+        else
+            output += replacement;
+        cursor = offset + match.token.length;
+    }
+    output += node.value.slice(cursor);
+    if (codepointLength(output) > SCALAR_LENGTH_LIMIT) {
+        const first = matches[0];
+        addDiagnostic(ctx, {
+            code: 'RESOURCE_LIMIT', line: first.line, token: first.token,
+            message: `Lima: scalar exceeds maximum length of ${SCALAR_LENGTH_LIMIT} code points at line ${first.line}`,
+        }, first.offset);
+    }
+    return { value: { ...node, value: output, references2: unresolvedTokens }, complete };
+};
+/** Successful and failed dependency results are immutable and budget-specific. */
+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)
+        return resolveNodeUncached(node, document, partials, ctx, remainingEdges, stack);
+    const byBudget = ctx.cache.get(node);
+    const cached = byBudget?.get(remainingEdges);
+    if (cached !== undefined)
+        return cached;
+    const result = resolveNodeUncached(node, document, partials, ctx, remainingEdges, stack);
+    if (byBudget !== undefined)
+        byBudget.set(remainingEdges, result);
+    else
+        ctx.cache.set(node, new Map([[remainingEdges, result]]));
+    return result;
+};
+const validatePartials = (raw) => {
+    const names = Object.keys(raw);
+    if (names.length > PARTIAL_COUNT_LIMIT) {
+        throw new LimaError({ code: 'INVALID_PARTIAL', message: `Lima: too many partials (max ${PARTIAL_COUNT_LIMIT})` });
+    }
+    for (const name of names) {
+        if (!PARTIAL_NAME_RE.test(name)) {
+            throw new LimaError({ code: 'INVALID_PARTIAL', partial: name, message: `Lima: invalid partial name "${name}"` });
+        }
+        if (codepointLength(name) > PARTIAL_NAME_LENGTH_LIMIT) {
+            throw new LimaError({ code: 'INVALID_PARTIAL', partial: name, message: `Lima: invalid partial name "${name}": exceeds maximum length of ${PARTIAL_NAME_LENGTH_LIMIT} code points` });
+        }
+    }
+    const ingested = new Map();
+    for (const name of names)
+        ingested.set(name, ingestPartialValue(raw[name], name, name));
+    let nodes = 0;
+    for (const value of ingested.values())
+        nodes += countNodes(value);
+    if (nodes > PARTIAL_NODE_LIMIT) {
+        throw new LimaError({ code: 'INVALID_PARTIAL', message: `Lima: partials exceed the combined maximum of ${PARTIAL_NODE_LIMIT} value nodes` });
+    }
+    const result = new Map();
+    for (const [name, value] of ingested)
+        result.set(name, partialToPositioned(value, 0));
+    return result;
+};
+const scanUnresolved = (node, ctx) => {
+    if (isActiveString(node)) {
+        for (const match of tokenMatches(node)) {
+            addDiagnostic(ctx, {
+                code: 'UNRESOLVED_REFERENCE', line: match.line, token: match.token,
+                message: `Lima: unresolved reference "${match.token}" at line ${match.line}`,
+            }, match.offset);
+        }
+        return;
+    }
+    if (node.kind === 'array')
+        for (const item of node.items)
+            scanUnresolved(item, ctx);
+    if (node.kind === 'mapping')
+        for (const child of node.entries.values())
+            scanUnresolved(child, ctx);
+};
+export const parse = (frontMatter, options) => {
+    if (options?.mode !== undefined && options.mode !== 'core' && options.mode !== 'references') {
+        throw new TypeError(`Lima: invalid parse mode "${String(options.mode)}"`);
+    }
+    if (options?.mode === 'core') {
+        if (Object.prototype.hasOwnProperty.call(options, 'partials')) {
+            throw new TypeError('Lima: partials cannot be supplied in core mode');
+        }
+        // Core ignores the additional `mode` property. Passing the same object
+        // avoids allocating a projected options object on this hot dispatch path.
+        return parseCore(frontMatter, options);
+    }
+    const partials = validatePartials(options?.partials ?? {});
+    if (!frontMatter.includes('$(')) {
+        return parseCore(frontMatter, options);
+    }
+    const document = parseCoreWithPositions(frontMatter, { strict: options?.strict ?? false, onWarning: options?.onWarning });
+    const ctx = { diagnostics: [], cache: new WeakMap() };
+    const resolved = new Map();
+    for (const [key, value] of document) {
+        const stack = new Set([value]);
+        resolved.set(key, resolveNode(value, document, partials, ctx, MAX_EDGES, stack).value);
+    }
+    if (options?.strict)
+        for (const value of resolved.values())
+            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 finalized = [...resolved].map(([key, value]) => [key, finalizePositioned(value)]);
+    const depth = finalized.length === 0 ? 0 : Math.max(...finalized.map(([, value]) => value.depth));
+    if (depth > NESTING_DEPTH_LIMIT) {
+        const participants = finalized.filter(([, value]) => value.depth === depth).flatMap(([, value]) => value.deepestParticipants);
+        const winner = earliestParticipant(participants);
+        throw new LimaError({
+            code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
+            message: `Lima: nesting depth exceeds maximum of ${NESTING_DEPTH_LIMIT} at line ${winner?.line ?? 1}`,
+        });
+    }
+    let nodeCount = 1;
+    for (const [, value] of finalized)
+        nodeCount += value.nodeCount;
+    if (nodeCount > RESULT_NODE_LIMIT) {
+        const participants = [];
+        for (const value of resolved.values())
+            collectAllParticipants(value, participants);
+        const winner = earliestParticipant(participants);
+        throw new LimaError({
+            code: 'RESOURCE_LIMIT', line: winner?.line ?? 1, token: winner?.token,
+            message: `Lima: result exceeds maximum size of ${RESULT_NODE_LIMIT} total nodes at line ${winner?.line ?? 1}`,
+        });
+    }
+    const out = emptyMapping();
+    for (const [key, value] of finalized)
+        out[key] = value.native;
+    return out;
+};
+/** @deprecated Use parse(). */
+export const parseReferences = parse;

package/dist/scalars.d.ts

@@ -7,6 +7,7 @@
 import { type LimaValue } from './value.js';
 import { type ParseContext } from './normalize.js';
 import type { ValueBuilder } from './builder.js';
+import { type ReferenceToken2 } from './reference-tokens2.js';
 /**
  * `insertedAt` is never set by Core — it's a References-only annotation
  * (see references.ts's `resolveTree`), stamped on the root of a value
@@ -45,6 +46,7 @@ export type PositionedValue = {
     value: string;
     line: number;
     quoted: boolean;
+    references2?: ReferenceToken2[];
     insertedAt?: InsertedAt;
 } | {
     kind: 'instant';
@@ -55,13 +57,16 @@ export type PositionedValue = {
     kind: 'array';
     items: PositionedValue[];
     line: number;
+    references2Active?: boolean;
     insertedAt?: InsertedAt;
 } | {
     kind: 'mapping';
     entries: Map<string, PositionedValue>;
     line: number;
+    references2Active?: boolean;
     insertedAt?: InsertedAt;
 };
+export declare const hasActiveReferences2: (value: PositionedValue) => boolean;
 /** The `ValueBuilder<PositionedValue>` — reconstructs today's annotated tree exactly, for References. */
 export declare const positionedBuilder: ValueBuilder<PositionedValue>;
 /** Strips position/quoted-origin annotations, recursively — the public parseCore() projection. */

package/dist/scalars.js

@@ -7,15 +7,29 @@
 import { LNull, LBool, LFloat, LInt, LString, LInstant } from './value.js';
 import { checkStringLimit } from './normalize.js';
 import { LimaError } from './errors.js';
+import { scanReferenceTokens2 } from './reference-tokens2.js';
+export const hasActiveReferences2 = (value) => value.kind === 'string' ? (value.references2?.length ?? 0) > 0
+    : value.kind === 'array' || value.kind === 'mapping' ? value.references2Active === true
+        : false;
 /** The `ValueBuilder<PositionedValue>` — reconstructs today's annotated tree exactly, for References. */
 export const positionedBuilder = {
+    tracksStringSourcePositions: true,
     null: (line) => ({ kind: 'null', line }),
     bool: (value, line) => ({ kind: 'bool', value, line }),
     int: (value, line) => ({ kind: 'int', value, line }),
     float: (value, line) => ({ kind: 'float', value, line }),
-    string: (value, line, quoted) => ({ kind: 'string', value, line, quoted }),
+    string: (value, line, quoted, sourceSpans) => {
+        const references2 = quoted ? undefined : scanReferenceTokens2(value, line, sourceSpans);
+        return {
+            kind: 'string', value, line, quoted,
+            ...(references2 && references2.length > 0 ? { references2 } : {}),
+        };
+    },
     instant: (value, line) => ({ kind: 'instant', value, line }),
-    array: (items, line) => ({ kind: 'array', items, line }),
+    array: (items, line) => ({
+        kind: 'array', items, line,
+        ...(items.some(hasActiveReferences2) ? { references2Active: true } : {}),
+    }),
     createMapping: () => new Map(),
     createMappingWith: (key, value) => new Map([[key, value]]),
     hasMappingKey: (entries, key) => entries.has(key),
@@ -28,7 +42,16 @@ export const positionedBuilder = {
         }
         return max;
     },
-    mapping: (entries, line) => ({ kind: 'mapping', entries, line }),
+    mapping: (entries, line) => {
+        let references2Active = false;
+        for (const value of entries.values()) {
+            if (hasActiveReferences2(value)) {
+                references2Active = true;
+                break;
+            }
+        }
+        return { kind: 'mapping', entries, line, ...(references2Active ? { references2Active: true } : {}) };
+    },
 };
 /** Strips position/quoted-origin annotations, recursively — the public parseCore() projection. */
 export const toPlainValue = (v) => {
@@ -87,7 +110,7 @@ const parseExactIsoSpan = (source, start, end, strict, line) => {
         hour > 23 || minute > 59 || second > 59) {
         if (strict) {
             const raw = source.slice(start, end);
-            throw new LimaError({ code: 'INVALID_DATE', line, message: `LIMA: invalid date "${raw}" at line ${line}` });
+            throw new LimaError({ code: 'INVALID_DATE', line, message: `Lima: invalid date "${raw}" at line ${line}` });
         }
         return null;
     }
@@ -102,7 +125,7 @@ const parseExactIsoSpan = (source, start, end, strict, line) => {
 const parseDateUTC = (str, strict = false, line = 0) => {
     const invalid = () => {
         if (strict)
-            throw new LimaError({ code: 'INVALID_DATE', line, message: `LIMA: invalid date "${str}" at line ${line}` });
+            throw new LimaError({ code: 'INVALID_DATE', line, message: `Lima: invalid date "${str}" at line ${line}` });
         return null;
     };
     const exact = parseExactIsoSpan(str, 0, str.length, strict, line);
@@ -258,14 +281,14 @@ const buildTyped = (str, strict, line, builder) => {
                 if (strict)
                     throw new LimaError({
                         code: 'INVALID_NUMBER', line,
-                        message: `LIMA: float value overflows to a non-finite value at line ${line}: "${str}"`,
+                        message: `Lima: float value overflows to a non-finite value at line ${line}: "${str}"`,
                     });
             }
             else if (n === 0 && !isZeroLiteral(str)) {
                 if (strict)
                     throw new LimaError({
                         code: 'INVALID_NUMBER', line,
-                        message: `LIMA: non-zero float value underflows to zero at line ${line}: "${str}"`,
+                        message: `Lima: non-zero float value underflows to zero at line ${line}: "${str}"`,
                     });
             }
             else {
@@ -312,7 +335,7 @@ export const unescapeDQ = (s, strict = false, line = 0) => {
     if (strict) {
         for (const m of s.matchAll(ANY_ESCAPE_RE)) {
             if (!isValidEscape(m[0].slice(1))) {
-                throw new LimaError({ code: 'INVALID_ESCAPE', line, message: `LIMA: unknown escape sequence "${m[0]}" at line ${line}` });
+                throw new LimaError({ code: 'INVALID_ESCAPE', line, message: `Lima: unknown escape sequence "${m[0]}" at line ${line}` });
             }
         }
     }
@@ -385,7 +408,7 @@ export const parseQuotedOrTyped = (raw, ctx, line, topLevel, builder) => {
             return builder.string(value, line, true);
         }
         if (topLevel && ctx.strict) {
-            throw new LimaError({ code: 'INVALID_QUOTE', line, message: `LIMA: non-whitespace content after closing quote at line ${line}` });
+            throw new LimaError({ code: 'INVALID_QUOTE', line, message: `Lima: non-whitespace content after closing quote at line ${line}` });
         }
     }
     if (raw !== '' && raw !== 'null' && raw !== '~' && raw !== 'true' && raw !== 'false' &&
@@ -400,7 +423,7 @@ export const parseScalarValue = (raw, ctx, line, builder) => {
     if (ctx.strict && (first === 91 || first === 123)) {
         throw new LimaError({
             code: 'INVALID_FLOW_SYNTAX', line,
-            message: `LIMA: unclosed flow ${first === 91 ? 'sequence' : 'mapping'} at line ${line}`,
+            message: `Lima: unclosed flow ${first === 91 ? 'sequence' : 'mapping'} at line ${line}`,
         });
     }
     return parseQuotedOrTyped(raw, ctx, line, true, builder);

package/dist/value.js

@@ -106,7 +106,7 @@ export const ingestPartialValue = (value, partialName, path, depth = 0, seen = n
     const invalid = (reason) => {
         throw new LimaError({
             code: 'INVALID_PARTIAL', partial: partialName, path,
-            message: `LIMA: invalid partial "${partialName}" at path "${path}": ${reason}`,
+            message: `Lima: invalid partial "${partialName}" at path "${path}": ${reason}`,
         });
     };
     if (value === null)
@@ -147,7 +147,7 @@ export const ingestPartialValue = (value, partialName, path, depth = 0, seen = n
             if (Array.isArray(item)) {
                 throw new LimaError({
                     code: 'INVALID_PARTIAL', partial: partialName, path: `${path}[${i}]`,
-                    message: `LIMA: invalid partial "${partialName}" at path "${path}[${i}]": nested arrays are not supported`,
+                    message: `Lima: invalid partial "${partialName}" at path "${path}[${i}]": nested arrays are not supported`,
                 });
             }
             return ingestPartialValue(item, partialName, `${path}[${i}]`, depth + 1, seen);
@@ -167,13 +167,13 @@ export const ingestPartialValue = (value, partialName, path, depth = 0, seen = n
             if (!descriptor || !('value' in descriptor)) {
                 throw new LimaError({
                     code: 'INVALID_PARTIAL', partial: partialName, path: `${path}.${key}`,
-                    message: `LIMA: invalid partial "${partialName}" at path "${path}.${key}": accessor properties are not supported`,
+                    message: `Lima: invalid partial "${partialName}" at path "${path}.${key}": accessor properties are not supported`,
                 });
             }
             if (codepointLength(key) > PARTIAL_KEY_LENGTH_LIMIT) {
                 throw new LimaError({
                     code: 'INVALID_PARTIAL', partial: partialName, path: `${path}.${key}`,
-                    message: `LIMA: invalid partial "${partialName}" at path "${path}.${key}": key exceeds maximum length of ${PARTIAL_KEY_LENGTH_LIMIT} code points`,
+                    message: `Lima: invalid partial "${partialName}" at path "${path}.${key}": key exceeds maximum length of ${PARTIAL_KEY_LENGTH_LIMIT} code points`,
                 });
             }
             entries.set(key, ingestPartialValue(value[key], partialName, `${path}.${key}`, depth + 1, seen));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limaformat/lima",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lima frontmatter parser — LIMA Is Metadata Annotation",
   "keywords": ["frontmatter", "parser", "yaml", "markdown", "metadata"],
   "homepage": "https://limaformat.dev",
@@ -30,12 +30,15 @@
     "bench": "bun run bench/index.ts",
     "bench:vs-yaml": "bun run bench/vs-yaml.ts",
     "bench:vs-yaml:node": "node bench/vs-yaml-node.mjs",
-    "bench:differential": "bun run bench/differential.ts"
+    "bench:cross-language": "bun run bench/cross-language.ts",
+    "bench:differential": "bun run bench/differential.ts",
+    "wordcount": "bun run scripts/wordcount.ts"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "@types/js-yaml": "^4.0.9",
     "js-yaml": "^5.2.3",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "typescript-classic": "npm:typescript@^5.9.3"
   }
 }