Release 0.4¶

Incan 0.4 is the release that turns the compiler from something you mostly evaluate from a checkout into something you can install, try, inspect, and wire into tooling. The release direction is intentionally narrow:

0.3 made real programs credible. 0.4 makes the stack tryable.

That means 0.4 does not reopen broad language or runtime scope. It focuses on the first-contact path around the compiler: install the toolchain, create a project, run it, test it, understand diagnostics, inspect generated artifacts, export compiler facts for tools and agents, and keep import/package/vocab boundary regressions from leaking downstream again.

If you are looking for the previous release story, start with Release 0.3. For current 0.4 user docs, start with Install and run Incan, Getting started with Incan, the CLI reference, Codegraph inspection, and the generated feature inventory.

What 0.4 is about¶

The release is built around a practical evaluator workflow rather than a new language headline.

Install and first run: A release manifest, checksum-verified toolchain installer, Rust backend provisioning, Homebrew formula generation, npm and pip thin installers, and a zero-clone starter project make Incan usable without cloning the compiler repository first (#428, #553, #551).
Diagnostics and reports: incan check, JSON diagnostics, incan explain, build reports, and generated Rust inspection give tools stable contracts instead of scraping terminal prose (#589, #590, #591, #567).
Semantic inspection: incan inspect codegraph exports compiler-backed JSONL records for source files, modules, declarations, imports, exports, syntax-level references and calls, conservative checked target ids, diagnostics, spans, provenance, and degraded-state facts (#666, #778, #770, RFC 102, RFC 106).
Performance and observability: Test/build preheat phases now report visible timing, cache hits or misses, Rust metadata reuse, and Cargo target information so long dependency work is measurable instead of silent (#707, #723, #697, #769).
Boundary parity: Compact fixtures exercise provider/facade/consumer packages, dependency-owned unions, decorated aliases, partial presets, dependency vocab, formatter/test-batch paths, and generated Rust ownership before downstream packages rediscover those bugs (#760, #699, #753).
Release discipline: The 0.4 notes, roadmap, RFC template, and feature inventory are kept current while the work lands, instead of being reconstructed at release freeze (#223, #554, #592).

Migrating from 0.3¶

Most 0.3 source programs should keep compiling. The main changes are new commands and contributor-facing layout changes.

Use incan check for new tooling. The existing --check FILE spelling remains compatible, but incan check <file|dir> --format text|json is the canonical command for check-only workflows and machine-readable diagnostics (#589).
Use incan explain for stable diagnostic help. Diagnostic codes such as INCAN-T0001 can be explained through the catalog instead of relying on terminal output text (#590).
Use incan build --report json for build metadata. Build reports are the stable place for generated project paths, artifact paths, timing, dependency summaries, package metadata, and partial-report notes (#591).
Use incan inspect rust instead of treating --emit-rust as a product surface. Generated Rust remains inspectable current backend output, but it is not a stable Rust ABI contract (#567).
Use incan inspect codegraph for source-structure facts. The 0.4 graph export is Incan-language JSONL only. First-class Rust graph records, MCP serving, Architect findings, and task context packing remain follow-up layers on the RFC 106 parent tracker (#573), while the shipped 0.4 slice is tracked by #778.
For contributors, auxiliary workspaces moved under workspaces/. Release packaging now lives under workspaces/release, VS Code/Cursor extension tooling under workspaces/ide/vscode, and repository benchmarks under workspaces/benchmarks.

Feature guide¶

Use this section as the release map. Each feature names the user-facing entry point, links to the docs that carry the detail, and keeps issue/RFC references close to the relevant behavior.

Install and first contact¶

Toolchain installer and release manifest: The public install path is a GitHub Release-backed manifest that selects a host archive, provisions stable Rust through rustup when needed, ensures wasm32-wasip1, verifies checksums, installs incan and incan-lsp, and records the Rust backend policy used by packages with vocab companions. Start with Install and run Incan and the feature inventory entry (#428, #551, RFC 015).
Homebrew, npm, and pip adapters: Homebrew formula generation, @incan/toolchain npm packaging, and incan pip/pipx packaging are thin adapters over the same toolchain manifest and archive contract. npm and pipx delegate to the shared installer and can provision Rust automatically; Homebrew installs the prebuilt command binaries and expects Rust to be managed separately (#428).
Zero-clone starter flow: incan new hello --yes, incan run, incan test, and incan build --release now form the first-contact project path with a manifest, entrypoint, starter test, README, .gitignore, and release-line requires-incan constraint. Read Getting started with Incan, Your first project, and Project lifecycle (#553, #551, RFC 015).
First-contact positioning docs: The docs now connect install, quickstart, Python/Rust comparisons, and Encero-stack positioning so a new evaluator can understand what 0.4 is good for and what is deliberately not in scope. Read Encero stack, Incan vs Python, and Incan vs Rust (#551, #554).

Diagnostics and reports¶

Canonical incan check: incan check <file|dir> --format text|json is the stable check-only command. JSON output includes schema version, code, severity, phase, message, primary span, notes, hints, and source text facts where available, while human text remains the default. The legacy --check FILE spelling remains for compatibility. Read the CLI reference (#589, RFC 015).
Diagnostic explanations: incan explain <CODE> [--format text|json] is backed by a catalog instead of ad hoc CLI prose. The first catalog covers broad parser, typechecker, import/tooling, and compiler fallback codes; more precise frontend/backend code families belong to the later semantic-inspection and diagnostic-enrichment work. Read the CLI reference (#590, #666).
Build reports: incan build ... --report json and incan build --lib --report json can emit versioned build reports to stdout or --report-output <path>. Reports include compiler version, profile, entrypoint or library root, generated Rust path, artifact paths, package metadata, dependency summaries, interop summary, timing, and partial-report notes. Read the CLI reference (#591, RFC 015).
Generated Rust inspection: incan inspect rust <file|project> [--lib] [--format text|json] promotes generated Rust inspection from a debug flag to an intentional tooling surface. Public emitted Rust items preserve checked Incan docstrings as Rust doc comments when available, and the docs state clearly that generated Rust is current backend output rather than a stable Rust ABI. Read Generated Rust quality and the CLI reference (#567, RFC 015).

Semantic inspection and codegraph export¶

Semantic-inspection baseline: incan check --format json, incan build --report json, incan inspect rust --format json, and incan inspect codegraph --format jsonl now form a coherent 0.4 inspection plane. They are separate focused commands, but they share schema-version expectations, compiler-version reporting, project/source identity, artifact breadcrumbs, and explicit diagnostics or degraded-state records where their scopes overlap (#567, #666, RFC 102).
Compiler-backed codegraph inspection: incan inspect codegraph <path> --format jsonl exports deterministic records for Incan source files, modules, top-level declarations, imports, public exports, syntax-level body references, syntax-level body calls, conservative resolved reference and call targets, containment, diagnostics, source spans, provenance, language tags, and degraded state. Read Codegraph inspection, RFC 106, and RFC 102 (#778, #666, #770).
Strict and tolerant graph modes: Strict mode fails when parse/import/typecheck diagnostics exist for the checked entrypoint or directory. --allow-errors emits parseable facts plus diagnostic records and marks the export degraded, which is useful for WIP packages and agent context but not for clean release gates (#778).
Clear boundary with runtime graph APIs: incan inspect codegraph is tooling output about source structure. It is not std.graph, not a graph database, not a resolved call graph, and not generated-Rust ABI. Runtime graph APIs remain documented under std.graph; richer graph consumers are tracked as follow-up RFC 106 work (#573, #666).

Performance and observability¶

Visible test and build phases: Verbose test runs now show generated-harness planning, package/dependency preparation, preheat timing, Cargo target directories, Cargo execution timing, and cache hit/miss reasons. Ordinary output stays quieter, but long-running preheat work is no longer silent (#707, #723).
Generated-library preheat alignment: incan build --lib preheats generated-library dependencies into the same release-profile Cargo target directory as the real generated library build, so unchanged lock/profile/target inputs can reuse warmed artifacts instead of compiling into a separate preheat domain (#697).
Shared generated Cargo target and vocab cache: incan build --generated-cargo-target-dir <path> makes the generated-project Cargo target explicit instead of relying only on INCAN_GENERATED_CARGO_TARGET_DIR, and unchanged vocab companion metadata/desugarer artifacts are cached by companion input fingerprint beside that shared target. This reduces cold clean-checkout rebuilds for downstream packages without pretending external Rust dependencies never need to compile (#769).
Rust metadata prewarm reuse: rust_inspect prewarm now reports warmed, reused, and skipped metadata items, loads persisted disk-cache state before deciding to extract, and exposes cache split reasons through INCAN_RUST_INSPECT_TIMING=1 so cold-path work can be measured without pulling heavyweight downstream dependencies into the Incan regression suite (#769).
Measured downstream proof lanes: IncQL remains the main heavy downstream proof lane for preheat/runtime behavior, but 0.4 keeps the regression suite synthetic and compact so Incan does not need heavyweight downstream dependencies in core tests (#707, #723, #697).

Boundary parity and symbol identity¶

Compact boundary parity fixtures: The new fixture suite models provider → facade → consumer APIs, decorated callable aliases, partial presets, dependency-owned unions, public helper calls, dependency vocab, formatter/test-batch parsing, and generated Rust ownership. This is the 0.4 answer to the 0.3 RC failure pattern where features worked locally but broke across import/package boundaries (#760).
Unified symbol identity across boundaries: Public import resolution and backend method lookup reuse checked API metadata where manifest aliases point through facades, keeping provider-owned identity attached to the original declaration instead of reconstructing a second answer from stale manifest-only surfaces (#699).
Partial presets in const metadata: Model-constructor partials can materialize const metadata values when preset and call-site arguments are named and const-valid, including FrozenStr/str compatibility for metadata builder presets (#753).
Rust interop generic constructors: Rust associated function calls with explicit receiver type arguments now place the turbofish on the receiver type, while ordinary associated calls keep their existing Type::method(...) shape (#806, #807).

Compiler correctness and interop hardening¶

Rust Result interop in check/build paths: incan check and incan build now prepare the same Rust metadata workspace before typechecking direct Rust calls, and stable std::fs free-function signatures are available even when sysroot crates are not rust-inspect workspace dependencies. This keeps source-level ? working for calls such as std::fs::metadata(...) that return std::io::Result<T> (#801).
Contextual float literals in generated Rust: Float literals now emit as inferable Rust literals instead of hard-suffixed f64 tokens, so contexts such as value: f32 = 0.0 and calls to f32 Rust APIs compile without source-level casts or helper wrappers (#802).
Patched WASI runtime dependency line: The embedded Wasmtime/WASI stack moves to the patched 45.0.3 line for RUSTSEC-2026-0188, which raises the compiler repository MSRV from Rust 1.92 to Rust 1.93. The public installer still provisions current stable Rust by default.

Contributor and release infrastructure¶

RFC inspectability prompts: The RFC template now asks authors to name metadata/artifact, command, diagnostic, provenance, and generated-output/report consequences early, so inspectability is part of design instead of a post-hoc tooling pass (#592).
Workspace consolidation: Release packaging, IDE tooling, and benchmarks now live under workspaces/release, workspaces/ide/vscode, and workspaces/benchmarks. The root stays more focused on compiler crates, examples, tests, scripts, and project-level automation.
Generated feature inventory stays current: 0.4 feature entries are present in the generated feature inventory, including install, starter, diagnostics, build reports/Rust inspection, build/test preheat observability, and codegraph inspection (#223, #554).

Issue traceability¶

The items below connect the public release story to the GitHub scope. They are grouped by user-facing capability.

Release direction and docs discipline¶

#223: 0.4 umbrella for the tooling, inspection, installer, starter, and first-contact release.
#554: release direction notes and explicit exclusions.
#592: RFC inspectability prompts for metadata, commands, diagnostics, provenance, generated output, and reports.

Install and first contact¶

#428: canonical toolchain installer and release manifest.
#553: zero-clone starter project flow.
#551: first-contact quickstart and positioning docs.

Diagnostics and reports¶

#589: stable machine-readable diagnostics through incan check.
#590: diagnostic explanation catalog through incan explain.
#591: build artifact reports.
#567: generated Rust inspection tooling and quality gates.

Semantic inspection and codegraph export¶

#666: RFC 102 semantic inspection umbrella.
#778: RFC 106 first slice for compiler-backed codegraph JSONL export.
#770: compiler-proven codegraph reference and call targets.

Performance and observability¶

#707: visible prewarm/progress behavior for long-running build and test phases.
#723: test runner progress/performance observability.
#697: generated-library dependency preheat alignment when timing evidence justifies it.
#769: rust-inspect cold prewarm timing, cache reuse, and cache split explanation.

Boundary parity and symbol identity¶

#760: compact boundary parity fixture suite.
#699: unified symbol identity across local/import/reexport/package/test/vocab/generated-Rust boundaries.
#753: partial presets constructing const metadata values.
#806: Rust interop receiver-side turbofish placement for generic associated constructors.

Compiler correctness and interop hardening¶

#801: direct Rust Result interop calls keep usable return typing for source-level ? across incan check and incan build.
#802: contextual f32 float literals emit inferable Rust literals instead of hard-coded f64 literals.

RFCs and design references¶

Implemented or extended in 0.4¶

RFC 015: Project lifecycle tooling is extended with the installed-toolchain starter path, release-build spelling, stable check/report/inspect command surfaces, and installer-oriented docs.
RFC 102: Semantic inspection becomes a release-organizing constraint for diagnostics, reports, generated artifacts, provenance, and graph facts.
RFC 106: The first compiler-backed codegraph slice ships as incan inspect codegraph <path> --format jsonl.

Existing RFCs carried forward by 0.4 tooling¶

RFC 048: Checked API metadata remains the source of truth for public API identity where boundary parity, generated reports, and downstream consumers need provider-owned facts.
RFC 053: Formatter behavior remains part of the tooling contract, including dependency-vocab formatting and expression-position vocab blocks from the 0.3 stabilization work.
RFC 084: RHS partial callable presets are extended by the 0.4 const-metadata path for metadata builder presets.

Explicitly not implemented in 0.4¶

RFC 037 std.web redesign and RFC 066 std.http implementation work are future release lanes, not part of this release.
RFC 097 Rust-hosted caller/ABI architecture is a later backend and integration concern.
Source-local feature metadata beyond maintaining the generated feature inventory is not part of 0.4.
Hees.ai, IncQL, Pallay, Omerus, and Hees.io product implementation are downstream proof lanes only; they are not Incan 0.4 product scope.

Known limitations¶

The 0.4 toolchain installer ships macOS arm64, macOS x86_64, and Linux x86_64 archives. Native Windows and Linux arm64 are not part of the initial toolchain installer; use WSL2 or a source build for those hosts for now.
Direct, npm, and pipx installation provision the Rust backend through rustup unless explicitly skipped. Homebrew is the exception: the generated formula installs the prebuilt Incan commands and leaves Rust management to the user because a formula should not silently bootstrap rustup into a home directory.
Homebrew, npm, and pip are thin toolchain installers over the same release manifest. They are not independent compiler builds, and they depend on the GitHub Release assets being published correctly.
The 0.4 diagnostics catalog starts with broad phase-level codes. More precise codes, structured expected/actual facts, and richer related spans belong to the later diagnostic and semantic-inspection work rather than this first stable CLI surface.
The 0.4 codegraph export emits Incan-language facts only. It can populate conservative reference.target_id and call.target_id values for compiler-proven source declarations, but whole-program call graph precision, first-class Rust records, MCP tools, task-ranked context packs, process-risk signals, and Architect findings remain follow-up RFC 106 work tracked by #573 and #771-#777.
Generated Rust remains inspectable backend output, not a stable ABI. Public compatibility should be based on Incan source, manifests, checked metadata, documented reports, and CLI schemas.