Backend behavior inventory¶
This inventory classifies compiler, stdlib and runtime behavior for backend replacement: the behavior categories and their migration decisions, the evidence lanes that prove a behavior, the repository anchors for each boundary, the backend-foundation artifacts, the behavior matrix, the hosted-runtime assumptions, and the classified Rust boundary behavior. Why the inventory exists is explained in Rust-source backend deprecation; reviewing a change against it is described in Auditing generated Rust.
Categories¶
| Category | Meaning | Migration decision |
|---|---|---|
| Supported language contract | Behavior documented or intentionally exposed as source-level Incan semantics. | Preserve through stable IDs, semantic facts, HIR, Body IR, diagnostics, or authored user docs. |
| Stdlib/runtime behavior | Behavior owned by a component's facet under loaves/stdlib/<component>/rust, loaves/kernel/incan_lang, or .incn stdlib source. |
Preserve as stdlib/runtime contract, and record runtime-service requirements explicitly. |
| Rust interop behavior | Behavior that crosses rust:: imports, rust-inspect metadata, Rust callable boundaries, or generated Cargo projects. |
Preserve where documented, but move identity, call planning, and coercion decisions out of emitter guesses. |
| Generated-artifact behavior | Behavior visible mainly through generated Rust shape, generated Cargo manifests, or target/incan/** layout. |
Keep useful inspection, but replace semantic authority with HIR/facts/ABI metadata. |
| Diagnostic behavior | Error/warning codes, spans, JSON schema facts, and text diagnostics. | Preserve user-facing clarity; move expected/actual/source facts into stable diagnostics when possible. |
| Accidental accepted behavior | Behavior that a parser, typechecker or lowering path accepts without a documented contract. | Either document and test it as supported or reject it with a clear diagnostic. |
| Bug-compatible behavior | Behavior preserved for a workaround users may rely on, or whose fix requires a larger migration. | Record the owning issue and removal condition; it is not promoted to architecture. |
Evidence lanes¶
| Lane | Evidence examples | What it proves |
|---|---|---|
| Direct parser/typechecker tests | loaves/compiler/incan_frontend/src/** unit tests, diagnostics tests, parser snapshots. |
Source acceptance/rejection and diagnostic shape. |
| Codegen snapshots | loaves/compiler/incan_emit/tests/codegen_snapshot_tests.rs, loaves/compiler/incan_emit/tests/snapshots/**. |
Generated Rust shape and emitter obligations. |
| Generated-project runs | Integration tests, stdlib runtime tests, smoke tests. | Rust compile/runtime behavior, generated Cargo/project layout, runtime helper availability. |
| Package/import boundaries | Package consumer fixtures, facade/reexport tests, checked API metadata tests. | Public identity, imports, aliases, defaults, and dependency-owned type behavior. |
| Vocab/test-batch lanes | Vocab desugarer tests, formatter/test-runner activation paths. | File-scoped activation and generated helper behavior outside ordinary direct builds. |
| Downstream proof lanes | IncQL or Hees.ai acceptance runs when the surface is exercised there. | Cross-repo behavior and installed-SDK assumptions that synthetic fixtures may miss. |
Test-level counterpart¶
The test corpus inventory is this inventory's test-level counterpart: it gives every Rust test and .incn fixture root a disposition (keep, re-point, retire, unaffected) by what it proves and how. For the evidence lane a row of the behavior matrix names, it states which tests in that lane are kept untouched, which are re-pointed at the replacement route, and which retire with the emitter.
Representative repo anchors¶
| Boundary | Existing anchors |
|---|---|
| Parser, syntax, and diagnostics | loaves/kernel/incan_syntax/src/parser/tests/, loaves/compiler/incan_test_support/fixtures/valid/**, loaves/compiler/incan_test_support/fixtures/invalid/**, loaves/compiler/incan_emit/tests/construction_diagnostics_tests.rs, loaves/toolchain/incan-cli/tests/cli_surface_tests.rs, loaves/toolchain/incan-cli/src/commands/diagnostics.rs. |
| Code generation snapshots | loaves/compiler/incan_emit/tests/codegen_snapshot_tests.rs, loaves/compiler/incan_emit/tests/codegen_snapshots/**, loaves/compiler/incan_emit/tests/snapshots/codegen_snapshot_tests__*.snap. |
| Generated projects and public artifacts | loaves/compiler/incan_driver/tests/generated_rust_artifact_tests.rs, loaves/compiler/incan_driver/tests/generated_rust_audit_tests.rs, loaves/compiler/incan_driver/tests/generated_rust_callability_artifact_tests.rs, loaves/compiler/incan_driver/tests/generated_rust_native_consumer_tests.rs, loaves/compiler/incan_driver/tests/fixtures/generated_rust_artifacts/**, loaves/compiler/incan_driver/tests/fixtures/generated_rust_callability/**, loaves/compiler/incan_driver/tests/fixtures/generated_rust_native_consumer/**. |
| Package, import, facade, and checked API identity | loaves/compiler/incan_test_support/fixtures/boundary_parity/README.md, loaves/compiler/incan_driver/tests/generated_rust_callability_artifact_tests.rs, workspaces/docs-site/docs/tooling/reference/checked_api_metadata.md. |
| Stdlib and runtime surface | loaves/compiler/incan_emit/tests/stdlib_generated_rust_snapshot_tests.rs, loaves/toolchain/incan-cli/tests/std_encoding_algorithm_modules.rs, loaves/compiler/incan_test_support/fixtures/valid/std_*_surface.incn, workspaces/docs-site/docs/contributing/reference/generated_rust_stdlib_coverage.md. |
| Rust interop | loaves/compiler/incan_emit/tests/codegen_snapshots/rfc041_rust_coercions.incn, loaves/compiler/incan_emit/tests/codegen_snapshots/rfc041_interop_into_via.incn, loaves/compiler/incan_emit/tests/codegen_snapshots/rust_interop_associated_functions.incn, loaves/compiler/incan_emit/tests/codegen_snapshots/rust_interop_field_access.incn, loaves/compiler/incan_emit/tests/codegen_snapshots/rfc043_imported_trait_associated_type.incn, examples/pro/rust_interop_pro.incn, workspaces/docs-site/docs/language/how-to/rust_interop.md. |
| Vocab and desugaring | loaves/toolchain/incan-cli/tests/vocab_guardrails.rs, loaves/compiler/incan_emit/tests/codegen_snapshots/vocab_block_desugaring.incn, loaves/compiler/incan_emit/tests/codegen_snapshot_tests.rs (inline helper-backed desugaring case), examples/pro/vocab_studiokit/**, examples/pro/vocab_querykit/**, examples/pro/vocab_routekit/**. |
| Inspection and reports | workspaces/docs-site/docs/tooling/reference/codegraph_inspection.md, workspaces/docs-site/docs/tooling/reference/checked_api_metadata.md, workspaces/docs-site/docs/language/reference/feature_inventory.md. |
Backend-foundation artifacts¶
These artifacts are compiler-facing.
| Artifact | Meaning | Boundary |
|---|---|---|
CompilerNodeId |
Stable compiler-owned identity for a package, module, declaration, statement, expression, local, or type. | IDs are semantic, not emitted Rust paths. |
SemanticFactStore |
Deterministic store of facts about compiler-owned subjects: each fact has a CompilerNodeId subject, a SemanticFactKind and a value. |
Fact kinds: type, symbol target, symbol identity, declaration identity, reference owner, stable declaration context, reference span, required member owner, required reference target, registry, runtime requirement, diagnostic, backend obligation, and authority decision. |
IncanType |
Backend-neutral type vocabulary independent of Rust spelling. | Used for semantic type facts and ABI v0 hooks; it is compiler-facing and not a stable public ABI. |
| ABI v0 type facts | Conservative identity, ownership, runtime requirements, representation, and reserved target/runtime slots (layout, repr, alignment, no-std availability, panic strategy, allocator, target profile, runtime layer) for semantic types. | Records unknowns explicitly; it does not promise layout or target compatibility. |
HirModule |
Declaration-level HIR v0: a module's declarations with source spans, an optional type-fact subject and an optional canonical identity. | Holds declarations only. |
SemanticModuleSnapshot |
Bundled HIR plus semantic facts for one module. | Produced by CompilationSession; codegraph reads checked source-target facts from it. |
Behavior matrix¶
| Behavior | Category | Evidence | Migration owner | Decision |
|---|---|---|---|---|
| Source syntax accepted/rejected by parser and lexer. | Supported language contract / accidental accepted behavior. | Parser tests, formatter tests, language reference. | Stable IDs, HIR v0. | Preserve documented syntax; add diagnostics for accidental accepted syntax. |
| Typechecker overload, trait, callable, union, and generic decisions. | Supported language contract. | Typechecker tests, checked API metadata tests, package fixtures. | Semantic facts database, IncanType, HIR v0. |
Preserve decisions as frontend-owned facts instead of re-deriving them in lowering/emission. |
| Ownership and duckborrowing decisions for calls, returns, matches, and interop boundaries. | Supported language contract / generated-artifact behavior. | Codegen snapshots, generated-project runs, issue-specific regressions. | Duckborrower facts, Body IR. | Preserve intended source semantics; avoid adding local .clone(), .into(), or .as_ref() emitter patches without a migration note. |
| Generated Rust layout for user projects. | Generated-artifact behavior. | Generated Rust snapshots, CLI build/report tests. | Backend preparation and artifact plan. | Keep inspectable layout, but do not define source semantics by emitted Rust shape. |
Checked std.* providers and generated Rust support in consumer projects. |
Stdlib/runtime behavior / generated-artifact behavior. | Provider-plan, component-profile, package-feature, artifact, and generated-Rust regressions. | Session-owned provider plan and implementation facets. | Keep module authority in checked provider manifests; generated projects may link provider artifacts but must not rediscover semantics from source or Cargo features. |
| CLI diagnostics and machine-readable reports. | Diagnostic behavior. | CLI integration tests, JSON output tests, the CLI reference. | Diagnostics schema and semantic facts. | Preserve schema compatibility where documented; add richer stable facts without binding to generated Rust internals. |
| Rust method/associated function call planning. | Rust interop behavior. | Rust interop codegen snapshots, rust-inspect metadata tests. | Semantic facts, call planning, Rust boundary metadata. | Preserve documented interop; move receiver/type-arg/coercion identity out of emitter-only heuristics. |
| Vocab-generated helper calls. | Supported language contract. | Vocab tests and package consumer fixtures. | Stable IDs, HIR, semantic facts. | Preserve helper identity and public API metadata across desugarer output. |
Hosted-runtime assumptions¶
The Rust-source backend and the stdlib assume a hosted Rust std environment in these places:
| Assumption | Examples | Migration owner |
|---|---|---|
| Filesystem access | std.fs, toolchain cache, generated project emission, diagnostics source loading. |
Runtime-service metadata, target profiles. |
| Process/environment access | CLI commands, toolchain installer, std.environ, release scripts. |
Runtime-service metadata, target profiles. |
| Default allocator | Collections, strings, generated project runtime, many stdlib helpers. | ABI v0 hooks, IncanType, allocator policy. |
| Panic behavior | Generated panic hooks, test runner, runtime helper failures. | ABI v0 hooks, panic-strategy metadata. |
| Threads/async runtime | LSP, async stdlib, task/channel/sync helpers. | Runtime-service metadata, std.async contracts. |
| Native target availability | Toolchain installer, generated Cargo projects, rust-inspect workspaces. | SDK/toolchain metadata, target profiles. |
| Rust stdlib and third-party crates | rust:: imports, stdlib runtime facades, generated Cargo manifests. |
Rust interop metadata, package/dependency facts. |
Rust boundary classification¶
| Behavior | Category | Owner | Decision |
|---|---|---|---|
At a Rust boundary, the pointer-sized numeric types isize and usize match the same spelling exactly; no numeric type widens to or from a pointer-sized type. |
Rust interop behavior. | The shared coercion matrix (loaves/kernel/incan_lang/src/interop/coercions.rs) and the frontend Rust-boundary matcher (rust_arg_matches_boundary). |
Preserve; regression coverage sits at both the shared coercion matrix and the frontend Rust-boundary matcher. |