@globaltypesystem/gts-ts 0.1.1 → 0.3.0

package/dist/store.js

@@ -81,8 +81,12 @@ class GtsStore {
     }
     validateInstance(gtsId) {
         try {
-            const gid = gts_1.Gts.parseGtsID(gtsId);
-            const obj = this.get(gid.id);
+            let objId = gtsId;
+            if (gts_1.Gts.isValidGtsID(gtsId)) {
+                const gid = gts_1.Gts.parseGtsID(gtsId);
+                objId = gid.id;
+            }
+            const obj = this.get(objId);
             if (!obj) {
                 return {
                     id: gtsId,
@@ -174,6 +178,9 @@ class GtsStore {
         }
         const normalized = {};
         for (const [key, value] of Object.entries(obj)) {
+            // Strip x-gts-ref so Ajv never sees the unknown keyword
+            if (key === 'x-gts-ref')
+                continue;
             let newKey = key;
             let newValue = value;
             // Convert $$ prefixed keys to $ prefixed keys
@@ -197,6 +204,23 @@ class GtsStore {
             }
             normalized[newKey] = newValue;
         }
+        // Clean up combinator arrays: remove subschemas that were x-gts-ref-only (now empty after stripping)
+        for (const combinator of ['oneOf', 'anyOf', 'allOf']) {
+            if (Array.isArray(normalized[combinator])) {
+                normalized[combinator] = normalized[combinator].filter((_sub, idx) => {
+                    const original = obj[combinator]?.[idx];
+                    const isXGtsRefOnly = original &&
+                        typeof original === 'object' &&
+                        !Array.isArray(original) &&
+                        Object.keys(original).length === 1 &&
+                        original['x-gts-ref'] !== undefined;
+                    return !isXGtsRefOnly;
+                });
+                if (normalized[combinator].length === 0) {
+                    delete normalized[combinator];
+                }
+            }
+        }
         // Normalize $id values
         if (normalized['$id'] && typeof normalized['$id'] === 'string') {
             if (normalized['$id'].startsWith(types_1.GTS_URI_PREFIX)) {
@@ -908,6 +932,755 @@ class GtsStore {
         const unique = Array.from(new Set(arr));
         return unique.sort();
     }
+    validateSchemaAgainstParent(schemaId) {
+        const entity = this.get(schemaId);
+        if (!entity) {
+            return { id: schemaId, ok: false, error: `Entity not found: ${schemaId}` };
+        }
+        if (!entity.isSchema) {
+            return { id: schemaId, ok: false, error: `Entity is not a schema: ${schemaId}` };
+        }
+        const content = entity.content;
+        // Find parent reference in allOf
+        const parentRef = this.findParentRef(content);
+        if (!parentRef) {
+            // Base schema with no parent → still validate traits
+            return this.validateSchemaTraits(schemaId);
+        }
+        // Resolve parent entity
+        const parentId = parentRef.startsWith(types_1.GTS_URI_PREFIX) ? parentRef.substring(types_1.GTS_URI_PREFIX.length) : parentRef;
+        const parentEntity = this.get(parentId);
+        if (!parentEntity) {
+            return { id: schemaId, ok: false, error: `Parent schema not found: ${parentId}` };
+        }
+        if (!parentEntity.isSchema || !parentEntity.content) {
+            return { id: schemaId, ok: false, error: `Parent entity is not a schema: ${parentId}` };
+        }
+        // Detect cyclic $$ref / $ref references in the schema's own content
+        const cycleError = this.detectRefCycle(schemaId, content, new Set([schemaId]));
+        if (cycleError) {
+            return { id: schemaId, ok: false, error: cycleError };
+        }
+        // Resolve parent's effective (fully flattened) schema
+        const resolvedParent = this.resolveSchemaFully(parentEntity.content);
+        // Extract overlay from derived schema (non-$ref subschemas in allOf + top-level)
+        const overlay = this.extractOverlay(content);
+        // Compare overlay against resolved parent
+        const errors = this.compareOverlayToBase(overlay, resolvedParent, '');
+        if (errors.length > 0) {
+            return { id: schemaId, ok: false, error: errors.join('; ') };
+        }
+        // OP#13: Validate schema traits across the inheritance chain
+        const traitsResult = this.validateSchemaTraits(schemaId);
+        if (!traitsResult.ok) {
+            return traitsResult;
+        }
+        return { id: schemaId, ok: true, error: '' };
+    }
+    // OP#13: Validate schema traits across the inheritance chain
+    validateSchemaTraits(schemaId) {
+        // Build the chain of schema IDs from base to leaf
+        const chain = this.buildSchemaChain(schemaId);
+        // Collect trait schemas and trait values from each level, tracking immutability
+        const traitSchemas = [];
+        const mergedTraits = {};
+        const lockedTraits = new Set();
+        const knownDefaults = new Map();
+        for (const chainSchemaId of chain) {
+            const entity = this.get(chainSchemaId);
+            if (!entity || !entity.content)
+                continue;
+            // Collect trait schemas from this level and track which properties this level introduces
+            const prevSchemaCount = traitSchemas.length;
+            this.collectTraitSchemas(entity.content, traitSchemas);
+            const levelSchemaProps = new Set();
+            for (const ts of traitSchemas.slice(prevSchemaCount)) {
+                if (typeof ts === 'object' && ts !== null && typeof ts.properties === 'object' && ts.properties !== null) {
+                    for (const [propName, propSchema] of Object.entries(ts.properties)) {
+                        levelSchemaProps.add(propName);
+                        // Detect default override: ancestor default cannot be changed by descendant
+                        if (typeof propSchema === 'object' &&
+                            propSchema !== null &&
+                            'default' in propSchema) {
+                            const newDefault = propSchema.default;
+                            if (knownDefaults.has(propName)) {
+                                const oldDefault = knownDefaults.get(propName);
+                                if (JSON.stringify(oldDefault) !== JSON.stringify(newDefault)) {
+                                    return {
+                                        id: schemaId,
+                                        ok: false,
+                                        error: `trait schema default for '${propName}' in '${chainSchemaId}' overrides default set by ancestor`,
+                                    };
+                                }
+                            }
+                            else {
+                                knownDefaults.set(propName, newDefault);
+                            }
+                        }
+                    }
+                }
+            }
+            // Collect trait values from this level
+            const levelTraits = {};
+            this.collectTraitValues(entity.content, levelTraits);
+            // Check immutability: trait values set by ancestor are locked unless
+            // this level also introduces a trait schema covering that property
+            for (const [k, v] of Object.entries(levelTraits)) {
+                if (k in mergedTraits && JSON.stringify(mergedTraits[k]) !== JSON.stringify(v) && lockedTraits.has(k)) {
+                    return {
+                        id: schemaId,
+                        ok: false,
+                        error: `trait '${k}' in '${chainSchemaId}' overrides value set by ancestor`,
+                    };
+                }
+            }
+            // Mark trait values as locked or unlocked based on whether this level
+            // also introduced a trait schema covering the property
+            for (const k of Object.keys(levelTraits)) {
+                if (levelSchemaProps.has(k)) {
+                    lockedTraits.delete(k);
+                }
+                else {
+                    lockedTraits.add(k);
+                }
+            }
+            Object.assign(mergedTraits, levelTraits);
+        }
+        // If no trait schemas in the chain, nothing to validate
+        if (traitSchemas.length === 0) {
+            if (Object.keys(mergedTraits).length > 0) {
+                return {
+                    id: schemaId,
+                    ok: false,
+                    error: 'x-gts-traits values provided but no x-gts-traits-schema is defined in the inheritance chain',
+                };
+            }
+            return { id: schemaId, ok: true, error: '' };
+        }
+        // Validate each trait schema
+        for (let i = 0; i < traitSchemas.length; i++) {
+            const ts = traitSchemas[i];
+            // Check: trait schema must have type "object" (or no type, which defaults to object)
+            if (typeof ts === 'object' && ts !== null && ts.type && ts.type !== 'object') {
+                return {
+                    id: schemaId,
+                    ok: false,
+                    error: `x-gts-traits-schema must have type "object", got "${ts.type}"`,
+                };
+            }
+            // Check: trait schema must not contain x-gts-traits
+            if (typeof ts === 'object' && ts !== null && ts['x-gts-traits']) {
+                return {
+                    id: schemaId,
+                    ok: false,
+                    error: 'x-gts-traits-schema must not contain x-gts-traits',
+                };
+            }
+        }
+        // Resolve $ref inside trait schemas and check for cycles
+        const resolvedTraitSchemas = [];
+        for (const ts of traitSchemas) {
+            try {
+                const resolved = this.resolveTraitSchemaRefs(ts, new Set());
+                resolvedTraitSchemas.push(resolved);
+            }
+            catch (e) {
+                return {
+                    id: schemaId,
+                    ok: false,
+                    error: e instanceof Error ? e.message : String(e),
+                };
+            }
+        }
+        // Build effective trait schema (allOf composition)
+        let effectiveSchema;
+        if (resolvedTraitSchemas.length === 1) {
+            effectiveSchema = resolvedTraitSchemas[0];
+        }
+        else {
+            effectiveSchema = {
+                type: 'object',
+                allOf: resolvedTraitSchemas,
+            };
+        }
+        // Apply defaults from trait schema to merged traits
+        const effectiveTraits = this.applyTraitDefaults(effectiveSchema, mergedTraits);
+        // Validate effective traits against effective schema using AJV
+        try {
+            const normalizedSchema = this.normalizeSchema(effectiveSchema);
+            const validate = this.ajv.compile(normalizedSchema);
+            const isValid = validate(effectiveTraits);
+            if (!isValid) {
+                const errors = validate.errors?.map((e) => `${e.instancePath} ${e.message}`).join('; ') || 'Trait validation failed';
+                return { id: schemaId, ok: false, error: `trait validation: ${errors}` };
+            }
+        }
+        catch (e) {
+            return {
+                id: schemaId,
+                ok: false,
+                error: `failed to compile trait schema: ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+        // Check for unresolved trait properties (no value and no default)
+        const allProps = this.collectAllTraitProperties(effectiveSchema);
+        for (const [propName, propSchema] of Object.entries(allProps)) {
+            const hasValue = propName in effectiveTraits;
+            const hasDefault = typeof propSchema === 'object' && propSchema !== null && 'default' in propSchema;
+            if (!hasValue && !hasDefault) {
+                return {
+                    id: schemaId,
+                    ok: false,
+                    error: `trait property '${propName}' is not resolved: no value provided and no default defined`,
+                };
+            }
+        }
+        return { id: schemaId, ok: true, error: '' };
+    }
+    // OP#13: Entity-level traits validation
+    validateEntityTraits(entityId) {
+        const entity = this.get(entityId);
+        if (!entity) {
+            return { id: entityId, ok: false, error: `Entity not found: ${entityId}` };
+        }
+        if (!entity.isSchema) {
+            return { id: entityId, ok: true, error: '' };
+        }
+        // Build the chain for this schema
+        const chain = this.buildSchemaChain(entityId);
+        const traitSchemas = [];
+        let hasTraitValues = false;
+        for (const chainSchemaId of chain) {
+            const chainEntity = this.get(chainSchemaId);
+            if (!chainEntity || !chainEntity.content)
+                continue;
+            this.collectTraitSchemas(chainEntity.content, traitSchemas);
+            const levelTraits = {};
+            this.collectTraitValues(chainEntity.content, levelTraits);
+            if (Object.keys(levelTraits).length > 0) {
+                hasTraitValues = true;
+            }
+        }
+        if (traitSchemas.length === 0) {
+            return { id: entityId, ok: true, error: '' };
+        }
+        // If trait schemas exist but no trait values, entity is incomplete
+        if (!hasTraitValues) {
+            return {
+                id: entityId,
+                ok: false,
+                error: 'Entity defines x-gts-traits-schema but no x-gts-traits values are provided',
+            };
+        }
+        // Each trait schema must have additionalProperties: false (closed)
+        for (const ts of traitSchemas) {
+            if (typeof ts === 'object' && ts !== null) {
+                if (ts.additionalProperties !== false) {
+                    return {
+                        id: entityId,
+                        ok: false,
+                        error: 'Trait schema must set additionalProperties: false for entity validation',
+                    };
+                }
+            }
+        }
+        return { id: entityId, ok: true, error: '' };
+    }
+    // Build the schema chain from base to leaf for a given schema ID
+    buildSchemaChain(schemaId) {
+        // Parse the schema ID to get segments
+        try {
+            const gtsId = gts_1.Gts.parseGtsID(schemaId);
+            const segments = gtsId.segments;
+            const chain = [];
+            for (let i = 0; i < segments.length; i++) {
+                const id = 'gts.' +
+                    segments
+                        .slice(0, i + 1)
+                        .map((s) => s.segment)
+                        .join('');
+                chain.push(id);
+            }
+            return chain;
+        }
+        catch {
+            return [schemaId];
+        }
+    }
+    // Collect x-gts-traits-schema from a schema content (recursing into allOf)
+    collectTraitSchemas(content, out, depth = 0) {
+        if (depth > 64 || typeof content !== 'object' || content === null)
+            return;
+        if (content['x-gts-traits-schema'] !== undefined) {
+            out.push(content['x-gts-traits-schema']);
+        }
+        if (Array.isArray(content.allOf)) {
+            for (const item of content.allOf) {
+                this.collectTraitSchemas(item, out, depth + 1);
+            }
+        }
+    }
+    // Collect x-gts-traits from a schema content (recursing into allOf)
+    collectTraitValues(content, merged, depth = 0) {
+        if (depth > 64 || typeof content !== 'object' || content === null)
+            return;
+        if (typeof content['x-gts-traits'] === 'object' && content['x-gts-traits'] !== null) {
+            Object.assign(merged, content['x-gts-traits']);
+        }
+        if (Array.isArray(content.allOf)) {
+            for (const item of content.allOf) {
+                this.collectTraitValues(item, merged, depth + 1);
+            }
+        }
+    }
+    // Resolve $ref inside a trait schema, detecting cycles
+    resolveTraitSchemaRefs(schema, visited, depth = 0) {
+        if (depth > 64)
+            return schema;
+        if (typeof schema !== 'object' || schema === null)
+            return schema;
+        const result = {};
+        for (const [key, value] of Object.entries(schema)) {
+            if (key === '$$ref' || key === '$ref') {
+                const refUri = value;
+                const refId = refUri.startsWith(types_1.GTS_URI_PREFIX) ? refUri.substring(types_1.GTS_URI_PREFIX.length) : refUri;
+                if (visited.has(refId)) {
+                    throw new Error(`Cyclic reference detected in trait schema: ${refId}`);
+                }
+                visited.add(refId);
+                const refEntity = this.get(refId);
+                if (!refEntity || !refEntity.content) {
+                    throw new Error(`Unresolvable trait schema reference: ${refUri}`);
+                }
+                const resolved = this.resolveTraitSchemaRefs(refEntity.content, visited, depth + 1);
+                // Merge resolved content into result
+                for (const [rk, rv] of Object.entries(resolved)) {
+                    if (rk !== '$id' && rk !== '$$id' && rk !== '$schema' && rk !== '$$schema') {
+                        result[rk] = rv;
+                    }
+                }
+                continue;
+            }
+            if (key === 'allOf' && Array.isArray(value)) {
+                result.allOf = value.map((item) => this.resolveTraitSchemaRefs(item, visited, depth + 1));
+            }
+            else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                result[key] = this.resolveTraitSchemaRefs(value, new Set(visited), depth + 1);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    // Apply defaults from trait schema to trait values
+    applyTraitDefaults(schema, traits) {
+        const result = { ...traits };
+        const props = this.collectAllTraitProperties(schema);
+        for (const [propName, propSchema] of Object.entries(props)) {
+            if (!(propName in result) && typeof propSchema === 'object' && propSchema !== null && 'default' in propSchema) {
+                result[propName] = propSchema.default;
+            }
+        }
+        return result;
+    }
+    // Collect all properties from a trait schema (handling allOf composition)
+    collectAllTraitProperties(schema, depth = 0) {
+        const props = {};
+        if (depth > 64 || typeof schema !== 'object' || schema === null)
+            return props;
+        if (typeof schema.properties === 'object' && schema.properties !== null) {
+            Object.assign(props, schema.properties);
+        }
+        if (Array.isArray(schema.allOf)) {
+            for (const item of schema.allOf) {
+                Object.assign(props, this.collectAllTraitProperties(item, depth + 1));
+            }
+        }
+        return props;
+    }
+    // Detect cyclic $$ref/$ref references reachable from a schema's content
+    detectRefCycle(originId, content, visited, depth = 0) {
+        if (depth > 64 || !content || typeof content !== 'object')
+            return null;
+        // Check direct ref on this object
+        const ref = content['$$ref'] || content['$ref'];
+        if (typeof ref === 'string') {
+            const refId = ref.startsWith(types_1.GTS_URI_PREFIX) ? ref.substring(types_1.GTS_URI_PREFIX.length) : ref;
+            if (visited.has(refId)) {
+                return `Cyclic reference detected: ${refId}`;
+            }
+            const refEntity = this.get(refId);
+            if (refEntity && refEntity.content) {
+                visited.add(refId);
+                const inner = this.detectRefCycle(originId, refEntity.content, visited, depth + 1);
+                if (inner)
+                    return inner;
+            }
+        }
+        // Recurse into allOf
+        if (Array.isArray(content.allOf)) {
+            for (const sub of content.allOf) {
+                const inner = this.detectRefCycle(originId, sub, visited, depth + 1);
+                if (inner)
+                    return inner;
+            }
+        }
+        return null;
+    }
+    findParentRef(schema) {
+        if (!schema || !schema.allOf || !Array.isArray(schema.allOf)) {
+            return null;
+        }
+        for (const sub of schema.allOf) {
+            if (sub && typeof sub === 'object') {
+                const ref = sub['$$ref'] || sub['$ref'];
+                if (typeof ref === 'string') {
+                    return ref;
+                }
+            }
+        }
+        return null;
+    }
+    resolveSchemaFully(schema, visited = new Set()) {
+        const result = {
+            properties: {},
+            required: [],
+            additionalProperties: undefined,
+            type: schema.type,
+        };
+        // If this schema has allOf, resolve each part
+        if (schema.allOf && Array.isArray(schema.allOf)) {
+            for (const sub of schema.allOf) {
+                const ref = sub['$$ref'] || sub['$ref'];
+                if (typeof ref === 'string') {
+                    // Resolve referenced schema
+                    const refId = ref.startsWith(types_1.GTS_URI_PREFIX) ? ref.substring(types_1.GTS_URI_PREFIX.length) : ref;
+                    if (visited.has(refId)) {
+                        continue;
+                    }
+                    visited.add(refId);
+                    const refEntity = this.get(refId);
+                    if (refEntity && refEntity.content) {
+                        const resolved = this.resolveSchemaFully(refEntity.content, visited);
+                        Object.assign(result.properties, resolved.properties);
+                        if (resolved.required) {
+                            result.required.push(...resolved.required);
+                        }
+                        if (resolved.additionalProperties !== undefined) {
+                            result.additionalProperties = resolved.additionalProperties;
+                        }
+                        if (resolved.type && !result.type) {
+                            result.type = resolved.type;
+                        }
+                    }
+                }
+                else {
+                    // Non-ref subschema - merge it
+                    const resolved = this.resolveSchemaFully(sub, visited);
+                    // For overlay properties, merge them (they override)
+                    for (const [propName, propSchema] of Object.entries(resolved.properties || {})) {
+                        if (result.properties[propName]) {
+                            // Merge property constraints - overlay tightens base
+                            result.properties[propName] = this.mergePropertySchemas(result.properties[propName], propSchema);
+                        }
+                        else {
+                            result.properties[propName] = propSchema;
+                        }
+                    }
+                    if (resolved.required) {
+                        result.required.push(...resolved.required);
+                    }
+                    if (resolved.additionalProperties !== undefined) {
+                        result.additionalProperties = resolved.additionalProperties;
+                    }
+                }
+            }
+        }
+        // Add direct properties
+        if (schema.properties) {
+            for (const [propName, propSchema] of Object.entries(schema.properties)) {
+                if (result.properties[propName]) {
+                    result.properties[propName] = this.mergePropertySchemas(result.properties[propName], propSchema);
+                }
+                else {
+                    result.properties[propName] = propSchema;
+                }
+            }
+        }
+        // Add direct required
+        if (schema.required && Array.isArray(schema.required)) {
+            result.required.push(...schema.required);
+        }
+        // Direct additionalProperties
+        if (schema.additionalProperties !== undefined) {
+            result.additionalProperties = schema.additionalProperties;
+        }
+        // Deduplicate required
+        result.required = Array.from(new Set(result.required));
+        return result;
+    }
+    mergePropertySchemas(base, overlay) {
+        if (base === false || overlay === false) {
+            return false;
+        }
+        if (typeof base !== 'object' || typeof overlay !== 'object') {
+            return overlay;
+        }
+        const merged = { ...base };
+        for (const [key, val] of Object.entries(overlay)) {
+            if (key === 'properties' && merged.properties) {
+                merged.properties = { ...merged.properties, ...val };
+            }
+            else if (key === 'required' && merged.required) {
+                const mergedReq = new Set([...merged.required, ...val]);
+                merged.required = Array.from(mergedReq);
+            }
+            else {
+                merged[key] = val;
+            }
+        }
+        return merged;
+    }
+    extractOverlay(schema) {
+        const overlay = {
+            properties: {},
+            required: [],
+            additionalProperties: undefined,
+        };
+        if (schema.allOf && Array.isArray(schema.allOf)) {
+            for (const sub of schema.allOf) {
+                const ref = sub['$$ref'] || sub['$ref'];
+                if (typeof ref === 'string') {
+                    continue; // Skip ref subschemas
+                }
+                // This is a non-ref overlay subschema
+                if (sub.properties) {
+                    for (const [propName, propSchema] of Object.entries(sub.properties)) {
+                        overlay.properties[propName] = overlay.properties[propName]
+                            ? this.mergePropertySchemas(overlay.properties[propName], propSchema)
+                            : propSchema;
+                    }
+                }
+                if (sub.required && Array.isArray(sub.required)) {
+                    overlay.required.push(...sub.required);
+                }
+                if (sub.additionalProperties !== undefined) {
+                    overlay.additionalProperties = sub.additionalProperties;
+                }
+            }
+        }
+        // Add top-level properties (outside allOf)
+        if (schema.properties) {
+            for (const [propName, propSchema] of Object.entries(schema.properties)) {
+                overlay.properties[propName] = overlay.properties[propName]
+                    ? this.mergePropertySchemas(overlay.properties[propName], propSchema)
+                    : propSchema;
+            }
+        }
+        if (schema.required && Array.isArray(schema.required)) {
+            overlay.required.push(...schema.required);
+        }
+        if (schema.additionalProperties !== undefined && overlay.additionalProperties === undefined) {
+            overlay.additionalProperties = schema.additionalProperties;
+        }
+        return overlay;
+    }
+    compareOverlayToBase(overlay, baseResolved, path) {
+        const errors = [];
+        const overlayProps = overlay.properties || {};
+        const baseProps = baseResolved.properties || {};
+        for (const [propName, propSchema] of Object.entries(overlayProps)) {
+            const propPath = path ? `${path}.${propName}` : propName;
+            // Property schema set to false
+            if (propSchema === false) {
+                if (baseProps[propName] !== undefined) {
+                    errors.push(`Property '${propPath}' is set to false but exists in base`);
+                }
+                continue;
+            }
+            const baseProp = baseProps[propName];
+            if (baseProp === undefined || baseProp === null) {
+                // New property not in base
+                if (baseResolved.additionalProperties === false) {
+                    errors.push(`Property '${propPath}' not in base and base has additionalProperties: false`);
+                }
+                continue;
+            }
+            if (baseProp === false) {
+                // Base already set property to false, overlay can't use it
+                errors.push(`Property '${propPath}' is forbidden in base`);
+                continue;
+            }
+            // Both base and overlay have this property — compare constraints
+            if (typeof propSchema === 'object' && propSchema !== null) {
+                errors.push(...this.comparePropertyConstraints(propSchema, baseProp, propPath));
+            }
+        }
+        // Check additionalProperties
+        if (baseResolved.additionalProperties === false) {
+            if (overlay.additionalProperties === true) {
+                errors.push('Cannot loosen additionalProperties from false to true');
+            }
+            else if (overlay.additionalProperties === undefined) {
+                errors.push('Base has additionalProperties: false but derived does not restate it');
+            }
+        }
+        return errors;
+    }
+    comparePropertyConstraints(derived, base, propPath) {
+        const errors = [];
+        if (typeof base !== 'object' || base === null) {
+            return errors;
+        }
+        // Type check
+        const baseType = base.type;
+        const derivedType = derived.type;
+        if (baseType !== undefined && derivedType !== undefined) {
+            if (Array.isArray(derivedType)) {
+                // Derived has array type — widening (fail)
+                if (!Array.isArray(baseType)) {
+                    errors.push(`Property '${propPath}' widens type from '${baseType}' to array`);
+                    return errors;
+                }
+            }
+            if (Array.isArray(baseType)) {
+                if (!Array.isArray(derivedType)) {
+                    // Could be narrowing from array type
+                    if (!baseType.includes(derivedType)) {
+                        errors.push(`Property '${propPath}' type '${derivedType}' not in base types [${baseType}]`);
+                        return errors;
+                    }
+                }
+            }
+            else if (!Array.isArray(derivedType)) {
+                // Both scalar types
+                if (baseType !== derivedType) {
+                    errors.push(`Property '${propPath}' type changed from '${baseType}' to '${derivedType}'`);
+                    return errors;
+                }
+            }
+        }
+        // Determine if the overlay adds any NEW constraint keywords not in the base.
+        // Under allOf semantics, base constraints are preserved. Drops are only flagged
+        // when the overlay doesn't introduce any new tightening constraints.
+        const CONSTRAINT_KEYWORDS = [
+            'maxLength',
+            'minLength',
+            'maximum',
+            'minimum',
+            'maxItems',
+            'minItems',
+            'enum',
+            'const',
+            'pattern',
+            'items',
+        ];
+        const baseConstraintKeys = new Set(CONSTRAINT_KEYWORDS.filter((kw) => base[kw] !== undefined));
+        const derivedConstraintKeys = new Set(CONSTRAINT_KEYWORDS.filter((kw) => derived[kw] !== undefined));
+        const hasNewConstraints = [...derivedConstraintKeys].some((kw) => !baseConstraintKeys.has(kw));
+        // Max constraints (tightening = lower value OK; loosening = higher value FAIL)
+        for (const kw of ['maxLength', 'maximum', 'maxItems']) {
+            if (base[kw] !== undefined) {
+                if (derived[kw] === undefined) {
+                    if (!hasNewConstraints) {
+                        errors.push(`Property '${propPath}' drops constraint '${kw}'`);
+                    }
+                }
+                else if (derived[kw] > base[kw]) {
+                    errors.push(`Property '${propPath}' loosens '${kw}' from ${base[kw]} to ${derived[kw]}`);
+                }
+            }
+        }
+        // Min constraints (tightening = higher value OK; loosening = lower value FAIL)
+        for (const kw of ['minLength', 'minimum', 'minItems']) {
+            if (base[kw] !== undefined) {
+                if (derived[kw] === undefined) {
+                    if (!hasNewConstraints) {
+                        errors.push(`Property '${propPath}' drops constraint '${kw}'`);
+                    }
+                }
+                else if (derived[kw] < base[kw]) {
+                    errors.push(`Property '${propPath}' loosens '${kw}' from ${base[kw]} to ${derived[kw]}`);
+                }
+            }
+        }
+        // Enum check
+        if (base.enum !== undefined) {
+            if (derived.enum === undefined) {
+                if (!hasNewConstraints) {
+                    errors.push(`Property '${propPath}' drops constraint 'enum'`);
+                }
+            }
+            else {
+                const baseSet = new Set(base.enum.map((v) => JSON.stringify(v)));
+                for (const val of derived.enum) {
+                    if (!baseSet.has(JSON.stringify(val))) {
+                        errors.push(`Property '${propPath}' enum value '${val}' not in base enum`);
+                    }
+                }
+            }
+        }
+        // Const check
+        if (base.const !== undefined) {
+            if (derived.const === undefined) {
+                if (!hasNewConstraints) {
+                    errors.push(`Property '${propPath}' drops constraint 'const'`);
+                }
+            }
+            else if (JSON.stringify(base.const) !== JSON.stringify(derived.const)) {
+                errors.push(`Property '${propPath}' const conflict: ${JSON.stringify(derived.const)} vs base ${JSON.stringify(base.const)}`);
+            }
+        }
+        // Check const in derived against base numeric constraints
+        if (derived.const !== undefined && typeof derived.const === 'number') {
+            if (base.minimum !== undefined && derived.const < base.minimum) {
+                errors.push(`Property '${propPath}' const ${derived.const} violates base minimum ${base.minimum}`);
+            }
+            if (base.maximum !== undefined && derived.const > base.maximum) {
+                errors.push(`Property '${propPath}' const ${derived.const} violates base maximum ${base.maximum}`);
+            }
+        }
+        // Pattern check
+        if (base.pattern !== undefined) {
+            if (derived.pattern === undefined) {
+                if (!hasNewConstraints) {
+                    errors.push(`Property '${propPath}' drops constraint 'pattern'`);
+                }
+            }
+            else if (base.pattern !== derived.pattern) {
+                errors.push(`Property '${propPath}' pattern changed from '${base.pattern}' to '${derived.pattern}'`);
+            }
+        }
+        // Items check (array items)
+        if (base.items !== undefined) {
+            if (derived.items === undefined) {
+                if (!hasNewConstraints) {
+                    errors.push(`Property '${propPath}' drops constraint 'items'`);
+                }
+            }
+            else if (typeof base.items === 'object' && typeof derived.items === 'object') {
+                errors.push(...this.comparePropertyConstraints(derived.items, base.items, `${propPath}.items`));
+            }
+        }
+        // Nested object: recursively compare
+        if (base.type === 'object' && derived.type === 'object') {
+            if (base.properties || derived.properties) {
+                const nestedOverlay = {
+                    properties: derived.properties || {},
+                    required: derived.required || [],
+                    additionalProperties: derived.additionalProperties,
+                };
+                const nestedBase = {
+                    properties: base.properties || {},
+                    required: base.required || [],
+                    additionalProperties: base.additionalProperties,
+                };
+                errors.push(...this.compareOverlayToBase(nestedOverlay, nestedBase, propPath));
+            }
+        }
+        return errors;
+    }
     getAttribute(gtsId, path) {
         const entity = this.get(gtsId);
         if (!entity) {