feature - Start v1.0 compiler middle-end foundation in v0.5

[dannymeijer]

Area

• Compiler (frontend/backend/codegen)
• Incan Language (syntax/semantics)
• Tooling (CLI/formatter/test runner)

Problem statement

Incan's current compiler pipeline still puts too much semantic and backend knowledge in the Rust-source backend path. Continuing to add new language features directly to that path increases migration debt for the v1.0 architecture: backend-neutral semantic facts, HIR, Body IR, ABI/package metadata, source-surface frontends, and eventually a rustc-IR backend.

The release timing makes v0.5 the right place to start this shift:

• v0.3 is effectively ready.
• v0.4 is focused on tooling stability and does not add much feature surface.
• v0.5 can begin pulling the v1.0 middle-end forward without blocking current backend compatibility.

The goal is not to stop shipping or immediately replace the Rust-source backend. The goal is to stop making the current backend the place where new semantic authority accumulates.

Proposed solution

Start a v0.5 compiler-middle-end foundation that can run alongside the existing backend and gradually become the semantic handoff for all future backends.

Target architecture:

source surface / AST
  -> stable compiler IDs
  -> Incan semantic facts
  -> Incan HIR
  -> Duckborrower ownership facts
  -> Incan Body IR
  -> ABI/package metadata
  -> backend consumers

Initial v0.5 work should focus on the first useful slice:

AST + current TypeCheckInfo
  -> stable ID model
  -> backend-neutral semantic facts DB
  -> Incan HIR v0
  -> HIR snapshots

Then follow with Body IR and Duckborrower facts once the stable-ID/HIR foundation is in place.

Design constraints:

• Keep the current Rust-source backend working during migration.
• Treat the Rust-source backend as a consumer/reference, not the semantic center.
• Do not start with direct rustc MIR/rustc-IR injection.
• Keep generated Rust out of public package/frontend compatibility paths.
• Ensure file-scoped vocab/dialect/frontend surfaces can lower into this same middle layer.
• Preserve the existing test corpus as a regression oracle.

Relevant research notes:

• __research__/incan-abi-and-rustc-ir-architecture-2026-05-22.md
• __research__/file-scoped-vocab-dialect-frontend-surfaces-2026-05-22.md

Alternatives considered

1. Continue adding new features directly to the current backend.

   This keeps short-term velocity, but it increases migration debt because new semantic behavior keeps landing in Rust-source lowering/emission paths.

2. Pause all feature work until the v1.0 backend exists.

   This is too broad. Bug fixes, diagnostics, tests, stdlib work, package metadata, and backend-neutral semantic improvements should continue.

3. Start with rustc-IR/MIR backend work immediately.

   This is too low-level too early. Without a stable Incan-owned HIR/Body IR, rustc integration would become the new semantic center instead of consuming Incan semantics.

Scope / acceptance criteria

In scope for v0.5:

• Define stable compiler IDs for declarations, expressions, statements, locals, and types.
• Introduce a backend-neutral semantic facts database keyed by those IDs.
• Introduce IncanType or an equivalent backend-neutral type model, initially bridged from current ResolvedType/IrType.
• Introduce Incan HIR v0 as a normalized, source-mapped representation.
• Add HIR snapshot tests for representative existing fixtures.
• Keep the current Rust-source backend working.
• Document the migration path from current TypeCheckInfo/AstLowering/IR into the new middle layer.

Possible stretch scope:

• Begin Body IR v0 for a small function subset.
• Add Duckborrower fact snapshots for copy/borrow/move/clone decisions.
• Add a backend adapter proving one current feature can lower through HIR/Body IR into the existing Rust-source backend.

Out of scope for this issue:

• Full rustc-IR backend.
• Direct MIR injection.
• Replacing the current Rust-source backend.
• Full source-surface frontend implementation for TypeScript/Python/Ruby/Go/Kotlin.
• Stable public ABI guarantees.

Done when:

• v0.5 has a tracked middle-end foundation rather than only more Rust-source backend behavior.
• The new representation can be generated for real Incan programs and snapshot-tested.
• The current backend remains green against the existing suite.
• Future feature work has a clear place to put semantic meaning before backend emission.