design: define initial HIR and monomorphization boundary

[vycdev2]

Summary

Define the first backend-neutral contract between Jett's checked program and jett_hir, including how concrete generic function instantiations are discovered, identified, deduplicated, and represented before MIR lowering.

Source documentation

• docs/progress.md — Phase D: Code Generation
• docs/architecture.md — Phase 7: High-Level IR
• docs/architecture.md — Expression Type Checking
• docs/architecture.md — Phase D implementation plan
• docs/design.md — Generics

Current state

Phase D is documented as not started, and the workspace has no jett_hir crate. The typechecker checks concrete generic function bodies on demand and interns generic struct instances, but its public CheckResult exposes only diagnostics, a span-to-type map, the type interner, and reflection metadata. The architecture describes HIR as consuming a TypedTree, but no such checked representation currently exists.

The tree-walking interpreter separately substitutes generic arguments while executing the source AST. Existing generic tests therefore validate parsing, checking, and interpretation, not a canonical monomorphization manifest or HIR lowering boundary.

Scope

This is a design and staging issue. It includes:

• choosing the canonical checked-program representation consumed by HIR, whether that is a typed tree or a smaller checked AST plus compiler-owned maps;
• defining stable function and concrete-instantiation identities, including discovery, deduplication, recursion, source spans, resolved parameter/return types, and invalid-call behavior;
• defining the minimal initial HIR function/expression representation and which phase owns method resolution, desugaring, implicit views/copyability, and checked reflection metadata;
• specifying how generic reflection specialization and trusted stdlib provenance cross the boundary without duplicating the policies tracked by design: define reflection predicate facts for generic specialization #6 and design: define module imports and trusted stdlib origins #3;
• splitting implementation into independently testable stages with deterministic HIR snapshots or equivalent structural tests.

It does not include MIR/CFG lowering, definitive MIR ownership verification, optimization, LLVM/native code generation, a runtime library, interpreter bytecode, or changing current source-language semantics. It also does not require implementing the full HIR before the boundary is accepted.

Acceptance criteria

• A concrete checked-program-to-HIR input contract is recorded and reconciles the documented TypedTree with the typechecker's actual outputs.
• Canonical generic-instantiation discovery, identity, ordering, deduplication, recursion, and diagnostic behavior are specified.
• The initial HIR data model and ownership of the Phase 7 transformations are defined without moving language policy into backend-specific code.
• Reflection facts and trusted stdlib origin have explicit handoff points coordinated with design: define reflection predicate facts for generic specialization #6 and design: define module imports and trusted stdlib origins #3.
• Staged implementation units and focused structural/snapshot tests are identified for multiple concrete instantiations, repeated calls, nested generic calls, constraints, methods, and rejected calls.
• docs/design.md, docs/architecture.md, and docs/progress.md are updated to match the accepted boundary and status.
• The originating planning docs remain in place and reflect the issue's final status.

Dependencies / open questions

• design: define module imports and trusted stdlib origins #3 owns module identity and trusted stdlib provenance; the HIR contract should consume, not redefine, that decision.
• design: define reflection predicate facts for generic specialization #6 owns any expansion of reflection-predicate specialization; HIR must preserve accepted checker facts without making arbitrary booleans into type proofs.
• Should the first implementation expose a public typechecker instantiation manifest before introducing the jett_hir crate, or should both land as one vertical slice?

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.