@metaobjectsdev/metadata 1.0.2 → 1.0.4-rc.1

package/dist/library/library-sources.js

@@ -9,19 +9,30 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { FileSource } from "../loader/sources/file-source.js";
 import { InMemoryStringSource } from "../loader/meta-data-source.js";
-import { EMBEDDED_LIBRARY } from "./embedded-library.generated.js";
-// Package → ordered refs, derived from the generated embedded module so adding a
-// library file (which regenerates EMBEDDED_LIBRARY) needs no edit here.
-const REFS_BY_PACKAGE = (() => {
-    const map = {};
-    for (const ref of Object.keys(EMBEDDED_LIBRARY).sort()) {
-        const pkg = ref.split("/")[0];
-        if (pkg === undefined || pkg === "")
-            continue;
-        (map[pkg] ??= []).push(ref);
+import { EMBEDDED_LIBRARY, EMBEDDED_LIBRARY_MANIFESTS } from "./embedded-library.generated.js";
+const MANIFESTS = (() => {
+    const out = {};
+    for (const [name, text] of Object.entries(EMBEDDED_LIBRARY_MANIFESTS)) {
+        out[name] = JSON.parse(text);
     }
-    return map;
+    return out;
 })();
+/** Every shipped library's parsed manifest, keyed by name. */
+export function libraryManifests() {
+    return MANIFESTS;
+}
+/**
+ * Split a selection token into `[library, layer]` — `"iam"` → `["iam", ""]`,
+ * `"iam/db"` → `["iam", "db"]`.
+ *
+ * Path-like, so `libraries` stays `string[]` and no config schema moves. Only ONE
+ * separator is meaningful; anything after a second is part of the layer token, which
+ * keeps a typo failing loudly rather than resolving to a prefix.
+ */
+export function splitLayerToken(token) {
+    const i = token.indexOf("/");
+    return i === -1 ? [token, ""] : [token.slice(0, i), token.slice(i + 1)];
+}
 /**
  * Locate the repo-root `library/` directory by walking up from this module's
  * location until a directory contains BOTH `library/` and `server/` (the two
@@ -57,45 +68,156 @@ function getLibraryDir() {
  * available (Python's `project_config` draws the same line, in the same place).
  */
 export function knownLibraryPackages() {
-    return Object.keys(REFS_BY_PACKAGE).sort();
+    return Object.keys(MANIFESTS).sort();
 }
 /**
- * Returns a list of `MetaDataSource` instances for the requested library packages.
+ * Every package name a shipped library OWNS, across every library and layer.
  *
- * - Recognized packages: `"ai"` (others contribute no sources).
- * - Per ref: if the on-disk `library/<ref>.yaml` exists, returns a `FileSource`;
- *   otherwise falls back to an `InMemoryStringSource` built from the embedded content.
+ * The provenance key for FR-043 §5.4 — object coverage activates on adopter-authored
+ * requirements only, and "adopter-authored" means "declared outside every library
+ * package". It reads the manifests rather than node source ids deliberately: `packages`
+ * is a manifest fact the standalone gate resolves against the library loaded alone,
+ * while a source id differs between the on-disk dev layout (an absolute path) and the
+ * embedded one (`library:<ref>.yaml`), so a rule keyed on that would hold here and stop
+ * holding in an installed build.
+ */
+/**
+ * The source id a library file loads under, in EVERY build — `library:iam/model.yaml`.
  *
- * @param packages - Package names to include (e.g. `["ai"]`).
+ * Stable rather than path-derived so a library node's ADR-0009 provenance envelope reads
+ * the same from a checkout and from an installed package, carries no absolute path, and
+ * cannot be confused with an adopter file that happens to share a basename. The
+ * `library:` prefix is the discriminator {@link isLibraryFileId} reads.
  */
-export function librarySources(packages) {
-    const dir = getLibraryDir();
+export function libraryFileId(ref) {
+    return `${LIBRARY_FILE_ID_PREFIX}${ref}.yaml`;
+}
+/** The prefix every library source id carries. */
+export const LIBRARY_FILE_ID_PREFIX = "library:";
+/** True when a source id names a file a shipped library contributed. */
+export function isLibraryFileId(id) {
+    return id.startsWith(LIBRARY_FILE_ID_PREFIX);
+}
+export function libraryPackages() {
+    const out = new Set();
+    for (const manifest of Object.values(MANIFESTS)) {
+        for (const pkg of manifest.packages ?? [])
+            out.add(pkg);
+    }
+    return out;
+}
+/**
+ * Every selection token this build accepts, sorted — `["ai", "ai/db", "iam", "iam/db"]`.
+ *
+ * What a config error message should print, so an adopter who typed `iam/database` is
+ * shown the layer they meant rather than only the library they got right.
+ */
+export function knownLibraryTokens() {
     const out = [];
-    for (const pkg of packages) {
-        const refs = REFS_BY_PACKAGE[pkg];
-        if (refs === undefined)
-            continue; // unknown package — no sources
-        for (const ref of refs) {
-            if (dir !== undefined) {
-                const path = join(dir, `${ref}.yaml`);
-                if (existsSync(path)) {
-                    out.push(new FileSource(path));
-                    continue;
-                }
-            }
-            const embedded = EMBEDDED_LIBRARY[ref];
-            if (embedded !== undefined) {
-                out.push(new InMemoryStringSource(embedded, {
-                    id: `library:${ref}.yaml`,
-                    format: "yaml",
-                }));
-            }
-            else {
-                throw new Error(`library ref "${ref}" (package "${pkg}") has no on-disk file and no embedded entry — ` +
-                    `the embedded library module is stale; run scripts/generate-embedded-library.ts`);
-            }
+    for (const [name, manifest] of Object.entries(MANIFESTS)) {
+        for (const layer of Object.keys(manifest.layers ?? { "": { refs: [] } })) {
+            out.push(layer === "" ? name : `${name}/${layer}`);
         }
     }
-    return out;
+    return out.sort();
+}
+/**
+ * `MetaDataSource` instances for the requested library selection.
+ *
+ * **Layer-granular.** A token is `<library>` or `<library>/<layer>`; the CORE layer is
+ * the bare name. This used to be package-granular — every ref under a library came back
+ * for a bare `"iam"` — which under the layered design would have handed an adopter the
+ * db and ui layers they did not ask for, and with them a migration proposing nine tables.
+ *
+ * **`"iam/db"` IMPLIES `"iam"`**, and the implication is not a convenience: a db layer is
+ * nothing but `overlay: true` redeclarations, and an overlay whose target was never
+ * declared is `ERR_OVERLAY_NO_TARGET`. Resolving the layer without its core would produce
+ * exactly that error, so implying it is the only coherent reading.
+ *
+ * Refs are de-duplicated and returned in a stable order — core first, then each requested
+ * layer in the manifest's own order — because an overlay must be parsed after its base
+ * even though ADR-0055 applies overlays in a deferred pass.
+ *
+ * An unrecognised token contributes nothing and is skipped silently: that is right for a
+ * programmatic caller asking for something a given version may not ship. A name a HUMAN
+ * typed is a different case and is refused by the config readers, which call
+ * {@link knownLibraryTokens} to say what is available.
+ *
+ * @param selection - Tokens, e.g. `["iam", "iam/db"]`.
+ */
+export function librarySources(selection) {
+    const refs = [];
+    const seen = new Set();
+    const add = (ref) => {
+        if (seen.has(ref))
+            return;
+        seen.add(ref);
+        refs.push(ref);
+    };
+    // Core layers first, across every requested library, so a db layer named before its
+    // core in the config still parses after it.
+    //
+    // A token whose LAYER is unknown is dropped whole, not reduced to its core. The core is
+    // implied by a VALID layer token; implying it from an invalid one would answer a
+    // mistyped `iam/database` with an inert core and no tables — "I asked for the db layer
+    // and got nothing" with no diagnostic, which is the worst of the available outcomes.
+    const wanted = selection
+        .map(splitLayerToken)
+        .filter(([lib, layer]) => lib in MANIFESTS && (MANIFESTS[lib].layers ?? {})[layer] !== undefined);
+    for (const [lib] of wanted) {
+        for (const ref of MANIFESTS[lib].layers?.[""]?.refs ?? [])
+            add(ref);
+    }
+    for (const [lib, layer] of wanted) {
+        if (layer === "")
+            continue;
+        for (const ref of MANIFESTS[lib].layers?.[layer]?.refs ?? [])
+            add(ref);
+    }
+    return refs.map(libraryRefSource);
+}
+/**
+ * One library ref as a source — on-disk first, embedded otherwise.
+ *
+ * Factored out of {@link librarySources} because `meta eject <library>` needs the TEXT
+ * of one ref and must resolve it exactly the way a load does: an adopter ejecting from a
+ * checkout must get the file they can see, and from an installed package the embedded
+ * copy, with no third rule to keep in step.
+ */
+export function libraryRefSource(ref) {
+    const dir = getLibraryDir();
+    if (dir !== undefined) {
+        const path = join(dir, `${ref}.yaml`);
+        if (existsSync(path)) {
+            // The SAME id the embedded branch below uses, deliberately. A `FileSource`
+            // defaults its id to the file's BASENAME, which would make a library node's error
+            // envelope read `model.yaml` in a checkout and `library:iam/model.yaml` in an
+            // installed build — and would collide outright with an adopter file of that name.
+            // One stable id makes the two builds report identically and gives anything asking
+            // "did a library declare this node" an unambiguous answer.
+            return new FileSource(path, { id: libraryFileId(ref) });
+        }
+    }
+    const embedded = EMBEDDED_LIBRARY[ref];
+    if (embedded === undefined) {
+        throw new Error(`library ref "${ref}" has no on-disk file and no embedded entry — ` +
+            `the embedded library module is stale; run scripts/generate-embedded-library.ts`);
+    }
+    return new InMemoryStringSource(embedded, { id: libraryFileId(ref), format: "yaml" });
+}
+/** Every ref one library contributes, core layer first — what `meta eject` copies. */
+export function libraryRefs(name) {
+    const layers = MANIFESTS[name]?.layers ?? {};
+    const refs = [];
+    const seen = new Set();
+    for (const token of ["", ...Object.keys(layers).filter((k) => k !== "")]) {
+        for (const ref of layers[token]?.refs ?? []) {
+            if (seen.has(ref))
+                continue;
+            seen.add(ref);
+            refs.push(ref);
+        }
+    }
+    return refs;
 }
 //# sourceMappingURL=library-sources.js.map

package/dist/library/library-sources.js.map

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

package/dist/loader/meta-data-loader.d.ts

@@ -38,6 +38,50 @@ export interface LoadResult {
     warnings: LoaderWarning[];
     errors: Error[];
 }
+/** One root-level declaration as `declaredTopLevelKeys` structurally scans it —
+ *  before registry-driven parsing, super resolution, or merge. */
+export interface DeclaredTopLevelKey {
+    /** The wrapper key's TYPE segment (e.g. "object" for "object.entity"). A bare
+     *  wrapper key with no "." is its own type — this walk never consults the
+     *  registry for a default subType, because it never needs the subType. */
+    type: string;
+    /** The resolution key the declaration would carry once parsed: the child's
+     *  own `package` if set (expanded against the root's `package` via
+     *  `expandPackageForPath` when it's a relative, `::`-prefixed path — e.g.
+     *  root `acme` + own `::garage` → `acme::garage`), else the root's
+     *  `package` verbatim, then `::`, then its `name`. Exactly
+     *  `rootChildResolutionKey` (parser-core.ts) — including the relative-path
+     *  expansion, reusing `expandPackageForPath` rather than reimplementing it,
+     *  because a second copy is exactly how this walk and the real parser
+     *  silently disagreed on a relative package (task 17 fix-round-1: this
+     *  function used to return `::garage::Garage` for a fixture the real
+     *  loader resolves to `acme::garage::Garage`). */
+    key: string;
+    /** Whether the declaration's body carries `overlay: true`. */
+    overlay: boolean;
+}
+/**
+ * Structurally scan a source's raw content (JSON via `JSON.parse`; sigil-free
+ * authoring YAML via the raw YAML walker — `overlay: true` is a bare key
+ * before desugar) and report every top-level declaration under
+ * `metadata.root.children`: its type, the resolution key it would carry once
+ * parsed, and whether it carries `overlay: true`.
+ *
+ * A declaration with no (string, non-empty) `name` is skipped — a resolution
+ * key can't be computed for it, and the real parser will report it as a
+ * loader error rather than silently reusing or creating a node. Malformed
+ * root shapes (root missing, not an object, `children` absent or not an
+ * array) return `[]` rather than throwing — the real parse loop is where a
+ * genuine structural error surfaces; this walk must never crash a caller
+ * that is only trying to answer "what does this file declare".
+ *
+ * Written for the #160 overlay-only source partition, which ADR-0055 retired —
+ * overlays are now applied in a post-parse pass, so no ordering decision needs
+ * this walk. Its remaining caller is the `meta verify` overlay authoring lint,
+ * which needs per-file declaration provenance precisely because the MERGED tree
+ * has already lost which file contributed which declaration.
+ */
+export declare function declaredTopLevelKeys(content: string, format: MetaDataFormat): Promise<ReadonlyArray<DeclaredTopLevelKey>>;
 export declare class MetaDataLoader {
     private readonly _registry;
     private readonly _freeze;
@@ -120,27 +164,6 @@ export declare class MetaDataLoader {
     protected parseSource(content: string, source: MetaDataSource, parseOpts: ParseOptions): ParseResult;
     private static _yamlParser;
     private static _ensureYamlParser;
-    /**
-     * Stable-partition `sources` so that "overlay-only" sources — every top-level
-     * object declaration carries `overlay: true`, i.e. the source declares no base
-     * objects of its own and only re-opens objects declared elsewhere — are parsed
-     * LAST. Preserves original order within each group.
-     *
-     * A source whose content can't be read or structurally scanned stays in the
-     * base group (never overlay-only) — this partition must never crash the loader;
-     * any genuine read/parse failure surfaces later, in the real parse loop.
-     */
-    private static _partitionOverlayLast;
-    /**
-     * Structurally scan a source's raw content (JSON via JSON.parse; sigil-free
-     * authoring YAML via the raw YAML walker — `overlay: true` is a bare key
-     * before desugar) and report whether every top-level object declaration under
-     * `metadata.root.children` carries `overlay: true` (and there is at least one).
-     */
-    private static _isOverlayOnlySource;
-    /** True when the structurally-parsed root has ≥1 child and every top-level
-     * child node carries `overlay: true` (declares no base objects). */
-    private static _rootIsOverlayOnly;
     /**
      * Load metadata from one or more MetaDataSource instances. Sources are read
      * in order; each source's content is parsed and merged into the accumulating

package/dist/loader/meta-data-loader.d.ts.map

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

package/dist/loader/meta-data-loader.js

@@ -11,11 +11,11 @@ import { TypeId, TypeRegistry } from "../registry.js";
 import { coreProviders } from "../core-types.js";
 import { composeRegistry } from "../provider.js";
 import { TYPE_METADATA, SUBTYPE_ROOT } from "../shared/base-types.js";
-import { RESERVED_KEY_CHILDREN, RESERVED_KEY_OVERLAY } from "../shared/structural.js";
+import { PACKAGE_SEPARATOR, RESERVED_KEY_CHILDREN, RESERVED_KEY_NAME, RESERVED_KEY_OVERLAY, RESERVED_KEY_PACKAGE, TYPE_SUBTYPE_SEPARATOR, } from "../shared/structural.js";
 import { ParseError } from "../errors.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
-import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateSortableHasSupportedSubtype, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateIndexLookupFields, validateProjectionFilter, validateRetiredRequirementLinks } from "./validation-passes.js";
+import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateSortableHasSupportedSubtype, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateOneSideReferenceResolution, validateIndexLookupFields, validateProjectionFilter, validateRetiredRequirementLinks } from "./validation-passes.js";
 import { runRegisteredValidation } from "./validation-registry.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { validateSourceEscapes } from "../persistence/source/validate-source-escapes.js";
@@ -30,12 +30,94 @@ import { validateMaxOccurs } from "../validate-max-occurs.js";
 import { validateIdentityPassthrough } from "../core/identity/validate-identity-passthrough.js";
 import { validateAttrSchema } from "../attr-schema-validate.js";
 import { InMemoryStringSource } from "./meta-data-source.js";
+import { expandPackageForPath, applyPendingOverlays } from "../parser-core.js";
 // ---------------------------------------------------------------------------
 // Synthetic empty root (used when all sources fail to parse)
 // ---------------------------------------------------------------------------
 function makeSyntheticRoot() {
     return new MetaRoot(new TypeId(TYPE_METADATA, SUBTYPE_ROOT), "");
 }
+/**
+ * Structurally scan a source's raw content (JSON via `JSON.parse`; sigil-free
+ * authoring YAML via the raw YAML walker — `overlay: true` is a bare key
+ * before desugar) and report every top-level declaration under
+ * `metadata.root.children`: its type, the resolution key it would carry once
+ * parsed, and whether it carries `overlay: true`.
+ *
+ * A declaration with no (string, non-empty) `name` is skipped — a resolution
+ * key can't be computed for it, and the real parser will report it as a
+ * loader error rather than silently reusing or creating a node. Malformed
+ * root shapes (root missing, not an object, `children` absent or not an
+ * array) return `[]` rather than throwing — the real parse loop is where a
+ * genuine structural error surfaces; this walk must never crash a caller
+ * that is only trying to answer "what does this file declare".
+ *
+ * Written for the #160 overlay-only source partition, which ADR-0055 retired —
+ * overlays are now applied in a post-parse pass, so no ordering decision needs
+ * this walk. Its remaining caller is the `meta verify` overlay authoring lint,
+ * which needs per-file declaration provenance precisely because the MERGED tree
+ * has already lost which file contributed which declaration.
+ */
+export async function declaredTopLevelKeys(content, format) {
+    // Strip UTF-8 BOM if present (mirrors parseJson / parseYaml).
+    const normalized = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+    let parsed;
+    if (format === "json") {
+        parsed = JSON.parse(normalized);
+    }
+    else if (format === "yaml") {
+        const { parseYamlWithPositions } = await import("../core/yaml-positions-walker.js");
+        parsed = parseYamlWithPositions(normalized).value;
+    }
+    else {
+        return [];
+    }
+    return declaredTopLevelKeysFromParsedRoot(parsed);
+}
+/** The structural walk `declaredTopLevelKeys` performs once content is
+ *  structurally parsed — split out so it takes no format/BOM concerns. */
+function declaredTopLevelKeysFromParsedRoot(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    const parsedRecord = parsed;
+    // Canonical JSON always fuses the subType onto the root wrapper key
+    // ("metadata.root"); sigil-free YAML authoring writes the bare type
+    // ("metadata") and leaves the default subType to the registry — this
+    // structural walk runs BEFORE desugar/registry resolution, so it must
+    // accept both spellings rather than only ever matching JSON's.
+    const explicitRootKey = `${TYPE_METADATA}${TYPE_SUBTYPE_SEPARATOR}${SUBTYPE_ROOT}`; // "metadata.root"
+    const rootBody = parsedRecord[explicitRootKey] ?? parsedRecord[TYPE_METADATA];
+    if (typeof rootBody !== "object" || rootBody === null)
+        return [];
+    const rawRootPkg = rootBody[RESERVED_KEY_PACKAGE];
+    const rootPkg = typeof rawRootPkg === "string" ? rawRootPkg : "";
+    const children = rootBody[RESERVED_KEY_CHILDREN];
+    if (!Array.isArray(children))
+        return [];
+    const declared = [];
+    for (const child of children) {
+        if (typeof child !== "object" || child === null)
+            continue;
+        // Each child is a single-key wrapper: { "object.entity": { ... } }.
+        for (const [wrapperKey, body] of Object.entries(child)) {
+            if (typeof body !== "object" || body === null)
+                continue;
+            const bodyRecord = body;
+            const name = bodyRecord[RESERVED_KEY_NAME];
+            if (typeof name !== "string" || name === "")
+                continue;
+            const dotIdx = wrapperKey.indexOf(TYPE_SUBTYPE_SEPARATOR);
+            const type = dotIdx < 0 ? wrapperKey : wrapperKey.slice(0, dotIdx);
+            const rawOwnPkg = bodyRecord[RESERVED_KEY_PACKAGE];
+            const pkg = typeof rawOwnPkg === "string" && rawOwnPkg !== ""
+                ? expandPackageForPath(rootPkg, rawOwnPkg)
+                : rootPkg;
+            const key = pkg !== "" ? `${pkg}${PACKAGE_SEPARATOR}${name}` : name;
+            declared.push({ type, key, overlay: bodyRecord[RESERVED_KEY_OVERLAY] === true });
+        }
+    }
+    return declared;
+}
 // ---------------------------------------------------------------------------
 // MetaDataLoader class
 // ---------------------------------------------------------------------------
@@ -230,80 +312,6 @@ export class MetaDataLoader {
         MetaDataLoader._yamlParser = mod.parseYaml;
     }
     // ---------------------------------------------------------------------------
-    // #160 — overlay-only source partition (stable, overlay-only sources last)
-    // ---------------------------------------------------------------------------
-    /**
-     * Stable-partition `sources` so that "overlay-only" sources — every top-level
-     * object declaration carries `overlay: true`, i.e. the source declares no base
-     * objects of its own and only re-opens objects declared elsewhere — are parsed
-     * LAST. Preserves original order within each group.
-     *
-     * A source whose content can't be read or structurally scanned stays in the
-     * base group (never overlay-only) — this partition must never crash the loader;
-     * any genuine read/parse failure surfaces later, in the real parse loop.
-     */
-    static async _partitionOverlayLast(sources) {
-        const base = [];
-        const overlayOnly = [];
-        for (const source of sources) {
-            let isOverlayOnly = false;
-            try {
-                const content = await source.read();
-                isOverlayOnly = await MetaDataLoader._isOverlayOnlySource(content, source.format);
-            }
-            catch {
-                isOverlayOnly = false;
-            }
-            (isOverlayOnly ? overlayOnly : base).push(source);
-        }
-        return [...base, ...overlayOnly];
-    }
-    /**
-     * Structurally scan a source's raw content (JSON via JSON.parse; sigil-free
-     * authoring YAML via the raw YAML walker — `overlay: true` is a bare key
-     * before desugar) and report whether every top-level object declaration under
-     * `metadata.root.children` carries `overlay: true` (and there is at least one).
-     */
-    static async _isOverlayOnlySource(content, format) {
-        // Strip UTF-8 BOM if present (mirrors parseJson / parseYaml).
-        const normalized = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
-        let parsed;
-        if (format === "json") {
-            parsed = JSON.parse(normalized);
-        }
-        else if (format === "yaml") {
-            const { parseYamlWithPositions } = await import("../core/yaml-positions-walker.js");
-            parsed = parseYamlWithPositions(normalized).value;
-        }
-        else {
-            return false;
-        }
-        return MetaDataLoader._rootIsOverlayOnly(parsed);
-    }
-    /** True when the structurally-parsed root has ≥1 child and every top-level
-     * child node carries `overlay: true` (declares no base objects). */
-    static _rootIsOverlayOnly(parsed) {
-        if (typeof parsed !== "object" || parsed === null)
-            return false;
-        const rootKey = `${TYPE_METADATA}.${SUBTYPE_ROOT}`; // "metadata.root"
-        const rootBody = parsed[rootKey];
-        if (typeof rootBody !== "object" || rootBody === null)
-            return false;
-        const children = rootBody[RESERVED_KEY_CHILDREN];
-        if (!Array.isArray(children) || children.length === 0)
-            return false;
-        return children.every((child) => {
-            if (typeof child !== "object" || child === null)
-                return false;
-            // Each child is a single-key wrapper: { "object.projection": { ... } }.
-            const bodies = Object.values(child);
-            return (bodies.length > 0 &&
-                bodies.every((body) => typeof body === "object" &&
-                    body !== null &&
-                    body[RESERVED_KEY_OVERLAY] === true));
-        });
-    }
-    // ---------------------------------------------------------------------------
     // load — async pipeline over MetaDataSource[]
     // ---------------------------------------------------------------------------
     /**
@@ -338,19 +346,17 @@ export class MetaDataLoader {
         if (sources.some((s) => s.format === "yaml")) {
             await MetaDataLoader._ensureYamlParser();
         }
-        // #160 — this loader merges DURING parse (each source is streamed into the
-        // accumulating `root` via parseOpts.intoRoot). A source that ONLY re-opens
-        // objects declared elsewhere (every top-level object carries `overlay: true`)
-        // must therefore be parsed AFTER the sources that declare those base objects,
-        // or the overlaid node lands ahead of its base entities — leaving a projection
-        // before its base so order-dependent super-resolution can't resolve its
-        // `extends`/`@via`, and the streaming merge errors ERR_OVERLAY_NO_TARGET.
-        // Directory discovery order is not guaranteed to present base files first
-        // (basename sort can put an overlay-only file first), so stable-partition
-        // overlay-only sources to the END here, making the merge order-independent.
-        // Stable within each group preserves last-writer-wins overlay semantics.
-        sources = await MetaDataLoader._partitionOverlayLast(sources);
+        // ADR-0055 — sources are parsed in the order given. Overlays are not applied
+        // during the walk: each parse QUEUES its `overlay: true` declarations and the
+        // loader applies them below, once every base exists. That retired the #160
+        // overlay-only source partition, whose file-level predicate could not rescue a
+        // MIXED file (plain + overlay declarations together) and therefore left the
+        // load order-dependent — and divergent across ports, since every port's
+        // directory walk orders files differently.
         let root;
+        // ADR-0055 — every source's queue, concatenated in parse order, which is
+        // already "source order, then declaration order within a source" (G2).
+        const pendingOverlays = [];
         // Parse all sources with super resolution DEFERRED so cross-file super
         // refs work — one source may declare a super target that's defined in a
         // source parsed later. A second pass (resolveDeferredSupers) resolves
@@ -372,6 +378,10 @@ export class MetaDataLoader {
                 registry: this._registry,
                 strict: this._strict,
                 deferSuperResolution: true,
+                // ADR-0055 — queue overlays; this loader drains them after every source
+                // is parsed. Without it each document would drain its own queue and an
+                // overlay could still not reach a base declared in a later source.
+                deferOverlays: true,
                 sourceName: source.id,
             };
             if (root !== undefined)
@@ -384,6 +394,7 @@ export class MetaDataLoader {
                 // source). The legacy `warnings` channel still flows into the
                 // WARN_LEGACY-wrapping path below for unchanged behavior.
                 envelopeWarnings.push(...parseResult.envelopeWarnings);
+                pendingOverlays.push(...parseResult.pendingOverlays);
                 root = parseResult.root;
             }
             catch (err) {
@@ -392,6 +403,20 @@ export class MetaDataLoader {
                     : new Error(`Parse error in "${source.id}": ${String(err)}`));
             }
         }
+        // ADR-0055 — apply every queued overlay now: all plain declarations from all
+        // sources are in the tree (G1), so a base/overlay relation no longer depends
+        // on file order (G4). This runs BEFORE super resolution so a node an overlay
+        // contributes is visible to every `extends` (G5) — the ordering #160's
+        // partition was reaching for, now guaranteed rather than approximated.
+        if (root !== undefined && pendingOverlays.length > 0) {
+            const applied = applyPendingOverlays(pendingOverlays, {
+                registry: this._registry,
+                strict: this._strict,
+            });
+            warnings.push(...applied.warnings);
+            errors.push(...applied.errors);
+            envelopeWarnings.push(...applied.envelopeWarnings);
+        }
         // Second pass: resolve every deferred super ref against the full tree.
         // Unresolved refs are always errors (matches the original eager-throw
         // behavior — broken metadata is broken regardless of strict mode).
@@ -458,6 +483,11 @@ export class MetaDataLoader {
             // @symmetric is self-join-only + mutually exclusive with @sourceRefField; M:N attrs
             // are invalid on a 1:N relationship.
             errors.push(...validateRelationships(root));
+            // Rule (e) — #368: a `@cardinality: one` relationship must resolve to
+            // exactly one identity.reference when its declaring entity holds more
+            // than one onto the same target; an unresolvable case is a load error
+            // naming the candidates (ADR-0029 §5).
+            errors.push(...validateOneSideReferenceResolution(root));
             // index.lookup @fields resolution — each index.lookup must name ≥1 field,
             // and every field must exist in the entity's effective (resolved) field set
             // (ADR-0039: resolving accessor, so inherited fields via extends are visible).