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

package/README.md

@@ -11,13 +11,64 @@ pnpm add @metaobjectsdev/metadata
 ## Usage
 
 ```ts
-import { MetaDataLoader, InMemorySource } from "@metaobjectsdev/metadata";
+import { MetaDataLoader, InMemoryStringSource } from "@metaobjectsdev/metadata";
 
 const json = `{ "metadata.root": { "package": "demo", "children": [] } }`;
-const result = await new MetaDataLoader().load([new InMemorySource(json)]);
+const result = await new MetaDataLoader().load([new InMemoryStringSource(json)]);
 ```
 
-The public loader API is `MetaDataLoader` + `InMemorySource`. A `MetaDataLoader` instance is single-use; construct a new one per load.
+The public loader API is `MetaDataLoader` + `InMemoryStringSource`. A `MetaDataLoader` instance is single-use; construct a new one per load.
+
+## Loader errors (FR5a)
+
+Every loader error conforms to the cross-port `LoaderError` envelope
+(ADR-0009):
+
+```ts
+interface LoaderError {
+  code: string;            // ERR_UNKNOWN_TYPE, ERR_BAD_ATTR_VALUE, ...
+  message: string;
+  source: ErrorSource;     // always populated
+}
+
+type ErrorSource =
+  | { format: "json"; files: [string]; jsonPath: string }
+  | { format: "yaml"; files: [string]; jsonPath: string; yamlPosition?: { line: number; col: number } }
+  | { format: "merged"; files: string[]; jsonPath: string; contributors: Contributor[] }
+  | { format: "resolved"; files: string[]; jsonPath?: string; referrer?: string; target?: string }
+  | { format: "database"; dbLocation: { table: string; id: string }; jsonPath?: string }
+  | { format: "code"; caller?: string };
+```
+
+Every `MetaData` node also carries a populated `source` field, so
+post-load consumers (drift detection, MCP, debug tools) can answer
+"where did this node come from?" without an extra lookup table.
+
+`LoadResult.warnings` is a parallel `LoaderWarning[]` channel — same
+envelope shape, `WARN_*` prefixed codes. Pre-FR5a string warnings are
+wrapped at the loader boundary as `WARN_LEGACY` envelopes; FR5c will
+retire the legacy code by routing each emit site through a proper
+envelope-shaped helper.
+
+The package re-exports the envelope types and the `codeSource()`
+helper for consumers that catch + repackage `ParseError`s or build
+synthetic envelopes for programmatic-construction tests:
+
+```ts
+import type {
+  ErrorSource,
+  LoaderError,
+  LoaderWarning,
+  NodeContext,
+  Contributor,
+} from "@metaobjectsdev/metadata";
+import { codeSource } from "@metaobjectsdev/metadata";
+```
+
+See [ADR-0009](../../../../spec/decisions/ADR-0009-loader-error-envelope-and-source-on-node.md)
+for the full schema and the FR5 family for the per-error-class
+rollout plan (5a JSON shape, 5b YAML positions, 5c multi-file merge
+attribution, 5d reference resolution, 5e database sources).
 
 ## Links
 

package/dist/attr-schema-validate.js

@@ -67,7 +67,7 @@ function validateNode(node, registry, errors, reportedConflicts) {
     for (const ca of registry.getCommonAttrs()) {
         if (byName.has(ca.name)) {
             if (!reportedConflicts.has(typeKey)) {
-                errors.push(new ParseError(`Common attr '${ca.name}' conflicts with per-type attr on ${typeKey}`, { code: "ERR_PROVIDER_ATTR_CONFLICT" }));
+                errors.push(new ParseError(`Common attr '${ca.name}' conflicts with per-type attr on ${typeKey}`, { code: "ERR_PROVIDER_ATTR_CONFLICT", source: node.source }));
                 reportedConflicts.add(typeKey);
             }
             continue; // per-type wins
@@ -87,7 +87,7 @@ function validateNode(node, registry, errors, reportedConflicts) {
     const effective = node.attrs();
     for (const spec of byName.values()) {
         if (spec.required && !effective.has(spec.name)) {
-            errors.push(new ParseError(`${nodeLabel(node)} is missing required attribute '@${spec.name}'`, { code: "ERR_MISSING_REQUIRED_ATTR" }));
+            errors.push(new ParseError(`${nodeLabel(node)} is missing required attribute '@${spec.name}'`, { code: "ERR_MISSING_REQUIRED_ATTR", source: node.source }));
         }
     }
     // --- Checks 2 + 3: declared attrs on the node are well-typed + in range ---
@@ -104,7 +104,7 @@ function validateNode(node, registry, errors, reportedConflicts) {
             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
             }
@@ -114,7 +114,7 @@ function validateNode(node, registry, errors, reportedConflicts) {
             if (!spec.allowedValues.includes(value)) {
                 errors.push(new ParseError(`${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" }));
+                    `${spec.allowedValues.map((v) => String(v)).join(", ")}`, { code: "ERR_BAD_ATTR_VALUE", source: node.source }));
             }
         }
     }
@@ -129,7 +129,7 @@ function validateNode(node, registry, errors, reportedConflicts) {
         const rawValues = node.ownAttrs().get(FIELD_ATTR_VALUES);
         if (Array.isArray(rawValues)) {
             if (rawValues.length === 0) {
-                errors.push(new ParseError(`${nodeLabel(node)} must declare at least one value in '@${FIELD_ATTR_VALUES}'.`, { code: "ERR_BAD_ATTR_VALUE" }));
+                errors.push(new ParseError(`${nodeLabel(node)} must declare at least one value in '@${FIELD_ATTR_VALUES}'.`, { code: "ERR_BAD_ATTR_VALUE", source: node.source }));
             }
             else {
                 // rawValues is the only array variant of AttrValue, so each member is a
@@ -139,10 +139,10 @@ function validateNode(node, registry, errors, reportedConflicts) {
                     if (!ENUM_MEMBER_PATTERN.test(member)) {
                         errors.push(new ParseError(`${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" }));
+                            `Non-identifier-safe member strings require a symbol↔value mapping (deferred).`, { 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" }));
+                        errors.push(new ParseError(`${nodeLabel(node)} attribute '@${FIELD_ATTR_VALUES}' has duplicate member '${member}'.`, { code: "ERR_BAD_ATTR_VALUE", source: node.source }));
                     }
                     else {
                         seen.add(member);

package/dist/attr-schema-validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"attr-schema-validate.js","sourceRoot":"","sources":["../src/attr-schema-validate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"attr-schema-validate.js","sourceRoot":"","sources":["../src/attr-schema-validate.ts"],"names":[],"mappings":"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"}

package/dist/core/export-json.d.ts

@@ -1,4 +1,4 @@
-import type { LoadOptions } from "../loader/meta-data-loader.js";
+import { type LoadOptions } from "../loader/meta-data-loader.js";
 export interface ExportResult {
     /** The single flattened canonical-JSON document of the entire loaded metadata model. */
     json: string;
@@ -14,14 +14,13 @@ 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 declare function loadAndExportJson(dir: string, opts?: LoadOptions & {
     exclude?: string[];

package/dist/core/export-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export-json.d.ts","sourceRoot":"","sources":["../../src/core/export-json.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAOjE,MAAM,WAAW,YAAY;IAC3B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAC1C,OAAO,CAAC,YAAY,CAAC,CAYvB"}
+{"version":3,"file":"export-json.d.ts","sourceRoot":"","sources":["../../src/core/export-json.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAOjF,MAAM,WAAW,YAAY;IAC3B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAC1C,OAAO,CAAC,YAAY,CAAC,CAWvB"}

package/dist/core/export-json.js

@@ -10,36 +10,34 @@
 //   - 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.
-import { FileMetaDataLoader } from "./file-meta-data-loader.js";
+//   - 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 { MetaDataLoader } from "../loader/meta-data-loader.js";
 import { canonicalSerialize } from "../serializer-json.js";
 /**
  * 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, opts) {
-    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),
     };
 }
 //# sourceMappingURL=export-json.js.map

package/dist/core/export-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"export-json.js","sourceRoot":"","sources":["../../src/core/export-json.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,2EAA2E;AAC3E,uEAAuE;AACvE,iEAAiE;AACjE,EAAE;AACF,oDAAoD;AACpD,+EAA+E;AAC/E,gFAAgF;AAChF,kFAAkF;AAClF,gEAAgE;AAChE,8EAA8E;AAC9E,8EAA8E;AAC9E,sCAAsC;AAEtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAkB3D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW,EACX,IAA2C;IAE3C,MAAM,EAAE,OAAO,EAAE,GAAG,UAAU,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAClD,oFAAoF;IACpF,MAAM,OAAO,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO;QACL,IAAI;QACJ,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"export-json.js","sourceRoot":"","sources":["../../src/core/export-json.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,2EAA2E;AAC3E,uEAAuE;AACvE,iEAAiE;AACjE,EAAE;AACF,oDAAoD;AACpD,+EAA+E;AAC/E,gFAAgF;AAChF,kFAAkF;AAClF,8EAA8E;AAC9E,0EAA0E;AAC1E,6EAA6E;AAC7E,yBAAyB;AAEzB,OAAO,EAAE,cAAc,EAAoB,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAkB3D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW,EACX,IAA2C;IAE3C,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO;QACL,IAAI;QACJ,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,2EAA2E;QAC3E,0EAA0E;QAC1E,2BAA2B;QAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;KAChD,CAAC;AACJ,CAAC"}

package/dist/core/index.d.ts

@@ -1,5 +1,7 @@
-export { FileSource } from "./file-source.js";
-export { FileMetaDataLoader } from "./file-meta-data-loader.js";
+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/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,YAAY,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAE5D,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/core/index.js

@@ -4,8 +4,12 @@
 // dependency: the file loaders, the YAML authoring parser, and the
 // 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 { UriSource } from "../loader/sources/uri-source.js";
 export { parseYaml } from "./parser-yaml.js";
 export { loadAndExportJson } from "./export-json.js";
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,uEAAuE;AACvE,mEAAmE;AACnE,4EAA4E;AAC5E,iEAAiE;AAEjE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,uEAAuE;AACvE,mEAAmE;AACnE,4EAA4E;AAC5E,iEAAiE;AAEjE,yEAAyE;AACzE,8EAA8E;AAC9E,wEAAwE;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAExE,OAAO,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAE5D,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/core/parser-yaml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser-yaml.d.ts","sourceRoot":"","sources":["../../src/core/parser-yaml.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGnE,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,WAAW,CAgD1E"}
+{"version":3,"file":"parser-yaml.d.ts","sourceRoot":"","sources":["../../src/core/parser-yaml.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAcnE,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,WAAW,CAgD1E"}

package/dist/core/parser-yaml.js

@@ -6,8 +6,17 @@
 // produces.
 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 { desugar } from "./yaml-desugar.js";
+/** FR5a / ADR-0009 — build a YAML-source envelope rooted at "$".
+ *  yamlPosition is FR5b territory and not populated here. */
+function yamlSource(sourceName) {
+    return {
+        format: "yaml",
+        files: [sourceName ?? "<unknown>"],
+        jsonPath: "$",
+    };
+}
 export function parseYaml(content, opts) {
     // Strip UTF-8 BOM if present (consistent with parseJson).
     const normalizedContent = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
@@ -18,7 +27,7 @@ export function parseYaml(content, opts) {
         parsed = parseYamlText(normalizedContent);
     }
     catch (err) {
-        throw new ParseError(`Invalid YAML: ${err.message}`, { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" });
+        throw new ParseError(`Invalid YAML: ${err.message}`, { code: "ERR_MALFORMED_YAML", source: yamlSource(opts.sourceName) });
     }
     // Desugar the sugared authoring object into the canonical structure.
     const { canonical, errors: desugarErrors } = desugar(parsed, opts.registry);
@@ -26,7 +35,7 @@ export function parseYaml(content, opts) {
     // first desugar error as a throw — parallels parseJson's top-level throws.
     if (Object.keys(canonical).length === 0) {
         const first = desugarErrors[0];
-        throw new ParseError(first.message, { ...errOpts(opts.sourceName), code: first.code ?? "ERR_MALFORMED_YAML" });
+        throw new ParseError(first.message, { code: first.code ?? "ERR_MALFORMED_YAML", source: yamlSource(opts.sourceName) });
     }
     const result = buildTree(canonical, opts);
     // Merge collected desugar errors ahead of buildTree's own collected errors.
@@ -34,8 +43,8 @@ export function parseYaml(content, opts) {
     // ERR_YAML_COERCION from the D2 type-coercion guard); the malformed-document
     // shape errors fall back to ERR_MALFORMED_YAML.
     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,

package/dist/core/parser-yaml.js.map

@@ -1 +1 @@
-{"version":3,"file":"parser-yaml.js","sourceRoot":"","sources":["../../src/core/parser-yaml.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,6EAA6E;AAC7E,YAAY;AAEZ,OAAO,EAAE,KAAK,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,IAAkB;IAC3D,0DAA0D;IAC1D,MAAM,iBAAiB,GACrB,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAEhE,wEAAwE;IACxE,+EAA+E;IAC/E,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,UAAU,CAClB,iBAAkB,GAAa,CAAC,OAAO,EAAE,EACzC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAC5D,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAE5E,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAE,CAAC;QAChC,MAAM,IAAI,UAAU,CAClB,KAAK,CAAC,OAAO,EACb,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,oBAAoB,EAAE,CAC1E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAE1C,4EAA4E;IAC5E,iEAAiE;IACjE,6EAA6E;IAC7E,gDAAgD;IAChD,MAAM,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAC1C,CAAC,CAAC,EAAE,EAAE,CACJ,IAAI,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE;QACxB,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;QAC3B,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,oBAAoB;KACrC,CAAC,CACL,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,CAAC,GAAG,kBAAkB,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;KAClD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"parser-yaml.js","sourceRoot":"","sources":["../../src/core/parser-yaml.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,6EAA6E;AAC7E,YAAY;AAEZ,OAAO,EAAE,KAAK,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C;6DAC6D;AAC7D,SAAS,UAAU,CAAC,UAA8B;IAChD,OAAO;QACL,MAAM,EAAE,MAAM;QACd,KAAK,EAAE,CAAC,UAAU,IAAI,WAAW,CAAC;QAClC,QAAQ,EAAE,GAAG;KACd,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,IAAkB;IAC3D,0DAA0D;IAC1D,MAAM,iBAAiB,GACrB,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAEhE,wEAAwE;IACxE,+EAA+E;IAC/E,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,UAAU,CAClB,iBAAkB,GAAa,CAAC,OAAO,EAAE,EACzC,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CACpE,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAE5E,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAE,CAAC;QAChC,MAAM,IAAI,UAAU,CAClB,KAAK,CAAC,OAAO,EACb,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,oBAAoB,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAClF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAE1C,4EAA4E;IAC5E,iEAAiE;IACjE,6EAA6E;IAC7E,gDAAgD;IAChD,MAAM,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAC1C,CAAC,CAAC,EAAE,EAAE,CACJ,IAAI,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE;QACxB,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,oBAAoB;QACpC,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC;KACpC,CAAC,CACL,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,CAAC,GAAG,kBAAkB,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;KAClD,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -1,14 +1,34 @@
+import type { ErrorSource, LoaderError, NodeContext } from "./source.js";
 /** Stable, language-neutral error codes — mirrors fixtures/conformance/ERROR-CODES.json. */
 export declare const ERROR_CODES: readonly ["ERR_TOP_LEVEL_NOT_OBJECT", "ERR_UNKNOWN_TYPE", "ERR_UNKNOWN_SUBTYPE", "ERR_MISSING_SUBTYPE", "ERR_DUPLICATE_NAME", "ERR_UNRESOLVED_SUPER", "ERR_INVALID_SUBTYPE_CHILD", "ERR_UNKNOWN_ATTR", "ERR_BAD_ATTR_VALUE", "ERR_BAD_DEFAULT_SORT_FIELD", "ERR_PROVIDER_DEPENDENCY_CYCLE", "ERR_PROVIDER_DUPLICATE_ID", "ERR_PROVIDER_MISSING_DEPENDENCY", "ERR_PROVIDER_ATTR_CONFLICT", "ERR_MALFORMED_JSON", "ERR_MISSING_REQUIRED_ATTR", "ERR_SUBTYPE_RULE_VIOLATION", "ERR_OVERLAY_NO_TARGET", "ERR_MALFORMED_YAML", "ERR_INVALID_ORIGIN", "ERR_INVALID_TEMPLATE", "ERR_VAR_NOT_ON_PAYLOAD", "ERR_PARTIAL_UNRESOLVED", "ERR_REQUIRED_SLOT_UNUSED", "ERR_OUTPUT_TAG_MISSING", "ERR_BAD_ATTR_FILTER", "ERR_STORAGE_FLATTENED_ARRAY", "ERR_STORAGE_WITHOUT_OBJECT_REF", "ERR_RESERVED_ATTR", "ERR_SOURCE_NO_PRIMARY", "ERR_SOURCE_MULTIPLE_PRIMARY", "ERR_YAML_COERCION", "ERR_UNKNOWN"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
-export declare class ParseError extends Error {
-    readonly source: string | undefined;
-    readonly path: string | undefined;
-    readonly code: ErrorCode | undefined;
-    constructor(message: string, opts?: {
-        source?: string;
-        path?: string;
-        code?: ErrorCode;
+/**
+ * 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 declare 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: {
+        code: ErrorCode;
+        source: ErrorSource;
+        suggestions?: string[];
+        fixture?: string;
+        node?: NodeContext;
     });
 }
 /**

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,4FAA4F;AAc5F,eAAO,MAAM,WAAW,41BAqCd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;gBAGnC,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE;CAQ9D;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE;CAKzD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEzE,4FAA4F;AAc5F,eAAO,MAAM,WAAW,41BAqCd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAW,SAAQ,KAAM,YAAW,WAAW;IAC1D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;gBAG1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QACJ,IAAI,EAAE,SAAS,CAAC;QAChB,MAAM,EAAE,WAAW,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,WAAW,CAAC;KACpB;CAiBJ;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE;CAKzD"}

package/dist/errors.js

@@ -51,16 +51,42 @@ export const ERROR_CODES = [
     "ERR_YAML_COERCION",
     "ERR_UNKNOWN",
 ];
+/**
+ * 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 {
-    source;
-    path; // logical path within the JSON, e.g. "metadata.children[2].field"
     code;
+    source;
+    suggestions;
+    fixture;
+    node;
     constructor(message, opts) {
         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.suggestions = opts.suggestions;
+        }
+        if (opts.fixture !== undefined) {
+            this.fixture = opts.fixture;
+        }
+        if (opts.node !== undefined) {
+            this.node = opts.node;
+        }
     }
 }
 /**

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAE/C,4FAA4F;AAC5F,kFAAkF;AAClF,yDAAyD;AACzD,4FAA4F;AAC5F,gGAAgG;AAChG,2EAA2E;AAC3E,0FAA0F;AAC1F,EAAE;AACF,oFAAoF;AACpF,uFAAuF;AACvF,mFAAmF;AACnF,uFAAuF;AACvF,uFAAuF;AACvF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,0BAA0B;IAC1B,kBAAkB;IAClB,qBAAqB;IACrB,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;IACtB,2BAA2B;IAC3B,kBAAkB;IAClB,oBAAoB;IACpB,4BAA4B;IAC5B,+BAA+B;IAC/B,2BAA2B;IAC3B,iCAAiC;IACjC,4BAA4B;IAC5B,oBAAoB;IACpB,2BAA2B;IAC3B,4BAA4B;IAC5B,uBAAuB;IACvB,oBAAoB;IACpB,oBAAoB;IACpB,sBAAsB;IACtB,wBAAwB;IACxB,wBAAwB;IACxB,0BAA0B;IAC1B,wBAAwB;IACxB,qBAAqB;IACrB,6BAA6B;IAC7B,gCAAgC;IAChC,qFAAqF;IACrF,mBAAmB;IACnB,uBAAuB;IACvB,6BAA6B;IAC7B,uEAAuE;IACvE,oEAAoE;IACpE,mBAAmB;IACnB,aAAa;CACL,CAAC;AAIX,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,MAAM,CAAqB;IAC3B,IAAI,CAAqB,CAAC,kEAAkE;IAC5F,IAAI,CAAwB;IAErC,YACE,OAAe,EACf,IAA2D;QAE3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;IACzB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAwB;IAErC,YAAY,OAAe,EAAE,IAA2B;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAI/C,4FAA4F;AAC5F,kFAAkF;AAClF,yDAAyD;AACzD,4FAA4F;AAC5F,gGAAgG;AAChG,2EAA2E;AAC3E,0FAA0F;AAC1F,EAAE;AACF,oFAAoF;AACpF,uFAAuF;AACvF,mFAAmF;AACnF,uFAAuF;AACvF,uFAAuF;AACvF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,0BAA0B;IAC1B,kBAAkB;IAClB,qBAAqB;IACrB,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;IACtB,2BAA2B;IAC3B,kBAAkB;IAClB,oBAAoB;IACpB,4BAA4B;IAC5B,+BAA+B;IAC/B,2BAA2B;IAC3B,iCAAiC;IACjC,4BAA4B;IAC5B,oBAAoB;IACpB,2BAA2B;IAC3B,4BAA4B;IAC5B,uBAAuB;IACvB,oBAAoB;IACpB,oBAAoB;IACpB,sBAAsB;IACtB,wBAAwB;IACxB,wBAAwB;IACxB,0BAA0B;IAC1B,wBAAwB;IACxB,qBAAqB;IACrB,6BAA6B;IAC7B,gCAAgC;IAChC,qFAAqF;IACrF,mBAAmB;IACnB,uBAAuB;IACvB,6BAA6B;IAC7B,uEAAuE;IACvE,oEAAoE;IACpE,mBAAmB;IACnB,aAAa;CACL,CAAC;AAIX;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,IAAI,CAAY;IAChB,MAAM,CAAc;IACpB,WAAW,CAAY;IACvB,OAAO,CAAU;IACjB,IAAI,CAAe;IAE5B,YACE,OAAe,EACf,IAMC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,wDAAwD;QACxD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YAClC,IAAmC,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACtE,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9B,IAA6B,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QACxD,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3B,IAA+B,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACpD,CAAC;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAwB;IAErC,YAAY,OAAe,EAAE,IAA2B;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;IACzB,CAAC;CACF"}

package/dist/index.d.ts

@@ -64,12 +64,15 @@ export type { SerializeOptions } from "./serializer-json.js";
 export { resolveSuperRef } from "./super-resolve.js";
 export { MetaDataLoader } from "./loader/meta-data-loader.js";
 export type { LoadOptions, LoadResult, LoadingState } from "./loader/meta-data-loader.js";
-export { InMemorySource } from "./loader/meta-data-source.js";
+export { InMemoryStringSource } from "./loader/meta-data-source.js";
 export type { MetaDataSource, MetaDataFormat } from "./loader/meta-data-source.js";
+export { loadDirectory, loadUris, loadString, } from "./loader/shortcuts.js";
 export { ParseError, MetaModelError, ERROR_CODES } from "./errors.js";
 export type { ErrorCode } from "./errors.js";
+export type { ErrorSource, LoaderError, LoaderWarning, NodeContext, Contributor, } from "./source.js";
+export { codeSource } from "./source.js";
 export { validateAttrSchema } from "./attr-schema-validate.js";
 export type { AttrSchemaValidationResult } from "./attr-schema-validate.js";
-export { toSnakeCase, pluralize, resolveTableName, resolveColumnName, resolveTableSchema, buildNameMap, stripPackage, } from "./naming.js";
-export type { EntityNameMap } from "./naming.js";
+export { toSnakeCase, toKebabCase, pluralize, applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY, resolveTableName, resolveColumnName, resolveTableSchema, buildNameMap, stripPackage, } from "./naming.js";
+export type { EntityNameMap, ColumnNamingStrategy } from "./naming.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -71,12 +71,19 @@ export { serializeJson, canonicalSerialize, inferAttrSubType } from "./serialize
 export { resolveSuperRef } from "./super-resolve.js";
 // Loader hierarchy
 export { MetaDataLoader } from "./loader/meta-data-loader.js";
-export { InMemorySource } from "./loader/meta-data-source.js";
+export { InMemoryStringSource } from "./loader/meta-data-source.js";
+// Module-level loader shortcuts — delegate to MetaDataLoader.from* static
+// factories. The shortcuts honor the ergonomic per-port pattern (TS and
+// Python expose both class statics AND module-level functions); Java/C# stay
+// class-only. Browser safety is preserved: the underlying sources are
+// loaded via dynamic import inside MetaDataLoader.from*.
+export { loadDirectory, loadUris, loadString, } from "./loader/shortcuts.js";
 // Errors
 export { ParseError, MetaModelError, ERROR_CODES } from "./errors.js";
+export { codeSource } from "./source.js";
 // Attribute-schema validation pass (Phase A3)
 export { validateAttrSchema } from "./attr-schema-validate.js";
 // Naming — hoisted from runtime-ts in v0.2.3 so multiple consumers (runtime-ts, migrate-ts, codegen-ts)
 // share identical name resolution. See spec §4.1.
-export { toSnakeCase, pluralize, resolveTableName, resolveColumnName, resolveTableSchema, buildNameMap, stripPackage, } from "./naming.js";
+export { toSnakeCase, toKebabCase, pluralize, applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY, resolveTableName, resolveColumnName, resolveTableSchema, buildNameMap, stripPackage, } from "./naming.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/json-path.d.ts

@@ -0,0 +1,8 @@
+export declare class JsonPathBuilder {
+    private readonly segments;
+    pushKey(key: string): void;
+    pushIndex(idx: number): void;
+    pop(): void;
+    toString(): string;
+}
+//# sourceMappingURL=json-path.d.ts.map

package/dist/json-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-path.d.ts","sourceRoot":"","sources":["../src/json-path.ts"],"names":[],"mappings":"AAiBA,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI1B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI5B,GAAG,IAAI,IAAI;IAIX,QAAQ,IAAI,MAAM;CAanB"}

package/dist/json-path.js

@@ -0,0 +1,39 @@
+// server/typescript/packages/metadata/src/json-path.ts
+//
+// FR5a / ADR-0009 — Canonical JSONPath builder.
+//
+// Construction rules (cross-port-aligned):
+//   - Root is `$`.
+//   - Object keys matching /^[A-Za-z_][A-Za-z0-9_]*$/ use dot notation: `.foo`.
+//   - All other keys use single-quoted bracket form: `['my-key']`, `['@attr']`.
+//   - Array indices use bracket form: `[N]`.
+//   - No trailing dots, no whitespace.
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export class JsonPathBuilder {
+    segments = [];
+    pushKey(key) {
+        this.segments.push({ kind: "key", value: key });
+    }
+    pushIndex(idx) {
+        this.segments.push({ kind: "index", value: idx });
+    }
+    pop() {
+        this.segments.pop();
+    }
+    toString() {
+        let out = "$";
+        for (const seg of this.segments) {
+            if (seg.kind === "index") {
+                out += `[${seg.value}]`;
+            }
+            else if (IDENT_RE.test(seg.value)) {
+                out += `.${seg.value}`;
+            }
+            else {
+                out += `['${seg.value.replace(/'/g, "\\'")}']`;
+            }
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=json-path.js.map

package/dist/json-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-path.js","sourceRoot":"","sources":["../src/json-path.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,gDAAgD;AAChD,EAAE;AACF,2CAA2C;AAC3C,mBAAmB;AACnB,gFAAgF;AAChF,gFAAgF;AAChF,6CAA6C;AAC7C,uCAAuC;AAEvC,MAAM,QAAQ,GAAG,0BAA0B,CAAC;AAM5C,MAAM,OAAO,eAAe;IACT,QAAQ,GAAc,EAAE,CAAC;IAE1C,OAAO,CAAC,GAAW;QACjB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,SAAS,CAAC,GAAW;QACnB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,GAAG;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;IACtB,CAAC;IAED,QAAQ;QACN,IAAI,GAAG,GAAG,GAAG,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACzB,GAAG,IAAI,IAAI,GAAG,CAAC,KAAK,GAAG,CAAC;YAC1B,CAAC;iBAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpC,GAAG,IAAI,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,GAAG,IAAI,KAAK,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;YACjD,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}