structured-context 0.11.0 → 0.13.0

package/dist/schema/schema.js

@@ -1,10 +1,12 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, extname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { isDeepStrictEqual } from 'node:util';
-import Ajv, {} from 'ajv';
+import Ajv2020 from 'ajv/dist/2020';
 import JSON5 from 'json5';
-import { DIALECT_META_SCHEMA, METADATA_SCHEMA, SCHEMA_META_ID, } from './metadata-contract';
+import { SCHEMA_URI_SCHEME } from '../constants';
+import { shortenPluginName } from '../plugins/util';
+import { loadMetaSchemas } from './meta-schemas';
+import { METADATA_SCHEMA, } from './metadata-contract';
 import { isObject, mergeVariantProperties, resolveJsonPointer } from './schema-refs';
 const packageDir = import.meta.url ? dirname(fileURLToPath(import.meta.url)) : '';
 export let bundledSchemasDir = packageDir ? join(packageDir, '..', '..', 'schemas') : '';
@@ -12,9 +14,95 @@ export let bundledSchemasDir = packageDir ? join(packageDir, '..', '..', 'schema
 export function setBundledSchemasDir(dir) {
     bundledSchemasDir = dir;
 }
-const validateMetadataContract = new Ajv().compile(METADATA_SCHEMA);
+const validateMetadataContract = new Ajv2020().compile(METADATA_SCHEMA);
+/** File stem of each schema read from disk — the default name of the hierarchy it declares. */
+const schemaFileStems = new WeakMap();
 export function readRawSchema(schemaPath) {
-    return JSON5.parse(readFileSync(resolve(schemaPath), 'utf-8'));
+    const schema = JSON5.parse(readFileSync(resolve(schemaPath), 'utf-8'));
+    rewriteLegacyCoreRefs(schema, schemaPath);
+    schemaFileStems.set(schema, basename(schemaPath, extname(schemaPath)));
+    return schema;
+}
+/**
+ * Schema `$id` namespaces. Every `$id` uses the `sctx://` scheme, and its shape says where the schema comes from:
+ * - `sctx://core/<name>` — bundled with structured-context
+ * - `sctx://<plugin>/<name>` — contributed by a plugin, prefixed with the plugin's short name
+ * - `sctx://<name>` — local to a space's schema directory (a single segment, no path)
+ */
+const SCTX_SCHEME = `${SCHEMA_URI_SCHEME}://`;
+export const CORE_SCHEMA_PREFIX = `${SCTX_SCHEME}core/`;
+/**
+ * Bundled schema `$id`s from before the `sctx://core/` namespace. References to them keep resolving
+ * (with a deprecation warning) until 1.0, and local schemas may not claim them.
+ */
+const LEGACY_CORE_IDS = new Set([
+    '_sctx_base',
+    '_ost_strict',
+    '_strategy_general',
+    '_knowledge_wiki',
+    'strict_ost',
+    'strategy_general',
+    'knowledge_wiki',
+].map((name) => `${SCTX_SCHEME}${name}`));
+const warnedLegacyIds = new Set();
+function upgradeLegacyCoreRef(ref, schemaPath) {
+    const hashIndex = ref.indexOf('#');
+    const id = hashIndex === -1 ? ref : ref.slice(0, hashIndex);
+    if (!LEGACY_CORE_IDS.has(id))
+        return ref;
+    const upgraded = `${CORE_SCHEMA_PREFIX}${id.slice(SCTX_SCHEME.length)}`;
+    if (!warnedLegacyIds.has(id)) {
+        warnedLegacyIds.add(id);
+        console.warn(`Warning: "${id}" is deprecated and will stop resolving in 1.0; use "${upgraded}" instead (referenced in ${schemaPath}).`);
+    }
+    return hashIndex === -1 ? upgraded : `${upgraded}${ref.slice(hashIndex)}`;
+}
+/** Rewrite references to legacy bundled `$id`s (in `$ref` and `$metadata.imports`) to their `sctx://core/` form. */
+function rewriteLegacyCoreRefs(node, schemaPath) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            rewriteLegacyCoreRefs(item, schemaPath);
+        return;
+    }
+    if (!isObject(node))
+        return;
+    if (typeof node.$ref === 'string')
+        node.$ref = upgradeLegacyCoreRef(node.$ref, schemaPath);
+    if (isObject(node.$metadata) && Array.isArray(node.$metadata.imports)) {
+        node.$metadata.imports = node.$metadata.imports.map((entry) => typeof entry === 'string' ? upgradeLegacyCoreRef(entry, schemaPath) : entry);
+    }
+    for (const value of Object.values(node))
+        rewriteLegacyCoreRefs(value, schemaPath);
+}
+/** Throw if `id` doesn't belong to the namespace of the source it was loaded from. */
+function assertIdNamespace(id, source) {
+    if (source.kind === 'core') {
+        if (!id.startsWith(CORE_SCHEMA_PREFIX)) {
+            throw new Error(`Bundled schema $id "${id}" must start with "${CORE_SCHEMA_PREFIX}".`);
+        }
+        return;
+    }
+    const where = source.kind === 'plugin' ? `schema in plugin "${source.pluginName}"` : `local schema in "${source.dir}"`;
+    const expected = source.kind === 'plugin' ? `"${SCTX_SCHEME}${source.shortName}/<name>"` : `"${SCTX_SCHEME}<name>"`;
+    if (!id.startsWith(SCTX_SCHEME)) {
+        throw new Error(`Schema namespace violation: ${where} uses $id "${id}". Use the form ${expected}.`);
+    }
+    const segments = id.slice(SCTX_SCHEME.length).split('/');
+    if (source.kind === 'plugin') {
+        if (source.shortName === 'core') {
+            throw new Error(`Schema namespace violation: plugin "${source.pluginName}" can't contribute schemas; "core" is reserved for bundled schemas.`);
+        }
+        if (segments.length < 2 || segments[0] !== source.shortName) {
+            throw new Error(`Schema namespace violation: ${where} uses $id "${id}". Use the form ${expected}.`);
+        }
+        return;
+    }
+    if (segments.length !== 1) {
+        throw new Error(`Schema namespace violation: ${where} uses $id "${id}". Local schema $ids are a single name, ${expected}; "${SCTX_SCHEME}<prefix>/..." is reserved for bundled ("core") and plugin schemas.`);
+    }
+    if (LEGACY_CORE_IDS.has(id)) {
+        throw new Error(`Schema namespace violation: ${where} uses $id "${id}", which is reserved as an alias for "${CORE_SCHEMA_PREFIX}${segments[0]}" until 1.0. Choose another name.`);
+    }
 }
 /**
  * Build a registry of all schemas in the given directory, keyed by $id.
@@ -38,37 +126,97 @@ function buildSchemaRegistry(dir, targetFile) {
     return schemaRefRegistry;
 }
 /**
- * Build the full two-layer registry for a schema path:
+ * Build the full multi-layer registry for a schema path:
  * - Layer 1: bundled schemas/ dir (partials only, as fallback)
- * - Layer 2: schema's own dir (partials + target file) — overrides layer 1
- * Does not throw on $id collision; layer 2 silently wins.
+ * - Layer 2: plugin schema dirs (partials + target file if schemaPath is in this plugin's schemasDir)
+ * - Layer 3: schema's own dir (partials + target file)
+ * Throws if a lower-precedence schema collides with a reserved $id or violates namespace rules.
  */
-export function buildFullRegistry(schemaPath) {
+export function buildFullRegistry(schemaPath, pluginSchemas) {
     const absPath = resolve(schemaPath);
     const targetFile = basename(absPath);
     const targetDir = dirname(absPath);
     const schemaRefRegistry = new Map();
     // Layer 1: bundled schemas/ dir (partials only)
     for (const [id, schema] of buildSchemaRegistry(bundledSchemasDir)) {
+        assertIdNamespace(id, { kind: 'core' });
         schemaRefRegistry.set(id, schema);
     }
-    // Layer 2: schema's own dir (partials + target file)
-    if (targetDir !== bundledSchemasDir) {
-        const bundledIds = new Set(schemaRefRegistry.keys());
-        bundledIds.add(SCHEMA_META_ID);
+    const bundledIds = new Set(schemaRefRegistry.keys());
+    for (const id of loadMetaSchemas(bundledSchemasDir).keys())
+        bundledIds.add(id);
+    // Layer 2: plugin schema dirs
+    const pluginIds = new Map(); // id -> pluginName
+    if (pluginSchemas) {
+        for (const { schemasDir, pluginName } of pluginSchemas) {
+            if (!existsSync(schemasDir))
+                continue;
+            const isTargetDir = resolve(schemasDir) === targetDir;
+            const shortName = shortenPluginName(pluginName);
+            for (const [id, schema] of buildSchemaRegistry(schemasDir, isTargetDir ? targetFile : undefined)) {
+                if (bundledIds.has(id)) {
+                    throw new Error(`Schema collision: schema in plugin "${pluginName}" (${schemasDir}) uses $id "${id}" which is reserved by a default schema. Please use a unique $id for plugin schemas.`);
+                }
+                const existingPlugin = pluginIds.get(id);
+                if (existingPlugin) {
+                    throw new Error(`Schema collision: schema in plugin "${pluginName}" (${schemasDir}) uses $id "${id}" which is already defined by plugin "${existingPlugin}".`);
+                }
+                assertIdNamespace(id, { kind: 'plugin', pluginName, shortName });
+                schemaRefRegistry.set(id, schema);
+                pluginIds.set(id, pluginName);
+            }
+        }
+    }
+    // Layer 3: schema's own dir (partials + target file)
+    const isPluginDir = pluginSchemas?.some((p) => resolve(p.schemasDir) === targetDir);
+    if (targetDir !== bundledSchemasDir && !isPluginDir) {
+        const reservedIds = new Set(schemaRefRegistry.keys());
+        for (const id of loadMetaSchemas(bundledSchemasDir).keys())
+            reservedIds.add(id);
         for (const [id, schema] of buildSchemaRegistry(targetDir, targetFile)) {
-            if (bundledIds.has(id)) {
-                throw new Error(`Schema collision: partial schema in ${targetDir} uses $id "${id}" which is reserved by a default schema. Please use a unique $id for local partials.`);
+            if (reservedIds.has(id)) {
+                throw new Error(`Schema collision: local schema in ${targetDir} uses $id "${id}", which is already defined by a bundled or plugin schema. Choose another name.`);
             }
+            assertIdNamespace(id, { kind: 'local', dir: targetDir });
             schemaRefRegistry.set(id, schema);
         }
     }
     return schemaRefRegistry;
 }
+const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_TIME_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(\.\d+)?)?(Z|[+-](\d{2}):(\d{2}))?$/;
+function isCalendarDate(year, month, day) {
+    const d = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+    return d.getUTCMonth() === Number(month) - 1 && d.getUTCDate() === Number(day);
+}
+/** ISO 8601 date, e.g. 2026-03-31. */
+function isDate(value) {
+    const m = DATE_PATTERN.exec(value);
+    return m !== null && isCalendarDate(m[1], m[2], m[3]);
+}
+/**
+ * ISO 8601 datetime. `strict` requires seconds and a UTC offset (e.g. 2026-03-31T09:15:00+10:00);
+ * otherwise both are optional, as in the local datetimes Obsidian writes (e.g. 2026-03-31T09:15).
+ */
+function isDateTime(value, strict) {
+    const m = DATE_TIME_PATTERN.exec(value);
+    if (!m || !isCalendarDate(m[1], m[2], m[3]))
+        return false;
+    const [, , , , hour, minute, second, , offset, offsetHour, offsetMinute] = m;
+    if (strict && (second === undefined || offset === undefined))
+        return false;
+    return (Number(hour) < 24 &&
+        Number(minute) < 60 &&
+        Number(second ?? 0) < 60 &&
+        Number(offsetHour ?? 0) < 24 &&
+        Number(offsetMinute ?? 0) < 60);
+}
 function compileValidator(targetSchema, schemaRefRegistry) {
-    const ajv = new Ajv();
+    const ajv = new Ajv2020();
     ajv.addFormat('path', (value) => value.length > 0 && !value.includes('\0'));
-    ajv.addFormat('date', (value) => /^\d{4}-\d{2}-\d{2}$/.test(value));
+    ajv.addFormat('date', isDate);
+    ajv.addFormat('date-time', (value) => isDateTime(value, true));
+    ajv.addFormat('date-or-date-time', (value) => isDate(value) || isDateTime(value, false));
     ajv.addFormat('wikilink', (value) => /^\[\[.+\]\]$/.test(value));
     ajv.addKeyword({
         keyword: '$metadata',
@@ -77,37 +225,39 @@ function compileValidator(targetSchema, schemaRefRegistry) {
         valid: true,
         errors: false,
     });
-    const metaSchema = DIALECT_META_SCHEMA;
-    ajv.addSchema(metaSchema, SCHEMA_META_ID);
+    const metaSchemas = loadMetaSchemas(bundledSchemasDir);
+    for (const schema of metaSchemas.values())
+        ajv.addSchema(schema);
     // Register all except target schema (AJV compiles targetSchema explicitly)
     for (const [id, schema] of schemaRefRegistry) {
-        if (id === targetSchema.$id || id === SCHEMA_META_ID)
+        if (id === targetSchema.$id || metaSchemas.has(id))
             continue;
         ajv.addSchema(schema);
     }
     return ajv.compile(targetSchema);
 }
-export function createValidator(schemaPath) {
-    return compileValidator(readRawSchema(schemaPath), buildFullRegistry(schemaPath));
+export function createValidator(schemaPath, pluginSchemas) {
+    return compileValidator(readRawSchema(schemaPath), buildFullRegistry(schemaPath, pluginSchemas));
 }
 export function resolveNodeType(type, typeAliases) {
     return typeAliases?.[type] ?? type;
 }
-const RULE_CATEGORIES = new Set(['validation', 'coherence', 'workflow', 'best-practice']);
-const RULE_ALLOWED_KEYS = new Set(['id', 'category', 'description', 'check', 'type', 'scope', 'override']);
 function readTopLevelMetadata(schema) {
     const metadata = schema.$metadata;
     if (!isObject(metadata))
         return undefined;
+    const schemaId = typeof schema.$id === 'string' ? schema.$id : '(unknown schema)';
+    if (isObject(metadata.hierarchy) && '$ref' in metadata.hierarchy && Object.keys(metadata.hierarchy).length > 1) {
+        throw new Error(`Invalid $metadata in schema "${schemaId}": hierarchy both declares levels and selects a hierarchy with "$ref". Use one or the other.`);
+    }
     if (!validateMetadataContract(metadata)) {
-        const schemaId = typeof schema.$id === 'string' ? schema.$id : '(unknown schema)';
         const errors = validateMetadataContract.errors?.map((e) => `${e.instancePath || '(root)'} ${e.message}`).join('; ') ??
             'unknown error';
         throw new Error(`Invalid $metadata in schema "${schemaId}": ${errors}`);
     }
     return metadata;
 }
-function resolveRefTargetForRule(ref, currentRootSchema, schemaRefRegistry) {
+function resolveMetadataRef(ref, currentRootSchema, schemaRefRegistry) {
     if (ref.startsWith('#')) {
         const pointer = ref.slice(1);
         const rootId = typeof currentRootSchema.$id === 'string' ? currentRootSchema.$id : '(root schema)';
@@ -130,180 +280,140 @@ function resolveRefTargetForRule(ref, currentRootSchema, schemaRefRegistry) {
         refKey: `${baseId}#${pointer}`,
     };
 }
-function collectExternalRefIdsInOrder(schema) {
-    const refs = [];
-    const seen = new Set();
-    const walk = (value) => {
-        if (!isObject(value))
-            return;
-        for (const [key, child] of Object.entries(value)) {
-            if (key === '$ref' && typeof child === 'string' && !child.startsWith('#')) {
-                const schemaId = child.split('#', 1)[0] ?? child;
-                if (!seen.has(schemaId)) {
-                    seen.add(schemaId);
-                    refs.push(schemaId);
-                }
-                continue;
-            }
-            walk(child);
-        }
-    };
-    walk(schema);
-    return refs;
-}
+/**
+ * Collect metadata providers in merge order: each schema's `$metadata.imports` depth-first, in
+ * order, then the schema's own metadata. Each schema contributes at most once. `$ref` does not
+ * import metadata.
+ */
 function collectMetadataProviders(rootSchema, schemaRefRegistry) {
     const providers = [];
-    const visitedSchemaIds = new Set();
-    const walk = (schema) => {
-        const refs = collectExternalRefIdsInOrder(schema);
-        for (const schemaId of refs) {
-            if (visitedSchemaIds.has(schemaId))
-                continue;
-            visitedSchemaIds.add(schemaId);
-            const referencedSchema = schemaRefRegistry.get(schemaId);
-            if (!referencedSchema)
+    const rootSchemaId = typeof rootSchema.$id === 'string' ? rootSchema.$id : '(root schema)';
+    const visitedSchemaIds = new Set([rootSchemaId]);
+    const walk = (schema, schemaId) => {
+        const metadata = readTopLevelMetadata(schema);
+        if (!metadata)
+            return;
+        for (const importId of metadata.imports ?? []) {
+            if (visitedSchemaIds.has(importId))
                 continue;
-            walk(referencedSchema);
-            const metadata = readTopLevelMetadata(referencedSchema);
-            if (metadata) {
-                providers.push({ schemaId, schema: referencedSchema, metadata });
+            visitedSchemaIds.add(importId);
+            const importedSchema = schemaRefRegistry.get(importId);
+            if (!importedSchema) {
+                throw new Error(`Cannot resolve import "${importId}" in schema "${schemaId}".`);
             }
+            walk(importedSchema, importId);
         }
+        providers.push({ schemaId, schema, metadata });
     };
-    walk(rootSchema);
-    const rootMetadata = readTopLevelMetadata(rootSchema);
-    if (rootMetadata) {
-        const rootSchemaId = typeof rootSchema.$id === 'string' ? rootSchema.$id : '(root schema)';
-        providers.push({ schemaId: rootSchemaId, schema: rootSchema, metadata: rootMetadata });
-    }
+    walk(rootSchema, rootSchemaId);
     return providers;
 }
-function isRuleRefEntry(value) {
+function isRefEntry(value) {
     if (!isObject(value))
         return false;
     return typeof value.$ref === 'string' && value.$ref.length > 0 && Object.keys(value).length === 1;
 }
-function isMetadataRule(value) {
-    if (!isObject(value))
-        return false;
-    const record = value;
-    if (typeof record.id !== 'string' || record.id.length === 0)
-        return false;
-    if (typeof record.category !== 'string' || !RULE_CATEGORIES.has(record.category))
-        return false;
-    if (typeof record.description !== 'string' || record.description.length === 0)
-        return false;
-    if (typeof record.check !== 'string' || record.check.length === 0)
-        return false;
-    if ('type' in record && (typeof record.type !== 'string' || record.type.length === 0))
-        return false;
-    if ('scope' in record && record.scope !== 'global')
-        return false;
-    if ('override' in record && typeof record.override !== 'boolean')
-        return false;
-    for (const key of Object.keys(record)) {
-        if (!RULE_ALLOWED_KEYS.has(key))
-            return false;
-    }
-    return true;
-}
-function resolveRuleEntries(ruleEntry, provider, schemaRefRegistry, stack) {
-    if (isMetadataRule(ruleEntry)) {
-        return [ruleEntry];
-    }
-    if (!isRuleRefEntry(ruleEntry)) {
-        throw new Error(`Invalid rule entry in metadata from "${provider.schemaId}".`);
-    }
-    const target = resolveRefTargetForRule(ruleEntry.$ref, provider.schema, schemaRefRegistry);
-    if (stack.has(target.refKey)) {
-        throw new Error(`Cyclic rule import detected while loading metadata from "${provider.schemaId}": ${[...stack, target.refKey].join(' -> ')}`);
-    }
-    stack.add(target.refKey);
-    try {
-        const value = target.value;
-        const resolveArray = (arr) => {
-            const resolvedRules = [];
-            for (const child of arr) {
-                if (!isObject(child)) {
-                    throw new Error(`Invalid rule import target for "${ruleEntry.$ref}" from "${provider.schemaId}". Rule sets must contain objects.`);
-                }
-                resolvedRules.push(...resolveRuleEntries(child, { ...provider, schema: target.rootSchema }, schemaRefRegistry, stack));
-            }
-            return resolvedRules;
-        };
-        if (Array.isArray(value)) {
-            return resolveArray(value);
-        }
-        if (isObject(value) && 'rules' in value) {
-            const nestedRules = value.rules;
-            if (!Array.isArray(nestedRules)) {
-                throw new Error(`Invalid rule import target for "${ruleEntry.$ref}" from "${provider.schemaId}". "rules" must be an array.`);
-            }
-            return resolveArray(nestedRules);
-        }
-        if (isObject(value)) {
-            return resolveRuleEntries(value, { ...provider, schema: target.rootSchema }, schemaRefRegistry, stack);
-        }
-        throw new Error(`Invalid rule import target for "${ruleEntry.$ref}" from "${provider.schemaId}". Expected a rule object or rule set.`);
-    }
-    finally {
-        stack.delete(target.refKey);
+/**
+ * The single metadata merge rule: a duplicate key is an error unless the later entry sets
+ * `override: true`, in which case it replaces the earlier one (keeping its position).
+ */
+function mergeEntry(merged, key, label, value, override, providerId) {
+    const existing = merged.get(key);
+    if (existing && override !== true) {
+        throw new Error(`Duplicate ${label} found in "${existing.providerId}" and "${providerId}". Set "override": true on the later one to replace it.`);
     }
+    merged.set(key, { providerId, value });
 }
-function normalizeRule(rule) {
-    const { override, ...normalized } = rule;
-    return normalized;
-}
-function areRulesEquivalent(left, right) {
-    return isDeepStrictEqual(normalizeRule(left), normalizeRule(right));
+function values(merged) {
+    return [...merged.values()].map(({ value }) => value);
 }
 function extractMetadata(schema, schemaRefRegistry) {
     const metadataProviders = collectMetadataProviders(schema, schemaRefRegistry);
-    let mergedHierarchy;
-    const mergedAliases = {};
+    // Hierarchies are merged by name; the declaring object is kept so a root `hierarchy: { $ref }`
+    // selection can be matched to it.
+    const mergedHierarchies = new Map();
+    let rootHierarchy;
+    let mainSelection;
+    const mergedAliases = new Map();
     const mergedRules = new Map();
-    const mergedRelationships = [];
+    const mergedRelationships = new Map();
     for (const provider of metadataProviders) {
-        if (provider.metadata.hierarchy) {
-            // Later providers (including root schema) override earlier ones (e.g. partials).
-            // This allows partials to define a default hierarchy that composing schemas can override.
-            mergedHierarchy = provider.metadata.hierarchy;
+        const { schemaId, metadata } = provider;
+        const declaredHierarchy = metadata.hierarchy;
+        const isRoot = provider.schema === schema;
+        if (isRefEntry(declaredHierarchy)) {
+            // A hierarchy selection only applies when its schema is the root; imported schemas contribute
+            // their declared hierarchies, not their selections.
+            if (isRoot)
+                mainSelection = declaredHierarchy;
         }
-        if (provider.metadata.aliases) {
-            Object.assign(mergedAliases, provider.metadata.aliases);
+        else if (declaredHierarchy) {
+            const hierarchy = normalizeHierarchy(declaredHierarchy, provider);
+            const label = `hierarchy "${hierarchy.name}"`;
+            mergeEntry(mergedHierarchies, hierarchy.name, label, { declared: declaredHierarchy, hierarchy }, declaredHierarchy.override, schemaId);
+            if (isRoot)
+                rootHierarchy = declaredHierarchy;
         }
-        if (provider.metadata.relationships) {
-            mergedRelationships.push(...provider.metadata.relationships);
+        for (const [alias, target] of Object.entries(metadata.aliases ?? {})) {
+            const [type, override] = typeof target === 'string' ? [target, false] : [target.type, target.override];
+            mergeEntry(mergedAliases, alias, `alias "${alias}"`, type, override, schemaId);
         }
-        if (provider.metadata.rules) {
-            for (const entry of provider.metadata.rules) {
-                const resolvedRules = resolveRuleEntries(entry, provider, schemaRefRegistry, new Set());
-                for (const incomingRule of resolvedRules) {
-                    const existingRule = mergedRules.get(incomingRule.id);
-                    if (!existingRule) {
-                        mergedRules.set(incomingRule.id, { providerId: provider.schemaId, rule: incomingRule });
-                        continue;
-                    }
-                    if (incomingRule.override === true) {
-                        mergedRules.set(incomingRule.id, { providerId: provider.schemaId, rule: incomingRule });
-                        continue;
-                    }
-                    if (!areRulesEquivalent(existingRule.rule, incomingRule)) {
-                        throw new Error(`Conflicting rule "${incomingRule.id}" found in "${existingRule.providerId}" and "${provider.schemaId}". Set "override": true on the later rule to replace it.`);
-                    }
-                }
-            }
+        for (const rel of metadata.relationships ?? []) {
+            const field = rel.field ?? 'parent';
+            const label = `relationship "${rel.parent} → ${rel.type}" (field "${field}")`;
+            mergeEntry(mergedRelationships, `${rel.parent}\0${rel.type}\0${field}`, label, rel, rel.override, schemaId);
+        }
+        for (const rule of metadata.rules ?? []) {
+            mergeEntry(mergedRules, rule.id, `rule "${rule.id}"`, rule, rule.override, schemaId);
+        }
+    }
+    const merged = values(mergedHierarchies);
+    const allHierarchies = merged.map(({ hierarchy }) => hierarchy);
+    validateHierarchyTypes(allHierarchies);
+    const findDeclared = (declared) => merged.find((entry) => entry.declared === declared)?.hierarchy;
+    let mainHierarchy = rootHierarchy ? findDeclared(rootHierarchy) : undefined;
+    if (mainSelection) {
+        const target = resolveMetadataRef(mainSelection.$ref, schema, schemaRefRegistry);
+        mainHierarchy = findDeclared(target.value);
+        if (!mainHierarchy) {
+            throw new Error(`Hierarchy $ref "${mainSelection.$ref}" does not point to a hierarchy declared by an imported schema. Expected a ref like "<schema $id>#/$metadata/hierarchy".`);
         }
     }
+    else if (!mainHierarchy && allHierarchies.length === 1) {
+        mainHierarchy = allHierarchies[0];
+    }
+    else if (!mainHierarchy && allHierarchies.length > 1) {
+        const rootSchemaId = typeof schema.$id === 'string' ? schema.$id : '(root schema)';
+        throw new Error(`Schema "${rootSchemaId}" imports multiple hierarchies (${allHierarchies.map((h) => `"${h.name}"`).join(', ')}) but selects none as its main hierarchy. Declare one, or select one with "hierarchy": { "$ref": "<schema $id>#/$metadata/hierarchy" }.`);
+    }
+    const typeAliases = Object.fromEntries([...mergedAliases].map(([alias, { value }]) => [alias, value]));
+    const rules = values(mergedRules).map(({ override, ...rule }) => rule);
+    const relationships = values(mergedRelationships);
     // Collect valid type names from the schema's oneOf list for validation
     const validTypeNames = extractSchemaTypeNames(schema, schemaRefRegistry);
-    // Validate and filter metadata references against valid type names
-    validateMetadataReferences({ mergedHierarchy, mergedAliases, mergedRules, mergedRelationships }, validTypeNames);
+    // Validate metadata references against valid type names
+    validateMetadataReferences({ allHierarchies, typeAliases, rules }, validTypeNames);
     // Filter relationships to only include those where both parent and child types are valid
-    const filteredRelationships = mergedRelationships.filter((rel) => {
+    const filteredRelationships = relationships.filter((rel) => {
         return validTypeNames.has(rel.parent) && validTypeNames.has(rel.type);
     });
-    const levels = mergedHierarchy?.levels.map((entry) => {
+    return {
+        hierarchy: mainHierarchy,
+        hierarchies: allHierarchies.length > 0 ? allHierarchies : undefined,
+        typeAliases: Object.keys(typeAliases).length > 0 ? typeAliases : undefined,
+        rules: rules.length > 0 ? rules : undefined,
+        relationships: filteredRelationships.length > 0
+            ? filteredRelationships.map(({ override, ...rel }) => ({
+                ...rel,
+                field: rel.field ?? 'parent',
+                fieldOn: rel.fieldOn === 'parent' ? 'parent' : 'child',
+                multiple: rel.multiple ?? false,
+            }))
+            : undefined,
+    };
+}
+function normalizeHierarchy(declared, provider) {
+    const levels = declared.levels.map((entry) => {
         if (typeof entry === 'string') {
             return { type: entry, field: 'parent', fieldOn: 'child', multiple: false, selfRef: false };
         }
@@ -322,24 +432,24 @@ function extractMetadata(schema, schemaRefRegistry) {
         };
     });
     return {
-        hierarchy: levels !== undefined
-            ? {
-                levels,
-                allowSkipLevels: mergedHierarchy?.allowSkipLevels,
-            }
-            : undefined,
-        typeAliases: Object.keys(mergedAliases).length > 0 ? mergedAliases : undefined,
-        rules: mergedRules.size > 0 ? [...mergedRules.values()].map(({ rule }) => normalizeRule(rule)) : undefined,
-        relationships: filteredRelationships.length > 0
-            ? filteredRelationships.map((rel) => ({
-                ...rel,
-                field: rel.field ?? 'parent',
-                fieldOn: rel.fieldOn === 'parent' ? 'parent' : 'child',
-                multiple: rel.multiple ?? false,
-            }))
-            : undefined,
+        name: declared.name ?? schemaFileStems.get(provider.schema) ?? provider.schemaId,
+        levels,
+        allowSkipLevels: declared.allowSkipLevels,
     };
 }
+/** Each type may belong to at most one hierarchy. */
+function validateHierarchyTypes(hierarchies) {
+    const typeOwners = new Map();
+    for (const hierarchy of hierarchies) {
+        for (const { type } of hierarchy.levels) {
+            const owner = typeOwners.get(type);
+            if (owner !== undefined && owner !== hierarchy.name) {
+                throw new Error(`Type "${type}" belongs to both hierarchy "${owner}" and hierarchy "${hierarchy.name}". Each type may belong to at most one hierarchy.`);
+            }
+            typeOwners.set(type, hierarchy.name);
+        }
+    }
+}
 function validateMetadataReferences(metadata, validTypes) {
     // Skip validation if no types are defined (e.g., schemas without oneOf or placeholder schemas)
     if (validTypes.size === 0) {
@@ -347,23 +457,22 @@ function validateMetadataReferences(metadata, validTypes) {
     }
     const errors = [];
     // Validate hierarchy level types
-    if (metadata.mergedHierarchy?.levels) {
-        for (const level of metadata.mergedHierarchy.levels) {
-            const typeName = typeof level === 'string' ? level : level.type;
-            if (!validTypes.has(typeName)) {
-                errors.push(`Hierarchy level "${typeName}" is not a valid type in the schema's oneOf list`);
+    for (const hierarchy of metadata.allHierarchies) {
+        for (const { type } of hierarchy.levels) {
+            if (!validTypes.has(type)) {
+                errors.push(`Hierarchy "${hierarchy.name}" level "${type}" is not a valid type in the schema's oneOf list`);
             }
         }
     }
     // Validate alias targets (the values)
-    for (const [alias, target] of Object.entries(metadata.mergedAliases)) {
+    for (const [alias, target] of Object.entries(metadata.typeAliases)) {
         if (!validTypes.has(target)) {
             errors.push(`Alias "${alias}" → "${target}" references type "${target}" which is not in the schema's oneOf list`);
         }
     }
     // Note: relationships are filtered (not validated) - see extractMetadata
     // Validate rule types
-    for (const { rule } of metadata.mergedRules.values()) {
+    for (const rule of metadata.rules) {
         if (rule.type && !validTypes.has(rule.type)) {
             errors.push(`Rule "${rule.id}" has type "${rule.type}" which is not in the schema's oneOf list`);
         }
@@ -401,12 +510,12 @@ export function extractEntityInfo(schema, schemaRefRegistry) {
 export function extractSchemaTypeNames(schema, schemaRefRegistry) {
     return new Set(extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type));
 }
-export function loadMetadata(schemaPath) {
-    return extractMetadata(readRawSchema(schemaPath), buildFullRegistry(schemaPath));
+export function loadMetadata(schemaPath, pluginSchemas) {
+    return extractMetadata(readRawSchema(schemaPath), buildFullRegistry(schemaPath, pluginSchemas));
 }
-export function loadSchema(schemaPath) {
+export function loadSchema(schemaPath, pluginSchemas) {
     const rawSchema = readRawSchema(schemaPath);
-    const schemaRefRegistry = buildFullRegistry(schemaPath);
+    const schemaRefRegistry = buildFullRegistry(schemaPath, pluginSchemas);
     const schema = {
         ...rawSchema,
         metadata: extractMetadata(rawSchema, schemaRefRegistry),