flowgraph/tasks/analysis-type-compat.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
analysis/type-compat	Implement typeCompat function — deep structural schema compatibility checking	completed	schema/node-attrs schema/edge-attrs error/hierarchy setup/test-infrastructure	moderate	high	phase	implementation

Description

Implement the typeCompat function that performs deep recursive structural comparison between two TypeBox schemas to determine if an output schema is compatible with an input schema. This is the core of the operation graph's type-compatibility edge construction.

Acceptance Criteria

• typeCompat(outputSchema: TSchema, inputSchema: TSchema): TypeCompatResult — standalone function in src/analysis/type-compat.ts
• TypeCompatResult: { compatible: boolean; detail?: string; mismatches?: TypeMismatch[] }
• TypeMismatch: { path: string; expected: string; actual: string }
• Exact match → compatible: true
• Output is superset of input (output has extra fields beyond input requirements) → compatible: true
• Output is subset of input (output missing required fields) → compatible: false with mismatches
• Type mismatch at field level → compatible: false with mismatches at that path
• Either schema is Type.Unknown() → return nothing / undefined (no edge should be created, compatibility unknown)
• Handles: nested objects (recursive), arrays (element type comparison), optional fields, union types (subtype checking)
• Subtype checking: output must be at least as specific as input (string compatible with string|number, but NOT reverse)
• mismatches array provides JSON-path level diagnostics for incompatible results
• Unit tests: exact match, superset, subset, type mismatch, unknown passthrough, nested objects, arrays, unions, optional fields, complex realistic schemas

References

• docs/architecture/analysis.md — typeCompat contract, compatibility rules, depth of checking, subtype rules
• docs/architecture/schema.md — TypeCompatResult, TypeMismatch interfaces

Notes

To be filled by implementation agent

Summary

To be filled on completion