Module builtin_signatures 

Single source of truth for builtin function signatures used by the parser and runtime VM: identifier resolution, typo suggestions, return-type inference, static arity & per-arg type checks, runtime arity & type enforcement, and lint awareness all consult the registry through the lookup / is_builtin helpers.

Architecture

Historically every builtin lived in two places — its implementation + runtime registration in harn-vm/src/stdlib/*.rs, and a hand-written BuiltinSignature literal under signatures/*.rs here in the parser. Drift between the two was caught at test time but cost a 2-file tax per new builtin.

That two-sided system has been replaced by the #[harn_builtin] proc-macro (see harn-builtin-macros), which emits both the runtime handler registration AND the parser BuiltinSignature from a single annotated function. The vm crate aggregates them and installs them here at driver startup via harn_builtin_registry::install_builtin_signatures.

During migration the legacy static signatures::groups() tables remain as a fallback so unmigrated builtins still type-check. Lookups always consult installed entries first and fall through to the static tables; installed wins on name collisions. As modules port to #[harn_builtin] their entries move out of the static tables into the macro-emitted MODULE_BUILTINS slices. Once all signatures have migrated the static tables are deleted.

Structs

BuiltinMetadata

Public view of one builtin used by harn-lint and other crates that need just identifier + return-type hints (no parameter types).

BuiltinSignature

A complete, static description of one builtin: identifier, arity range, per-parameter types, generic type parameters, return type, and any where-clause bounds the type checker should enforce on call.

Param

One parameter slot inside a BuiltinSignature.

ShapeFieldDescriptor

Enums

Ty

const-friendly type IR used in builtin descriptors. Mirrors the runtime TypeExpr from harn-parser but is constructable in const position with no allocation. Convert to TypeExpr at the boundary via the parser-side Ty::to_type_expr helper.

Constants

TY_ANY

TY_BOOL

TY_BYTES

TY_BYTES_OR_NIL

bytes | nil.

TY_CLOSURE

TY_DICT

TY_DICT_OR_NIL

dict | nil.

TY_DURATION

TY_FLOAT

TY_INT

TY_INT_OR_NIL

int | nil.

TY_LIST

TY_NEVER

TY_NIL

TY_NUMBER

int | float.

TY_STRING

TY_STRING_OR_NIL

string | nil.

Traits

BuiltinSignatureExt

TyExt

Parser-side extension methods on Ty and BuiltinSignature that depend on the parser’s owned AST types (kept out of harn-builtin-meta so that crate stays dep-free).

Functions

builtin_return_type

Statically-known return type for name, materialized as a TypeExpr. Returns None for unknown names AND for builtins whose return type is genuinely dynamic (Ty::Any).

install_builtin_signatures

Install the process-global signature registry. Called once by the driver (CLI, LSP, lint, serve, dap) at startup. Test harnesses that build a Vm via harn_vm::stdlib::stdlib_probe_vm() inherit the install through that helper.

is_builtin

Is name a builtin known to the parser?

is_untyped_boundary_source

Returns true if this builtin produces an untyped/opaque value that should be validated before field access in strict types mode.

iter_builtin_metadata

Iterate over every builtin’s name and statically-known return-type strings. Used by harn-lint and other consumers that want a lightweight “what does this builtin return” view without bringing in the full type IR.

iter_builtin_names

Every builtin name. Installed names come first, then any static-only names that aren’t shadowed by installed entries. Output is NOT alphabetically sorted (callers that need that re-sort themselves).

lookup

Linear scan of the installed slice plus the static groups for a given name. Installed entries win when both sides carry the same name (the #[harn_builtin]-emitted signature shadows any legacy static duplicate). O(N+M) per call where N+M ≈ 600 — well below any typecheck hot path, and explicitly NOT cached so installs after the first call are picked up without leaking an old merged slice.

static_signature_names

Names that come only from the hand-written static fallback tables (signatures::groups()), independent of whatever the driver installed.

ty_to_type_expr

Convert a const-IR Ty into the parser’s owned TypeExpr. Generic references stay as Named(name) so the checker’s existing scope-based generic-param resolution applies.