17. The standard library at a glance

Client networking is deadline-bounded by default: net.connect!, tls.connect!, and the one-shot HTTP helpers use one absolute 60-second budget across resolution, connection, TLS negotiation, request write, and response read. The net and tls modules expose connect_with_deadline!; full TCP/TLS streams and http.Client expose set_deadline!. Expiry is the typed TimedOut case at each face, including the transport-independent HttpError.TimedOut. See §4 for reset and immediate-poll semantics.

Hanki's libraries form four tiers along two distribution mechanisms. The mechanism settles a tier's other properties: two questions that could be answered separately are made to coincide, is it part of the language? and is it baked into the compiler?, and that splits the four tiers in two.

• Baked: compiled into the compiler binary, and into the stdlib_baked.bin archive, through include_str!. This is the language's own surface. → core, extra.
• Packages: resolved by the package manager, versioned with independent SemVer, and pure Hanki only. → contrib, universe.

A third, stricter line sits inside the baked half: the native @intrinsic seam is confined to core alone, and neither extra nor any package may cross it. The package manager covers all three tiers, with transitive universe-dependency resolution, contrib-tier resolution from the toolchain's seeded source, local path deps, the resolve, add and publish CLI verbs, and the effect-growth gate on top (§21). Only the hosted registry is unimplemented. This section fixes their model.

The baked tiers, core and extra, are the language's own curated surface, core locked and extra evolving. Their module names are flat, with no path prefix at import sites, and the directory their source sits in names the tier. A flat name is a claim on the one namespace user code shares (§14): a baked log means no project may have a log.hk, and adding a baked module is a source-breaking change, announced with the name it claims. That is the cost of extra being the evolving tier, and the reason its name list is pinned in a test in place of growing with whoever adds a file. They compile into one artifact, and core and extra share a single version, the toolchain and language version. The tier difference is the bump policy on it: a breaking change is a major bump for core and a minor bump for extra, one notch looser, while additions are minor and fixes patch. The package tiers, contrib and universe, are not part of the language. They never enter the compiler binary or its baked archive, they have their own independent SemVer, being distributed separately so that versioning granularity tracks the mechanism, and the native seam is closed to them, statically enforced; see The boundary, locked. universe is a provisional name for the decentralized tier, and the final name is deferred.

stdlib_baked.bin is one fingerprinted, framed artifact with three independently encoded payload sections: the semantic type index, lowered bytecode seed and qualified stdlib AST. Its fixed-width header records the HANKIBAK magic, the compiler's wire-schema revision, the stdlib-source fingerprint and the section count; the ordered section table records each payload's kind, absolute offset and byte length. The whole outer frame is validated before any section is exposed. The index section has its own HANKIIDX frame: each semantic side table is a sorted array of fixed-width Span or NodeId keys and 32-bit offsets into separately postcard-encoded values. A lookup binary-searches those borrowed keys and decodes and caches only the value it reaches; misses decode nothing. The bytecode and qualified-AST sections are postcard-decoded and cached only on the first accessor that needs them. A stale or structurally invalid outer frame makes every accessor take the full-source fallback. A malformed inner index frame or postcard failure inside an outer frame already accepted as the compiler's committed include_bytes! artifact is corruption and a hard invariant failure, never permission to mix one baked payload with freshly qualified or lowered source.

Tier 1: core

A locked surface. A breaking change in any of these cascades into every program, and promotion or demotion takes a decision ticket. Opened by convention.

The general index surface is int. Every persistent-collection length, byte and element offset, and count returns and accepts the lowercase scripting-default int: List and bytes length/get, slices, find, split pieces, BytesReader.take!, position! and remaining!, serializer count headers, and each_with_index!'s index. Unsuffixed literals and int loop counters therefore compose with no conversions (xs.get(i + 1), 0 seeds), and there is no platform cap on sizes. An index that is out of range, beyond i64, or an in-band sentinel behaves like any other out-of-range value: slices clamp, and reads return None. The exception is the fixed-width numeric Array: its length, get, get_or and set use i64; LLVM then sees a native induction variable and can vectorize the contiguous loop, while its allocation can never approach the i64 limit. Crossing either surface to a wire width goes through the conversion bridge (§3). The int representation has a small-int fast path, but retaining a possible boxed edge in native loop IR is the cost Array's fixed index avoids.

Checked string and byte bodies. Deserializer exposes take_string_header!() and take_bytes_header!(), each returning Result<BodyHeader, DecodeError>. A header parses only the wire type and length; it does not check body availability, inspect UTF-8, copy body bytes, or acquire ownership of the body backing. BodyHeader is opaque, with byte_length: int, offset: int (header start), and kind: BodyKind properties. BodyKind has StringBody and BytesBody variants. Lengths count bytes, including UTF-8 bytes, and preserve the complete binary u32 or CBOR u64 advertised length as an exact int.

take_string_body!(header) and take_bytes_body!(header) consume a checked header and return detached string or bytes storage. skip_body!(header) -> Result<(), DecodeError> advances past the advertised body without reading, copying, retaining, or validating UTF-8. It supports string and byte bodies; nested-value traversal requires an application decoder. Applications can inspect lengths, debit their own aggregate budget, then read or skip. Generic Decode and derived decoders continue to use unbounded reads unless a handwritten decoder explicitly applies a policy; this API does not impose an aggregate budget, container limit, or depth policy.

take_string_bounded!(max_bytes: int) and take_bytes_bounded!(max_bytes: int) are trait defaults over header then body. Limits must be finite and nonnegative; zero admits only an empty body. InvalidByteLimit(supplied, operation_start) occurs before any input consumption. A malformed, truncated, or wrong-kind wire header returns the format's existing header error first. After a valid header, an advertised length exceeding the limit returns ByteLimitExceeded(advertised, limit, header_start) before body availability or UTF-8 checks, leaving the cursor immediately after the header, even when the body is missing. No body allocation, copy, read, or new body backing ownership occurs on that rejection. The caller's existing reader still retains its original input. Within the limit, a short body returns Truncated(header_start) without advancing beyond the header; invalid UTF-8 consumes the complete body and returns BadUtf8(header_start). Successful bounded reads have the same detached ownership as unbounded reads. A failed header can consume a partial header: binary reports its prefix start; CBOR reports the initial byte's offset if absent, or the argument start if the argument is short.

A header is bound to its source reader's current checkpoint. Copying it does not duplicate permission to consume a body. A successful body claim consumes the checkpoint even for an empty or truncated body; a second attempt returns InvalidBodyHeader(current_position). A different reader or body kind returns the same error without consuming the valid checkpoint or moving either cursor. Any actual advancement through a reader alias invalidates its outstanding checkpoint. Peeking, querying position or remaining length, and zero-byte operations do not invalidate it. A new checkpoint replaces the previous one. Sharing the same underlying reader through another deserializer wrapper shares its cursor and checkpoint as well.

Format implementors supply the two header methods, two body methods, and skip method; the unbounded and bounded materializers are defaults. BodyHeader.new!(src: BytesReader, length: u64, offset: int, kind: BodyKind) -> Result<BodyHeader, DecodeError> issues the checked metadata after an implementor has parsed a header. It rejects a non-finite offset or one outside 0..=src.position!() with InvalidBodyHeader(current_position), without replacing the current checkpoint. header.take_string!(src), header.take_bytes!(src), and header.skip!(src) implement the body operations for reader-backed formats. Implementors are responsible for parsing their format correctly before issuing metadata.

BytesReader.checkpoint!() -> ReadCheckpoint mints a one-use marker; consume_checkpoint!(checkpoint) -> bool checks and consumes it. ReadCheckpoint is a native resource, also spelled bytes.ReadCheckpoint. It retains only identity storage, never the reader or input. BytesReader.skip!(n: int) -> int advances without accessing the body and returns the count skipped, with the same clamping as take!. All three operations are actions and comptime-foldable; checkpoints cannot escape as runtime constants. Header and checkpoint resources follow the existing resource ownership and derivation restrictions.

Planned for core, and not yet implemented: float. The numeric-tower trait hub is numeric, above.

Tier 2: extra

Curated, foundational capability and utility modules, evolving and not locked like core. They are import-gated (§14), in scope only after a file uses or opens them, and a file therefore declares the capability vocabulary it pulls in. They are qualified by default: write use net in place of open net. io is conventionally opened, for a bare print!, and still requires the import like every other extra module.

read_key! buffers unfinished input behind a documented finite byte cap and processes a stream in amortized linear time. Once an event crosses that cap, the sole terminal reader enters a persistent constant-memory discard state. Per-call timeout and resize results do not clear it or expose the unread tail as later key events; the reader drains through the event's syntactic boundary, or EOF, and then returns TooLarge(limit), where limit is the enforced cap; the attacker-controlled observed length is not reported. EOF with nonempty pending bytes that never crossed the cap returns Truncated(pending); the payload is bounded by the same cap, and bare Eof means no bytes were pending. Unrecognized(bytes) remains the lossless result for a complete sequence the decoder does not know and for an ordinary partial sequence abandoned at its follow-up timeout.

Pseudoterminal subprocesses: process.start_pty!(cmd, args, opts, columns, rows) -> Result<Child, sys.ProcessFailure> [env, process] is the third standard-stream disposition beside capture and attach. It returns immediately like start!, but creates a fresh POSIX pseudoterminal whose slave is the child's controlling terminal and stdin, stdout and stderr. This is the streaming form for preserving colour, isatty behaviour and interactive line discipline without lending the child the program's own terminal. The initial dimensions are in terminal cells; Child.set_size!(columns, rows) changes them and the kernel delivers SIGWINCH to the slave's foreground process group. The master is one bidirectional endpoint: write_stdin! sends input, read_stdout! receives the merged stdout and stderr stream, and read_stderr! returns Failed. SpawnOptions.merge_stderr is irrelevant to this face because a pseudoterminal is intrinsically merged. A pseudoterminal cannot half-close: close_stdin! hangs it up and makes later output unavailable. The Child remains actor-owned and has the same interruptible operations, termination, reaping and final-drop rules as a piped child. Dimensions must fit the platform's unsigned 16-bit terminal fields. The operation reports Err on non-Unix hosts; it does not pretend Windows ConPTY has the POSIX contract.

Child.write_stdin!(data, timeout_ms) returns after the first successful native write, which may accept only a prefix. A zero timeout polls, a positive timeout bounds the complete operation across retries, and a negative timeout waits for the first progress. Expiry returns Ok(0). An empty buffer on an open stdin also returns Ok(0); a closed stdin returns Err. An error accepts no bytes in that call. Retain data.view(count, data.length) after success and alternate writes with output reads. The caller owns every unwritten byte; the runtime queues none privately. PTY and piped children have the same write contract. Timeout neither closes a stream nor terminates the child.

Child.try_wait!() -> sys.ChildPoll [process] performs one immediate exit-status poll for piped and pseudoterminal children. ChildPoll has three cases: Running, Exited(i32), and Failed(ProcessFailure). An exit is reaped and cached; later polls, waits, and kills return the recorded exit code. The code follows ProcessOutcome.Exited, including -1 for signal termination. Polling preserves stdin and unread output, sends no signal, and treats pipe EOF independently from process exit. A polling error records no exit and releases the process handle, which a later kill or release must not signal; its failure operation is try_wait. A closed handle returns Failed. A cached failure from wait! or kill! also returns Failed.

Child.write_all_stdin!(data) -> Result<(), sys.ProcessFailure> repeats negative-timeout writes until all input is accepted. An error may follow an already-written prefix. Use it when the child consumes input without requiring this actor to drain output. Simultaneously full input and output queues can deadlock this helper. Both write forms charge [process], and Unix actor shutdown interrupts a parked write. Resize, wait, kill, explicit close, final drop, and PTY hangup follow the single-owner lifecycle above; neither write creates directional handles. Drain output before waiting for a child that may block while writing it.

A full-duplex owner can perform one bounded input/output step as follows. This example uses merged output, from a PTY or SpawnOptions.with_merge_stderr(true):

use process

open result

struct ChildProgress
  pending: bytes
  output: sys.StdinRead
end

def poll_child!(child: Child, pending: bytes) -> Result<ChildProgress, sys.ProcessFailure> [process]
  Ok(count) = child.write_stdin!(pending, 0i32) else Err(failure) -> return Err(failure)
  Ok(ChildProgress(
    pending=pending.view(count, pending.length),
    output=child.read_stdout!(8192, 0i32)
  ))
end

An actor stores the pending suffix in state, handles the read result, and returns from its handler after this step. Schedule the next step through actor.send_after! with a finite delay while work remains; a zero-progress result must not cause an immediate busy loop. Each return permits queued input, resize, and ordinary control messages to run. Separate stdout and stderr pipes need one bounded read from each per step. wait! belongs after output has reached EOF; kill! terminates the child while retaining its output for a final drain, and close! releases everything.

The lifetime exemption is process.spawn_detached!(cmd, args, opts) -> Result<(), sys.ProcessFailure> [env, process]. It reports whether the final executable started, then returns no Child, streams or exit status; actor death and program exit cannot reclaim it. Its three standard streams are the platform null device. On POSIX it starts a new session and double-forks. The final process is not a session leader and cannot acquire a controlling terminal later. SpawnOptions supplies cwd and environment while merge_stderr has no meaning. A stronger capability atom would be fictitious: [process] already permits launching a shell that backgrounds its own grandchild, and a second atom therefore could not form a sandbox boundary. The distinct name makes the exemption visible during audit; it is no option on an owned spawn.

Planned: test. Each new module's tier is decided at module-creation time and recorded by its directory placement.

regex's engine is fixed: a Pike-VM and Thompson-NFA matcher written in pure Hanki, linear in pattern by text, with no backreferences and no lookaround. The reason is §23's. The step budget, --max-steps, is bytecode-only and the AOT tier omits it, and for an AOT binary a linear-time guarantee is the only bound standing between a hostile pattern and unbounded work. A matcher is also the one decoder whose pattern is as likely to be untrusted as its input, any grep-shaped tool taking the pattern from its user. That places it alongside the other inherent, tier-agnostic bounds this section's decoders have. A derivative-based scanning layer over the same core is the intended later optimisation and no competing design, which is also how the production engines are built: .NET's non-backtracking engine is derivative-based and recovers capture groups through an NFA simulation, and Rust's regex pairs a lazy DFA for the search with a Pike VM for the groups.

Structured-data interchange is CBOR (RFC 8949), with CDDL (RFC 8610) for schemas, as the interoperability format. JSON (RFC 8259, the json module) is supported for compatibility with existing ecosystems, and is not the primary format. The two take different forms. CBOR is type-driven, @derive(Encode, Decode) giving any type a codec through the Serializer and Deserializer framework. JSON is a standalone JsonValue tree you parse and then pattern-match, walk with accessors, or decode into and encode from your own types through hand-written FromJson and ToJson impls; its arbitrary key order, single number type and text escapes do not fit the positional framework, and it is therefore not auto-derived. Types are the single schema source: a type's @derive(Encode, Decode) fixes its CBOR encoding, and hanki cddl <path> emits the RFC 8610 CDDL describing that encoding, a publishable contract for non-Hanki consumers, where a struct becomes a positional array, a sum a choice of [tag, …] arrays, and List, Option and Map become [* T], (T) / null and {* K => V}. That structural inference applies to generated codecs only. If the schema closure reaches a type with a hand-written canonical Encode or Decode impl, each such impl must carry an impl-local @cddl("type-expression") attribute; where both impls exist, both attributes are required and their parsed forms must agree. The payload is one RFC 8610 type-expression right-hand side: rule definitions, group entries and trailing text are rejected. A named reference must resolve to a generated project rule, the CDDL prelude, or a generic parameter on the target declaration's emitted CDDL rule. Such a parameter binds by its position in the rule head when parsed; peer Encode/Decode forms compare that positional binding, independent of the parameter's source spelling. Thus @cddl("[T]") truthfully describes a hand-written codec for Box<T>. The original fragment is emitted, while parsed canonical form is used for the Encode/Decode agreement check. Without valid metadata, hanki cddl exits nonzero, names the type and impl on stderr, and emits no schema on stdout. An impl body is ordinary code and compiler reflection exposes no expressions by design; neither body inference nor a declaration-shaped fallback may publish a guessed wire contract. Requiring metadata on each direction makes each codec self-describing and prevents one annotated impl from standing in for its unannotated peer. The schema covers a project and no single file: a directory is read through its manifest's programs and exports, and a file is read as the entry of the project around it. The emitted rules span every module reachable from those roots. Relative and absolute spellings of a file path select the same entry and modules. Rule names follow the source spelling, bare for the entry module's own types and module-qualified for the rest (Envelope, wire.Frame), which is what makes the cross-module references resolve. RFC 8610 §3.1 blesses the dot for this, and its one caveat, that a dot continues a name and a range or control operator therefore needs surrounding space, cannot reach a generator that emits neither. A module the entry cannot reach contributes nothing and is named on stderr. Using Hanki's own value syntax as a serialization format, Hanki-source-as-data, was considered and declined for wire use: it serves only Hanki-to-Hanki exchange and would force map and tuple literals into the language, and the Hanki-native human-readable need is met by the configuration DSL (§21). Binary payloads and codecs traffic in the bytes core type (§4). A CBOR integer decoded into u8, u16, u32, i32 or i64 must fit that target's range; an out-of-range wire value is a decode error and never the modular fixed-width conversion an explicit Hanki to_* call would request.

Tier 3: contrib

Globally useful and neither foundational nor part of the language: a TUI library, a money-handling library and the like. Curated at a lower bar than extra and distributed with the toolchain, and realized as a bundled package and no baked code. A contrib library is an ordinary package the manager resolves from a pre-seeded local source shipped in the toolchain directory, and it never bloats the compiler binary or stdlib_baked.bin. It is versioned with independent SemVer per library. The set is curated, and contrib libraries therefore earn short flat names (use money), the curation being what authorizes the name. Pure Hanki only: like every package, a contrib library has no @intrinsic and builds only on the effect faces core and extra expose.

Contrib resolution is the package manager's local-source path, with no bespoke loader. A deps entry with no URL binding is contrib (§21), and the resolver maps it to the pre-seeded contrib/<name>/ source the toolchain installs. Where that tree sits is derived from the executable's own location at run time, which leaves a toolchain relocatable with nothing baked in at build time: contrib/ beside the hanki executable, which a flat unpack produces; <prefix>/contrib for a <prefix>/bin/hanki, the split layout a release bundle installs; and <prefix>/share/hanki/contrib, the FHS spelling of that same split and the only one a /usr/bin/hanki can use, its prefix being /usr and no distro package being allowed to create a top-level /usr/contrib. In a dev tree the executable sits under cargo's target/, and discovery falls back to the repo-root contrib/. HANKI_CONTRIB_DIR overrides the search for any layout those miss, the counterpart of the link driver's HANKI_RUNTIME_DIR and authoritative in the same way: set-but-not-a-directory is an error and no quiet fall-through to the probes, an override existing to replace the search. The root is threaded and not re-read, and tests point resolution at a scratch dir. A toolchain that ships no tree at all is a partial install, and every diagnostic about it says so and names both remedies, reinstalling or pointing the override at a checkout. The toolchain bundles one version per contrib package. Resolution checks the declared constraint against that shipped version and errors naming it where unsatisfied, and the lockfile pins the reserved contrib:<name>@<version> identity with a deterministic sha256: tree hash over the seeded source, which has no git. --frozen hash-verifies that tree and never fetches, the tier shipping with the toolchain. Three packages exist in-tree and are resolvable: contrib/sql/, an sqlx-flavored SQL toolkit over extra/sqlite; contrib/tui/, a ratatui-flavored immediate-mode terminal UI toolkit over extra/terminal; and contrib/tz/, IANA timezone offsets and abbreviations for a named zone, over a committed tzdata table. tz is the tier's first data package, and the reason the tier exists: named zones and daylight saving have a release cadence of their own, and they sit beside the language in place of in it, the chrono and chrono-tz split, and datetime.local_offset_at! remains what it says it is, the host's zone with no database opened. hanki list enumerates the tier locally (§21). The curation and inclusion policy is open.

Tier 4: universe

The decentralized long tail: libraries spread across git repositories worldwide, over which the Hanki project has no governance say. A universe package's identity is its git URL (host/user/repo), namespacing is therefore inherent, and name-squatting is structurally impossible, there being no flat global namespace to grab. The project offers at most a discovery index, a searchable directory of opt-in-listed repositories, and never an identity or gatekeeping authority. For ergonomics a project may bind a project-local alias to a package's git URL in its own manifest (http = "git.sr.ht/~user/http"), and its source then reads use http without minting a global short name; the alias is scoped to that project, which leaves the global namespace alias-free and squatting-free. That one binding does double duty: it is both the import alias and the dependency's URL source, a deps entry names it by short name (Dep(source = "http", …)), and the presence of the binding is what marks that dep as universe and not contrib (§21). The alias is a handle on the whole package: use http reaches its http.hk and use http.<module> any other module it exports (§14), and a multi-module dependency is one binding and one deps entry, and not one pair per module. Independent SemVer, and pure Hanki only, as with contrib. universe is a provisional working name, the final name deferred, and unlike the curated tiers it is no governed set, only everything else, discoverable.

The boundary, locked

The decision locks these commitments, the parts a future change must not break without saying so. The descriptive table above is not itself the contract.

1. The native seam is core-only. No package, curated contrib or open universe, may add native code, and the entire trusted native surface therefore remains the @intrinsic defs in core even with a full third-party ecosystem. This is enforced at check time: an @intrinsic declared outside the core stdlib, in extra or in user or package code, is a compile error at the def site and no deferred runtime failure.

The application root is the one amendment, and it reverses nothing. A program's own root may open a rift: a Rust implementation of the ops an effect declaration names, supplied by the application and linked into, or loaded by, that application (§6, Rifts). The sentence above remains literally true, no package gains native code, and nothing new is reachable through the package manager. What the amendment adds is scoped by who ships it: a provider sits in the application's own repository, is written by the same author as the program it serves, and is first-party by definition. A dependency cannot introduce one, cannot ask for one, and cannot tell whether one is present.

Three properties make that a scoping and no hole, and each is a rule the implementation enforces. A rift is bound only at the application root and never by a resolved package at any depth, a dependency's manifest carrying rifts failing resolution (H0641). The surface it implements is a checked effect declaration, and the boundary is typed and no open FFI. And the effect it answers is an ordinary capability atom that --allow and --deny gate, more strictly than the rest, a blanket allowance not covering it (§23). The atom is spelled two ways and a binding contributes both: the module-qualified pty.Pty, for effect Pty in pty.hk, and the spelling the program root's own effect rows use. An effect declared in the entry file is keyed bare, and a binding of main.Device therefore contributes Device (the H0645 rule below). A package may declare an effect and leave it unprovided, which is the capability-interface form, and only the root may answer with native code.

1. Resolution and trust descend by tier: baked core / extra (never re-fetched) → bundled contrib → git-fetched universe. The manager will resolve in that order, with trust diminishing along it.
2. Universe identity is its git URL, which makes name-squatting structurally impossible and leaves the index discovery-only. Short flat names are reserved for the curated tiers, core, extra and contrib, and universe is aliased only project-locally.

Mechanism: the directory hierarchy

A module's tier is derived from the directory its source sits in, and there is no per-file annotation.

A compiler-enforced invariant: a core stdlib module cannot use or open an extra stdlib module. A violation surfaces as a check-phase diagnostic naming both modules and their tiers. The rule is internal to the stdlib, and user modules are untiered and can freely use or open either tier.

Seams and rifts are two words for one story, and both are enforced. A seam is core's @intrinsic boundary and is core-only. A rift is the application's own opening, typed by an effect, bound in its manifest, and accepted by name under an effect allowance; §6, Rifts, has the mechanics. All native code is confined to core: an @intrinsic def is allowed only in a core module, never in extra and never in user or package code, with a check-phase diagnostic at the def site in each case. The OS-capability primitives sit in one core module, sys, and the extra capabilities io, fs and process are pure-Hanki faces that declare their effect and delegate to a sys primitive: io.print! calls sys.stdout_write!, and fs.read! calls sys.file_read!. The entire trusted native surface is therefore the @intrinsic defs in core, the same closure The boundary, locked, invariant 1, applies to user and package code. The one addition invariant 1 makes to that closure is an application-root rift, which is first-party code in the program's own repository and nothing the package manager can reach. @intrinsic itself is core-only and is not the mechanism, and every sentence above about the seam remains literally true: the amendment adds that an application root may open a rift, and it does not widen the seam. module retains its own intrinsics as core substrate; it is core, and no face.

Almost every sys primitive is an OS capability and declares an effect row. The seam is defined by being native and not by being effectful, and two members show the difference: sys.aead_encrypt and sys.aead_decrypt, behind the extra/aead face, are pure, encryption being a deterministic function of its inputs, with no authority to gate and nothing to declare. They are native for speed alone, which the seam rule still confines to core, and the one effectful step in that flow, minting a key or nonce, is sys.random_bytes! and gated as always. A native primitive that needs no capability is therefore pure, and is not given a decorative effect row, which would make --deny and the signature both lie.

Promoting an extra module to core, or demoting a core module to extra, takes a fresh, explicitly recorded decision that quotes the existing carve-up.

Combinators and method-style surface

Pure generic combinators have short names (map, filter, fold); effectful variants get ! suffix (map!, filter!, fold!). The effectful variant accepts a callback with any effects; those effects bubble up to the call site.

Generic containers (Option<T>, List<T>) and the built-in string expose their stdlib helpers as inherent methods and never as free functions. Call sites use receiver-first method-chain form:

open option

def surface(xs: List<i32>, x: i32) -> ()
  Some(7i32).unwrap_or(0i32)
  xs.append(x).length
  "foo".repeat(2)
  ()
end

The associated function for empty containers is on the type: xs: List<i32> = List.empty(). The annotation fixes the element type; there is no inline-type-argument spelling (§11). Accumulate with append; no ListBuilder is needed. A chain of n successive appends from empty takes O(n) structural work on both bytecode and AOT, including child-handle accounting, cached byte-budget charges and final release. Any subset of earlier versions may remain live. For example, old = xs, then xs = xs.append(value), then a read of old.length preserves this bound. Receiver uniqueness and element representation impose no restriction. Element construction, callbacks, indexed reads and actor transfer have separate costs.

For k appends starting at an existing List of height h, construction takes O(k + h), plus eventual release of the pre-existing storage. Each independently forked chain has this initial term; repeatedly forking at a carry boundary can repeat O(h) work. The amortized bound concerns append chains and includes the runtime's ownership and budget accounting, using the usual expected constant-time hash-table operations.

Let h count tree levels, including the leaf level. Length and cloning are O(1); indexed reads, updates, slices and concatenation take O(h) structural work, with the greater input height for concatenation. List height is O(log(n + 2)) in its current length, including after slicing. Slicing normalizes sparse top levels and shares unchanged interior subtrees. The stdlib combinators use indexed reads. Visiting m elements therefore takes O(m * h) traversal work, plus callbacks and result construction. A linear callback count is separate from total running time: partition makes n predicate calls, unique makes O(n²) equality comparisons, and merge sort makes O(n log n) comparisons, each with additional indexed traversal. Full operation descriptions are available through hanki doc --find list.

Low-level terminal control sits on the same native seam. sys.stdin_is_tty!() and sys.stdout_is_tty!() give -> bool [io], and false where piped or redirected. sys.term_size!() -> Result<TermSize, TermError> [io] gives TermSize { columns, rows } with int fields, per the index-surface convention, and NotATty where stdout is not a terminal. sys.term_set_raw!(enabled) -> Result<(), TermError> [io] is character-at-a-time with no echo, idempotent whichever way it is called, and the first enable saves the original terminal state. sys.term_restore_write!(s) [io] registers bytes written to stdout at process exit, a single slot with overwrite semantics, empty clearing it, and a full-screen face registers alt-screen-leave and cursor-show here. Its input sibling is sys.stdin_read!(max: int, timeout_ms: i32) -> StdinRead [io], the timed raw read behind a terminal event loop, giving input bytes or a timeout: Bytes(bytes), TimedOut, Eof, Failed(message) or Resized, one OS read of up to max bytes, clamped to at least 1 with no accumulation, timeout_ms < 0 blocking indefinitely and 0 polling immediately. It reads the raw descriptor directly with no buffering layer, and interleaving with stdin_read_line! cannot swallow bytes. A parked read is cancellable by actor.shutdown! (§15). A finite timeout is a wall-clock bound across all read retries. Under --deterministic, a deadline already pending on the virtual clock bounds the native wait in real time (§6). The runtime guarantees the exit restore: the first raw-mode save, or restore-bytes registration, installs a C-runtime exit hook that puts the saved terminal state back and writes the registered bytes on every exit path that returns through the C runtime, a normal main! return and the fatal 254, 253 and 252 exits alike. A terminating signal is not a return through the C runtime, and the same registration therefore takes over SIGTERM, SIGINT and SIGHUP. Each restores the saved terminal state and attempts the registered output in signal context, then re-raises at the default disposition; the process dies of the signal with status 143, 130 or 129. Without an actor watcher, a watchdog bounds the output attempt to 100 ms after terminal state is restored, subject to OS scheduling. A watcher uses its registered grace deadline for restoration and actor cleanup together. Blocked stdout cannot postpone termination indefinitely. Signal-path output is best effort and may be incomplete at the deadline. If the watchdog cannot be prepared or notified, the handler skips output, restores terminal state and re-raises. Stdout file-status flags are unchanged. A registered signal watcher receives bounded actor cleanup (§15). A signal already carrying a non-default disposition is left as it is, an inherited SIG_IGN under nohup and any handler an embedding host installed among them. The signal path writes a registration of up to 1024 bytes, past which the exit hook alone writes it, half an escape sequence being worse than none. abort bypasses both, SIGABRT not being a return and its disposition never displaced: that is how the runtime ends an unrecoverable seam failure, an allocation failure among them. SIGPIPE is the single signal the runtime disposes of, and its disposition is what leaves that one case on an ordinary exit path (§22). TermError is NotATty or Other(message). The ergonomic escape-sequence and key-input face over this seam is a staged extra library.

On Unix, terminal input also parks on a process-wide SIGWINCH self-pipe. StdinRead appends a dimensionless Resized arm, and terminal.KeyRead passes it through unchanged. The sole terminal reader receives it, then queries term_size! once; draining the self-pipe coalesces a resize burst. Thus timeout_ms < 0 remains idle-quiet while still waking for input, actor shutdown, or resize, and a timeout controls only an application's own tick cadence. The runtime installs a persistent resize handler only while the signal still has its default disposition, as for its terminating-signal ownership rule. Child stdout and stderr reads reuse the StdinRead type but never produce its stdin-only Resized arm.

Most stdlib items are written in Hanki itself, and their sources are embedded into the compiler at build time. Items that must bottom out in host code, sys.stdout_write!, string.find, Display<i32>::to_string and the like, are declared in a core module only, per the native-seam rule above, with the @intrinsic annotation:

@intrinsic def stdout_write!(s: string) -> () [io]
end

@intrinsic is a top-of-item attribute, a sibling of @derive. The compiler ignores the def's body and emits a single host-call thunk that dispatches by name into a runtime-registered Rust closure. @intrinsic is reserved for the stdlib, and within the stdlib for core alone, and user code cannot declare its own intrinsics; the call site looks like any other Hanki call. The signature is the entire contract, and the body may be empty.

io.read_line! returns a sum and no bare string. Empty input on a still-open stream is a legitimate value, the user having pressed Enter, and must be distinguishable from end-of-stream, Ctrl+D or a closed pipe. To hold both cases, read_line! returns io.Line:

type Line
  Line(string)
  Eof
end

@intrinsic def read_line!() -> Line [io]

Read loops pattern-match and break on Eof. Under use io the call site and variants are qualified, and under open io they read bare:

use io

def handle!(line: string) -> () [io]
  io.print!(line)
end

def repl!() -> () [io]
  loop
    io.print!("> ")
    match io.read_line!()
      io.Eof        -> break
      io.Line(line) -> handle!(line)
    end
  end
end

open io

def handle!(line: string) -> () [io]
  print!("got: #{line}\n")
end

def repl!() -> () [io]
  loop  print!("> ")
    match read_line!()
      Eof        -> break
      Line(line) -> handle!(line)
    end
  end
end

The dedicated sum is favoured over Option<string> for self-documenting variant names, Eof being clearer than None for the end-of-file case, and because it leaves room for future variants such as Interrupted and Closed without breaking the API. Reading past Eof is the caller's responsibility: the scheduler goes on returning Eof, and a sensible loop breaks on the first one.

Compiler reflection (experimental)

The compiler core module exposes the front end's outputs to a running Hanki program, and the off-path developer tools, fmt, doc, lint, effects and the rest, can therefore be written in Hanki over a faithful parse and check model in place of in Rust. It runs the in-process compiler over a source string and marshals the result into ordinary Hanki records:

def api_version() -> int                                 # reflection schema revision (21)
@intrinsic def parse(src: string) -> Result<Ast, ParseError>              # shallow item headers
@intrinsic def type_decls(src: string) -> Result<List<Decl>, ParseError>  # deep structured decls
@intrinsic def imports(src: string) -> Result<List<Import>, ParseError>   # use/open directives
@intrinsic def diagnostics(src: string, module_name: string) -> List<Diagnostic>
                                                         # `module_name` is the stdlib module `src`
                                                         # IS, so the shipped copy stands aside;
                                                         # `""` for ordinary source
@intrinsic def effect_surface(src: string) -> EffectSurface
@intrinsic def doc_items(src: string) -> List<DocItem>
@intrinsic def stdlib_modules() -> List<StdModule>       # the embedded stdlib (name, source, tier) set
@intrinsic def project_modules!(root: string) -> Result<Project, string> [fs_read]  # a project's own modules
@intrinsic def project_diagnostics!(path: string, src: string) -> Result<List<Diagnostic>, string> [fs_read]  # check a module IN ITS PACKAGE, `src` standing in for it
@intrinsic def bundled_card() -> string                  # embedded HANKI-CARD.md
@intrinsic def bundled_reference() -> string             # embedded HANKI.md
@intrinsic def bundled_skills() -> List<BundledSkill>    # embedded agent skills (name, summary, body)

• parse is shallow. Ast is the list of top-level item headers, Item { kind, name, doc: Option<string>, exported, action, property, span }, where kind is "import", "fn", "act", "struct", "type", "trait", "impl", "actor", "effect", "provide", "meta" or "test". Expression and pattern trees are not mirrored: the deep syntactic AST is the future pure-Hanki parser's job and no part of this seam.
• type_decls is the deep counterpart to parse: the type- and signature-bearing declarations as List<Decl>, with import, provide and test items omitted, each one Decl { name, exported, action, is_meta, encapsulated, intrinsic, generics, doc, body, span }. The body is a sum over the declaration kinds, Fn(Sig) for a def or def! with the ! shown on action, Struct, Sum, Trait, Impl, Actor, Effect and Const, each carrying that kind's own detail: a struct's fields, a sum's variants each with its 0-based tag, a trait's type_members as AssocDecl { name, bounds }, a Sig { params, return_type, effects }, an actor's state_fields, handlers and has_migrate, and so on. A generic or associated declaration's bound has the form TraitBound { ty, row: Option<List<Effect>> }. For Stream[e], the record includes both the trait type and the named row. A member row, a trait or impl method, an actor handler, or an effect op, is a Method { name, action, prop, encapsulated, intrinsic, generics, sig, span }, whose generics are the member's own type parameters, the container's sitting on the enclosing Decl. Every type position is a reflected Type tree mirroring the parser verbatim: Name(string) for a primitive, nominal type or generic parameter alike, App(string, List<Type>) for List<T>, Map<K, V> or a user generic, Unit, Fn(List<Type>, Type, List<Effect>), or Infer. An effect row, a Sig's effects and a function type's Fn row alike, is a List<Effect> in source order, each one Simple(string), a bare tag such as io, fs, Crash or a user effect, or, where its name is a single lowercase letter such as e or r, an effect variable, recognised by that rule as an implicit single-uppercase type parameter is; or Throws(Type), a throws E clause with its error type. Like parse it is purely syntactic, with no inference and expression bodies still not mirrored, and it backs the type-driven ports, cddl and api-diff. Full record shapes are in stdlib/core/compiler.hk; api_version() is 21 for this record shape.
• diagnostics returns what hanki check reports, Diagnostic { message, code, span }, with code the stable H#### string; a parse failure surfaces as a single diagnostic. effect_surface returns the capability surface (§6) as EffectSurface { effects: List<string>, sites: List<EffectSite> }, backing hanki effects. doc_items returns hanki doc's documentable symbols as DocItem { name, qualified, kind, anchor, signature, effects: List<string>, doc: Option<string>, has_doctest, heading, level, line }, where anchor is the stable cross-reference slug matching the hanki doc Markdown {#anchor} and the --format=json anchor, heading is the rendered Markdown section heading, the bare name or a head like impl Display<Point>, level is its heading depth, 2 for a top-level item and 3 for a member, and line is the 1-based source line of the declaration, its name token, for file:line diagnostics like hanki doc --check. diag_codes takes no source and returns the whole stable-diagnostic registry as DiagCodeInfo { code, title, explanation } in registry order, the hanki explain data as values, and an agent can turn a Diagnostic.code into its explanation and fix recipe without shelling out. bundled_card and bundled_reference likewise take no source and return the compiler-embedded HANKI-CARD.md and HANKI.md as strings, the docs hanki new scaffolds into a project, and a generated project's own agent can read the canonical reference at runtime, and the Hanki hanki new port reads them from the same single embed. bundled_skills completes that embedded set with the agent-agnostic skills as BundledSkill { name, summary, body } records, the source of truth hanki new writes into a project's skills/ and indexes from AGENTS.md, and the Hanki port ships the same set as the Rust command with no second copy to drift. These typed, effect and doc views reuse the compiler's own analysis, and they remain this seam's lasting surface even after syntactic tools migrate to the Hanki parser.
• imports returns the source's use and open directives as Import { path: List<string>, is_open, alias: Option<string>, span }, the one header detail parse's Item drops, collapsing an import to its dotted path. is_open tells open M, which folds M's names into bare scope, from use M, reached as M.name, and alias is the use M as N qualifier. stdlib_modules takes no source and returns the embedded standard library as StdModule { name, source, tier } in load order, where tier is a StdTier sum, Core or Extra, derived from the directory the module's source sits in (§17). The tier is reflected and not left to the consumer because it is a fact the compiler already owns: a tool grouping an API index into core and extra sections that hardcoded the core list would go stale the first time a module is promoted, which is an explicitly supported move. It is a sum and no is_core flag, and the registry's community tier can be added without breaking the form. Together they let a Hanki tool reconstruct name qualification, which bare names an open pulls in, without re-deriving it: walk each stdlib module's type_decls for its exported names, then fold the ones the user file opens. This backs the api-diff port's open-against-qualified normalization.
• project_diagnostics! is diagnostics asked in the right place: it checks the module at path in the package it belongs to, with src standing in for that file's contents on disk. Everything else about the file's context comes from the tree, and a caller supplying a source string that never existed there, the older of two revisions or an unsaved editor buffer, gets the answer hanki check would give and not the answer a file with no neighbours gets. Two things are lost by checking a module alone, and each alone is enough to sink the result. Its siblings: a use of one reports no such module and then reports itself unused, the name it bound never having resolved. And the manifest's exports classification: a module listed under exports and not under programs reports H0610 for the very capability interface it publishes (§6). This is the second seam here to read the filesystem, hence the ! and the [fs_read] row. An Err reports a rendered message: path is not a file, or its project cannot be located.
• project_modules! is the other seam here that reads the filesystem in place of a source string, and it is therefore an action and takes [fs_read]. Given a path it answers with Project { package: string, entries: List<string>, modules: List<ProjectModule>, unresolved: List<UnresolvedImport> }, where package is the manifest's evaluated name (typed bindings and pure expressions included), falling back to the package directory's basename for a loose file or an enclosing manifest that cannot be evaluated, and a ProjectModule { name, path, reachable, source } is one .hk file of the project. entries is every root the manifest declares, its programs and then its exports, de-duplicated, the same set every CLI command answers about, and reachability is rooted at all of them, and a package declaring three programs over one library therefore reflects as the whole package. It is one field and no primary-plus-rest pair, and a tool cannot read half a package by accident. A directory root is a project and its manifest names the roots. A file root is its own single entry, and its project is the tree of the nearest manifest enclosing it, its own directory alone where none does, and a tool handed main.hk still reports on the modules main.hk sits among. name is the bare name a use spells, the file stem, flat across the project (§14), and path still tells two same-stem files apart, and a tool can name both of a collision the compiler refuses. reachable is a field and no filter because consumers disagree: a schema generator emits the reachable modules and reports the rest, while a doc index may list them all. source rides along, and the module set and the text it describes are one snapshot in place of something a consumer re-reads and finds changed. A use that binds neither the stdlib nor a module of the project, normally a declared dependency, whose resolution would mean fetching and locking and is therefore out of a reflection call's remit, is reported in unresolved and not dropped, and a tool can say what it could not see in place of emitting references to types it never read. A dotted use <dependency>.<module> (§14) is always one of those, and its UnresolvedImport.name reports the path as written and no head segment that names no module. This is what lets a delegated tool get from the path it was invoked with to the program: without it hanki cddl could see one file, and emitted schemas that referenced rules they never defined.
• A Span { file_id, start, stop } is a half-open [start, stop) byte range into the file file_id identifies. The reflected source is file_id 1, and its offsets slice the src you passed; a diagnostics span may instead point at a stdlib definition site, a different file_id, indexing that file. file_id 0 means there is no file to slice: the span belongs to a node the compiler synthesised, a derived impl, a where-block constructor, or an inherited trait-default body, whose offsets index no text at all.

A reflected Decl reports is_meta for a top-level meta def; the field is is_meta and not meta, which is a keyword, since the modifier shows in the rendered signature. It reports encapsulated and intrinsic for the same reason, neither being recoverable from the signature. An @encapsulated def presents the same empty effect row a plain one does, and anything accounting for purity has to count it on its own line in place of folding it into either side; an @intrinsic body is a placeholder dispatching into the runtime, which is what makes it the hole in a pure-Hanki claim. Only a def can be @encapsulated, and both a def and a def! can be @intrinsic. parse's Item reports property for a @property test, which is otherwise indistinguishable from a plain one, both carrying kind == "test". That flag is reachable because parse hands back the raw items the source wrote, with no desugar run: a doctest fence inside a doc comment is not a synthesized test item, and a property test still shows the typed parameters the property desugar would otherwise consume. Anything counting a source's tests depends on that, the desugared view reporting a test per doctest as well. A meta constant's reflected body reports its value twice: value_source is the verbatim slice, and value_rendered is the same expression printed back from the parse. A comparison wants the rendered one, two spellings differing only in layout rendering identically and a reformat being no value change, and a tool showing the user what they wrote wants the slice. Experimental. The surface is destined for the 1.0 contract and remains unstable until the tool ports validate its form. Treat the records as provisional, and check api_version() for a revision change. The intrinsics run on both tiers: on the bytecode tier, hanki run, test and the REPL, directly, and in an AOT-compiled binary that calls one by linking the embedded front end, the same statically-linked compile pipeline and VM a load!-using build links (§14), and a reflected value is byte-identical across tiers. The cost is paid only where used: a hanki build of a program that calls no reflection intrinsic retains the lean, LLVM-free AOT baseline and pays nothing, while one that does pulls the front end into the binary's size and trust surface, the same trade load! makes. Comptime reflection is a follow-up.