@metaobjectsdev/metadata 0.9.0-rc.1 → 0.10.0

package/src/errors.ts

@@ -23,7 +23,32 @@ export const ERROR_CODES = [
   "ERR_MISSING_SUBTYPE",
   "ERR_DUPLICATE_NAME",
   "ERR_UNRESOLVED_SUPER",
+  // FR-024 (ADR-0029) — a dotted `Entity.child` extends ref resolved to a node
+  // whose type or subtype does not match the extending node's. Dotted-only.
+  "ERR_EXTENDS_TARGET_MISMATCH",
+  // FR-024 — an identity.* node has no name. Identities are named,
+  // author-chosen (e.g. "id"), so the dotted by-name extends form can
+  // address them.
+  "ERR_IDENTITY_NAME_REQUIRED",
+  // FR-024 — an identity.* on an object.projection lacks `extends`; a
+  // projection identity is a pass-through of an entity identity.
+  "ERR_PROJECTION_IDENTITY_NOT_EXTENDED",
+  // FR-024 — identity key correspondence broken: an extended-identity field
+  // has no local pass-through field extending it, or an explicit @fields
+  // disagrees with the computed pass-through key.
+  "ERR_IDENTITY_KEY_MISMATCH",
+  // FR-024 (ADR-0028) — a source.* on an object.projection has a writable
+  // @kind (table, or @kind omitted which defaults to table). Projections are
+  // derived read-only representations; their sources must be read-only kinds.
+  "ERR_PROJECTION_SOURCE_WRITABLE",
   "ERR_INVALID_SUBTYPE_CHILD",
+  // FR-033 — a STRUCTURAL child (field/identity/source/validator/… — not an
+  // attr) is placed under a parent whose registered childRules do not admit it
+  // (the structural analogue of ERR_UNKNOWN_ATTR). Enforced in validate()
+  // against the merged wildcard-match semantics; a NO-OP under today's wildcard
+  // childRules (the rail strict per-subtype rules will use in S1). Strict-load
+  // only. Detail names the parent, the child, and which placement was rejected.
+  "ERR_CHILD_NOT_ALLOWED",
   "ERR_UNKNOWN_ATTR",
   "ERR_BAD_ATTR_VALUE",
   "ERR_BAD_DEFAULT_SORT_FIELD",
@@ -37,7 +62,39 @@ export const ERROR_CODES = [
   "ERR_OVERLAY_NO_TARGET",
   "ERR_MALFORMED_YAML",
   "ERR_INVALID_ORIGIN",
+  // FR-024 (ADR-0029 decision 5) — an implicit (omitted-@via) origin path is
+  // ambiguous: more than one single-hop relationship leads from the base
+  // entity to the @from/@of entity (the error names the candidates), or a
+  // projection's base entity cannot be derived because its fields extend
+  // multiple entities and no extended identity anchors the base.
+  "ERR_AMBIGUOUS_PATH",
+  // FR-024 (ADR-0029 decision 6) — origin cardinality contract broken: a
+  // passthrough @via path crosses a to-many hop (row-multiplying — you meant
+  // aggregate), or an aggregate @via path is to-one at every hop (you meant
+  // passthrough). Checked on explicit AND inferred paths.
+  "ERR_ORIGIN_CARDINALITY",
+  // FR-024 (ADR-0029 decision 7) — a field declares BOTH an entity-nested
+  // `extends` (shape lineage) and an `origin.passthrough` @from (data lineage)
+  // and they disagree: the resolved @from target is not the field's resolved
+  // extends target (nor anywhere on its extends chain). Host-agnostic
+  // (projections, entities, values). Aggregates are never judged (they
+  // compute something new); a top-level abstract extends target is never
+  // judged (shape-only reuse makes no lineage claim).
+  "ERR_EXTENDS_ORIGIN_MISMATCH",
+  // FR-024 (spec §7) — an object.entity field carrying an origin.* child is
+  // derived (read-only), so the entity must declare at least one source with
+  // a read-only @kind (view/materializedView/storedProc/tableFunction) to
+  // provide it. Table-only (or source-less) entities with derived fields
+  // error. Projections and object.value hosts are exempt. Until the Phase-E
+  // B4b cutover removes view-PRIMARY entities, a read-only-kind PRIMARY
+  // source also counts as providable (legacy spelling).
+  "ERR_DERIVED_FIELD_NO_READ_SOURCE",
+  "ERR_ENTITY_PRIMARY_SOURCE_READONLY",
   "ERR_INVALID_TEMPLATE",
+  // FR-017 — M:N relationship validation (slim vocabulary): @through must name a
+  // junction declaring two identity.reference children; @sourceRefField must match
+  // one of them; M:N attrs are invalid on a 1:N (@cardinality:one / no @through).
+  "ERR_INVALID_RELATIONSHIP",
   "ERR_VAR_NOT_ON_PAYLOAD",
   "ERR_PARTIAL_UNRESOLVED",
   "ERR_REQUIRED_SLOT_UNUSED",
@@ -45,6 +102,9 @@ export const ERROR_CODES = [
   "ERR_BAD_ATTR_FILTER",
   "ERR_STORAGE_FLATTENED_ARRAY",
   "ERR_STORAGE_WITHOUT_OBJECT_REF",
+  // ADR-0013 — a field.object REQUIRES @objectRef (open/untyped JSON uses
+  // the physical @dbColumnType: jsonb escape hatch on field.string instead).
+  "ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF",
   // Source v2 (ADR-0007) error codes — enforcement added during the source-v2 rollout.
   "ERR_RESERVED_ATTR",
   "ERR_SOURCE_NO_PRIMARY",
@@ -71,6 +131,24 @@ export const ERROR_CODES = [
   // FR5c — multi-file overlay merge produced a conflicting attribute value:
   // two contributors set the same @attr to different non-empty values.
   "ERR_MERGE_CONFLICT",
+  // SP-H Unit9 — @filterable: true on a field subtype with no filter-operator
+  // band (e.g. field.object). Would silently generate an empty-ops filter.
+  "ERR_FILTERABLE_UNSUPPORTED_SUBTYPE",
+  // ADR-0023 — a registration was attempted against a registry sealed after its
+  // agreed metamodel-provider bootstrap. Codegen cannot invent metamodel attrs.
+  "ERR_REGISTRY_SEALED",
+  // FR-032 (ADR-0032) — a ref-bearing attr (extends/@objectRef/@references/
+  // origin @from/@of/@via/@parameterRef/@payloadRef/@responseRef) in CANONICAL
+  // JSON used a relative authoring form (leading `::` or `..::`). Canonical JSON
+  // is the self-contained interchange form: every ref MUST be fully-qualified.
+  // Relative navigation is YAML-only (the desugar expands it via expandRef).
+  "ERR_RELATIVE_REF_IN_CANONICAL",
+  // FR-033 — a provider set's merged metamodel constraint graph is contradictory.
+  // Surfaced by validateConstraints (constraint-validate.ts) at registry compose:
+  // dangling ref / unsatisfiable required child / bad cardinality / closed-set
+  // clash / required-child cycle / conflicting attr redefinition. The detail names
+  // which of the six checks fired and the offending type(s).
+  "ERR_INVALID_METAMODEL_CONSTRAINT",
   "ERR_UNKNOWN",
 ] as const;
 

package/src/index.ts

@@ -68,11 +68,23 @@ export {
   MetaReferenceIdentity,
 } from "./core/identity/meta-identity.js";
 export type { IdentityGeneration } from "./core/identity/meta-identity.js";
+// FR-024 — projection identity pass-through derivation (computed local key;
+// pure tree read, codegen-facing).
+export {
+  computedIdentityFields,
+  identityOwnFields,
+  identityEffectiveFields,
+  resolveIdentityPassthrough,
+} from "./core/identity/validate-identity-passthrough.js";
+export type { IdentityPassthroughResolution } from "./core/identity/validate-identity-passthrough.js";
 // Relationship
 export { MetaRelationship } from "./core/relationship/meta-relationship.js";
 // Cross-entity reference lookup
 export { findReferenceBetween } from "./core/relationship/find-reference.js";
 export type { ReferenceLookup } from "./core/relationship/find-reference.js";
+// FR-017 — M:N junction FK derivation (hetero / directed-self-join / symmetric)
+export { deriveM2MFields, M2MDerivationError } from "./core/relationship/derive-m2m-fields.js";
+export type { M2MFields } from "./core/relationship/derive-m2m-fields.js";
 // Validator: base + subtype-specific
 export {
   MetaValidator,
@@ -122,9 +134,39 @@ export type AnyMeta =
 export { TypeId, TypeRegistry, childRuleMatches } from "./registry.js";
 export type { AttrSchema, ChildRule, TypeDefinition } from "./registry.js";
 export { registerCoreTypes, coreTypesProvider, coreProviders } from "./core-types.js";
+
+// FR-033 — the constraint engine: additive merge + the contradiction validator.
+export { mergeConstraints } from "./constraint-merge.js";
+export type { EffectiveConstraints } from "./constraint-merge.js";
+export { validateConstraints } from "./constraint-validate.js";
+
+// Registry conformance manifest (SP-G) — the canonical logical-vocabulary serializer.
+export { buildRegistryManifest, emitRegistryManifest, classifyPerTypeAttr } from "./registry-manifest.js";
+export type { AttrClassification } from "./registry-manifest.js";
+export { ExclusionReason } from "./registry-manifest-exclusions.js";
+
+// FR-033 S3 — metamodel doc-gen: tiered, LLM-readable docs FOR THE METAMODEL
+// (the type/subtype/attr vocabulary), generated from the strict registry.
+// Distinct from `meta docs --model` (which documents a user's entities).
+export {
+  renderMetamodelDocs,
+  buildMetamodelProvenance,
+  coreProviderDescriptions,
+  renderCoreMetamodelDocs,
+} from "./metamodel-docs/index.js";
+export type { MetamodelProvenance } from "./metamodel-docs/index.js";
+
+// Registry coverage (SP-G Unit 5) — untested-vocabulary report (manifest vs
+// fixture corpora). NODE-ONLY: registry-coverage.ts statically imports node:fs
+// to scan the fixture corpora, so it must NOT be re-exported from this
+// browser-facing barrel (it would drag node:fs into the root entry, breaking
+// browser-safety.test.ts). It is a build-time tooling module — consumers (and
+// its test) import it directly by path: `@metaobjectsdev/metadata/src/registry-coverage`.
 export { dbProvider } from "./persistence/db/db-provider.js";
-export { commonDocAttrs } from "./core/documentation/doc-schema.js";
 export { docProvider } from "./core/documentation/doc-provider.js";
+export { promptProvider } from "./template/prompt-provider.js";
+export { uiProvider } from "./presentation/ui/ui-provider.js";
+export { FIELD_ATTR_XML_TEXT } from "./template/template-constants.js";
 
 // Type provider model
 export { composeRegistry } from "./provider.js";
@@ -157,9 +199,12 @@ export type { SerializeOptions } from "./serializer-json.js";
 // Super resolution helper (most resolution moved into parser; this is the lookup utility)
 export { resolveSuperRef } from "./super-resolve.js";
 
+// FR-032 (ADR-0032) — canonical reference expansion + FQN object matching.
+export { expandRef, isRelativeRef, refMatchesObject, REF_BEARING_ATTR_NAMES } from "./naming-refs.js";
+
 // Loader hierarchy
 export { MetaDataLoader } from "./loader/meta-data-loader.js";
-export type { LoadOptions, LoadResult, LoadingState } from "./loader/meta-data-loader.js";
+export type { LoadOptions, LoadResult, LoadingState, DirectoryFactoryOptions } from "./loader/meta-data-loader.js";
 export { InMemoryStringSource } from "./loader/meta-data-source.js";
 export type { MetaDataSource, MetaDataFormat } from "./loader/meta-data-source.js";
 

package/src/library/embedded-library.generated.ts

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by scripts/generate-embedded-library.ts — DO NOT EDIT.
+// Canonical source: repo-root library/**/*.yaml
+// Regenerate: bun run scripts/generate-embedded-library.ts
+//
+// Embeds the canonical library files as string literals so they resolve
+// wherever the on-disk library/ directory is unavailable.
+// Keys are refs: path under library/ minus the .yaml extension.
+export const EMBEDDED_LIBRARY: Record<string, string> = {
+  "ai/llm-call": "# library/ai/llm-call.yaml\n# MetaObjects-shipped standard metadata. Adopters opt in via the loader's\n# `libraries: [\"ai\"]` option, then `extends: \"metaobjects::ai::LlmCallBase\"`.\nmetadata:\n  package: metaobjects::ai\n  children:\n    - object.entity:\n        name: LlmCallBase\n        abstract: true\n        children:\n          - field.uuid:     { name: traceId }\n          - field.uuid:     { name: spanId }\n          - field.uuid:     { name: parentSpanId }\n          - field.string:   { name: sessionId }\n          - field.string:   { name: callType }\n          - field.string:   { name: system }\n          - field.string:   { name: requestModel }\n          - field.string:   { name: responseModel }\n          - field.int:      { name: inputTokens }\n          - field.int:      { name: outputTokens }\n          - field.currency: { name: costMinor, currency: USD }\n          - field.int:      { name: latencyMs }\n          - field.string:   { name: finishReason }\n          - field.string:   { name: status }\n          - field.string:   { name: errorDetail }\n          - field.timestamp: { name: startedAt }\n          - field.string:   { name: llmRequest,  dbColumnType: jsonb }   # generic jsonb (no objectRef)\n          - field.string:   { name: llmResponse, dbColumnType: jsonb }\n    - object.entity:\n        name: LlmCall\n        extends: metaobjects::ai::LlmCallBase\n        children:\n          - source.rdb:      { table: llm_call, role: primary }\n          - identity.primary: { name: id, fields: [\"spanId\"] }\n",
+};

package/src/library/library-sources.ts

@@ -0,0 +1,97 @@
+// library-sources.ts — resolves MetaDataSource instances for shipped library packages.
+//
+// On-disk-first: if the repo-root library/ tree is reachable (dev / installed-from-source
+// layout), a FileSource is returned so edits to the on-disk YAML are picked up immediately.
+// Embedded fallback: when the binary is compiled (bun --compile) or the library/ directory
+// is absent, the content embedded in embedded-library.generated.ts is used.
+
+import { existsSync } from "node:fs";
+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 type { MetaDataSource } 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: Readonly<Record<string, readonly string[]>> = (() => {
+  const map: Record<string, string[]> = {};
+  for (const ref of Object.keys(EMBEDDED_LIBRARY).sort()) {
+    const pkg = ref.split("/")[0];
+    if (pkg === undefined || pkg === "") continue;
+    (map[pkg] ??= []).push(ref);
+  }
+  return map;
+})();
+
+/**
+ * Locate the repo-root `library/` directory by walking up from this module's
+ * location until a directory contains BOTH `library/` and `server/` (the two
+ * structural anchors that identify the repo root). Returns the path to the
+ * `library/` subdirectory if found, or `undefined` when absent (compiled binary).
+ */
+function libraryDirOnDisk(): string | undefined {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 12; i++) {
+    if (existsSync(join(dir, "library")) && existsSync(join(dir, "server"))) {
+      return join(dir, "library");
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+  return undefined;
+}
+
+// Cache the on-disk location: resolved once per process.
+let _cache: { dir: string | undefined } | undefined;
+
+function getLibraryDir(): string | undefined {
+  return (_cache ??= { dir: libraryDirOnDisk() }).dir;
+}
+
+/**
+ * Returns a list of `MetaDataSource` instances for the requested library packages.
+ *
+ * - 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.
+ *
+ * @param packages - Package names to include (e.g. `["ai"]`).
+ */
+export function librarySources(packages: string[]): MetaDataSource[] {
+  const dir = getLibraryDir();
+  const out: MetaDataSource[] = [];
+
+  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`,
+        );
+      }
+    }
+  }
+
+  return out;
+}

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

@@ -17,7 +17,7 @@ import { ParseError } from "../errors.js";
 import type { LoaderWarning } from "../source.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
-import { validateDataGridSortFields, validateFilterableHasIndex, validateOriginPaths, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs, validateFieldDefaults } from "./validation-passes.js";
+import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships } from "./validation-passes.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { validateSourcePhysicalNames } from "../persistence/source/validate-source-physical-names.js";
 import { validateSourceParameterRef } from "../persistence/source/validate-source-parameter-ref.js";
@@ -25,6 +25,7 @@ import { validateFieldReadOnly } from "../core/field/validate-field-readonly.js"
 import { validateDiscriminator } from "../core/object/validate-discriminator.js";
 import { resolveDeferredSupers } from "../super-resolve.js";
 import { validateSubtypeRules } from "../subtype-rules.js";
+import { validateIdentityPassthrough } from "../core/identity/validate-identity-passthrough.js";
 import { validateAttrSchema } from "../attr-schema-validate.js";
 import type { MetaDataFormat, MetaDataSource } from "./meta-data-source.js";
 import { InMemoryStringSource } from "./meta-data-source.js";
@@ -35,9 +36,18 @@ import type { ParseOptions, ParseResult } from "../parser-core.js";
 // 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 = {
+export type DirectoryFactoryOptions = {
   exclude?: string[];
   recurse?: boolean;
+  /**
+   * Opt-in library packages to prepend before the directory's own sources.
+   * Library sources are prepended so `extends` references to library-shipped
+   * abstract bases are resolvable from app metadata files.
+   *
+   * Example: `{ libraries: ["ai"] }` prepends the `metaobjects::ai` library
+   * (LlmCallBase etc.) so app entities may use `extends: "metaobjects::ai::LlmCallBase"`.
+   */
+  libraries?: string[];
 };
 
 // YAML parser and node:fs-backed Source impls are loaded lazily (dynamic
@@ -101,7 +111,9 @@ export class MetaDataLoader {
   }
 
   private static _defaultRegistry(): TypeRegistry {
-    return composeRegistry(coreProviders);
+    // FR-033 — validate the library's own metamodel at bootstrap: a contradictory
+    // core provider set fails fast here (the real metamodel must be contradiction-free).
+    return composeRegistry(coreProviders, { validate: true });
   }
 
   // ---------------------------------------------------------------------------
@@ -124,7 +136,7 @@ export class MetaDataLoader {
     dir: string,
     opts?: DirectoryFactoryOptions & LoadOptions,
   ): Promise<LoadResult> {
-    const { exclude, recurse, ...loaderOpts } = opts ?? {};
+    const { exclude, recurse, libraries, ...loaderOpts } = opts ?? {};
     // Conditional spreads honor exactOptionalPropertyTypes — only forward keys
     // when the caller supplied a value, so DirectorySource's own defaults apply.
     const dirOpts: DirectoryFactoryOptions = {
@@ -134,8 +146,19 @@ export class MetaDataLoader {
     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);
+      const dirSources = await new DirectorySource(dir, dirOpts).expand();
+      // Library sources are loaded lazily and conditionally to keep the import
+      // path away from the browser-safe entry (library-sources.ts uses node:fs)
+      // and to avoid the import cost when no libraries are requested.
+      let libSources: MetaDataSource[] = [];
+      if (libraries?.length) {
+        const { librarySources } = await import("../library/library-sources.js");
+        libSources = librarySources(libraries);
+      }
+      // Prepend library sources so `extends` refs to library-shipped abstract
+      // bases are resolvable when the merged root is built. Super resolution is
+      // deferred (order-independent), but prepending is the deterministic choice.
+      return loader.load([...libSources, ...dirSources]);
     } catch (err) {
       // Match the pre-unification contract: a missing/unreadable directory is
       // surfaced as a collected error on the LoadResult, not a throw. The
@@ -396,6 +419,22 @@ export class MetaDataLoader {
         // parse-time source supplies files + jsonPath (the location of the
         // broken `extends:` on disk); referrer = the declaring node's FQN;
         // target = the unresolved supertype ref.
+        if (failure.kind === "target-mismatch") {
+          // FR-024 — a dotted child-targeting ref resolved, but the target's
+          // type/subtype differs from the extending node's. Dotted-only check.
+          const r = failure.referrer;
+          const t = failure.target;
+          errors.push(
+            new ParseError(
+              `the extends target '${failure.ref}' is ${t?.type}.${t?.subType} but the extending node '${failure.nodeFqn}' is ${r?.type}.${r?.subType} — a dotted extends must target a node of the same type and subtype`,
+              {
+                code: "ERR_EXTENDS_TARGET_MISMATCH",
+                source: resolvedSource(failure.source, failure.nodeFqn, failure.ref),
+              },
+            ),
+          );
+          continue;
+        }
         errors.push(
           new ParseError(
             `the SuperClass '${failure.ref}' does not exist (referenced by ${failure.nodeFqn})`,
@@ -413,19 +452,39 @@ export class MetaDataLoader {
       errors.push(...ruleResult.errors);
       warnings.push(...ruleResult.warnings);
 
+      // FR-024 B3 — projection identity pass-through + key correspondence
+      // (ERR_PROJECTION_IDENTITY_NOT_EXTENDED / ERR_IDENTITY_KEY_MISMATCH).
+      errors.push(...validateIdentityPassthrough(root));
+
       // Fourth pass: data-grid @defaultSortField cross-reference validation.
       errors.push(...validateDataGridSortFields(root));
 
       // Fifth pass: @filterable without index drift warning.
       warnings.push(...validateFilterableHasIndex(root));
 
+      // SP-H Unit9 — @filterable on a subtype with no operator band → error
+      // (would silently generate a filter that rejects every request).
+      errors.push(...validateFilterableHasSupportedOps(root));
+
       // Sixth pass: origin path validation — validates passthrough.@from,
       // aggregate.@of, and .@via relationship chains.
       errors.push(...validateOriginPaths(root));
 
+      // FR-024 B6 — derived-field providability: an entity field carrying an
+      // origin.* is derived (read-only) and must be providable by at least one
+      // read-only-kind source on the entity (spec §7 multi-source pattern);
+      // projections and object.value hosts are exempt.
+      errors.push(...validateDerivedFieldProvidability(root));
+
       // Seventh pass: @filter value validation — fields filterable + ops allowed per subtype.
       errors.push(...validateDataGridFilterValues(root));
 
+      // FR-017 — M:N relationship validation (deferred-resolution): @through names a
+      // junction declaring two identity.reference children; @sourceRefField matches one;
+      // @symmetric is self-join-only + mutually exclusive with @sourceRefField; M:N attrs
+      // are invalid on a 1:N relationship.
+      errors.push(...validateRelationships(root));
+
       // template.* validation — @payloadRef resolves to a known object;
       // @requiredSlots are real fields on it (FR-004 Plan #3, T2).
       errors.push(...validateTemplatePayloadRefs(root));
@@ -433,7 +492,7 @@ export class MetaDataLoader {
       // Eighth pass: attribute-schema validation (Phase A3) — checks each
       // node's @-attributes against its (type, subType) AttrSchema: required
       // attrs present, declared attrs well-typed, allowedValues honored.
-      const attrSchemaResult = validateAttrSchema(root, this._registry);
+      const attrSchemaResult = validateAttrSchema(root, this._registry, this._strict);
       errors.push(...attrSchemaResult.errors);
       warnings.push(...attrSchemaResult.warnings);
 

package/src/loader/shortcuts.ts

@@ -8,12 +8,12 @@
 // 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 { LoadOptions, LoadResult, DirectoryFactoryOptions } from "./meta-data-loader.js";
 import type { MetaDataFormat } from "./meta-data-source.js";
 
 export function loadDirectory(
   dir: string,
-  opts?: { exclude?: string[]; recurse?: boolean } & LoadOptions,
+  opts?: DirectoryFactoryOptions & LoadOptions,
 ): Promise<LoadResult> {
   return MetaDataLoader.fromDirectory(dir, opts);
 }