---
id: analysis/type-compat
name: Implement typeCompat function — deep structural schema compatibility checking
status: completed
depends_on:
  - schema/node-attrs
  - schema/edge-attrs
  - error/hierarchy
  - setup/test-infrastructure
scope: moderate
risk: high
impact: phase
level: 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