@metaobjectsdev/metadata 0.6.0-rc.1 → 0.7.0-rc.1

package/src/loader/meta-data-loader.ts

@@ -14,15 +14,34 @@ import { coreProviders } from "../core-types.js";
 import { composeRegistry } from "../provider.js";
 import { TYPE_METADATA, SUBTYPE_ROOT } from "../shared/base-types.js";
 import { ParseError } from "../errors.js";
+import type { LoaderWarning } from "../source.js";
+import { codeSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
 import { validateDataGridSortFields, validateFilterableHasIndex, validateOriginPaths, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs } from "./validation-passes.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { resolveDeferredSupers } from "../super-resolve.js";
 import { validateSubtypeRules } from "../subtype-rules.js";
 import { validateAttrSchema } from "../attr-schema-validate.js";
-import type { MetaDataSource } from "./meta-data-source.js";
+import type { MetaDataFormat, MetaDataSource } from "./meta-data-source.js";
+import { InMemoryStringSource } from "./meta-data-source.js";
 import type { ParseOptions, ParseResult } from "../parser-core.js";
 
+// Local mirror of DirectorySource's options shape. Deliberately inlined here
+// (instead of `import type`'d from ./sources/directory-source.js) so the
+// browser-safety crawler — which walks every `import|export from` it sees,
+// type-only or not — never follows a path into a node:fs-using file.
+// Keep field-for-field in sync with `DirectoryOptions` in `./sources/directory-source.ts`.
+type DirectoryFactoryOptions = {
+  exclude?: string[];
+  recurse?: boolean;
+};
+
+// YAML parser and node:fs-backed Source impls are loaded lazily (dynamic
+// import) inside the methods that need them. Reason: the package root
+// (src/index.ts) re-exports MetaDataLoader and must stay browser-safe —
+// the browser-safety test asserts that no file reachable from index.ts
+// statically imports `yaml` or `node:fs(/promises)`.
+
 // ---------------------------------------------------------------------------
 // Public API types
 // ---------------------------------------------------------------------------
@@ -41,7 +60,13 @@ export interface LoadOptions {
 
 export interface LoadResult {
   root: MetaRoot;
-  warnings: string[];
+  /** Cross-port-aligned warning envelopes per ADR-0009.
+   *  FR5a creates the channel; FR5c (overlay-merge duplicate detection)
+   *  will be the first feature to populate it. Legacy string warnings
+   *  collected during parse/validation are wrapped at the loader boundary
+   *  with `code: "WARN_LEGACY"` and `source: { format: "code" }` so the
+   *  channel always presents the envelope shape to consumers. */
+  warnings: LoaderWarning[];
   errors: Error[];
 }
 
@@ -75,6 +100,71 @@ export class MetaDataLoader {
     return composeRegistry(coreProviders);
   }
 
+  // ---------------------------------------------------------------------------
+  // Static factories — the 99% case (cross-language consistent)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Load every supported file (`.json` / `.yaml` / `.yml`) under `dir` in
+   * deterministic ordinal-basename order. Recurses by default.
+   *
+   * Convenience for the typical "load a directory of metadata" path. The
+   * `DirectorySource` impl is loaded lazily to keep the package root
+   * browser-safe (the underlying source uses node:fs).
+   *
+   * A missing/unreadable directory is surfaced as a collected entry in
+   * `result.errors`; the loader returns a synthetic empty root rather than
+   * throwing — preserves the `meta export` CLI exit-code contract.
+   */
+  static async fromDirectory(
+    dir: string,
+    opts?: DirectoryFactoryOptions & LoadOptions,
+  ): Promise<LoadResult> {
+    const { exclude, recurse, ...loaderOpts } = opts ?? {};
+    // Conditional spreads honor exactOptionalPropertyTypes — only forward keys
+    // when the caller supplied a value, so DirectorySource's own defaults apply.
+    const dirOpts: DirectoryFactoryOptions = {
+      ...(exclude !== undefined && { exclude }),
+      ...(recurse !== undefined && { recurse }),
+    };
+    const { DirectorySource } = await import("./sources/directory-source.js");
+    const loader = new MetaDataLoader(loaderOpts);
+    try {
+      const sources = await new DirectorySource(dir, dirOpts).expand();
+      return loader.load(sources);
+    } catch (err) {
+      // Match the pre-unification contract: a missing/unreadable directory is
+      // surfaced as a collected error on the LoadResult, not a throw. The
+      // pipeline still completes with a synthetic empty root.
+      const emptyResult = await loader.load([]);
+      const expandErr =
+        err instanceof Error
+          ? err
+          : new Error(`MetaDataLoader.fromDirectory: ${String(err)}`);
+      return { ...emptyResult, errors: [expandErr, ...emptyResult.errors] };
+    }
+  }
+
+  /**
+   * Load each URI as a {@link UriSource}. Supports `file://`, `http://`,
+   * `https://` schemes. The source impl is loaded lazily to keep the package
+   * root browser-safe.
+   */
+  static async fromUris(uris: string[], opts?: LoadOptions): Promise<LoadResult> {
+    const { UriSource } = await import("./sources/uri-source.js");
+    const sources = uris.map((u) => new UriSource(u));
+    return new MetaDataLoader(opts).load(sources);
+  }
+
+  /** Load a single in-memory string of the given format. */
+  static async fromString(
+    content: string,
+    format: MetaDataFormat,
+    opts?: LoadOptions,
+  ): Promise<LoadResult> {
+    return new MetaDataLoader(opts).load([new InMemoryStringSource(content, { format })]);
+  }
+
   // ---------------------------------------------------------------------------
   // Lifecycle
   // ---------------------------------------------------------------------------
@@ -156,10 +246,16 @@ export class MetaDataLoader {
   // ---------------------------------------------------------------------------
 
   /**
-   * Parse one source's raw content into a ParseResult. The base loader handles
-   * JSON only; a non-JSON format throws. Subclasses override this seam to add
-   * formats — e.g. FileMetaDataLoader (in @metaobjectsdev/metadata/core) adds YAML.
-   * This keeps the browser-safe base loader free of the YAML parser.
+   * Parse one source's raw content into a ParseResult. Dispatches on the
+   * source's declared `format` — `"json"` runs the canonical JSON parser,
+   * `"yaml"` desugars the authoring YAML into canonical JSON via parseYaml.
+   * Cross-language consistent: the same format vocabulary is honored by the
+   * Java / C# / Python MetaDataLoaders.
+   *
+   * The YAML parser is loaded lazily so the browser-safe root entry never
+   * statically pulls in the `yaml` dependency — see the module-header comment.
+   * `parseYaml` is preloaded inside `load()` if any source declares YAML
+   * format so the call here can stay synchronous.
    */
   protected parseSource(
     content: string,
@@ -169,12 +265,35 @@ export class MetaDataLoader {
     if (source.format === "json") {
       return parseJson(content, parseOpts);
     }
+    if (source.format === "yaml") {
+      const fn = MetaDataLoader._yamlParser;
+      if (fn === undefined) {
+        throw new Error(
+          `MetaDataLoader: YAML parser was not preloaded — this is an internal bug. ` +
+            `Source "${source.id}" declares format "yaml".`,
+        );
+      }
+      return fn(content, parseOpts);
+    }
     throw new Error(
-      `MetaDataLoader parses JSON only; format "${source.format}" for source ` +
-        `"${source.id}" requires FileMetaDataLoader (from @metaobjectsdev/metadata/core)`,
+      `MetaDataLoader: unsupported source format "${source.format}" ` +
+        `on source "${source.id}"`,
     );
   }
 
+  // Cached lazy YAML parser — populated by _ensureYamlParser() before
+  // parseSource is invoked on a YAML source. Module-level cache (one import
+  // per process) keeps the per-load cost negligible.
+  private static _yamlParser:
+    | ((content: string, opts: ParseOptions) => ParseResult)
+    | undefined;
+
+  private static async _ensureYamlParser(): Promise<void> {
+    if (MetaDataLoader._yamlParser !== undefined) return;
+    const mod = await import("../core/parser-yaml.js");
+    MetaDataLoader._yamlParser = mod.parseYaml;
+  }
+
   // ---------------------------------------------------------------------------
   // load — async pipeline over MetaDataSource[]
   // ---------------------------------------------------------------------------
@@ -203,6 +322,14 @@ export class MetaDataLoader {
     const warnings: string[] = [];
     const errors: Error[] = [];
 
+    // Pre-load the YAML parser via dynamic import if any source declares
+    // YAML format. This keeps `parseSource` synchronous and the package root
+    // (src/index.ts) browser-safe — yaml is never statically imported from a
+    // file reachable from the package entry. See `_ensureYamlParser`.
+    if (sources.some((s) => s.format === "yaml")) {
+      await MetaDataLoader._ensureYamlParser();
+    }
+
     let root: MetaRoot | undefined;
 
     // Parse all sources with super resolution DEFERRED so cross-file super
@@ -255,7 +382,7 @@ export class MetaDataLoader {
         errors.push(
           new ParseError(
             `the SuperClass '${failure.ref}' does not exist (referenced by ${failure.nodeFqn})`,
-            { code: "ERR_UNRESOLVED_SUPER" },
+            { code: "ERR_UNRESOLVED_SUPER", source: failure.source },
           ),
         );
       }
@@ -316,6 +443,17 @@ export class MetaDataLoader {
     }
 
     this._root = root;
-    return { root, warnings, errors };
+    // Wrap legacy string warnings collected from parser-core / validators in
+    // LoaderWarning envelopes at the loader boundary. The parser/validator
+    // surface keeps its `string[]` shape internally (parser-core is shared
+    // with parseJson() / parseYaml() callers who consume string warnings
+    // directly). FR5c will retire WARN_LEGACY by routing the duplicate-
+    // declaration site through a proper envelope-shaped emit helper.
+    const envelopeWarnings: LoaderWarning[] = warnings.map((msg) => ({
+      code: "WARN_LEGACY",
+      message: msg,
+      source: codeSource("MetaDataLoader"),
+    }));
+    return { root, warnings: envelopeWarnings, errors };
   }
 }

package/src/loader/meta-data-source.ts

@@ -1,8 +1,8 @@
 // MetaDataSource — the raw-document unit consumed by the loader pipeline.
 //
-// A loader (FileMetaDataLoader, later UrlMetaDataLoader) discovers/acquires
-// sources; the MetaDataLoader pipeline calls read() on each. read() is async
-// so file/URL sources can do I/O; InMemorySource resolves immediately.
+// A loader (MetaDataLoader, fed by FileSource/DirectorySource/UriSource/
+// InMemoryStringSource) parses each source's content. read() is async so file
+// and URI sources can do I/O; InMemoryStringSource resolves immediately.
 
 /** Format of a source's content. Selects the parser. */
 export type MetaDataFormat = "json" | "yaml";
@@ -17,15 +17,19 @@ export interface MetaDataSource {
   read(): Promise<string>;
 }
 
-/** A metadata source backed by an in-memory string. */
-export class InMemorySource implements MetaDataSource {
+/**
+ * A metadata source backed by an in-memory string. The default identity is
+ * `"<inline>"` — matches the cross-language convention shared by the Java /
+ * C# / Python ports.
+ */
+export class InMemoryStringSource implements MetaDataSource {
   readonly id: string;
   readonly format: MetaDataFormat;
   private readonly _content: string;
 
   constructor(content: string, opts?: { id?: string; format?: MetaDataFormat }) {
     this._content = content;
-    this.id = opts?.id ?? "<in-memory>";
+    this.id = opts?.id ?? "<inline>";
     this.format = opts?.format ?? "json";
   }
 

package/src/loader/shortcuts.ts

@@ -0,0 +1,31 @@
+// Module-level loader shortcuts — one-liners that delegate to the
+// MetaDataLoader.from* static factories. Per the cross-language convention:
+// TS and Python expose both class statics AND module-level shortcuts; Java
+// and C# stay class-only.
+//
+// These functions do not statically import any node:fs- or yaml-using file;
+// MetaDataLoader.from* loads the underlying source impls via dynamic import,
+// preserving the package root's browser-safety contract.
+
+import { MetaDataLoader } from "./meta-data-loader.js";
+import type { LoadOptions, LoadResult } from "./meta-data-loader.js";
+import type { MetaDataFormat } from "./meta-data-source.js";
+
+export function loadDirectory(
+  dir: string,
+  opts?: { exclude?: string[]; recurse?: boolean } & LoadOptions,
+): Promise<LoadResult> {
+  return MetaDataLoader.fromDirectory(dir, opts);
+}
+
+export function loadUris(uris: string[], opts?: LoadOptions): Promise<LoadResult> {
+  return MetaDataLoader.fromUris(uris, opts);
+}
+
+export function loadString(
+  content: string,
+  format: MetaDataFormat,
+  opts?: LoadOptions,
+): Promise<LoadResult> {
+  return MetaDataLoader.fromString(content, format, opts);
+}

package/src/loader/sources/directory-source.ts

@@ -0,0 +1,90 @@
+// DirectorySource — expands a directory into a sorted list of FileSource.
+//
+// Discovers .json / .yaml / .yml files (case-insensitive on extension).
+// Recurses by default — matches Java/Python/C# DirectorySource behavior.
+// Sort order is ordinal-by-basename so the overlay merge is deterministic
+// across environments and language ports.
+
+import { readdir, stat } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { FileSource } from "./file-source.js";
+import type { MetaDataSource } from "../meta-data-source.js";
+
+export interface DirectoryOptions {
+  /** Filename patterns to exclude. Supports literal match and `*` / `**` globs. */
+  exclude?: string[];
+  /** Recurse into subdirectories. Default: true. */
+  recurse?: boolean;
+}
+
+const SUPPORTED_EXTS = new Set([".json", ".yaml", ".yml"]);
+
+/** Minimal glob matcher supporting `*` (any chars except `/`) and `**` (any chars). */
+function matchSimpleGlob(pattern: string, value: string): boolean {
+  const regexStr = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "::DOUBLESTAR::")
+    .replace(/\*/g, "[^/]*")
+    .replace(/::DOUBLESTAR::/g, ".*");
+  return new RegExp(`^${regexStr}$`).test(value);
+}
+
+export class DirectorySource {
+  constructor(
+    public readonly directory: string,
+    public readonly opts: DirectoryOptions = {},
+  ) {}
+
+  async expand(): Promise<MetaDataSource[]> {
+    const recurse = this.opts.recurse ?? true;
+    const exclude = this.opts.exclude ?? [];
+
+    const files = await this.collect(this.directory, recurse);
+    const filtered: string[] = [];
+    for (const p of files) {
+      if (!SUPPORTED_EXTS.has(extname(p).toLowerCase())) continue;
+      const name = basename(p);
+      if (exclude.some((pat) => matchSimpleGlob(pat, name))) continue;
+      filtered.push(p);
+    }
+
+    // Sort by basename (ordinal) for deterministic overlay order. The
+    // pre-unification FileMetaDataLoader sorted readdir entries (basenames)
+    // for the same reason — that contract carries forward here.
+    filtered.sort((a, b) => {
+      const an = basename(a);
+      const bn = basename(b);
+      return an < bn ? -1 : an > bn ? 1 : 0;
+    });
+
+    return filtered.map((p) => new FileSource(p));
+  }
+
+  private async collect(dir: string, recurse: boolean): Promise<string[]> {
+    let entries: string[];
+    try {
+      entries = await readdir(dir);
+    } catch (err) {
+      throw new Error(
+        `DirectorySource: cannot read ${dir}: ${(err as Error).message}`,
+      );
+    }
+    const out: string[] = [];
+    for (const entry of entries) {
+      const full = join(dir, entry);
+      let s;
+      try {
+        s = await stat(full);
+      } catch {
+        // Entry vanished between readdir and stat (TOCTOU) or is not accessible.
+        continue;
+      }
+      if (s.isDirectory()) {
+        if (recurse) out.push(...(await this.collect(full, recurse)));
+      } else if (s.isFile()) {
+        out.push(full);
+      }
+    }
+    return out;
+  }
+}

package/src/{core → loader/sources}/file-source.ts

@@ -1,9 +1,9 @@
 // FileSource — a MetaDataSource backed by a file on disk. Server-side only
-// (touches node:fs); lives under src/core/ so the browser-safe root never
-// imports it.
+// (touches node:fs); lives under src/loader/sources/ alongside the other
+// MetaDataSource implementations.
 
 import { basename, extname } from "node:path";
-import type { MetaDataFormat, MetaDataSource } from "../loader/meta-data-source.js";
+import type { MetaDataFormat, MetaDataSource } from "../meta-data-source.js";
 
 /** Infer a source format from a file extension. `.yaml`/`.yml` → "yaml";
  *  everything else (including `.json`) → "json", the canonical default. */

package/src/loader/sources/index.ts

@@ -0,0 +1,6 @@
+// Barrel re-export for the MetaDataSource implementations.
+
+export { FileSource } from "./file-source.js";
+export { DirectorySource } from "./directory-source.js";
+export type { DirectoryOptions } from "./directory-source.js";
+export { UriSource } from "./uri-source.js";

package/src/loader/sources/uri-source.ts

@@ -0,0 +1,44 @@
+// UriSource — a MetaDataSource that fetches content from a URI.
+// Supports file://, http://, and https:// schemes.
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { extname } from "node:path";
+import type { MetaDataFormat, MetaDataSource } from "../meta-data-source.js";
+
+function inferFormat(uri: string): MetaDataFormat {
+  // URL constructor handles file://, http://, https:// uniformly.
+  // Strip query/fragment by reading .pathname.
+  try {
+    const pathname = new URL(uri).pathname;
+    const ext = extname(pathname).toLowerCase();
+    return ext === ".yaml" || ext === ".yml" ? "yaml" : "json";
+  } catch {
+    // If the URI isn't a valid URL, fall back to JSON.
+    return "json";
+  }
+}
+
+export class UriSource implements MetaDataSource {
+  readonly id: string;
+  readonly format: MetaDataFormat;
+
+  constructor(public readonly uri: string, format?: MetaDataFormat) {
+    this.id = uri;
+    this.format = format ?? inferFormat(uri);
+  }
+
+  async read(): Promise<string> {
+    if (this.uri.startsWith("file://")) {
+      return readFile(fileURLToPath(this.uri), "utf-8");
+    }
+    if (this.uri.startsWith("http://") || this.uri.startsWith("https://")) {
+      const res = await fetch(this.uri);
+      if (!res.ok) {
+        throw new Error(`UriSource: ${this.uri} -> HTTP ${res.status}`);
+      }
+      return res.text();
+    }
+    throw new Error(`UriSource: unsupported scheme on ${this.uri}`);
+  }
+}

package/src/loader/validation-passes.ts

@@ -11,6 +11,7 @@
 
 import type { MetaData } from "../shared/meta-data.js";
 import { ParseError } from "../errors.js";
+import type { ErrorSource } from "../source.js";
 import {
   TYPE_OBJECT,
   TYPE_FIELD,
@@ -72,7 +73,7 @@ export function validateDataGridSortFields(root: MetaData): ParseError[] {
           new ParseError(
             `dataGrid layout "${layout.name}" on entity "${obj.name}" has @defaultSortField "${sortField}" ` +
             `but no such field exists on "${obj.name}". Available fields: ${[...fieldNames].join(", ")}`,
-            { code: "ERR_BAD_DEFAULT_SORT_FIELD" },
+            { code: "ERR_BAD_DEFAULT_SORT_FIELD", source: layout.source },
           ),
         );
       }
@@ -102,7 +103,7 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
       errors.push(
         new ParseError(
           `template "${tmpl.name}" @payloadRef "${payloadRef}" does not resolve to a known object in this model`,
-          { code: "ERR_INVALID_TEMPLATE" },
+          { code: "ERR_INVALID_TEMPLATE", source: tmpl.source },
         ),
       );
       continue;
@@ -118,7 +119,7 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
           new ParseError(
             `template "${tmpl.name}" @requiredSlots "${slot}" is not a field on payload "${payloadRef}". ` +
             `Available fields: ${[...fieldNames].join(", ")}`,
-            { code: "ERR_INVALID_TEMPLATE" },
+            { code: "ERR_INVALID_TEMPLATE", source: tmpl.source },
           ),
         );
       }
@@ -196,6 +197,7 @@ function _validateFromPath(
   root: MetaData,
   projectionName: string,
   fieldName: string,
+  originSource: ErrorSource,
   errors: ParseError[],
   label: string = "origin.passthrough.@from",
 ): void {
@@ -204,7 +206,7 @@ function _validateFromPath(
     errors.push(
       new ParseError(
         `${label} "${fromAttr}" on ${projectionName}.${fieldName}: must be of form "Entity.field".`,
-        { code: "ERR_INVALID_ORIGIN" },
+        { code: "ERR_INVALID_ORIGIN", source: originSource },
       ),
     );
     return;
@@ -216,7 +218,7 @@ function _validateFromPath(
     errors.push(
       new ParseError(
         `${label} "${fromAttr}" on ${projectionName}.${fieldName}: no such entity "${entityName}".`,
-        { code: "ERR_INVALID_ORIGIN" },
+        { code: "ERR_INVALID_ORIGIN", source: originSource },
       ),
     );
     return;
@@ -226,7 +228,7 @@ function _validateFromPath(
     errors.push(
       new ParseError(
         `${label} "${fromAttr}" on ${projectionName}.${fieldName}: no such field "${targetFieldName}" on ${entityName}.`,
-        { code: "ERR_INVALID_ORIGIN" },
+        { code: "ERR_INVALID_ORIGIN", source: originSource },
       ),
     );
   }
@@ -237,6 +239,7 @@ function _validateViaPath(
   root: MetaData,
   projectionName: string,
   fieldName: string,
+  originSource: ErrorSource,
   errors: ParseError[],
 ): void {
   const segments = viaAttr.split(".");
@@ -244,7 +247,7 @@ function _validateViaPath(
     errors.push(
       new ParseError(
         `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: must be of form "Entity.relationship[.relationship...]".`,
-        { code: "ERR_INVALID_ORIGIN" },
+        { code: "ERR_INVALID_ORIGIN", source: originSource },
       ),
     );
     return;
@@ -255,7 +258,7 @@ function _validateViaPath(
     errors.push(
       new ParseError(
         `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such entity "${entityName}".`,
-        { code: "ERR_INVALID_ORIGIN" },
+        { code: "ERR_INVALID_ORIGIN", source: originSource },
       ),
     );
     return;
@@ -266,7 +269,7 @@ function _validateViaPath(
       errors.push(
         new ParseError(
           `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such relationship "${relName}" on ${currentObj.name}.`,
-          { code: "ERR_INVALID_ORIGIN" },
+          { code: "ERR_INVALID_ORIGIN", source: originSource },
         ),
       );
       return;
@@ -276,7 +279,7 @@ function _validateViaPath(
       errors.push(
         new ParseError(
           `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: relationship "${relName}" on ${currentObj.name} is missing @objectRef.`,
-          { code: "ERR_INVALID_ORIGIN" },
+          { code: "ERR_INVALID_ORIGIN", source: originSource },
         ),
       );
       return;
@@ -286,7 +289,7 @@ function _validateViaPath(
       errors.push(
         new ParseError(
           `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: relationship "${relName}" points to non-existent entity "${refTarget}".`,
-          { code: "ERR_INVALID_ORIGIN" },
+          { code: "ERR_INVALID_ORIGIN", source: originSource },
         ),
       );
       return;
@@ -306,15 +309,15 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             errors.push(
               new ParseError(
                 `origin.passthrough on ${obj.name}.${field.name}: missing @from.`,
-                { code: "ERR_INVALID_ORIGIN" },
+                { code: "ERR_INVALID_ORIGIN", source: origin.source },
               ),
             );
             continue;
           }
-          _validateFromPath(from, root, obj.name, field.name, errors);
+          _validateFromPath(from, root, obj.name, field.name, origin.source, errors);
           const via = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
-            _validateViaPath(via, root, obj.name, field.name, errors);
+            _validateViaPath(via, root, obj.name, field.name, origin.source, errors);
           }
         } else if (origin.subType === ORIGIN_SUBTYPE_AGGREGATE) {
           const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
@@ -322,23 +325,23 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             errors.push(
               new ParseError(
                 `origin.aggregate on ${obj.name}.${field.name}: missing @of.`,
-                { code: "ERR_INVALID_ORIGIN" },
+                { code: "ERR_INVALID_ORIGIN", source: origin.source },
               ),
             );
             continue;
           }
-          _validateFromPath(of_, root, obj.name, field.name, errors, "origin.aggregate.@of");
+          _validateFromPath(of_, root, obj.name, field.name, origin.source, errors, "origin.aggregate.@of");
           const via = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
           if (typeof via !== "string" || via === "") {
             errors.push(
               new ParseError(
                 `origin.aggregate on ${obj.name}.${field.name}: missing @via (aggregates require a relationship path).`,
-                { code: "ERR_INVALID_ORIGIN" },
+                { code: "ERR_INVALID_ORIGIN", source: origin.source },
               ),
             );
             continue;
           }
-          _validateViaPath(via, root, obj.name, field.name, errors);
+          _validateViaPath(via, root, obj.name, field.name, origin.source, errors);
         }
       }
     }
@@ -371,7 +374,7 @@ export function validateFieldObjectStorage(root: MetaData): ParseError[] {
         errors.push(
           new ParseError(
             `field "${obj.name}.${field.name}" sets @storage but has no @objectRef`,
-            { code: "ERR_STORAGE_WITHOUT_OBJECT_REF" },
+            { code: "ERR_STORAGE_WITHOUT_OBJECT_REF", source: field.source },
           ),
         );
       }
@@ -379,7 +382,7 @@ export function validateFieldObjectStorage(root: MetaData): ParseError[] {
         errors.push(
           new ParseError(
             `field "${obj.name}.${field.name}" sets @storage "flattened" with isArray=true; flattened storage requires a single nested value`,
-            { code: "ERR_STORAGE_FLATTENED_ARRAY" },
+            { code: "ERR_STORAGE_FLATTENED_ARRAY", source: field.source },
           ),
         );
       }
@@ -413,7 +416,7 @@ export function validateDataGridFilterValues(root: MetaData): ParseError[] {
       const filter = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_FILTER);
       // Type errors (e.g. legacy string form) are reported by validateAttrSchema.
       if (typeof filter !== "object" || filter === null || Array.isArray(filter)) continue;
-      checkFilterClauses(filter as Record<string, unknown>, allow, obj.name, layout.name, errors);
+      checkFilterClauses(filter as Record<string, unknown>, allow, obj.name, layout.name, layout.source, errors);
     }
   }
   return errors;
@@ -424,6 +427,7 @@ function checkFilterClauses(
   allow: Map<string, readonly string[]>,
   entityName: string,
   layoutName: string,
+  layoutSource: ErrorSource,
   errors: ParseError[],
 ): void {
   for (const [key, clause] of Object.entries(filter)) {
@@ -431,7 +435,7 @@ function checkFilterClauses(
       if (Array.isArray(clause)) {
         for (const sub of clause) {
           if (typeof sub === "object" && sub !== null && !Array.isArray(sub)) {
-            checkFilterClauses(sub as Record<string, unknown>, allow, entityName, layoutName, errors);
+            checkFilterClauses(sub as Record<string, unknown>, allow, entityName, layoutName, layoutSource, errors);
           }
         }
       }
@@ -443,7 +447,7 @@ function checkFilterClauses(
         new ParseError(
           `dataGrid layout "${layoutName}" on entity "${entityName}" has @filter over ` +
             `non-filterable field "${key}". Filterable fields: ${[...allow.keys()].join(", ") || "(none)"}`,
-          { code: "ERR_BAD_ATTR_FILTER" },
+          { code: "ERR_BAD_ATTR_FILTER", source: layoutSource },
         ),
       );
       continue;
@@ -457,7 +461,7 @@ function checkFilterClauses(
             new ParseError(
               `dataGrid layout "${layoutName}" on entity "${entityName}" @filter uses disallowed ` +
                 `op "${key}.${op}". Allowed ops for "${key}": ${allowedOps.join(", ")}`,
-              { code: "ERR_BAD_ATTR_FILTER" },
+              { code: "ERR_BAD_ATTR_FILTER", source: layoutSource },
             ),
           );
         }