@metaobjectsdev/metadata 0.6.0 → 0.7.0-rc.2

package/src/attr-schema-validate.ts

@@ -100,7 +100,7 @@ function validateNode(
         errors.push(
           new ParseError(
             `Common attr '${ca.name}' conflicts with per-type attr on ${typeKey}`,
-            { code: "ERR_PROVIDER_ATTR_CONFLICT" },
+            { code: "ERR_PROVIDER_ATTR_CONFLICT", source: node.source },
           ),
         );
         reportedConflicts.add(typeKey);
@@ -126,7 +126,7 @@ function validateNode(
       errors.push(
         new ParseError(
           `${nodeLabel(node)} is missing required attribute '@${spec.name}'`,
-          { code: "ERR_MISSING_REQUIRED_ATTR" },
+          { code: "ERR_MISSING_REQUIRED_ATTR", source: node.source },
         ),
       );
     }
@@ -145,7 +145,7 @@ function validateNode(
       const valueErrors = inst.validateValue(value);
       if (valueErrors.length > 0) {
         for (const ve of valueErrors) {
-          errors.push(new ParseError(`${nodeLabel(node)} ${ve.message}`, { code: "ERR_BAD_ATTR_VALUE" }));
+          errors.push(new ParseError(`${nodeLabel(node)} ${ve.message}`, { code: "ERR_BAD_ATTR_VALUE", source: node.source }));
         }
         continue; // type wrong → skip allowedValues
       }
@@ -159,7 +159,7 @@ function validateNode(
             `${nodeLabel(node)} attribute '@${inst.name}' has value ` +
               `'${String(value)}' which is not one of the allowed values: ` +
               `${spec.allowedValues.map((v) => String(v)).join(", ")}`,
-            { code: "ERR_BAD_ATTR_VALUE" },
+            { code: "ERR_BAD_ATTR_VALUE", source: node.source },
           ),
         );
       }
@@ -180,7 +180,7 @@ function validateNode(
         errors.push(
           new ParseError(
             `${nodeLabel(node)} must declare at least one value in '@${FIELD_ATTR_VALUES}'.`,
-            { code: "ERR_BAD_ATTR_VALUE" },
+            { code: "ERR_BAD_ATTR_VALUE", source: node.source },
           ),
         );
       } else {
@@ -194,14 +194,14 @@ function validateNode(
                 `${nodeLabel(node)} attribute '@${FIELD_ATTR_VALUES}' member '${member}' ` +
                   `is not a valid identifier (must match ${ENUM_MEMBER_PATTERN.source}). ` +
                   `Non-identifier-safe member strings require a symbol↔value mapping (deferred).`,
-                { code: "ERR_BAD_ATTR_VALUE" },
+                { code: "ERR_BAD_ATTR_VALUE", source: node.source },
               ),
             );
           } else if (seen.has(member)) {
             errors.push(
               new ParseError(
                 `${nodeLabel(node)} attribute '@${FIELD_ATTR_VALUES}' has duplicate member '${member}'.`,
-                { code: "ERR_BAD_ATTR_VALUE" },
+                { code: "ERR_BAD_ATTR_VALUE", source: node.source },
               ),
             );
           } else {

package/src/core/export-json.ts

@@ -10,13 +10,12 @@
 //   - Content errors (parse/validation failures) are collected in errors[] and
 //     returned in the result — they do NOT throw. `json` is still produced from
 //     whatever tree the Loader returned (Loader always returns a valid MetaData).
-//   - I/O failures (missing/unreadable directory) are caught by
-//     `loadFromDirectory` and returned in its `errors[]`; `loadAndExportJson`
-//     surfaces them unchanged in `ExportResult.errors`. It does not throw for
-//     directory or metadata problems.
+//   - I/O failures (missing/unreadable directory) surface as collected errors
+//     via MetaDataLoader.fromDirectory; `loadAndExportJson` surfaces them
+//     unchanged in `ExportResult.errors`. It does not throw for directory or
+//     metadata problems.
 
-import { FileMetaDataLoader } from "./file-meta-data-loader.js";
-import type { LoadOptions } from "../loader/meta-data-loader.js";
+import { MetaDataLoader, type LoadOptions } from "../loader/meta-data-loader.js";
 import { canonicalSerialize } from "../serializer-json.js";
 
 // ---------------------------------------------------------------------------
@@ -39,28 +38,26 @@ export interface ExportResult {
  * Load all metadata under `dir` and export the entire model as one flattened
  * canonical-JSON document.
  *
- * Internally constructs a fresh `FileMetaDataLoader` (using the default registry
- * composed via `composeRegistry(coreProviders)`), calls `loadDirectory`, then serializes the
- * resulting tree with `canonicalSerialize`.
+ * Routes through `MetaDataLoader.fromDirectory` (using the default registry
+ * composed via `composeRegistry(coreProviders)` when none supplied), then
+ * serializes the resulting tree with `canonicalSerialize`.
  *
  * @param dir  Absolute or relative path to the directory containing `meta.*.json` files.
- * @param opts Optional loader options forwarded to the `FileMetaDataLoader` constructor
- *             (registry, freeze, strict). The `exclude` glob list can be
- *             supplied as `opts.exclude` — see `FileMetaDataLoader.loadDirectory`.
+ * @param opts Optional loader options (registry, freeze, strict). The
+ *             `exclude` glob list can be supplied as `opts.exclude`.
  */
 export async function loadAndExportJson(
   dir: string,
   opts?: LoadOptions & { exclude?: string[] },
 ): Promise<ExportResult> {
-  const { exclude, ...loaderOpts } = opts ?? {};
-  const loader = new FileMetaDataLoader(loaderOpts);
-  // Only pass the exclude option when defined, to satisfy exactOptionalPropertyTypes.
-  const dirOpts = exclude !== undefined ? { exclude } : undefined;
-  const result = await loader.loadDirectory(dir, dirOpts);
+  const result = await MetaDataLoader.fromDirectory(dir, opts);
   const json = canonicalSerialize(result.root);
   return {
     json,
     errors: result.errors,
-    warnings: result.warnings,
+    // FR5a: LoadResult.warnings is now LoaderWarning[]; ExportResult preserves
+    // its public string[] shape (callers print warnings as text). Extract the
+    // message for back-compat.
+    warnings: result.warnings.map((w) => w.message),
   };
 }

package/src/core/index.ts

@@ -5,8 +5,14 @@
 // load-and-export convenience. The root `@metaobjectsdev/metadata` entry is
 // browser-safe and imports none of this. See the package README.
 
-export { FileSource } from "./file-source.js";
-export { FileMetaDataLoader } from "./file-meta-data-loader.js";
+// Source impls — the node:fs-backed MetaDataSource implementations. Live
+// under `loader/sources/`; re-exported here so server-side consumers can pull
+// them from the same `/core` entry that already houses the YAML parser.
+export { FileSource } from "../loader/sources/file-source.js";
+export { DirectorySource } from "../loader/sources/directory-source.js";
+export type { DirectoryOptions } from "../loader/sources/directory-source.js";
+export { UriSource } from "../loader/sources/uri-source.js";
+
 export { parseYaml } from "./parser-yaml.js";
 export { loadAndExportJson } from "./export-json.js";
 export type { ExportResult } from "./export-json.js";

package/src/core/parser-yaml.ts

@@ -1,15 +1,38 @@
 // Authoring YAML parser.
 //
-// parseYaml is a front-end: yaml.parse → desugar → the shared buildTree
-// (parser-core.ts). The desugar applies the four authoring-sugar rules so the
-// resulting typed tree is identical to the one the equivalent canonical JSON
-// produces.
+// parseYaml is a front-end: parseYamlWithPositions → desugar → the shared
+// buildTree (parser-core.ts). The desugar applies the four authoring-sugar
+// rules so the resulting typed tree is identical to the one the equivalent
+// canonical JSON produces.
+//
+// FR5b: the parse phase now preserves YAML source positions through the
+// pipeline. parseYamlWithPositions attaches a Symbol-keyed position-by-key
+// map onto every mapping object; desugar shallow-copies that property; and
+// buildTree's `format: "yaml"` mode reads the position when stamping
+// `node.source.yamlPosition` (see parser-core.ts).
 
-import { parse as parseYamlText } from "yaml";
 import { ParseError } from "../errors.js";
-import { buildTree, errOpts } from "../parser-core.js";
+import { buildTree } from "../parser-core.js";
 import type { ParseOptions, ParseResult } from "../parser-core.js";
+import type { ErrorSource } from "../source.js";
 import { desugar } from "./yaml-desugar.js";
+import { parseYamlWithPositions } from "./yaml-positions-walker.js";
+
+/** FR5a / ADR-0009 — build a YAML-source envelope rooted at "$".
+ *  yamlPosition on the envelope is left undefined here; envelopes for
+ *  THROWN parser errors carry positions only when the parse phase pushed
+ *  the path into the live parser-core builder (see populateNodeSource in
+ *  parser-core.ts). Errors raised before buildTree (e.g. yaml syntax
+ *  failures, an empty desugar result) lack a node — `yamlPosition` is
+ *  intentionally omitted, per the spec's "skip on desugar-synthesized
+ *  nodes" decision. */
+function yamlSource(sourceName: string | undefined): ErrorSource {
+  return {
+    format: "yaml",
+    files: [sourceName ?? "<unknown>"],
+    jsonPath: "$",
+  };
+}
 
 export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   // Strip UTF-8 BOM if present (consistent with parseJson).
@@ -20,11 +43,11 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   // The loader's per-source try/catch collects the throw into LoadResult.errors.
   let parsed: unknown;
   try {
-    parsed = parseYamlText(normalizedContent);
+    parsed = parseYamlWithPositions(normalizedContent).value;
   } catch (err) {
     throw new ParseError(
       `Invalid YAML: ${(err as Error).message}`,
-      { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" },
+      { code: "ERR_MALFORMED_YAML", source: yamlSource(opts.sourceName) },
     );
   }
 
@@ -37,11 +60,14 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
     const first = desugarErrors[0]!;
     throw new ParseError(
       first.message,
-      { ...errOpts(opts.sourceName), code: first.code ?? "ERR_MALFORMED_YAML" },
+      { code: first.code ?? "ERR_MALFORMED_YAML", source: yamlSource(opts.sourceName) },
     );
   }
 
-  const result = buildTree(canonical, opts);
+  // FR5b — buildTree needs to know the source-format discriminant so
+  // populateNodeSource emits `format: "yaml"` envelopes (with the
+  // optional yamlPosition) instead of the default `format: "json"`.
+  const result = buildTree(canonical, { ...opts, sourceFormat: "yaml" });
 
   // Merge collected desugar errors ahead of buildTree's own collected errors.
   // Each CollectedError carries its own stable code when set (e.g.
@@ -50,13 +76,14 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   const desugarParseErrors = desugarErrors.map(
     (e) =>
       new ParseError(e.message, {
-        ...errOpts(opts.sourceName),
         code: e.code ?? "ERR_MALFORMED_YAML",
+        source: yamlSource(opts.sourceName),
       }),
   );
   return {
     root: result.root,
     warnings: result.warnings,
     errors: [...desugarParseErrors, ...result.errors],
+    envelopeWarnings: result.envelopeWarnings,
   };
 }

package/src/core/yaml-desugar.ts

@@ -38,6 +38,11 @@ import {
   RESERVED_KEY_IS_ARRAY,
   TYPE_SUBTYPE_SEPARATOR,
 } from "../shared/structural.js";
+import {
+  getPositionMap,
+  setPositionMap,
+  type PositionMap,
+} from "./yaml-positions.js";
 import {
   ATTR_SUBTYPE_STRING,
   ATTR_SUBTYPE_CLASS,
@@ -99,6 +104,11 @@ function desugarNode(
   const rawKey = entries[0]!;
   const rawBody = (input as Record<string, unknown>)[rawKey];
 
+  // FR5b — capture the wrapper-level position-by-key map BEFORE re-keying.
+  // The author's raw key (with `[]` suffix and possibly omitted subType) is
+  // the lookup key; the desugar's canonical key is what we emit.
+  const wrapperPositions = getPositionMap(input);
+
   // Rule 4: a trailing "[]" on the key → isArray.
   let key = rawKey;
   let isArray = false;
@@ -111,7 +121,10 @@ function desugarNode(
   const canonicalKey = resolveKey(key, registry, errors, path);
 
   // Rule 2: a scalar body → { name: <scalar> }.
-  const body = desugarBody(rawBody, registry, canonicalKey, errors, path);
+  // FR5b — propagate the wrapper-key's position into the synthesized body
+  // when the input body was a scalar (no body-side positions to inherit).
+  const wrapperKeyPos = wrapperPositions?.[rawKey];
+  const body = desugarBody(rawBody, registry, canonicalKey, errors, path, wrapperKeyPos);
 
   // Rule 4 (cont.): stamp isArray onto the canonical body.
   if (isArray) body[RESERVED_KEY_IS_ARRAY] = true;
@@ -131,7 +144,16 @@ function desugarNode(
   }
   // A non-array `children` value is left untouched — buildTree reports it.
 
-  return { [canonicalKey]: body };
+  // FR5b — emit a wrapper-level position-by-key map for the canonical wrapper
+  // so buildTree's per-child iteration can read the position via the same
+  // lookup it uses for JSON input. The single key transformation is
+  // rawKey → canonicalKey (Rule 1 fuses the subType, Rule 4 strips `[]`).
+  const outWrapper: Record<string, unknown> = { [canonicalKey]: body };
+  if (wrapperKeyPos !== undefined) {
+    setPositionMap(outWrapper, { [canonicalKey]: wrapperKeyPos });
+  }
+
+  return outWrapper;
 }
 
 // Rule 1 — resolve a possibly-bare key to a fused `type.subType` token.
@@ -169,16 +191,30 @@ function desugarBody(
   canonicalKey: string,
   errors: CollectedError[],
   path: string,
+  /** FR5b — position of the WRAPPER key (the `field.string:` line). Used to
+   *  back-fill `yamlPosition` on synthesized bodies (Rule 2's scalar lift) +
+   *  empty bodies; for mapping bodies we use the body's own position-by-key
+   *  map. */
+  wrapperKeyPos: { line: number; col: number } | undefined,
 ): Record<string, unknown> {
   if (
     typeof rawBody === "string" ||
     typeof rawBody === "number" ||
     typeof rawBody === "boolean"
   ) {
-    return { [RESERVED_KEY_NAME]: rawBody };
+    // FR5b — the synthesized `{ name: rawBody }` has no YAML-side
+    // counterpart; we attribute the `name` slot to the wrapper-key's
+    // position (the only YAML position that meaningfully belongs to this
+    // synthesis).
+    const out: Record<string, unknown> = { [RESERVED_KEY_NAME]: rawBody };
+    if (wrapperKeyPos !== undefined) {
+      setPositionMap(out, { [RESERVED_KEY_NAME]: wrapperKeyPos });
+    }
+    return out;
   }
   if (rawBody === null || rawBody === undefined) {
     // An empty body (`field.string:` with nothing after) → an empty node.
+    // No body keys to position; the wrapper carries the node's position.
     return {};
   }
   if (Array.isArray(rawBody)) {
@@ -192,20 +228,38 @@ function desugarBody(
   // Rule D2 (type-coercion guard).
   const src = rawBody as Record<string, unknown>;
   const out: Record<string, unknown> = {};
+  // FR5b — translate the body's position-by-key map across the sigil-free
+  // rewrite. A bare `filterable` key in the source maps to `@filterable` in
+  // the canonical body; the YAML position belongs to BOTH names (the YAML
+  // author only wrote one). We re-key the position map to match the canonical
+  // body's keys so buildTree's per-attr inspection (FR5b follow-ups, e.g.
+  // ERR_BAD_ATTR_VALUE) can find the position via the canonical key.
+  const srcPositions = getPositionMap(src);
+  const outPositions: PositionMap = {};
+  let hasOutPositions = false;
   const schemaIndex = attrSchemaIndex(registry, canonicalKey);
   for (const key of Object.keys(src)) {
+    let outKey: string;
     if (RESERVED_KEYS.has(key) || key.startsWith(ATTR_PREFIX)) {
       out[key] = src[key];
+      outKey = key;
       // D2 also applies to author-written @-keys (the awkward form).
       const attrName = key.startsWith(ATTR_PREFIX) ? key.slice(ATTR_PREFIX.length) : "";
       if (attrName !== "" && !RESERVED_KEYS.has(attrName)) {
         checkCoercion(attrName, src[key], schemaIndex, errors, path);
       }
     } else {
-      out[`${ATTR_PREFIX}${key}`] = src[key];
+      outKey = `${ATTR_PREFIX}${key}`;
+      out[outKey] = src[key];
       checkCoercion(key, src[key], schemaIndex, errors, path);
     }
+    const pos = srcPositions?.[key];
+    if (pos !== undefined) {
+      outPositions[outKey] = pos;
+      hasOutPositions = true;
+    }
   }
+  if (hasOutPositions) setPositionMap(out, outPositions);
   return out;
 }
 

package/src/core/yaml-positions-walker.ts

@@ -0,0 +1,101 @@
+// FR5b — YAML AST → JS walker that preserves source positions.
+//
+// This module is the only place inside @metaobjectsdev/metadata that
+// imports the `yaml` package. It lives in core/ alongside parser-yaml.ts,
+// and is reached only via that parser — never via src/index.ts. The
+// browser-safety test guards this invariant.
+
+import {
+  parseDocument,
+  isAlias,
+  isMap,
+  isScalar,
+  isSeq,
+  LineCounter,
+  type Document,
+} from "yaml";
+
+import {
+  setPositionMap,
+  type PositionMap,
+} from "./yaml-positions.js";
+
+/** Result of parsing YAML text with positions retained. */
+export interface YamlParseResult {
+  /** The JS object (same shape as `yaml.parse(text)` returns), with
+   *  position-by-key maps attached to every mapping. */
+  value: unknown;
+  /** The yaml library's LineCounter — exposed for callers that need to map
+   *  additional ranges (e.g. surfacing errors raised by the YAML library
+   *  itself). */
+  lineCounter: LineCounter;
+}
+
+/** Parse YAML text and return a JS object with positions attached.
+ *
+ *  Mirrors the contract of `yaml.parse(text)` for the shapes the metaobjects
+ *  authoring grammar uses (mappings, sequences, scalars). Aliases and tags
+ *  are deferred via the underlying parseDocument call — i.e. they resolve as
+ *  the library normally would.
+ *
+ *  Throws on YAML syntax errors (same behavior as `yaml.parse`). */
+export function parseYamlWithPositions(text: string): YamlParseResult {
+  const lineCounter = new LineCounter();
+  const doc = parseDocument(text, { lineCounter });
+  // Surface YAML syntax errors as a throw, matching `yaml.parse` behavior.
+  // (parseDocument collects them rather than throwing.)
+  if (doc.errors.length > 0) {
+    throw doc.errors[0]!;
+  }
+  const value = yamlNodeToJs(doc.contents, lineCounter, doc);
+  return { value, lineCounter };
+}
+
+// Walk a yaml AST node into a JS structure. For each YAMLMap, attach a
+// position-by-key map onto the resulting JS object — the position of each
+// key is the (line, col) of the KEY token in the YAML source.
+function yamlNodeToJs(
+  node: unknown,
+  lineCounter: LineCounter,
+  doc: Document,
+): unknown {
+  if (node === null || node === undefined) return null;
+  if (isScalar(node)) {
+    // Honour the library's default scalar typing (numbers / booleans /
+    // strings / null all come through Scalar.value).
+    return node.value;
+  }
+  if (isAlias(node)) {
+    // Resolve an anchor alias (e.g. `*col` after `&col sku_code`) to its
+    // target value — same behaviour as the library's toJS().
+    const target = node.resolve(doc);
+    return yamlNodeToJs(target, lineCounter, doc);
+  }
+  if (isMap(node)) {
+    const out: Record<string, unknown> = {};
+    const positions: PositionMap = {};
+    let hasAnyPosition = false;
+    for (const pair of node.items) {
+      // Only string-keyed entries are valid in metaobjects authoring; ignore
+      // exotic keys (numeric / complex) — they'd already break the desugar.
+      if (!isScalar(pair.key)) continue;
+      const keyText = String(pair.key.value);
+      const valueJs = yamlNodeToJs(pair.value, lineCounter, doc);
+      out[keyText] = valueJs;
+      const keyRange = pair.key.range;
+      if (keyRange !== null && keyRange !== undefined) {
+        const pos = lineCounter.linePos(keyRange[0]);
+        positions[keyText] = { line: pos.line, col: pos.col };
+        hasAnyPosition = true;
+      }
+    }
+    if (hasAnyPosition) setPositionMap(out, positions);
+    return out;
+  }
+  if (isSeq(node)) {
+    return node.items.map((item) => yamlNodeToJs(item, lineCounter, doc));
+  }
+  // Tags / unsupported — fall back to null. The metaobjects authoring
+  // grammar does not use them.
+  return null;
+}

package/src/core/yaml-positions.ts

@@ -0,0 +1,80 @@
+// FR5b — YAML authoring source-position carrier (per ADR-0009).
+//
+// This module is split into two layers so the browser bundle (which
+// imports from src/index.ts) stays free of the Node-only `yaml` package:
+//
+//   - yaml-positions.ts (this file) — pure types + Symbol + accessors. NO
+//     `yaml` import. Imported by parser-core.ts so the source-on-node
+//     stamper can read positions when stamping `format: "yaml"` envelopes.
+//   - yaml-positions-walker.ts — depends on `yaml`. Imported only by
+//     parser-yaml.ts (and parser-yaml itself only ships server-side).
+//
+// Source-map carrier (per the FR5b spec's "open question" §2): a
+// Symbol-keyed, non-enumerable property on the wrapper-mapping object. The
+// symbol is the well-known cross-port key
+// `Symbol.for("@metaobjectsdev/yamlPositionByKey")`, so any plugin that
+// touches the canonical JS can read positions if it knows to look. The
+// map's keys are the wrapper's own keys (e.g. "object.entity" for a
+// wrapper `{ "object.entity": { ... } }` or "name" / "package" /
+// "children" for the body keys of a node).
+//
+// Rationale for "symbol-keyed property" over a parallel sourcemap / wrapper
+// type:
+//   - Invisible to JSON.stringify and Object.keys (non-enumerable).
+//   - No parallel data structure to keep in sync — the position rides with
+//     the node it describes.
+//   - No wrapper type — desugar still operates on plain JS objects, so the
+//     existing Rule 1–5 logic does not need a rewrite.
+//
+// On desugar-synthesized nodes (Rule 2's scalar-body lift): the synthesized
+// body `{ name: rawScalar }` inherits the wrapper key's position from the
+// parent's position map. On any other synthesis (Rule 4's isArray stamping,
+// for example), the position survives because we shallow-copy via the
+// existing desugar path.
+
+/** Cross-port well-known symbol key for the position-by-key map. */
+export const YAML_POSITION_BY_KEY = Symbol.for(
+  "@metaobjectsdev/yamlPositionByKey",
+);
+
+/** A YAML source position — 1-indexed line and column. */
+export interface YamlPosition {
+  readonly line: number;
+  readonly col: number;
+}
+
+/** The position-by-key map attached to a mapping object. */
+export type PositionMap = Record<string, YamlPosition>;
+
+/** Read the position-by-key map from a JS object, if present.
+ *  Returns undefined for primitives, arrays, null, and untagged objects. */
+export function getPositionMap(obj: unknown): PositionMap | undefined {
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+    return undefined;
+  }
+  return (obj as { [YAML_POSITION_BY_KEY]?: PositionMap })[YAML_POSITION_BY_KEY];
+}
+
+/** Read the position for a specific key on a mapping object. */
+export function getYamlPosition(
+  obj: unknown,
+  key: string,
+): YamlPosition | undefined {
+  const map = getPositionMap(obj);
+  return map?.[key];
+}
+
+/** Attach (or replace) the position-by-key map on a mapping object. The map
+ *  property is non-enumerable so JSON.stringify and `for (const k in obj)`
+ *  loops do not see it. */
+export function setPositionMap(
+  obj: Record<string, unknown>,
+  positions: PositionMap,
+): void {
+  Object.defineProperty(obj, YAML_POSITION_BY_KEY, {
+    value: positions,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+}

package/src/errors.ts

@@ -1,5 +1,7 @@
 // Typed error classes for the metadata parser.
 
+import type { ErrorSource, LoaderError, NodeContext } from "./source.js";
+
 /** Stable, language-neutral error codes — mirrors fixtures/conformance/ERROR-CODES.json. */
 // NOTE: The following codes are forward-declared (no emitting site in the current
 // TS parser/loader — the condition is not yet detected):
@@ -50,25 +52,72 @@ export const ERROR_CODES = [
   // ADR-0006 D2 — YAML type-coercion guard. Emitted by every port's YAML
   // loader when a coerced scalar mismatches the schema-declared type.
   "ERR_YAML_COERCION",
+  // FR5c — multi-file overlay merge produced a conflicting attribute value:
+  // two contributors set the same @attr to different non-empty values.
+  "ERR_MERGE_CONFLICT",
   "ERR_UNKNOWN",
 ] as const;
 
+/** Warning codes — same envelope shape as errors but advisory. */
+export const WARNING_CODES = [
+  // FR5c — two contributors declared the same node identically (no semantic
+  // change). Emitted at the overlay-merge boundary.
+  "WARN_DUPLICATE_DECLARATION",
+  // Pre-FR5c legacy: parser/validator messages still surface as plain
+  // strings; wrapped at the loader boundary into the envelope shape with
+  // this code. Retired as those sites are migrated to envelopes.
+  "WARN_LEGACY",
+] as const;
+export type WarningCode = (typeof WARNING_CODES)[number];
+
 export type ErrorCode = (typeof ERROR_CODES)[number];
 
-export class ParseError extends Error {
-  readonly source: string | undefined;
-  readonly path: string | undefined; // logical path within the JSON, e.g. "metadata.children[2].field"
-  readonly code: ErrorCode | undefined;
+/**
+ * Loader error carrying the ADR-0009 LoaderError envelope.
+ *
+ * Public shape (FR5a):
+ *   new ParseError(message, { code, source, suggestions?, fixture?, node? })
+ *
+ * - `code` and `source` are required.
+ * - `source` is the ErrorSource discriminated union (json/yaml/merged/resolved/
+ *   database/code) — the same envelope every cross-language port emits.
+ * - `suggestions[]`, `fixture`, `node` are optional per ADR-0009 §RECOMMENDED;
+ *   FR5a does not populate them, FR5b–FR5e may.
+ *
+ * Legacy fields (`path?: string`, `source?: string`) were superseded by the
+ * envelope's `jsonPath` and `files` and have been dropped — see CHANGELOG.
+ */
+export class ParseError extends Error implements LoaderError {
+  readonly code: ErrorCode;
+  readonly source: ErrorSource;
+  readonly suggestions?: string[];
+  readonly fixture?: string;
+  readonly node?: NodeContext;
 
   constructor(
     message: string,
-    opts?: { source?: string; path?: string; code?: ErrorCode },
+    opts: {
+      code: ErrorCode;
+      source: ErrorSource;
+      suggestions?: string[];
+      fixture?: string;
+      node?: NodeContext;
+    },
   ) {
     super(message);
     this.name = "ParseError";
-    this.source = opts?.source;
-    this.path = opts?.path;
-    this.code = opts?.code;
+    this.code = opts.code;
+    this.source = opts.source;
+    // exactOptionalPropertyTypes: only assign when defined.
+    if (opts.suggestions !== undefined) {
+      (this as { suggestions?: string[] }).suggestions = opts.suggestions;
+    }
+    if (opts.fixture !== undefined) {
+      (this as { fixture?: string }).fixture = opts.fixture;
+    }
+    if (opts.node !== undefined) {
+      (this as { node?: NodeContext }).node = opts.node;
+    }
   }
 }