Skip to content

Incan feature inventory

Generated file

Do not edit this page by hand. If it looks wrong/outdated, update crates/incan_stdlib/stdlib/capabilities.incn and regenerate it.

Regenerate with: cargo run --features cli --bin generate_feature_inventory

This page is a generated, present-tense atlas of user-facing Incan capabilities. It is intentionally higher-level than the generated language vocabulary tables: one feature can span syntax, type checking, stdlib source, manifests, tooling, and examples.

Use it when deciding whether code should use an existing Incan surface before adding wrappers, Rust fallbacks, or project-local conventions.

Contents

All features

Feature Category Since Activation Canonical forms Summary Prefer over References
Namespaced stdlib imports and decorators Stdlib 0.2 Import the relevant std.* module. from std.testing import assert_eq
from std.web.routing import route
@route("/hello")		 Standard-library APIs and compiler-owned decorators resolve through explicit std.* module paths. Bare pre-0.2 stdlib names and ambient decorator magic. Imports and modules, Standard library, Release 0.2
Rust interop boundary Interop 0.2 Declare Rust dependencies in incan.toml; import through rust / rust:: paths. from rust import uuid
from rust::std::time import Instant
type UserId = rusttype i64		 Incan can import Rust crates, bind Rust paths, declare rusttype wrappers, and model explicit interop edges. Custom Rust backend modules used when ordinary Rust imports or wrappers are sufficient. Rust interop, Rust types for Python developers, Release 0.2
Checked C binding foundation Interop 0.5 Import c from std.interop, then declare a binding in the importing module. from std.interop import c
binding LibC:
unsafe: LibC.absolute(-7)		 Explicit C headers, scalar signatures, opaque resources, output positions, enum carriers, and plain layouts are verified before private generated C ABI calls. Unverified Rust wrappers, ambient header discovery, or string-based dynamic symbol lookup. std.interop, RFC 116, Release 0.5
Locked Oven interop requirements Interop 0.5 Declare target-specific [oven.interop] requirements in incan.toml, then run incan lock. [oven.interop]
[[oven.interop.targets]]
incan lock		 Package-owned headers, artifacts, system capabilities, and C/C++ shim sources are declared explicitly alongside toolchain and SDK compatibility requirements, then frozen in the semantic lock. Ambient host discovery, untracked interop source trees, or package manifests that claim a concrete local compiler or SDK has already been selected. Project configuration, Checked C bindings, std.interop, RFC 116
Incan libraries and pub:: imports Libraries 0.2 Build libraries with incan build --lib; consume dependencies through pub:: imports. from pub::mylib import my_module
from pub::mylib.my_module import my_function
pub from session import Session		 Projects publish checked APIs through explicit root facades and source-derived module namespaces. Copying source files between projects or relying on private module paths. Imports and modules, Release 0.2, Release 0.5
Module static storage Syntax 0.2 None. static hits: int = 0
pub static registry: dict[str, int] = {}		 static declares live module-owned runtime storage, distinct from deeply immutable const values. Module-level mutable state hidden behind ad hoc helper functions. Static storage, Module state, Release 0.2
First-class function references TypeSystem 0.2 None. handler: Callable[int, str] = label
callbacks = [on_success, on_error]
Mapper with Callable1[int, str]		 Named functions and closures can be passed, stored, typed, and accepted through CallableN bounds. Closures or wrappers whose only job is to pass through an existing named function. Functions and calls, Callable objects, Release 0.2, Release 0.5
Explicit call-site generics TypeSystem 0.2 None. decode_rows[Order, _](path)
session.read_csv[Order](path)		 Direct function and method calls can spell type arguments when inference needs help. Adding throwaway typed locals or duplicate helper functions only to steer inference. Derives and traits, Why call-site type arguments exist, Release 0.2
Abstract traits and supertraits TypeSystem 0.2 None. trait OrderedCollection[T] with Collection[T]:
def first(values: Collection[int]) -> int:		 Trait names are abstract annotation types, and traits can adopt supertraits with with. Hidden generic bounds or duplicated method requirements when a trait annotation names the concept. Derives and traits, Derives and traits explained
Source-defined derives and trait contracts TypeSystem 0.2 Import the relevant std.derives.*, std.traits.*, or derivable module. @derive(json)
model Row with Serialize:
T with Clone		 Derive and trait surfaces are authored as named stdlib capability contracts rather than compiler folklore. Backend-only helper shims or comments that claim derive behavior without source-visible contracts. Derives and traits, std.derives, std.traits
Model field metadata and reflection TypeSystem 0.2 None for field metadata; import std.reflection helpers when needed. name as "wire_name": str
user.__fields__()		 Model fields can carry aliases/descriptions and reflection exposes typed FieldInfo metadata. Stringly schema maps that duplicate model field names and wire aliases. Reflection, std.reflection, Release 0.2
Type tokens and type-argument reflection TypeSystem 0.3 Use explicit type arguments for compile-time reflection, or call an overload that expects Type[T]. T.__class_name__()
def cast(expr: ColumnExpr, target: Type[int]) -> IntColumnExpr:
def accepts_schema(value: Type[MySchema]) -> str:
cast(col("amount"), int)		 Primitive type arguments expose stable source names, model type tokens carry checked source type evidence, and expected Type[T] parameters let visible type names select precise overloads without making types general runtime values. String target names, dummy schema values, or helper families used only to recover type-specific return types. Reflection, std.reflection, RFC 107 north star, Release 0.3
Value enums TypeSystem 0.3 None. enum Level(str):
WARN = "WARN"
Level.from_value(raw)		 Enums can use str or int backing values while preserving enum type safety. Loose string/int constants or duplicate parsing helpers around enum-like values. Enums explained, Modeling with enums, Release 0.3
Union types and narrowing TypeSystem 0.3 None. value: int \| str
if isinstance(value, int):
match value:		 Closed anonymous unions support Union[A, B], A \| B, narrowing, and exhaustive match type patterns. Untyped Any-like values, parallel option fields, or manual tag/payload models for closed alternatives. Union types, Release 0.3
Validated newtypes and checked coercion TypeSystem 0.3 None. type UserId = newtype int[ge=0]:
Email.new(value)
@no_implicit_coercion		 Newtypes can validate primitive constraints and participate in checked construction/coercion. Raw primitives passed across APIs with comments describing expected invariants. Newtypes, Book: newtypes, Release 0.3
Exact numeric types and conversions TypeSystem 0.3 None. count: u32 = 1
price: decimal[12, 2] = 19.99d
small = value.try_resize()		 Exact integer widths, float widths, schema aliases, decimal precision/scale, and explicit resize policies are typed language surface. Using broad int/float at wire, Rust interop, binary, or schema boundaries where representation matters. Numeric semantics, Choosing numeric types, Release 0.3
loop: expressions and break values Syntax 0.3 None. result = loop:
break value		 Intentional infinite loops can produce values directly through break <value>. Mutable sentinel initialization followed by later branch assignment. Control flow, Book: control flow, Release 0.3
if let and while let Syntax 0.3 None. if let Some(value) = maybe:
while let Some(item) = iterator.next():		 Single-pattern control flow handles the common success-path case without full match scaffolding. Verbose one-arm match blocks where the non-match path intentionally does nothing. Control flow, Release 0.3
Pattern alternation Syntax 0.3 None. Status.Pending \| Status.Retrying => handle_waiting() match and if let patterns can share a branch across alternatives with compatible bindings. Duplicated branch bodies for variants that have the same behavior. Control flow, Release 0.3
Enum methods and trait adoption TypeSystem 0.3 None. enum Direction with Display:
def opposite(self) -> Direction:		 Enums can own methods, associated functions, and trait implementations directly in the enum body. Detached helper functions for behavior that belongs to a closed enum. Enums explained, Derives and traits, Release 0.3
Computed properties Syntax 0.3 None. property display_name -> str:
return self.first + " " + self.last		 Models, classes, and traits can expose field-like computed readers with property. Zero-argument methods when callers should read a value-like member. Computed properties, Models, Classes
Symbol, method, and variant aliases Syntax 0.3 None. pub average = alias avg
mean = avg
WARNING = alias WARN		 Aliases expose another resolved name for the same declaration, method, or enum variant without duplicating behavior. Wrapper functions or duplicated enum variants used only for compatibility names. Symbol aliases, Imports and modules, Release 0.3
Callable presets with partial Syntax 0.3 None. pub get = partial route(method="GET")
set_alive = partial set_state(state=true)		 partial creates a callable surface from an existing callable by supplying named preset values. Hand-written wrappers whose only job is to pass the same keyword defaults. Callable presets, Callable presets explained, Release 0.3
Rest parameters, unpacking, and spreads Syntax 0.3 None. def log(*items: str, **fields: str) -> None:
f(*xs, **kw)
[*prefix, item]
{**base, "x": 1}		 Functions can capture *args / **kwargs; calls and literals support typed unpack/spread forms. Manually spelling every forwarding arity or merging collections one element at a time. Functions and calls, Release 0.3
User-defined decorators Syntax 0.3 None for user-defined decorators; compiler-owned decorators keep their documented imports. @logged
@registered("catalog.ref")
func.__name__
@registered[(str) -> ColumnExpr]("catalog.ref")		 Decorators are ordinary callable values applied to functions and methods, including generic decorator factories that infer or accept the decorated function type and decorator helpers that expose func.__name__. Boilerplate wrapper declarations around every function that needs the same callable transform. Language reference, Derives and traits, Release 0.3
Generators Syntax 0.3 None. def numbers() -> Generator[int]:
yield value
(x * 2 for x in values)		 yield-based functions and generator expressions produce lazy Generator[T] values. Eager list construction when callers only need lazy iteration. Generators, Generators how-to, Release 0.3
Iterator adapters and terminal consumers Stdlib 0.3 Use iterator values. values.iter().map(parse).filter(valid).collect()
items.enumerate().take(10)
numbers.fold(0, add)		 Iterator pipelines expose lazy adapters and explicit terminal consumers. Manual loop accumulators for ordinary map/filter/fold pipeline shapes. Collection protocols, Release 0.3
Fallible iteration and combinators Stdlib 0.5 Import FallibleIterator from std.derives.collection or use a standard fallible stream. for item in stream?:
stream.map(transform).map_err(to_domain_error)
stream.collect()?		 Fallible streams separate exhaustion from typed poll errors and support lazy pipelines. Hand-written polling loops that duplicate item, exhaustion, and error routing for each source. Collection protocols, std.io, Fallible and infallible paths, Release 0.5
Result[T, E] combinators Stdlib 0.3 Use Result[T, E] values. result.map(transform)
result.and_then(validate)
result.inspect(log_success)		 Result values support branch-local transforms, fallible chaining, recovery, and inspection taps. Nested matches that only rewrap Ok / Err around one transformed branch. std.result, Fallible and infallible paths, Release 0.3
Protocol hooks for core syntax TypeSystem 0.3 Define compatible dunder hooks and adopt/document the corresponding trait vocabulary where useful. def __len__(self) -> int:
def __iter__(self) -> Iterator[T]:
def __call__(self, value: T) -> U:		 User-defined types can participate in truthiness, length, membership, iteration, indexing, assignment, and calls. Special-casing custom types in caller code instead of giving the type the expected protocol. Traits as language hooks, Collection protocols, Operators
Rust trait adoption from Incan Interop 0.3 Import the Rust trait metadata and adopt with with TraitName. type UserId = rusttype i64 with Display:
def fmt(self, f: Formatter) for Display -> Result[None, FmtError]:
type Output for Add[int] = UserId		 Newtype and rusttype declarations can author Rust trait impls with Incan adoption syntax. Writing Rust-shaped impl Trait for Type concepts in comments or custom backend code. Rust interop, Derives and traits, Release 0.3
Targeted generated-Rust lint suppression Interop 0.3 Use @rust.allow(...) on supported declarations. @rust.allow("dead_code")
def helper() -> None:		 Generated Rust can receive narrow lint suppressions on individual items when source semantics require them. Project-wide lint disables or broad generated-Rust allowance groups. Rust interop, Release 0.3
Scoped DSL surfaces Syntax 0.3 Import a vocab package that publishes scoped surface descriptors. query:
.field
\|>
sum(value)		 Library vocab crates can activate declaration, clause, glyph, leading-dot, and scoped symbol syntax inside their own DSL blocks. Global parser changes for syntax that only belongs to one imported DSL. Authoring vocab crates, Release 0.3
std.web hosted web framework Stdlib 0.2 Import from std.web or submodules such as std.web.routing. from std.web.routing import route
from std.web.response import Json
@route("/health")		 std.web provides hosted web app, routing, request, response, and macro surfaces with compiler-activated web runtime dependencies. Compiler-special-cased web wrappers or direct Axum wiring for ordinary hosted Incan web apps. Imports and modules, Web framework tutorial, Release 0.2
std.math numeric helpers Stdlib 0.2 Import std.math. import std.math
math.sqrt(9.0)
math.gcd(12, 18)
math.is_float_like("1.25e3")		 std.math provides mathematical constants, integer gcd/lcm helpers, floating-point functions, and numeric-string shape checks. Direct Rust math imports or project-local numeric string probes for ordinary numeric helper calls. std.math, Release 0.2
std.collections specialized containers Stdlib 0.3 Import from std.collections. from std.collections import Deque, Counter, PriorityQueue
queue = Deque[int]()		 Specialized containers cover deque, counter, default dict, ordered/sorted maps and sets, chain maps, and priority queues. Encoding specialized container behavior in plain list, dict, or set plus ad hoc helpers. std.collections, Choosing collections, Release 0.3
std.graph directed graph types Stdlib 0.3 Import from std.graph. from std.graph import DiGraph, Dag
graph = DiGraph[Task]()		 Graph types provide stable node/edge ids, DAG invariants, adjacency queries, traversal, and topological ordering. Hand-rolled adjacency maps for ordinary dependency, plan, or workflow graphs. std.graph, Release 0.3
std.fs filesystem APIs Stdlib 0.3 Import from std.fs or submodules such as std.fs.path. from std.fs import Path
Path("data").join("orders.csv")		 Path-centric filesystem APIs cover paths, files, metadata, traversal, globbing, copy/move/delete, durability syncs, and crash-safe publication through same-filesystem replacement, directory synchronization, and advisory locks. One-off Rust filesystem wrappers for ordinary path and file work. std.fs, File IO, RFC 055, RFC 112, Release 0.5
std.io in-memory binary streams Stdlib 0.3 Import from std.io. from std.io import BytesIO, Endian
stream.write(value, Endian.Little)
for chunk in stream.chunks(65536)?:		 Binary streams cover endian-aware I/O, cursors, delimiters, fallible chunks, and buffer extraction. Byte-twiddling helpers with unclear endian or cursor semantics. std.io, Release 0.3
std.regex safe-default regular expressions Stdlib 0.3 Import from std.regex. from std.regex import Regex
regex = Regex(r"\w+")?
regex.find_iter(text)		 std.regex provides compiled regular expressions, match spans, captures, splitting, and replacement through the predictable stdlib regex engine. Ad hoc string scans or direct Rust regex interop when the safe default stdlib engine is sufficient. std.regex, Regular expressions, RFC 059, Release 0.3
std.uuid UUID values Stdlib 0.3 Import from std.uuid. from std.uuid import UUID
UUID.parse("550e8400-e29b-41d4-a716-446655440000")?
UUID.v7()?		 std.uuid provides RFC 9562 UUID parsing, formatting, generation, byte and integer conversion, version inspection, and standard namespace constants. Loose UUID strings, byte arrays, or project-local UUID wrappers when UUID semantics belong in the type. std.uuid, Working with UUIDs, RFC 060, Release 0.3
std.compression codec workflows Stdlib 0.3 Import from std.compression or one of its codec namespaces. from std.compression import gzip, decompress_auto
gzip.compress(payload)?
zstd.decompress_stream(source, target)?		 std.compression provides codec-explicit compression and decompression for byte payloads, streams, and file handles, with explicit decompression autodetection. Backend-crate compression wrappers, implicit codec guesses, or ad hoc byte transforms for standard compression formats. std.compression, Compress and decompress data, RFC 061, Release 0.3
std.encoding binary-text encodings Stdlib 0.3 Import from std.encoding. from std.encoding import base64, hex
base64.urlsafe_b64encode(payload)
hex.decode(text)?		 std.encoding provides explicit binary-to-text encoding and strict decoding helpers for hex, base32, base58, base64, base85, and Bech32 formats. Project-local encoding wrappers, hidden alphabet flags, or guessing formats from payload shape. std.encoding, Binary-text encoding, RFC 064, Release 0.3
std.hash hashing primitives Stdlib 0.3 Import from std.hash. from std.hash import Sha256Hasher, sha256, file_digest
sink: Sha256Hasher = sha256.new()
sha256.digest(payload)
xxh3_64.new()		 std.hash provides deterministic byte, file, reader, and incremental hashing through explicit cryptographic, compatibility, and non-cryptographic algorithm namespaces. Sha256Hasher is a public stored-state handle for byte streams owned across model or class methods. Ad hoc hashing shims, hidden default algorithms, or std.checksum when the caller needs hash rather than checksum semantics. std.hash, Hashing data, RFC 065, Release 0.3, Release 0.5
std.environ runtime environment access Stdlib 0.5 Import from std.environ. from std.environ import get, get_optional, get_or, get_as
token = get("API_TOKEN")?
port = get_as[Port]("PORT", default=8080)?		 std.environ provides redacted, read-only Unicode environment access through string helpers and typed TryFrom[str] reads for primitives, explicit adopters, and validated newtypes. Direct rust::std::env imports or shell glue for ordinary runtime environment reads. std.environ, RFC 089, Release 0.5
std.json dynamic JSON values Stdlib 0.3 Import from std.json. from std.json import JsonValue
JsonValue.parse(source)
value["key"]
value[0]		 JsonValue provides dynamic parse-inspect-transform JSON workflows with checked optional indexing, explicit shape inspection, mutation helpers, traversal, and typed-model interop. Ad hoc dictionaries or over-modeled schemas for payloads whose shape is intentionally open. std.json, Derives: Serialization, Release 0.3
std.tempfile temporary resources Stdlib 0.3 Import from std.tempfile. NamedTemporaryFile.try_new()
TemporaryDirectory.try_new()
tmp.persist()		 Temporary files and directories are explicit resources with cleanup and persist semantics. Manual random path generation or unchecked cleanup around temporary files. std.tempfile, Release 0.3
std.datetime temporal values Stdlib 0.3 Import from std.datetime modules or prelude. Date.utc_today()
DateTime.utc_now()
TimeDelta(days=1)		 Temporal APIs cover runtime timing, civil dates/times, fixed offsets, parsing/formatting, intervals, and calendar arithmetic. Raw strings or integer timestamps inside code that has date/time semantics. std.datetime, Dates and times, Dates and times how-to
std.telemetry.core data model Stdlib 0.3 Import from std.telemetry.core or the std.telemetry prelude. from std.telemetry.core import TelemetryValue, Attributes
TelemetryValue.string("ready")
Attributes.from_string_fields(fields)		 Telemetry core provides structured values, attributes, resources, scopes, and trace context identifiers without configuring providers or exporters. Stringifying structured observability fields before they reach logging or telemetry boundaries. std.logging, Release 0.3
std.logging structured logging Stdlib 0.3 Import from std.logging; ambient log is available for the current module logger. from std.logging import Level, basic_config
log.info("started", fields={"component": "worker"})		 Structured logging includes levels, named loggers, bound fields, formatting, JSON rendering, and telemetry values. Printing diagnostic strings or routing ordinary application logging through custom Rust shims. std.logging, Release 0.3
std.checksum CRC32 helpers Stdlib 0.5 Import from std.checksum. from std.checksum import crc32
crc32.value(b"abc")
crc32.digest(b"abc")
h = crc32.new()		 std.checksum exposes CRC32 value, digest-byte, and incremental helpers for compatibility and accidental-corruption checks, separate from std.hash hashing contracts. Project-local Rust shims or std.hash helpers when a protocol explicitly requires CRC32 checksum semantics. std.checksum, Hashing data, RFC 065 checksum boundary, Release 0.5
Testing assertions and markers Testing 0.3 Use assert directly; import marker/helper APIs from std.testing. assert value == expected
assert call() raises ValueError
@parametrize("case", cases)		 Tests can use language assertions, raises checks, helper assertions, fixtures, parametrization, and marker decorators. Ad hoc panic helpers or external test metadata formats for ordinary Incan tests. std.testing, Testing how-to, Release 0.3
incan test runner Testing 0.3 Run incan test. module tests:
incan test --list
incan test --format json --junit report.xml		 The runner owns discovery, inline test modules, stable ids, selection, fixtures, parametrization, reporting, shuffling, and scheduling. Project-local scripts that duplicate core test discovery and reporting behavior. Tooling: testing, std.testing, Release 0.3
Async and await Async 0.2 Import std.async or one of its submodules. from std.async.time import sleep
async def main() -> None:
await sleep(1)		 async and await are import-activated soft-keyword surfaces backed by std.async modules. Threading async behavior through synchronous wrappers or relying on pre-0.2 ambient async syntax. Async programming, std.async, Release 0.2
Async race and awaitability Async 0.3 Import std.async.race or the relevant async prelude helpers. race for value:
arm(task)
race(arms)		 Awaitable[T], race for, and helper-style race composition support first-ready async workflows. Legacy std.async.select or hand-rolled polling loops. Awaitable trait, Async programming, Release 0.3
Project lifecycle tooling Tooling 0.3 Use incan init, incan new, incan version, or incan env. incan new greeter --yes
incan version patch
incan env run dev test		 Project commands create scaffolds, manage versions, and run configured environments from incan.toml. One-off project scaffolding scripts or manual version-file edits. Project lifecycle, Project lifecycle how-to, Release 0.3
Workspace and multi-package projects Tooling 0.5 Declare [workspace] in the repository root and inspect or select members through the CLI. incan workspace inspect --format json
incan test --workspace
incan build --member packages/api --report json		 Workspaces supply explicit rooted/virtual member topology, deterministic scope selection, explicit shared dependency and environment inheritance, one durable root lock, and member-scoped command reports. Ad hoc directory conventions, member-local locks, or implicit cross-project dependency activation. Project lifecycle, CLI reference, Release 0.5
Toolchain installer and release manifest Tooling 0.4 Use the GitHub Release installer, Homebrew formula, npm package, pipx package, or versioned toolchain manifest. curl -fsSL https://github.com/encero-systems/incan/releases/latest/download/install.sh \| bash
brew tap encero-systems/tap && brew install incan
npm install -g @incan/toolchain
pipx install incan		 The toolchain install path is manifest-driven, checksum-verified, and installs incan plus incan-lsp from the same release archives across direct and package-manager channels. Direct, npm, and pipx installation can provision stable Rust and wasm32-wasip1; Homebrew installs the prebuilt command binaries and leaves Rust management to the user. Treating Cargo, repository checkouts, and package-manager adapters as separate sources of install truth. Install and run, Release 0.4
Zero-clone starter project flow Tooling 0.4 Use incan new, then run project commands from the generated directory. incan new hello --yes
cd hello
incan run
incan test
incan build --release		 incan new creates a runnable, testable project with a manifest, entrypoint, starter test, README, .gitignore, and release-line toolchain constraint. Cloning the compiler repository or copying examples manually before a first run. Getting started, Project lifecycle, Release 0.4
Stable diagnostics commands Tooling 0.4 Use incan check or incan explain. incan check src/main.incn --format json
incan explain INCAN-T0001		 Type-check diagnostics can be emitted as versioned JSON with stable codes, source spans, and catalog-backed explanations. Scraping terminal diagnostics or building tool-specific error-code maps. CLI reference, Release 0.4
Build reports and generated Rust inspection Tooling 0.4 Use incan build --report json or incan inspect rust. incan build src/main.incn --report json
incan build --lib --report json --report-output build.json
incan inspect rust src/main.incn --format json		 Builds can emit versioned machine-readable reports, generated Rust can be inspected intentionally as current backend output, and generated public Rust items preserve checked source docstrings as Rust doc comments when available. Scraping terminal progress output or treating --emit-rust debug output as a stable artifact contract. CLI reference, Release 0.4
Build and test preheat observability Tooling 0.4 Use verbose test output or INCAN_RUST_INSPECT_TIMING=1 when build/test preheat timing needs to be inspected. incan test -v tests
INCAN_RUST_INSPECT_TIMING=1 incan build --lib
incan build --lib		 Build and test preheat paths report phase timing, Cargo target reuse, Rust metadata warmed/reused/skipped counts, vocab companion cache reuse, and cache split reasons. Silent long-running preheat phases or separate probes that do not share the real build/test cache policy. CLI reference, Release 0.4
Compiler-backed codegraph inspection Tooling 0.4 Use incan inspect codegraph. incan inspect codegraph src/main.incn --format jsonl
incan inspect codegraph src --format jsonl --allow-errors		 Incan-language source files, modules, declarations, imports, exports, body-level reference and call syntax, conservative resolved reference and call targets, containment, spans, provenance, language tags, degraded state, and diagnostics can be exported as deterministic JSONL records. Repeated grep/read loops or tool-specific source scrapers when agents and tooling need basic Incan structure. Codegraph inspection, CLI reference, Release 0.4
Checked API metadata Tooling 0.3 Use incan tools metadata api or LSP metadata commands. incan tools metadata api src/lib.incn
incan tools metadata model emit		 Typechecked public APIs can emit structured metadata for docs, manifests, hovers, and model bundle tooling. Scraping source text or generated Rust when tooling needs API contracts. Release 0.3, Project lifecycle
Compiled providers, SDK components, and package features Libraries 0.5 Select SDK components in [sdk]; select additive package features in manifests or with Incan feature flags. [sdk] profile = "minimal" components = ["stdlib-data"]
incan build --features json --sdk-profile minimal
when feature("json"): pub from json_support import JsonReport
incan inspect providers --format json		 Checked libraries and official SDK components resolve through one provider plan, while package-owned features project additive source and dependency facts without exposing Cargo features as Incan API. Hardcoded stdlib inventories, copied provider source, or Cargo feature names used as public package semantics. SDK components and package features, Conditional compilation, Project configuration, Release 0.5
Formatter spacing and wrapping contract Tooling 0.3 Run incan fmt. incan fmt src/main.incn
incan fmt --check		 Formatter output has explicit vertical-spacing buckets, docstring normalization, comment attachment, and common wrapping rules. Hand-maintained whitespace conventions that drift from the formatter. Code style, Formatting how-to, Release 0.3
std.registry typed declaration catalogues Stdlib 0.5 Import from std.registry and define a typed static registry. from std.registry import Registry, RegistryEntry, RegistrySubject, SubjectKind
@describe(functions, FunctionId("normalize"), FunctionDescriptor(...))
pub static capability: RegistryEntry[CapabilityId, CapabilityDescriptor] = capabilities.entry(key=CapabilityId("std.logging"), subject=RegistrySubject.current_unit(), descriptor=CapabilityDescriptor(...))		 Typed registries associate checked structural descriptors with declarations, compilation units, or packages while keeping complete inspection distinct from loaded runtime entries. Comment metadata blocks, source scanners, global registration side effects, or Rust-authored catalog facades. std.registry, RFC 113, Release 0.5

Feature details

Namespaced stdlib imports and decorators

  • Id: NamespacedStdlib
  • Category: Stdlib
  • Since: 0.2
  • RFC: RFC 022
  • Stability: Stable
  • Activation: Import the relevant std.* module.
  • Use instead of: Bare pre-0.2 stdlib names and ambient decorator magic.
  • References: Imports and modules, Standard library, Release 0.2

Standard-library APIs and compiler-owned decorators resolve through explicit std.* module paths.

Canonical forms:

  • from std.testing import assert_eq
  • from std.web.routing import route
  • @route("/hello")

Rust interop boundary

  • Id: RustInteropBoundary
  • Category: Interop
  • Since: 0.2
  • RFC: RFC 041
  • Stability: Stable
  • Activation: Declare Rust dependencies in incan.toml; import through rust / rust:: paths.
  • Use instead of: Custom Rust backend modules used when ordinary Rust imports or wrappers are sufficient.
  • References: Rust interop, Rust types for Python developers, Release 0.2

Incan can import Rust crates, bind Rust paths, declare rusttype wrappers, and model explicit interop edges.

Canonical forms:

  • from rust import uuid
  • from rust::std::time import Instant
  • type UserId = rusttype i64

Checked C binding foundation

  • Id: CheckedCBindingFoundation
  • Category: Interop
  • Since: 0.5
  • RFC: RFC 116
  • Stability: Experimental
  • Activation: Import c from std.interop, then declare a binding in the importing module.
  • Use instead of: Unverified Rust wrappers, ambient header discovery, or string-based dynamic symbol lookup.
  • References: std.interop, RFC 116, Release 0.5

Explicit C headers, scalar signatures, opaque resources, output positions, enum carriers, and plain layouts are verified before private generated C ABI calls.

Canonical forms:

  • from std.interop import c
  • binding LibC:
  • unsafe: LibC.absolute(-7)

Locked Oven interop requirements

  • Id: OvenInteropRequirements
  • Category: Interop
  • Since: 0.5
  • RFC: RFC 116
  • Stability: Experimental
  • Activation: Declare target-specific [oven.interop] requirements in incan.toml, then run incan lock.
  • Use instead of: Ambient host discovery, untracked interop source trees, or package manifests that claim a concrete local compiler or SDK has already been selected.
  • References: Project configuration, Checked C bindings, std.interop, RFC 116

Package-owned headers, artifacts, system capabilities, and C/C++ shim sources are declared explicitly alongside toolchain and SDK compatibility requirements, then frozen in the semantic lock.

Canonical forms:

  • [oven.interop]
  • [[oven.interop.targets]]
  • incan lock

Incan libraries and pub:: imports

  • Id: IncanLibraries
  • Category: Libraries
  • Since: 0.2
  • RFC: RFC 031
  • Stability: Stable
  • Activation: Build libraries with incan build --lib; consume dependencies through pub:: imports.
  • Use instead of: Copying source files between projects or relying on private module paths.
  • References: Imports and modules, Release 0.2, Release 0.5

Projects publish checked APIs through explicit root facades and source-derived module namespaces.

Canonical forms:

  • from pub::mylib import my_module
  • from pub::mylib.my_module import my_function
  • pub from session import Session

Module static storage

  • Id: StaticStorage
  • Category: Syntax
  • Since: 0.2
  • RFC: RFC 052
  • Stability: Stable
  • Activation: None.
  • Use instead of: Module-level mutable state hidden behind ad hoc helper functions.
  • References: Static storage, Module state, Release 0.2

static declares live module-owned runtime storage, distinct from deeply immutable const values.

Canonical forms:

  • static hits: int = 0
  • pub static registry: dict[str, int] = {}

First-class function references

Named functions and closures can be passed, stored, typed, and accepted through CallableN bounds.

Canonical forms:

  • handler: Callable[int, str] = label
  • callbacks = [on_success, on_error]
  • Mapper with Callable1[int, str]

Explicit call-site generics

Direct function and method calls can spell type arguments when inference needs help.

Canonical forms:

  • decode_rows[Order, _](path)
  • session.read_csv[Order](path)

Abstract traits and supertraits

  • Id: AbstractTraits
  • Category: TypeSystem
  • Since: 0.2
  • RFC: RFC 042
  • Stability: Stable
  • Activation: None.
  • Use instead of: Hidden generic bounds or duplicated method requirements when a trait annotation names the concept.
  • References: Derives and traits, Derives and traits explained

Trait names are abstract annotation types, and traits can adopt supertraits with with.

Canonical forms:

  • trait OrderedCollection[T] with Collection[T]:
  • def first(values: Collection[int]) -> int:

Source-defined derives and trait contracts

  • Id: SourceDefinedDerivesTraits
  • Category: TypeSystem
  • Since: 0.2
  • RFC: RFC 024
  • Stability: Stable
  • Activation: Import the relevant std.derives.*, std.traits.*, or derivable module.
  • Use instead of: Backend-only helper shims or comments that claim derive behavior without source-visible contracts.
  • References: Derives and traits, std.derives, std.traits

Derive and trait surfaces are authored as named stdlib capability contracts rather than compiler folklore.

Canonical forms:

  • @derive(json)
  • model Row with Serialize:
  • T with Clone

Model field metadata and reflection

  • Id: ModelFieldMetadata
  • Category: TypeSystem
  • Since: 0.2
  • RFC: RFC 021
  • Stability: Stable
  • Activation: None for field metadata; import std.reflection helpers when needed.
  • Use instead of: Stringly schema maps that duplicate model field names and wire aliases.
  • References: Reflection, std.reflection, Release 0.2

Model fields can carry aliases/descriptions and reflection exposes typed FieldInfo metadata.

Canonical forms:

  • name as "wire_name": str
  • user.__fields__()

Type tokens and type-argument reflection

  • Id: TypeTokensReflection
  • Category: TypeSystem
  • Since: 0.3
  • RFC: RFC 107
  • Stability: Stable
  • Activation: Use explicit type arguments for compile-time reflection, or call an overload that expects Type[T].
  • Use instead of: String target names, dummy schema values, or helper families used only to recover type-specific return types.
  • References: Reflection, std.reflection, RFC 107 north star, Release 0.3

Primitive type arguments expose stable source names, model type tokens carry checked source type evidence, and expected Type[T] parameters let visible type names select precise overloads without making types general runtime values.

Canonical forms:

  • T.__class_name__()
  • def cast(expr: ColumnExpr, target: Type[int]) -> IntColumnExpr:
  • def accepts_schema(value: Type[MySchema]) -> str:
  • cast(col("amount"), int)

Value enums

  • Id: ValueEnums
  • Category: TypeSystem
  • Since: 0.3
  • RFC: RFC 032
  • Stability: Stable
  • Activation: None.
  • Use instead of: Loose string/int constants or duplicate parsing helpers around enum-like values.
  • References: Enums explained, Modeling with enums, Release 0.3

Enums can use str or int backing values while preserving enum type safety.

Canonical forms:

  • enum Level(str):
  • WARN = "WARN"
  • Level.from_value(raw)

Union types and narrowing

  • Id: UnionTypes
  • Category: TypeSystem
  • Since: 0.3
  • RFC: RFC 029
  • Stability: Stable
  • Activation: None.
  • Use instead of: Untyped Any-like values, parallel option fields, or manual tag/payload models for closed alternatives.
  • References: Union types, Release 0.3

Closed anonymous unions support Union[A, B], A | B, narrowing, and exhaustive match type patterns.

Canonical forms:

  • value: int | str
  • if isinstance(value, int):
  • match value:

Validated newtypes and checked coercion

  • Id: ValidatedNewtypes
  • Category: TypeSystem
  • Since: 0.3
  • RFC: RFC 017
  • Stability: Stable
  • Activation: None.
  • Use instead of: Raw primitives passed across APIs with comments describing expected invariants.
  • References: Newtypes, Book: newtypes, Release 0.3

Newtypes can validate primitive constraints and participate in checked construction/coercion.

Canonical forms:

  • type UserId = newtype int[ge=0]:
  • Email.new(value)
  • @no_implicit_coercion

Exact numeric types and conversions

  • Id: NumericTypeSystem
  • Category: TypeSystem
  • Since: 0.3
  • RFC: RFC 009
  • Stability: Stable
  • Activation: None.
  • Use instead of: Using broad int/float at wire, Rust interop, binary, or schema boundaries where representation matters.
  • References: Numeric semantics, Choosing numeric types, Release 0.3

Exact integer widths, float widths, schema aliases, decimal precision/scale, and explicit resize policies are typed language surface.

Canonical forms:

  • count: u32 = 1
  • price: decimal[12, 2] = 19.99d
  • small = value.try_resize()

loop: expressions and break values

  • Id: LoopExpressions
  • Category: Syntax
  • Since: 0.3
  • RFC: RFC 016
  • Stability: Stable
  • Activation: None.
  • Use instead of: Mutable sentinel initialization followed by later branch assignment.
  • References: Control flow, Book: control flow, Release 0.3

Intentional infinite loops can produce values directly through break <value>.

Canonical forms:

  • result = loop:
  • break value

if let and while let

  • Id: IfWhileLet
  • Category: Syntax
  • Since: 0.3
  • RFC: RFC 049
  • Stability: Stable
  • Activation: None.
  • Use instead of: Verbose one-arm match blocks where the non-match path intentionally does nothing.
  • References: Control flow, Release 0.3

Single-pattern control flow handles the common success-path case without full match scaffolding.

Canonical forms:

  • if let Some(value) = maybe:
  • while let Some(item) = iterator.next():

Pattern alternation

  • Id: PatternAlternation
  • Category: Syntax
  • Since: 0.3
  • RFC: RFC 071
  • Stability: Stable
  • Activation: None.
  • Use instead of: Duplicated branch bodies for variants that have the same behavior.
  • References: Control flow, Release 0.3

match and if let patterns can share a branch across alternatives with compatible bindings.

Canonical forms:

  • Status.Pending | Status.Retrying => handle_waiting()

Enum methods and trait adoption

  • Id: EnumMethodsTraits
  • Category: TypeSystem
  • Since: 0.3
  • RFC: RFC 050
  • Stability: Stable
  • Activation: None.
  • Use instead of: Detached helper functions for behavior that belongs to a closed enum.
  • References: Enums explained, Derives and traits, Release 0.3

Enums can own methods, associated functions, and trait implementations directly in the enum body.

Canonical forms:

  • enum Direction with Display:
  • def opposite(self) -> Direction:

Computed properties

  • Id: ComputedProperties
  • Category: Syntax
  • Since: 0.3
  • RFC: RFC 046
  • Stability: Stable
  • Activation: None.
  • Use instead of: Zero-argument methods when callers should read a value-like member.
  • References: Computed properties, Models, Classes

Models, classes, and traits can expose field-like computed readers with property.

Canonical forms:

  • property display_name -> str:
  • return self.first + " " + self.last

Symbol, method, and variant aliases

  • Id: SymbolAliases
  • Category: Syntax
  • Since: 0.3
  • RFC: RFC 083
  • Stability: Stable
  • Activation: None.
  • Use instead of: Wrapper functions or duplicated enum variants used only for compatibility names.
  • References: Symbol aliases, Imports and modules, Release 0.3

Aliases expose another resolved name for the same declaration, method, or enum variant without duplicating behavior.

Canonical forms:

  • pub average = alias avg
  • mean = avg
  • WARNING = alias WARN

Callable presets with partial

partial creates a callable surface from an existing callable by supplying named preset values.

Canonical forms:

  • pub get = partial route(method="GET")
  • set_alive = partial set_state(state=true)

Rest parameters, unpacking, and spreads

  • Id: VariadicAndSpreadCalls
  • Category: Syntax
  • Since: 0.3
  • RFC: RFC 038
  • Stability: Stable
  • Activation: None.
  • Use instead of: Manually spelling every forwarding arity or merging collections one element at a time.
  • References: Functions and calls, Release 0.3

Functions can capture *args / **kwargs; calls and literals support typed unpack/spread forms.

Canonical forms:

  • def log(*items: str, **fields: str) -> None:
  • f(*xs, **kw)
  • [*prefix, item]
  • {**base, "x": 1}

User-defined decorators

  • Id: UserDefinedDecorators
  • Category: Syntax
  • Since: 0.3
  • RFC: RFC 036
  • Stability: Stable
  • Activation: None for user-defined decorators; compiler-owned decorators keep their documented imports.
  • Use instead of: Boilerplate wrapper declarations around every function that needs the same callable transform.
  • References: Language reference, Derives and traits, Release 0.3

Decorators are ordinary callable values applied to functions and methods, including generic decorator factories that infer or accept the decorated function type and decorator helpers that expose func.__name__.

Canonical forms:

  • @logged
  • @registered("catalog.ref")
  • func.__name__
  • @registered[(str) -> ColumnExpr]("catalog.ref")

Generators

  • Id: Generators
  • Category: Syntax
  • Since: 0.3
  • RFC: RFC 006
  • Stability: Stable
  • Activation: None.
  • Use instead of: Eager list construction when callers only need lazy iteration.
  • References: Generators, Generators how-to, Release 0.3

yield-based functions and generator expressions produce lazy Generator[T] values.

Canonical forms:

  • def numbers() -> Generator[int]:
  • yield value
  • (x * 2 for x in values)

Iterator adapters and terminal consumers

  • Id: IteratorAdapters
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 088
  • Stability: Stable
  • Activation: Use iterator values.
  • Use instead of: Manual loop accumulators for ordinary map/filter/fold pipeline shapes.
  • References: Collection protocols, Release 0.3

Iterator pipelines expose lazy adapters and explicit terminal consumers.

Canonical forms:

  • values.iter().map(parse).filter(valid).collect()
  • items.enumerate().take(10)
  • numbers.fold(0, add)

Fallible iteration and combinators

  • Id: FallibleIteration
  • Category: Stdlib
  • Since: 0.5
  • RFC: RFC 115
  • Stability: Stable
  • Activation: Import FallibleIterator from std.derives.collection or use a standard fallible stream.
  • Use instead of: Hand-written polling loops that duplicate item, exhaustion, and error routing for each source.
  • References: Collection protocols, std.io, Fallible and infallible paths, Release 0.5

Fallible streams separate exhaustion from typed poll errors and support lazy pipelines.

Canonical forms:

  • for item in stream?:
  • stream.map(transform).map_err(to_domain_error)
  • stream.collect()?

Result[T, E] combinators

  • Id: ResultCombinators
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 070
  • Stability: Stable
  • Activation: Use Result[T, E] values.
  • Use instead of: Nested matches that only rewrap Ok / Err around one transformed branch.
  • References: std.result, Fallible and infallible paths, Release 0.3

Result values support branch-local transforms, fallible chaining, recovery, and inspection taps.

Canonical forms:

  • result.map(transform)
  • result.and_then(validate)
  • result.inspect(log_success)

Protocol hooks for core syntax

  • Id: ProtocolHooks
  • Category: TypeSystem
  • Since: 0.3
  • RFC: RFC 068
  • Stability: Stable
  • Activation: Define compatible dunder hooks and adopt/document the corresponding trait vocabulary where useful.
  • Use instead of: Special-casing custom types in caller code instead of giving the type the expected protocol.
  • References: Traits as language hooks, Collection protocols, Operators

User-defined types can participate in truthiness, length, membership, iteration, indexing, assignment, and calls.

Canonical forms:

  • def __len__(self) -> int:
  • def __iter__(self) -> Iterator[T]:
  • def __call__(self, value: T) -> U:

Rust trait adoption from Incan

  • Id: RustTraitAdoption
  • Category: Interop
  • Since: 0.3
  • RFC: RFC 043
  • Stability: Stable
  • Activation: Import the Rust trait metadata and adopt with with TraitName.
  • Use instead of: Writing Rust-shaped impl Trait for Type concepts in comments or custom backend code.
  • References: Rust interop, Derives and traits, Release 0.3

Newtype and rusttype declarations can author Rust trait impls with Incan adoption syntax.

Canonical forms:

  • type UserId = rusttype i64 with Display:
  • def fmt(self, f: Formatter) for Display -> Result[None, FmtError]:
  • type Output for Add[int] = UserId

Targeted generated-Rust lint suppression

  • Id: RustAllow
  • Category: Interop
  • Since: 0.3
  • RFC: RFC 057
  • Stability: Stable
  • Activation: Use @rust.allow(...) on supported declarations.
  • Use instead of: Project-wide lint disables or broad generated-Rust allowance groups.
  • References: Rust interop, Release 0.3

Generated Rust can receive narrow lint suppressions on individual items when source semantics require them.

Canonical forms:

  • @rust.allow("dead_code")
  • def helper() -> None:

Scoped DSL surfaces

  • Id: ScopedDslSurfaces
  • Category: Syntax
  • Since: 0.3
  • RFC: RFC 040
  • Stability: Stable
  • Activation: Import a vocab package that publishes scoped surface descriptors.
  • Use instead of: Global parser changes for syntax that only belongs to one imported DSL.
  • References: Authoring vocab crates, Release 0.3

Library vocab crates can activate declaration, clause, glyph, leading-dot, and scoped symbol syntax inside their own DSL blocks.

Canonical forms:

  • query:
  • .field
  • |>
  • sum(value)

std.web hosted web framework

  • Id: StdWeb
  • Category: Stdlib
  • Since: 0.2
  • RFC: RFC 023
  • Stability: Stable
  • Activation: Import from std.web or submodules such as std.web.routing.
  • Use instead of: Compiler-special-cased web wrappers or direct Axum wiring for ordinary hosted Incan web apps.
  • References: Imports and modules, Web framework tutorial, Release 0.2

std.web provides hosted web app, routing, request, response, and macro surfaces with compiler-activated web runtime dependencies.

Canonical forms:

  • from std.web.routing import route
  • from std.web.response import Json
  • @route("/health")

std.math numeric helpers

  • Id: StdMath
  • Category: Stdlib
  • Since: 0.2
  • RFC: RFC 022
  • Stability: Stable
  • Activation: Import std.math.
  • Use instead of: Direct Rust math imports or project-local numeric string probes for ordinary numeric helper calls.
  • References: std.math, Release 0.2

std.math provides mathematical constants, integer gcd/lcm helpers, floating-point functions, and numeric-string shape checks.

Canonical forms:

  • import std.math
  • math.sqrt(9.0)
  • math.gcd(12, 18)
  • math.is_float_like("1.25e3")

std.collections specialized containers

  • Id: StdCollections
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 030
  • Stability: Stable
  • Activation: Import from std.collections.
  • Use instead of: Encoding specialized container behavior in plain list, dict, or set plus ad hoc helpers.
  • References: std.collections, Choosing collections, Release 0.3

Specialized containers cover deque, counter, default dict, ordered/sorted maps and sets, chain maps, and priority queues.

Canonical forms:

  • from std.collections import Deque, Counter, PriorityQueue
  • queue = Deque[int]()

std.graph directed graph types

  • Id: StdGraph
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 047
  • Stability: Stable
  • Activation: Import from std.graph.
  • Use instead of: Hand-rolled adjacency maps for ordinary dependency, plan, or workflow graphs.
  • References: std.graph, Release 0.3

Graph types provide stable node/edge ids, DAG invariants, adjacency queries, traversal, and topological ordering.

Canonical forms:

  • from std.graph import DiGraph, Dag
  • graph = DiGraph[Task]()

std.fs filesystem APIs

  • Id: StdFs
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 055
  • Stability: Stable
  • Activation: Import from std.fs or submodules such as std.fs.path.
  • Use instead of: One-off Rust filesystem wrappers for ordinary path and file work.
  • References: std.fs, File IO, RFC 055, RFC 112, Release 0.5

Path-centric filesystem APIs cover paths, files, metadata, traversal, globbing, copy/move/delete, durability syncs, and crash-safe publication through same-filesystem replacement, directory synchronization, and advisory locks.

Canonical forms:

  • from std.fs import Path
  • Path("data").join("orders.csv")

std.io in-memory binary streams

  • Id: StdIo
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 056
  • Stability: Stable
  • Activation: Import from std.io.
  • Use instead of: Byte-twiddling helpers with unclear endian or cursor semantics.
  • References: std.io, Release 0.3

Binary streams cover endian-aware I/O, cursors, delimiters, fallible chunks, and buffer extraction.

Canonical forms:

  • from std.io import BytesIO, Endian
  • stream.write(value, Endian.Little)
  • for chunk in stream.chunks(65536)?:

std.regex safe-default regular expressions

  • Id: StdRegex
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 059
  • Stability: Stable
  • Activation: Import from std.regex.
  • Use instead of: Ad hoc string scans or direct Rust regex interop when the safe default stdlib engine is sufficient.
  • References: std.regex, Regular expressions, RFC 059, Release 0.3

std.regex provides compiled regular expressions, match spans, captures, splitting, and replacement through the predictable stdlib regex engine.

Canonical forms:

  • from std.regex import Regex
  • regex = Regex(r"\w+")?
  • regex.find_iter(text)

std.uuid UUID values

  • Id: StdUuid
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 060
  • Stability: Stable
  • Activation: Import from std.uuid.
  • Use instead of: Loose UUID strings, byte arrays, or project-local UUID wrappers when UUID semantics belong in the type.
  • References: std.uuid, Working with UUIDs, RFC 060, Release 0.3

std.uuid provides RFC 9562 UUID parsing, formatting, generation, byte and integer conversion, version inspection, and standard namespace constants.

Canonical forms:

  • from std.uuid import UUID
  • UUID.parse("550e8400-e29b-41d4-a716-446655440000")?
  • UUID.v7()?

std.compression codec workflows

  • Id: StdCompression
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 061
  • Stability: Stable
  • Activation: Import from std.compression or one of its codec namespaces.
  • Use instead of: Backend-crate compression wrappers, implicit codec guesses, or ad hoc byte transforms for standard compression formats.
  • References: std.compression, Compress and decompress data, RFC 061, Release 0.3

std.compression provides codec-explicit compression and decompression for byte payloads, streams, and file handles, with explicit decompression autodetection.

Canonical forms:

  • from std.compression import gzip, decompress_auto
  • gzip.compress(payload)?
  • zstd.decompress_stream(source, target)?

std.encoding binary-text encodings

  • Id: StdEncoding
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 064
  • Stability: Stable
  • Activation: Import from std.encoding.
  • Use instead of: Project-local encoding wrappers, hidden alphabet flags, or guessing formats from payload shape.
  • References: std.encoding, Binary-text encoding, RFC 064, Release 0.3

std.encoding provides explicit binary-to-text encoding and strict decoding helpers for hex, base32, base58, base64, base85, and Bech32 formats.

Canonical forms:

  • from std.encoding import base64, hex
  • base64.urlsafe_b64encode(payload)
  • hex.decode(text)?

std.hash hashing primitives

  • Id: StdHash
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 065
  • Stability: Stable
  • Activation: Import from std.hash.
  • Use instead of: Ad hoc hashing shims, hidden default algorithms, or std.checksum when the caller needs hash rather than checksum semantics.
  • References: std.hash, Hashing data, RFC 065, Release 0.3, Release 0.5

std.hash provides deterministic byte, file, reader, and incremental hashing through explicit cryptographic, compatibility, and non-cryptographic algorithm namespaces. Sha256Hasher is a public stored-state handle for byte streams owned across model or class methods.

Canonical forms:

  • from std.hash import Sha256Hasher, sha256, file_digest
  • sink: Sha256Hasher = sha256.new()
  • sha256.digest(payload)
  • xxh3_64.new()

std.environ runtime environment access

  • Id: StdEnviron
  • Category: Stdlib
  • Since: 0.5
  • RFC: RFC 089
  • Stability: Stable
  • Activation: Import from std.environ.
  • Use instead of: Direct rust::std::env imports or shell glue for ordinary runtime environment reads.
  • References: std.environ, RFC 089, Release 0.5

std.environ provides redacted, read-only Unicode environment access through string helpers and typed TryFrom[str] reads for primitives, explicit adopters, and validated newtypes.

Canonical forms:

  • from std.environ import get, get_optional, get_or, get_as
  • token = get("API_TOKEN")?
  • port = get_as[Port]("PORT", default=8080)?

std.json dynamic JSON values

  • Id: StdJson
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 051
  • Stability: Stable
  • Activation: Import from std.json.
  • Use instead of: Ad hoc dictionaries or over-modeled schemas for payloads whose shape is intentionally open.
  • References: std.json, Derives: Serialization, Release 0.3

JsonValue provides dynamic parse-inspect-transform JSON workflows with checked optional indexing, explicit shape inspection, mutation helpers, traversal, and typed-model interop.

Canonical forms:

  • from std.json import JsonValue
  • JsonValue.parse(source)
  • value["key"]
  • value[0]

std.tempfile temporary resources

  • Id: StdTempfile
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 010
  • Stability: Stable
  • Activation: Import from std.tempfile.
  • Use instead of: Manual random path generation or unchecked cleanup around temporary files.
  • References: std.tempfile, Release 0.3

Temporary files and directories are explicit resources with cleanup and persist semantics.

Canonical forms:

  • NamedTemporaryFile.try_new()
  • TemporaryDirectory.try_new()
  • tmp.persist()

std.datetime temporal values

  • Id: StdDatetime
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 058
  • Stability: Stable
  • Activation: Import from std.datetime modules or prelude.
  • Use instead of: Raw strings or integer timestamps inside code that has date/time semantics.
  • References: std.datetime, Dates and times, Dates and times how-to

Temporal APIs cover runtime timing, civil dates/times, fixed offsets, parsing/formatting, intervals, and calendar arithmetic.

Canonical forms:

  • Date.utc_today()
  • DateTime.utc_now()
  • TimeDelta(days=1)

std.telemetry.core data model

  • Id: StdTelemetryCore
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 072
  • Stability: Stable
  • Activation: Import from std.telemetry.core or the std.telemetry prelude.
  • Use instead of: Stringifying structured observability fields before they reach logging or telemetry boundaries.
  • References: std.logging, Release 0.3

Telemetry core provides structured values, attributes, resources, scopes, and trace context identifiers without configuring providers or exporters.

Canonical forms:

  • from std.telemetry.core import TelemetryValue, Attributes
  • TelemetryValue.string("ready")
  • Attributes.from_string_fields(fields)

std.logging structured logging

  • Id: StdLogging
  • Category: Stdlib
  • Since: 0.3
  • RFC: RFC 072
  • Stability: Stable
  • Activation: Import from std.logging; ambient log is available for the current module logger.
  • Use instead of: Printing diagnostic strings or routing ordinary application logging through custom Rust shims.
  • References: std.logging, Release 0.3

Structured logging includes levels, named loggers, bound fields, formatting, JSON rendering, and telemetry values.

Canonical forms:

  • from std.logging import Level, basic_config
  • log.info("started", fields={"component": "worker"})

std.checksum CRC32 helpers

  • Id: StdChecksum
  • Category: Stdlib
  • Since: 0.5
  • RFC: RFC 065
  • Stability: Stable
  • Activation: Import from std.checksum.
  • Use instead of: Project-local Rust shims or std.hash helpers when a protocol explicitly requires CRC32 checksum semantics.
  • References: std.checksum, Hashing data, RFC 065 checksum boundary, Release 0.5

std.checksum exposes CRC32 value, digest-byte, and incremental helpers for compatibility and accidental-corruption checks, separate from std.hash hashing contracts.

Canonical forms:

  • from std.checksum import crc32
  • crc32.value(b"abc")
  • crc32.digest(b"abc")
  • h = crc32.new()

Testing assertions and markers

  • Id: TestingAssertions
  • Category: Testing
  • Since: 0.3
  • RFC: RFC 018
  • Stability: Stable
  • Activation: Use assert directly; import marker/helper APIs from std.testing.
  • Use instead of: Ad hoc panic helpers or external test metadata formats for ordinary Incan tests.
  • References: std.testing, Testing how-to, Release 0.3

Tests can use language assertions, raises checks, helper assertions, fixtures, parametrization, and marker decorators.

Canonical forms:

  • assert value == expected
  • assert call() raises ValueError
  • @parametrize("case", cases)

incan test runner

  • Id: TestRunner
  • Category: Testing
  • Since: 0.3
  • RFC: RFC 019
  • Stability: Stable
  • Activation: Run incan test.
  • Use instead of: Project-local scripts that duplicate core test discovery and reporting behavior.
  • References: Tooling: testing, std.testing, Release 0.3

The runner owns discovery, inline test modules, stable ids, selection, fixtures, parametrization, reporting, shuffling, and scheduling.

Canonical forms:

  • module tests:
  • incan test --list
  • incan test --format json --junit report.xml

Async and await

  • Id: AsyncAwait
  • Category: Async
  • Since: 0.2
  • RFC: RFC 023
  • Stability: Stable
  • Activation: Import std.async or one of its submodules.
  • Use instead of: Threading async behavior through synchronous wrappers or relying on pre-0.2 ambient async syntax.
  • References: Async programming, std.async, Release 0.2

async and await are import-activated soft-keyword surfaces backed by std.async modules.

Canonical forms:

  • from std.async.time import sleep
  • async def main() -> None:
  • await sleep(1)

Async race and awaitability

  • Id: AsyncRace
  • Category: Async
  • Since: 0.3
  • RFC: RFC 039
  • Stability: Stable
  • Activation: Import std.async.race or the relevant async prelude helpers.
  • Use instead of: Legacy std.async.select or hand-rolled polling loops.
  • References: Awaitable trait, Async programming, Release 0.3

Awaitable[T], race for, and helper-style race composition support first-ready async workflows.

Canonical forms:

  • race for value:
  • arm(task)
  • race(arms)

Project lifecycle tooling

  • Id: ProjectLifecycle
  • Category: Tooling
  • Since: 0.3
  • RFC: RFC 015
  • Stability: Stable
  • Activation: Use incan init, incan new, incan version, or incan env.
  • Use instead of: One-off project scaffolding scripts or manual version-file edits.
  • References: Project lifecycle, Project lifecycle how-to, Release 0.3

Project commands create scaffolds, manage versions, and run configured environments from incan.toml.

Canonical forms:

  • incan new greeter --yes
  • incan version patch
  • incan env run dev test

Workspace and multi-package projects

  • Id: WorkspaceMultiPackageProjects
  • Category: Tooling
  • Since: 0.5
  • RFC: RFC 077
  • Stability: Stable
  • Activation: Declare [workspace] in the repository root and inspect or select members through the CLI.
  • Use instead of: Ad hoc directory conventions, member-local locks, or implicit cross-project dependency activation.
  • References: Project lifecycle, CLI reference, Release 0.5

Workspaces supply explicit rooted/virtual member topology, deterministic scope selection, explicit shared dependency and environment inheritance, one durable root lock, and member-scoped command reports.

Canonical forms:

  • incan workspace inspect --format json
  • incan test --workspace
  • incan build --member packages/api --report json

Toolchain installer and release manifest

  • Id: ToolchainInstallerManifest
  • Category: Tooling
  • Since: 0.4
  • RFC: RFC 015
  • Stability: Stable
  • Activation: Use the GitHub Release installer, Homebrew formula, npm package, pipx package, or versioned toolchain manifest.
  • Use instead of: Treating Cargo, repository checkouts, and package-manager adapters as separate sources of install truth.
  • References: Install and run, Release 0.4

The toolchain install path is manifest-driven, checksum-verified, and installs incan plus incan-lsp from the same release archives across direct and package-manager channels. Direct, npm, and pipx installation can provision stable Rust and wasm32-wasip1; Homebrew installs the prebuilt command binaries and leaves Rust management to the user.

Canonical forms:

  • curl -fsSL https://github.com/encero-systems/incan/releases/latest/download/install.sh | bash
  • brew tap encero-systems/tap && brew install incan
  • npm install -g @incan/toolchain
  • pipx install incan

Zero-clone starter project flow

  • Id: ZeroCloneStarterFlow
  • Category: Tooling
  • Since: 0.4
  • RFC: RFC 015
  • Stability: Stable
  • Activation: Use incan new, then run project commands from the generated directory.
  • Use instead of: Cloning the compiler repository or copying examples manually before a first run.
  • References: Getting started, Project lifecycle, Release 0.4

incan new creates a runnable, testable project with a manifest, entrypoint, starter test, README, .gitignore, and release-line toolchain constraint.

Canonical forms:

  • incan new hello --yes
  • cd hello
  • incan run
  • incan test
  • incan build --release

Stable diagnostics commands

  • Id: StableDiagnostics
  • Category: Tooling
  • Since: 0.4
  • RFC: RFC 015
  • Stability: Stable
  • Activation: Use incan check or incan explain.
  • Use instead of: Scraping terminal diagnostics or building tool-specific error-code maps.
  • References: CLI reference, Release 0.4

Type-check diagnostics can be emitted as versioned JSON with stable codes, source spans, and catalog-backed explanations.

Canonical forms:

  • incan check src/main.incn --format json
  • incan explain INCAN-T0001

Build reports and generated Rust inspection

  • Id: BuildReportsAndRustInspection
  • Category: Tooling
  • Since: 0.4
  • RFC: RFC 015
  • Stability: Stable
  • Activation: Use incan build --report json or incan inspect rust.
  • Use instead of: Scraping terminal progress output or treating --emit-rust debug output as a stable artifact contract.
  • References: CLI reference, Release 0.4

Builds can emit versioned machine-readable reports, generated Rust can be inspected intentionally as current backend output, and generated public Rust items preserve checked source docstrings as Rust doc comments when available.

Canonical forms:

  • incan build src/main.incn --report json
  • incan build --lib --report json --report-output build.json
  • incan inspect rust src/main.incn --format json

Build and test preheat observability

  • Id: BuildTestPreheatObservability
  • Category: Tooling
  • Since: 0.4
  • RFC: RFC 015
  • Stability: Stable
  • Activation: Use verbose test output or INCAN_RUST_INSPECT_TIMING=1 when build/test preheat timing needs to be inspected.
  • Use instead of: Silent long-running preheat phases or separate probes that do not share the real build/test cache policy.
  • References: CLI reference, Release 0.4

Build and test preheat paths report phase timing, Cargo target reuse, Rust metadata warmed/reused/skipped counts, vocab companion cache reuse, and cache split reasons.

Canonical forms:

  • incan test -v tests
  • INCAN_RUST_INSPECT_TIMING=1 incan build --lib
  • incan build --lib

Compiler-backed codegraph inspection

  • Id: CodegraphInspection
  • Category: Tooling
  • Since: 0.4
  • RFC: RFC 106
  • Stability: Stable
  • Activation: Use incan inspect codegraph.
  • Use instead of: Repeated grep/read loops or tool-specific source scrapers when agents and tooling need basic Incan structure.
  • References: Codegraph inspection, CLI reference, Release 0.4

Incan-language source files, modules, declarations, imports, exports, body-level reference and call syntax, conservative resolved reference and call targets, containment, spans, provenance, language tags, degraded state, and diagnostics can be exported as deterministic JSONL records.

Canonical forms:

  • incan inspect codegraph src/main.incn --format jsonl
  • incan inspect codegraph src --format jsonl --allow-errors

Checked API metadata

  • Id: CheckedApiMetadata
  • Category: Tooling
  • Since: 0.3
  • RFC: RFC 048
  • Stability: Stable
  • Activation: Use incan tools metadata api or LSP metadata commands.
  • Use instead of: Scraping source text or generated Rust when tooling needs API contracts.
  • References: Release 0.3, Project lifecycle

Typechecked public APIs can emit structured metadata for docs, manifests, hovers, and model bundle tooling.

Canonical forms:

  • incan tools metadata api src/lib.incn
  • incan tools metadata model emit

Compiled providers, SDK components, and package features

  • Id: CompiledProvidersSdkComponentsPackageFeatures
  • Category: Libraries
  • Since: 0.5
  • RFC: RFC 114
  • Stability: Stable
  • Activation: Select SDK components in [sdk]; select additive package features in manifests or with Incan feature flags.
  • Use instead of: Hardcoded stdlib inventories, copied provider source, or Cargo feature names used as public package semantics.
  • References: SDK components and package features, Conditional compilation, Project configuration, Release 0.5

Checked libraries and official SDK components resolve through one provider plan, while package-owned features project additive source and dependency facts without exposing Cargo features as Incan API.

Canonical forms:

  • [sdk] profile = "minimal" components = ["stdlib-data"]
  • incan build --features json --sdk-profile minimal
  • when feature("json"): pub from json_support import JsonReport
  • incan inspect providers --format json

Formatter spacing and wrapping contract

  • Id: FormatterContract
  • Category: Tooling
  • Since: 0.3
  • RFC: RFC 053
  • Stability: Stable
  • Activation: Run incan fmt.
  • Use instead of: Hand-maintained whitespace conventions that drift from the formatter.
  • References: Code style, Formatting how-to, Release 0.3

Formatter output has explicit vertical-spacing buckets, docstring normalization, comment attachment, and common wrapping rules.

Canonical forms:

  • incan fmt src/main.incn
  • incan fmt --check

std.registry typed declaration catalogues

  • Id: StdRegistry
  • Category: Stdlib
  • Since: 0.5
  • RFC: RFC 113
  • Stability: Experimental
  • Activation: Import from std.registry and define a typed static registry.
  • Use instead of: Comment metadata blocks, source scanners, global registration side effects, or Rust-authored catalog facades.
  • References: std.registry, RFC 113, Release 0.5

Typed registries associate checked structural descriptors with declarations, compilation units, or packages while keeping complete inspection distinct from loaded runtime entries.

Canonical forms:

  • from std.registry import Registry, RegistryEntry, RegistrySubject, SubjectKind
  • @describe(functions, FunctionId("normalize"), FunctionDescriptor(...))
  • pub static capability: RegistryEntry[CapabilityId, CapabilityDescriptor] = capabilities.entry(key=CapabilityId("std.logging"), subject=RegistrySubject.current_unit(), descriptor=CapabilityDescriptor(...))