structured-context 0.9.0

package/dist/schema/schema-refs.js

@@ -0,0 +1,168 @@
+export { decodeJsonPointerToken, isObject, resolveJsonPointer, resolveRefTarget };
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function decodeJsonPointerToken(token) {
+    return token.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+function resolveJsonPointer(root, pointer, fullRef) {
+    if (pointer === '')
+        return root;
+    if (!pointer.startsWith('/')) {
+        throw new Error(`Unsupported $ref pointer "${fullRef}". Expected a JSON pointer (e.g. "#/$defs/name").`);
+    }
+    let current = root;
+    for (const rawToken of pointer.slice(1).split('/')) {
+        const token = decodeJsonPointerToken(rawToken);
+        if (Array.isArray(current)) {
+            const index = Number.parseInt(token, 10);
+            if (Number.isNaN(index) || index < 0 || index >= current.length) {
+                throw new Error(`Cannot resolve $ref "${fullRef}": array index "${token}" is out of bounds.`);
+            }
+            current = current[index];
+            continue;
+        }
+        if (!isObject(current) || !(token in current)) {
+            throw new Error(`Cannot resolve $ref "${fullRef}": token "${token}" does not exist.`);
+        }
+        current = current[token];
+    }
+    if (!isObject(current)) {
+        throw new Error(`Cannot resolve $ref "${fullRef}": target is not an object schema.`);
+    }
+    return current;
+}
+function mergeSchemaObjects(base, overlay) {
+    const merged = { ...base, ...overlay };
+    const baseProps = isObject(base.properties) ? base.properties : undefined;
+    const overlayProps = isObject(overlay.properties)
+        ? overlay.properties
+        : undefined;
+    if (baseProps || overlayProps) {
+        merged.properties = {
+            ...(baseProps ?? {}),
+            ...(overlayProps ?? {}),
+        };
+    }
+    const baseRequired = asArray(base.required);
+    const overlayRequired = asArray(overlay.required);
+    if (baseRequired.length > 0 || overlayRequired.length > 0) {
+        merged.required = [...new Set([...baseRequired, ...overlayRequired])];
+    }
+    const baseAllOf = asArray(base.allOf);
+    const overlayAllOf = asArray(overlay.allOf);
+    if (baseAllOf.length > 0 || overlayAllOf.length > 0) {
+        merged.allOf = [...baseAllOf, ...overlayAllOf];
+    }
+    return merged;
+}
+function resolveRefTarget(ref, currentRootSchema, schemaRefRegistry) {
+    if (ref.startsWith('#')) {
+        const pointer = ref.slice(1);
+        const rootId = typeof currentRootSchema.$id === 'string' ? currentRootSchema.$id : '(root)';
+        return {
+            schema: resolveJsonPointer(currentRootSchema, pointer, ref),
+            rootSchema: currentRootSchema,
+            refKey: `${rootId}#${pointer}`,
+        };
+    }
+    const hashIndex = ref.indexOf('#');
+    const baseId = hashIndex >= 0 ? ref.slice(0, hashIndex) : ref;
+    const pointer = hashIndex >= 0 ? ref.slice(hashIndex + 1) : '';
+    const externalSchema = schemaRefRegistry.get(baseId);
+    if (!externalSchema) {
+        throw new Error(`Cannot resolve external $ref: ${ref}`);
+    }
+    return {
+        schema: resolveJsonPointer(externalSchema, pointer, ref),
+        rootSchema: externalSchema,
+        refKey: `${baseId}#${pointer}`,
+    };
+}
+function resolveRefWithContext(def, rootSchema, schemaRefRegistry, stack) {
+    if (!def)
+        return undefined;
+    const ref = typeof def.$ref === 'string' ? def.$ref : undefined;
+    if (!ref) {
+        return { schema: def, rootSchema };
+    }
+    const target = resolveRefTarget(ref, rootSchema, schemaRefRegistry);
+    if (stack.has(target.refKey)) {
+        throw new Error(`Cyclic $ref detected: ${[...stack, target.refKey].join(' -> ')}`);
+    }
+    stack.add(target.refKey);
+    const resolvedTarget = resolveRefWithContext(target.schema, target.rootSchema, schemaRefRegistry, stack);
+    stack.delete(target.refKey);
+    if (!resolvedTarget)
+        return undefined;
+    const overlay = {};
+    let hasOverlay = false;
+    for (const [k, v] of Object.entries(def)) {
+        if (k !== '$ref') {
+            overlay[k] = v;
+            hasOverlay = true;
+        }
+    }
+    if (!hasOverlay) {
+        return resolvedTarget;
+    }
+    return {
+        schema: mergeSchemaObjects(resolvedTarget.schema, overlay),
+        rootSchema: resolvedTarget.rootSchema,
+    };
+}
+function flattenAllOf(def, rootSchema, schemaRefRegistry, stack, visited = new Set()) {
+    const resolved = resolveRefWithContext(def, rootSchema, schemaRefRegistry, stack);
+    if (!resolved)
+        return [];
+    const schemaId = typeof resolved.schema.$id === 'string' ? resolved.schema.$id : undefined;
+    if (schemaId && visited.has(schemaId)) {
+        // Cycle detected via allOf: this schema is already being processed
+        return [];
+    }
+    if (schemaId)
+        visited.add(schemaId);
+    const parts = [];
+    const allOf = asArray(resolved.schema.allOf);
+    for (const sub of allOf) {
+        parts.push(...flattenAllOf(sub, resolved.rootSchema, schemaRefRegistry, stack, visited));
+    }
+    if (schemaId)
+        visited.delete(schemaId);
+    const own = { ...resolved.schema };
+    delete own.allOf;
+    parts.push({ schema: own, rootSchema: resolved.rootSchema });
+    return parts;
+}
+/**
+ * Resolve a schema definition, following cross-file and internal refs transitively.
+ */
+export function resolveRef(propDef, schema, schemaRefRegistry) {
+    return resolveRefWithContext(propDef, schema, schemaRefRegistry, new Set())?.schema;
+}
+/**
+ * Merge properties and required fields from allOf entries recursively across refs.
+ * allOf entries are flattened depth-first; direct properties on later fragments override earlier ones.
+ */
+export function mergeVariantProperties(variant, schema, schemaRefRegistry) {
+    const properties = {};
+    const requiredSet = new Set();
+    const fragments = flattenAllOf(variant, schema, schemaRefRegistry, new Set());
+    for (const fragment of fragments) {
+        const fragmentProps = isObject(fragment.schema.properties)
+            ? fragment.schema.properties
+            : undefined;
+        if (fragmentProps) {
+            for (const [key, value] of Object.entries(fragmentProps)) {
+                properties[key] = resolveRef(value, fragment.rootSchema, schemaRefRegistry) ?? value;
+            }
+        }
+        for (const req of asArray(fragment.schema.required)) {
+            requiredSet.add(req);
+        }
+    }
+    return { properties, required: [...requiredSet] };
+}

package/dist/schema/schema.d.ts

@@ -0,0 +1,27 @@
+import { type AnySchemaObject, type ValidateFunction } from 'ajv';
+import type { SchemaMetadata, SchemaWithMetadata } from '../types';
+export declare const bundledSchemasDir: string;
+export declare function readRawSchema(schemaPath: string): AnySchemaObject;
+/**
+ * Build the full two-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.
+ */
+export declare function buildFullRegistry(schemaPath: string): Map<string, AnySchemaObject>;
+export declare function createValidator(schemaPath: string): ValidateFunction;
+export declare function resolveNodeType(type: string, typeAliases: Record<string, string> | undefined): string;
+export interface EntityInfo {
+    type: string;
+    properties: string[];
+    required: string[];
+}
+export declare function extractEntityInfo(schema: SchemaWithMetadata, schemaRefRegistry: Map<string, AnySchemaObject>): EntityInfo[];
+export declare function extractSchemaTypeNames(schema: SchemaWithMetadata, schemaRefRegistry: Map<string, AnySchemaObject>): Set<string>;
+export declare function loadMetadata(schemaPath: string): SchemaMetadata;
+export interface LoadedSchema {
+    schema: SchemaWithMetadata;
+    schemaRefRegistry: Map<string, AnySchemaObject>;
+    schemaValidator: ValidateFunction;
+}
+export declare function loadSchema(schemaPath: string): LoadedSchema;

package/dist/schema/schema.js

@@ -0,0 +1,378 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+import Ajv, {} from 'ajv';
+import { JSON5 } from 'bun';
+import { DIALECT_META_SCHEMA, METADATA_SCHEMA, SCHEMA_META_ID, } from './metadata-contract';
+import { isObject, mergeVariantProperties, resolveJsonPointer } from './schema-refs';
+const packageDir = dirname(fileURLToPath(import.meta.url));
+export const bundledSchemasDir = join(packageDir, '..', '..', 'schemas');
+const validateMetadataContract = new Ajv().compile(METADATA_SCHEMA);
+export function readRawSchema(schemaPath) {
+    return JSON5.parse(readFileSync(resolve(schemaPath), 'utf-8'));
+}
+/**
+ * Build a registry of all schemas in the given directory, keyed by $id.
+ * Only loads "partial" schemas (starting with _) and an optional target file.
+ */
+function buildSchemaRegistry(dir, targetFile) {
+    const schemaRefRegistry = new Map();
+    if (!existsSync(dir))
+        return schemaRefRegistry;
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith('.json'))
+            continue;
+        const isPartial = file.startsWith('_');
+        const isTarget = targetFile !== undefined && file === targetFile;
+        if (!isPartial && !isTarget)
+            continue;
+        const schema = readRawSchema(join(dir, file));
+        if (typeof schema.$id === 'string')
+            schemaRefRegistry.set(schema.$id, schema);
+    }
+    return schemaRefRegistry;
+}
+/**
+ * Build the full two-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.
+ */
+export function buildFullRegistry(schemaPath) {
+    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)) {
+        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);
+        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.`);
+            }
+            schemaRefRegistry.set(id, schema);
+        }
+    }
+    return schemaRefRegistry;
+}
+function compileValidator(targetSchema, schemaRefRegistry) {
+    const ajv = new Ajv();
+    ajv.addFormat('path', (value) => value.length > 0 && !value.includes('\0'));
+    ajv.addFormat('date', (value) => /^\d{4}-\d{2}-\d{2}$/.test(value));
+    ajv.addFormat('wikilink', (value) => /^\[\[.+\]\]$/.test(value));
+    ajv.addKeyword({
+        keyword: '$metadata',
+        schemaType: 'object',
+        metaSchema: METADATA_SCHEMA,
+        valid: true,
+        errors: false,
+    });
+    const metaSchema = DIALECT_META_SCHEMA;
+    ajv.addSchema(metaSchema, SCHEMA_META_ID);
+    // Register all except target schema (AJV compiles targetSchema explicitly)
+    for (const [id, schema] of schemaRefRegistry) {
+        if (id === targetSchema.$id || id === SCHEMA_META_ID)
+            continue;
+        ajv.addSchema(schema);
+    }
+    return ajv.compile(targetSchema);
+}
+export function createValidator(schemaPath) {
+    return compileValidator(readRawSchema(schemaPath), buildFullRegistry(schemaPath));
+}
+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;
+    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) {
+    if (ref.startsWith('#')) {
+        const pointer = ref.slice(1);
+        const rootId = typeof currentRootSchema.$id === 'string' ? currentRootSchema.$id : '(root schema)';
+        return {
+            value: resolveJsonPointer(currentRootSchema, pointer, ref),
+            rootSchema: currentRootSchema,
+            refKey: `${rootId}#${pointer}`,
+        };
+    }
+    const hashIndex = ref.indexOf('#');
+    const baseId = hashIndex >= 0 ? ref.slice(0, hashIndex) : ref;
+    const pointer = hashIndex >= 0 ? ref.slice(hashIndex + 1) : '';
+    const externalSchema = schemaRefRegistry.get(baseId);
+    if (!externalSchema) {
+        throw new Error(`Cannot resolve external $ref: ${ref}`);
+    }
+    return {
+        value: resolveJsonPointer(externalSchema, pointer, ref),
+        rootSchema: externalSchema,
+        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;
+}
+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)
+                continue;
+            walk(referencedSchema);
+            const metadata = readTopLevelMetadata(referencedSchema);
+            if (metadata) {
+                providers.push({ schemaId, schema: referencedSchema, 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 });
+    }
+    return providers;
+}
+function isRuleRefEntry(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);
+    }
+}
+function normalizeRule(rule) {
+    const { override, ...normalized } = rule;
+    return normalized;
+}
+function areRulesEquivalent(left, right) {
+    return isDeepStrictEqual(normalizeRule(left), normalizeRule(right));
+}
+function extractMetadata(schema, schemaRefRegistry) {
+    const metadataProviders = collectMetadataProviders(schema, schemaRefRegistry);
+    let hierarchyProvider;
+    let mergedHierarchy;
+    const mergedAliases = {};
+    const mergedRules = new Map();
+    const mergedRelationships = [];
+    for (const provider of metadataProviders) {
+        if (provider.metadata.hierarchy) {
+            if (mergedHierarchy) {
+                throw new Error(`Multiple metadata providers define "$metadata.hierarchy": "${hierarchyProvider}" and "${provider.schemaId}". Exactly one provider is allowed.`);
+            }
+            hierarchyProvider = provider.schemaId;
+            mergedHierarchy = provider.metadata.hierarchy;
+        }
+        if (provider.metadata.aliases) {
+            Object.assign(mergedAliases, provider.metadata.aliases);
+        }
+        if (provider.metadata.relationships) {
+            mergedRelationships.push(...provider.metadata.relationships);
+        }
+        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.`);
+                    }
+                }
+            }
+        }
+    }
+    const levels = mergedHierarchy?.levels.map((entry) => {
+        if (typeof entry === 'string') {
+            return { type: entry, field: 'parent', fieldOn: 'child', multiple: false, selfRef: false };
+        }
+        // If selfRefField is set, imply selfRef: true
+        const selfRef = entry.selfRefField !== undefined ? true : (entry.selfRef ?? false);
+        return {
+            type: entry.type,
+            field: entry.field ?? 'parent',
+            fieldOn: entry.fieldOn === 'parent' ? 'parent' : 'child',
+            multiple: entry.multiple ?? false,
+            selfRef,
+            selfRefField: entry.selfRefField,
+            templateFormat: entry.templateFormat,
+            matchers: entry.matchers,
+            embeddedTemplateFields: entry.embeddedTemplateFields,
+        };
+    });
+    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: mergedRelationships.length > 0
+            ? mergedRelationships.map((rel) => ({
+                ...rel,
+                field: rel.field ?? 'parent',
+                fieldOn: rel.fieldOn === 'parent' ? 'parent' : 'child',
+                multiple: rel.multiple ?? false,
+            }))
+            : undefined,
+    };
+}
+export function extractEntityInfo(schema, schemaRefRegistry) {
+    if (!Array.isArray(schema.oneOf))
+        return [];
+    const result = [];
+    for (const entry of schema.oneOf) {
+        const { properties, required } = mergeVariantProperties(entry, schema, schemaRefRegistry);
+        const typeDef = properties.type;
+        if (typeDef?.const !== undefined) {
+            result.push({
+                type: String(typeDef.const),
+                properties: Object.keys(properties).filter((k) => k !== 'type'),
+                required: required.filter((r) => r !== 'type'),
+            });
+        }
+        else if (Array.isArray(typeDef?.enum)) {
+            for (const t of typeDef.enum) {
+                result.push({
+                    type: String(t),
+                    properties: Object.keys(properties).filter((k) => k !== 'type'),
+                    required: required.filter((r) => r !== 'type'),
+                });
+            }
+        }
+    }
+    return result;
+}
+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 loadSchema(schemaPath) {
+    const rawSchema = readRawSchema(schemaPath);
+    const schemaRefRegistry = buildFullRegistry(schemaPath);
+    const schema = {
+        ...rawSchema,
+        metadata: extractMetadata(rawSchema, schemaRefRegistry),
+    };
+    return {
+        schema,
+        schemaRefRegistry,
+        schemaValidator: compileValidator(rawSchema, schemaRefRegistry),
+    };
+}

package/dist/schema/validate-graph.d.ts

@@ -0,0 +1,24 @@
+import type { GraphViolation, SchemaMetadata, SpaceNode, UnresolvedRef } from '../types';
+export interface GraphValidationResult {
+    violations: GraphViolation[];
+    refErrors: Array<{
+        file: string;
+        parent: string;
+        error: string;
+    }>;
+}
+/**
+ * Validate graph structure using pre-collected unresolved refs from resolveGraphEdges.
+ * Assumes resolveGraphEdges has already been called to populate node.resolvedParents.
+ */
+export declare function validateGraph(nodes: SpaceNode[], metadata: SchemaMetadata, unresolvedRefs?: UnresolvedRef[]): GraphValidationResult;
+/**
+ * Validate that resolved parents follow hierarchy level rules and relationship type constraints.
+ *
+ * For hierarchy edges (fieldOn:'child', source:'hierarchy'): validates level ordering.
+ * For relationship edges (fieldOn:'child', source:'relationship'): validates parent type.
+ * For fieldOn:'parent' edges: validates child type, violation attributed to the field-owner node.
+ *
+ * Assumes resolveGraphEdges has already been called to populate node.resolvedParents.
+ */
+export declare function validateHierarchyStructure(nodes: SpaceNode[], metadata: SchemaMetadata): GraphViolation[];