Type Conversions in Envzn — AS / INTO Reference

Audience: Envzn developers and future Claude sessions. This is the practical lookup for "I have a value of type X and I want type Y — is it valid, do I write AS or INTO, and what do I get back?"

Source of truth: the normative spec is ENVZN_CONSTITUTION.md I.D.viii + IV.A.viii; the design rationale is conversion-operators-design.md. This document is a derived catalogue of the surface those define, enumerated from the kernel hosts that implement it (kernel/src/PrimitiveConversions.ev, NumberConverter.ev, FloatConverter.ev, CharConverter.ev, CharWidthConverter.ev, TextConverter.ev). Every row below is an OPERATOR that exists in those files today and compiles. When the kernel hosts change, re-derive this doc from them — do not let it drift.

1. The four rules that explain everything

1. Envzn has no casts. There is no syntax that reinterprets one type as another. Every crossing between numeric types, between numbers/chars and text, and between the text and binary container columns is a checked conversion written with one of two operators.

2. Two operators, split by the LOSS axis: - INTO = lossless. The target can represent every value of the source. Widening (int32 INTO int64), value→text (42 INTO String), and parse ("42" INTO int32). - AS = lossy. The conversion can lose data or cross a sign/range boundary, so it is range-checked at runtime, never a silent truncation (int64 AS int32, float64 AS int32, char32 AS char8).

3. A second, independent axis — FALLIBILITY — decides the return shape: - Total → a plain value. Consume it directly: String s := 42 INTO String. - Fallible → the pipe-XOR shape (T value | STATUS status) (I.M.i). Consume it as the condition of an IF/WHILE; in the success branch read the value with $= (the alias $RETURNED is equivalent), and in the failure branch read the failure STATUS with $! and its numeric error code with $#. $# is not always meaningful: it is 0 whenever the failure carried no numeric code — which is the case for every conversion operator here (they raise FAILURE("message") with a message but no code), so rely on $! for conversion failures and treat $# as 0. The code is only non-zero for STATUS values from sources that set one (e.g. an errno-bearing SETS_ERRNO FFI bind).

The two axes combine into exactly three live cells (there is no lossy-total cell — any lossy conversion is range-checked, hence fallible):

4. You never name the host. Write x INTO T or x AS T; the compiler resolves the single operator whose (source, target) signature matches. NumberConverter, PrimitiveConversions, etc. are where the operators live, not something you type at the call site. (They are extensible: a module can add its own CONVERSIONS host for its own types — see IV.A.viii.)

The two consumption shapes, concretely

// TOTAL — plain value, used directly
String label := 42 INTO String              // "42"
int64  wide  := myInt32 INTO int64           // widening
float64 d    := myInt32 INTO float64

// FALLIBLE — pipe-XOR, consumed by IF; $= (alias $RETURNED) is the value,
//            $! is the failure STATUS, $# is its error code
IF (userInput INTO int32) THEN {
    int32 n = $RETURNED                             // success: the parsed value; note that $= and $RETURNED are equivalent
    process(n)
} ELSE {
    String why := $!                         // failure: the STATUS (auto-converts to text)
    int32 errorcode = $#                     // error code, if any — 0 for conversion failures (no code set)
}

// narrowing is fallible too
IF (myFloat64 AS int32) THEN { pixel = $= }  // out-of-range / NaN → ELSE branch

The classic trap. int32 AS String is invalid — number→text loses nothing, so it is int32 INTO String. Reaching for AS where the conversion is lossless (or INTO where it is lossy) is a compile error, by design. Use the matrix below to pick correctly.

2. Quick matrix — every valid conversion, one row each

✓total = plain value · ✓fallible = (T | STATUS), consume with IF — value via $= (alias $RETURNED), failure STATUS via $!, its error code via $#. Anything not listed is not a valid conversion (compile error) — including the reverse of many one-way rows (e.g. there is no String AS int32; parse is String INTO int32).

2a. Numeric ↔ numeric

Every implicit widening of constitution I.J.iii.c — a same-signedness integer to a wider integer, ANY integer to a float, and float32 INTO float64 — is now also a registered total OPERATOR INTO (Bug #233/#234). int→float is registered even where wide (int64 INTO float32), following C++'s value conversion exactly as the pre-existing int32 INTO float32 does (the widening model treats int→float as total, I.J.iii.c). What is not registered: sign-mixing (int32 INTO uint32) and narrowing — an unregistered INTO/AS pair is now a clean E2086 at analysis time (Bug #233 hardening; it no longer slips to a clang reject).

Two cross-sign pairs ARE registered, and they are not exceptions to that rule — they are total. uint32 INTO int64 and uint64 INTO int128 go from an unsigned type to a signed one at least one width wider, so every source value lands in the target's non-negative half and nothing is lost. They are still explicit: widens_to (compiler/primitives.py) treats all sign-mixing as non-implicit, so an int64 parameter does not silently accept a uint32 — you write the INTO. The general sign-mix ban above is about pairs where a value genuinely can be lost (uint32 INTO int32 loses the top half, int32 INTO uint32 loses the negatives). The workhorse down-narrowings are registered: int64 AS int32, int128 AS int64, uint128 AS uint64, uint64 AS uint32 (the 128→64 / 64→32 range-checked pairs). Other integer narrowings not in this table (e.g. int32 AS int16) are not yet provided as operators — see §6. For a deliberately unchecked truncation, use NumericUtilities (§5), not AS.

2b. Value / char → String (rendering — always lossless + total)

You rarely write INTO String just to print: ->format(...) and the Stdio print methods auto-convert any argument (I.F.vi). Reach for explicit INTO String when you need the String as a value (storing it, concatenating, returning it).

2c. String → value (parse — lossless but can fail)

IF ("42" INTO int32) THEN { int32 n = $= } ELSE { /* not a number */ }

2d. Text ↔ binary (String ↔ ByteBuffer, UTF-8)

INTO here assumes UTF-8 (the canonical encoding). Other encodings are bulk operations, not single-pair operators — see UTFCodec (§5). For opaque-byte display (hex), use HexCodec, not this bridge.

2e. char ↔ integer (bit-twins, widening, narrowing)

A code point's own arithmetic is not a conversion. Since 2026-09-10 (I.D.i(c.ii), gh #285) char ± integer is an OFFSET yielding the char's own type — range-checked at runtime against that width's code-unit range — and char - char is a DISTANCE yielding int32. Neither needs a door. What still does: a plain integer landing in a char slot (char digit = 0x30 + d) is a crossing and is refused (E10096); write the offset, char digit = '0' + d. Everything else with a char operand — char + char, n - c, * / ~/ % ^ &* &+ &-, unary minus — is E2150, not a missing conversion.

Bit-equivalent twins — INTO, total, both directions (same storage width):

Widening into a wider char or a wider/equal integer — INTO, total:

Integer/float → char, narrowing — AS, fallible (range/scalar-checked):

char → narrow integer, narrowing — AS, fallible:

2e.i binary — the octet (added 2026-08-28; byte retired 2026-08-29)

binary is the language's 8-bit unsigned octet, and since 2026-08-29 it is the only one. It is deliberately not in GROUP Numeric — a bit pattern is not a number — and since 2026-09-08 it does not widen at all: no implicit conversion crosses the octet boundary in either direction any more, so every row below is an explicit INTO/AS, never the free widening uint8 would give:

And INTO binary — the inbound ladder (added 2026-08-30). Until 2026-08-29 there was none, because uint8 -> binary was implicit: an octet and a number were interchangeable at the same width. That is what let DynamicByteBuffer.append(uint8) compile at 15 kernel call sites, with clang unable to object because both lowered to uint8_t. Closing the implicit edge without providing an explicit one would leave a denial with no remedy, so:

Note the asymmetry with the outbound row above, which is deliberate rather than an oversight: binary AS int8 is fallible because 128..255 has no int8 spelling, while int8 INTO binary is total because every bit pattern is a valid octet. The octet is the wider domain in that pair.

The masked idiom needs none of these. x BAND 0xFF is typed binary — the mask literal fits an octet, so the AND yields one — which is why acc->append(x BAND 0xFF) compiles with no operator at all: the argument the call receives already is the octet type it wants. A masked integer assigned to an integer slot is the other half of the same idiom and stays a number, also with no operator (uint64 masked = word BAND 0xFF) — nothing in it was ever a stored bit pattern, so there is nothing to convert. Which one you get depends on the slot, not the expression; every hash and wire codec in the kernel reads unchanged either way. The AS rows cover the case the compiler cannot bound.

byte is gone. It was a third 8-bit unsigned spelling alongside uint8 and binary, all three lowering to uint8_t, and the primitives table described it as "distinct from uint8 only by intent" — an intent nothing enforced. Every one of its 19 type-position sites in the kernel existed only to support byte itself, and GROUP Numeric listed it while excluding binary, which settled what it actually was: the numeric octet, i.e. uint8. Sites that meant an octet are now binary; sites that meant a small number are now uint8.

No implicit conversion crosses the octet boundary, in either direction, as of 2026-09-08. int32 n = b — reading an octet as a number — used to widen for free, the same as uint8 INTO int32 does; it is refused now, and so is the reverse, binary b = u — writing a number into an octet. The signed INTO rows above (int16/int32/int64/int128) exist because that implicit widening is gone: a caller who wanted a signed target and knew the value fit used to get there by plain assignment (int32 d = raw[i]); the same read now has to say INTO at the call site, which is why the rows have to exist for it to say. Two codes name the two refused directions — E2139 when an octet is read where a number is wanted, E2145 when a number is written where an octet is wanted.

Why this exists. The byte containers store binary[] (§I.J.i(c)), so buf[i] INTO uint64 — the first move of every hash and every wire codec — is ordinary code. It worked only by accident before: the storage was spelled char8[], and char8, being signedness-neutral, carries the full numeric ladder including the signed targets. When the storage became binary[] the idiom stopped compiling in three kernel hot paths at once, which is how the gap was found — and the same audit is what closed the implicit crossing outright rather than patching the one site it broke.

2f. char-width narrowing (CharWidthConverter)

Widening between char widths is in §2e (INTO, total). Narrowing a wider char to a narrower one can fail (the code point may need multiple code units) — AS, fallible:

Implicit cross-char-type conversions warn (W10095). Writing one char type where another is expected without an explicit AS/INTO (e.g. char16 u = someChar8, or returning a char8 from a RETURNS char16) fires W10095 — a code unit of one encoding is not the same unit in another. Every char-type pair warns EXCEPT char16→char32 (a non-surrogate UTF-16 unit is the same UTF-32 scalar). It is the Envzn-native parallel to clang's -Wcharacter-conversion; both fire by default, and --no-clang-char-warnings silences clang's (not Envzn's). The warning is exempt inside an OPERATOR AS/INTO body (that is where the conversion is defined).

2g. number and complex (the value-class numeric primitives, §I.D.i(g))

number holds an int64 XOR a uint64 (the UNSIGNED overflow arm, #38) XOR a float64; complex is a pair of numbers. Widening into either is implicit/total; narrowing out of number is lossy ⇒ AS (fallible); extracting a real out of complex is lossless-but-precondition'd ⇒ INTO (fallible). (Hosts: NumberConversions.ev, ComplexConversions.ev.)

number/complex are Equatable only (not Hashable/Comparable): fine as values, never a Dictionary/Set key or SortedList element. There is no number AS String (text rendering is lossless ⇒ INTO), and no lossy-total cell here either — every AS above is fallible.

2h. decimal128 (the exact base-10 primitive, §I.D.i)

decimal128 is an IEEE 754-2008 exact base-10 numeric ({ int128 coefficient; int32 exponent }). Unlike the bare primitives, the kernel cannot construct it from a plain operator — so every inbound … INTO/AS decimal128 is compiler-assembled (a kernel helper returns the parts, the compiler builds the value); the outbound operators are ordinary OPERATORs in DecimalConversions. Widening a ≤64-bit int into decimal128 is exact/total; everything else inbound is INTO fallible — exact-when-representable, else FAILURE, never a silent round (decimal128's exactness contract; that is the lossless-fallible cell, so it is INTO, not AS). Narrowing out is lossy ⇒ AS (fallible). (Hosts: DecimalConversions.ev; inbound parts-helpers DecimalText / FloatToDecimal / NumberToDecimal / DecimalCodec.)

decimal128 stays "clean": a decimal128 operand in arithmetic/comparison combines only with another decimal128 or a ≤64-bit integer (which widens exactly). A float/number/complex/int128 counterpart is a compile error (E2121) — convert it explicitly so precision is never silently lost.

decimal128 IS Hashable + Comparable (cohort-normalized), so it is a valid Dictionary/Set key and SortedList element — the contrast with number/complex above. There is no decimal128 AS String (text is lossless ⇒ INTO), and the ByteBuffer ⇄ decimal128 pair is the IEEE BID wire codec (a single canonical encoding, hence AS/INTO, not a parameterized §5 codec).

3. Formatting (->format) and auto-conversion — what is handled, what is not

Conversion and formatting are related but distinct. ->format(...) (and the Stdio print methods, I.F.vi) auto-convert their arguments to text for you, which is why you rarely write an explicit INTO String just to print. But the auto-convert covers a fixed set of argument types — anything outside it either renders as a placeholder (with a compile warning) or must be converted by hand first. This section is the line between the two.

How a format call works

String msg := ("Processing item $1 of $2")->format(current, total)   // $1..$9 filled in order
String hex := ("color = #$1:0>6X")->format(v)                        // "color = #0000FF"

$1..$9 are the placeholders (filled left-to-right by the arguments); $$ is a literal $. Each placeholder may carry a spec $N:<fill><align><sign><width><type> mirroring Python's mini-language — type letters :d :x :X :o :b (integer bases) and :s (default render). The compiler chooses the right render for each argument at the call site, so a value never has to be threaded through (value INTO String) before a format call.

✓ Auto-converted (these render with no manual conversion)

✗ NOT auto-converted (placeholder render, warning, or you convert first)

Rule of thumb

If the value is a single primitive, a String/DynamicString, a byte container (and hex is what you want), or a class with a toString(), just pass it — ->format handles it. If it is a collection, a byte buffer you want as text, or a class without toString(), the auto-convert stops and you reach for an explicit conversion (§2, §5) or render the parts yourself. The format auto-convert is a convenience over the conversion surface in this document, not a replacement for it.

4. Per-host detail (where each operator lives + edge cases)

You never name these at the call site; they are listed so you know where to edit the surface and what each guarantees. All are CONVERSIONS hosts in kernel/.

• PrimitiveConversions.ev — the numeric/char widen+narrow matrix (§2a, §2e). Orders early in the kernel (depends only on primitives + STATUS), so every kernel class can use it. int32 INTO char32 is deliberately total (Bug #189): char32 is 32-bit storage, so no bits are lost; Unicode-scalar validity is not this conversion's concern.

• NumberConverter.ev — integer/boolean → String (total) and String → integer/ boolean parse (fallible) (§2b, §2c). Orders early (depends only on String/ DynamicString) so foundational classes can render with x INTO String. 128-bit values render via hand-rolled decimal (no libc path).

• FloatConverter.ev — float32/float64 → String (total), via the Ryu/FloatFormat engine: shortest decimal that round-trips. (Float parse lives in NumberConverter.)

• CharConverter.ev — char8/char16/char32 → String and char32[] → String (all total). The char32[] operator backs the compiler's error-message print auto-convert.

• CharWidthConverter.ev — the fallible char-width narrowings only (§2f). Delegates the actual encode to UTFCodec and succeeds only when the result is exactly one code unit.

• TextConverter.ev — the String ↔ ByteBuffer hard line (§2d), UTF-8. String INTO ByteBuffer is total (every code point encodes); ByteBuffer INTO String is fallible (arbitrary bytes may not be valid UTF-8).

• NumberConversions.ev — the number narrow-out matrix (§2g): number AS int*/uint* and number AS float32 (lossy, fallible — range-checked, float32 overflow detected via the finiteness identity (f - f) == 0 since a float32-max literal needs V2 scientific notation), plus the total number INTO float64 and the tag-aware number INTO String. Widening into number is implicit (no operator).

• ComplexConversions.ev — complex INTO String (total, canonical (a + bim), sign-aware on the imaginary part) and complex INTO float64 (lossless-fallible, succeeds iff the imaginary part is zero). complex AS <real> is intentionally absent — it is a compile error (E2106, Re-vs-magnitude ambiguity). Real → complex widening is implicit.

• DecimalConversions.ev — the decimal128 OUTBOUND matrix (§2h): decimal128 INTO String (total, exact decimal text), decimal128 INTO ByteBuffer (total, IEEE BID encode), and the decimal128 AS int*/uint*/float* narrowings (lossy, fallible). The INBOUND … INTO decimal128 conversions are NOT operators here — the kernel can't construct the value-class primitive, so the compiler assembles each from a parts-helper (String→DecimalText.parseDecimalParts, float*→ FloatToDecimal, number/complex→NumberToDecimal, ByteBuffer→DecimalCodec.bidToParts, int*→an exact-widen Decimal128(coeff, 0)).

• DecimalCodec.ev — the INBOUND half of the IEEE BID wire codec: bidToParts(ByteBuffer) → (DecimalParts | STATUS), decoding 16 big-endian BID bytes (simple 113-bit form) and rejecting a wrong length, the non-canonical "11" combination form, an out-of-range exponent, or a >34-digit coefficient. The compiler's ByteBuffer INTO decimal128 lowering calls it and builds the value.

5. Not AS/INTO — reach for these instead

Some type crossings are deliberately not checked conversions, so they are ordinary NAMESPACE free-function calls (Host->method(...)), not operators. Use these when the matrix above has no row for what you want:

Why they are not operators: a codec is parameterized (endianness, encoding) or many-to-one (bulk arrays), and AS/INTO are single-source/single-target; and NumericUtilities is intentionally unchecked — making it an AS would collide with the checked AS for the same type pair and hide the data loss the caller explicitly wants. (DateTime construction from parts/strings is fallible too but lives on the DateTimeFactory singleton, since Envzn has no static methods or fallible INIT.)

6. Boundaries / what is not here

• The C.* FFI boundary conversion is NOT an AS/INTO operator (shipped 2026-08-06, Constitution I.D.x). C.size_t · C.ssize_t · C.long · C.unsignedLong name a C typedef at a FOREIGN/FOREIGN BIND declaration and lower verbatim to that spelling. You never write a conversion for them and you never declare one: they are legal only in a foreign declaration (else E2143), so no C.* value exists in Envzn code to convert. The caller passes and receives an ordinary Envzn integer (uint64, int64) and the compiler converts at the boundary, in both directions, for a by-value argument and for the LOAD C.<type> in/out out-param alike. Inbound is CHECKED: a value outside the platform's range for that C type raises the MathError of I.F.ii(a.iii) rather than truncating — a silently narrowed size_t is precisely the wrapped-size defect the memory-safety floor forbids. Outbound is widening on every supported target and needs no check. Why the family exists at all: a fixed-width primitive cannot express a pointer to a C typedef — size_t is unsigned long where uint64_t is unsigned long long on Darwin, and the two swap on Linux, so the wrong spelling compiles on one target and fails on the other. By value the old advice merely worked by implicit conversion; by pointer it could not work at all. W2146 warns when a LOAD uses a 64-bit fixed-width type instead.
• No String AS T and no lossy-total cell. Parse is String INTO T (lossless-fallible). Every AS is fallible.
• Not every integer narrowing has an operator. Today the checked AS integer narrowings are those in §2a (int64 AS int32, float* AS int32) plus the char-target narrowings. Other pairs (e.g. int32 AS int16, int64 AS uint32) are not yet provided — if you need a deliberate unchecked narrowing, NumericUtilities covers it; a new checked pair is a one-operator addition to PrimitiveConversions.ev.
• Class ↔ class / custom types. A module may declare its own CONVERSIONS host with OPERATOR AS/INTO for its own types (IV.A.viii); the same x INTO T / x AS T surface and $=/$RETURNED/$!/$# consumption apply.
• No AS/INTO on arrays or N-D arrays. A value-array T[] and a dense N-D array T[,] / T[m,n] / T[3,4] (#31) are containers, not convertible scalars — there is no T[] AS … / float64[,] INTO …. Convert the elements (loop + x INTO U), or reach for the relevant codec (§5). N-D arithmetic / reshaping is the numeric-module (AdvancedMath) surface, not a conversion.

Maintenance: when you add or change an OPERATOR in any CONVERSIONS host under kernel/, update the matching row here. To re-verify the full inventory: grep -nE 'OPERATOR (INTO|AS)' kernel/{PrimitiveConversions,NumberConverter,FloatConverter,CharConverter,CharWidthConverter,TextConverter,NumberConversions,ComplexConversions,DecimalConversions}.ev (plus the compiler-assembled … INTO decimal128 set — sources in compiler/analyze/expr_diagnostics.py _ASSEMBLED_DECIMAL_SRC and the build_ir/lower_expr.py parts-helper map.)