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

113 numeric↔numeric operators — 51 total INTO, 62 fallible AS — read from kernel/src/*.ev at build time. Regenerate with python3 docs/build_conversions_table.py; do not hand-edit between the markers.

The table above is generated from the kernel registry. It used to be kept by hand, and it drifted the way a hand-kept list of a hundred-odd rows does: it went on saying sign-mixing and narrowing were unregistered, and that int32 AS int16 was "not yet provided", after both had stopped being true. Brian's Phase 8 ruling 4 made it derived — a generator reads kernel/src/*.ev and rewrites the region between the markers, so the doc cannot disagree with what actually resolves. Everything outside the markers, including this paragraph, is hand-written and carries the rationale the registry has no way to state.

The rule behind every row: every TOTAL conversion has an INTO, every FALLIBLE one an AS. Totality is a range question and nothing else — the source's range fits inside the destination's, or it does not — so the keyword is derived rather than chosen. The integer half is now complete: all 90 ordered pairs across the ten integer types are registered (Phase 8 family #2, 2026-09-21), which closed 59 crossings a developer could name but not spell. Before that, the analyzer refused those pairs with E2007 ("requires IS or Convert") while no Convert existed to reach for.

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 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.

A registered sign cross is still an EXPLICIT one. 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. That holds even for the ten cross-sign pairs that are total (uint8 and uint16 into the wider signed types, uint32 INTO int64, uint64 INTO int128), where every source value lands in the target's non-negative half and nothing can be lost: Brian's 2026-08-25 ruling is that a sign change is chosen by the developer, and the keyword is how they say the reading changed, even where the value cannot. (#38, and Phase 8 family #2 for the other eight.)

What is still not a conversion is a pair with no operator in either direction — int32 INTO boolean, for instance, since family #4 ruled INTO/AS closed to boolean both ways with b INTO String the sole exception. Those are a clean E2086 at analysis time (Bug #233 hardening; it no longer slips to a clang reject). 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(b.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):

A code point never lands in an integer slot implicitly, and never in another char width implicitly. Since 2026-09-18 (Phase 8, I.D.i(b.ii)/(d.i)) every row in the two tables below is a DOOR that must be written: int64 n = c and int64 n = c + p are both E10096 — the offset's result is the code point's own type, so an integer slot receives a crossing — and char16 u = c8 is E10096 too. (c + p) INTO int64 and (c8 INTO char16) are the spellings. The one thing that still crosses nothing is the DISTANCE c1 - c2, which is an int32 from the start. The keyword-bitwise operators (BAND BOR BXOR BNOT LSHIFT RSHIFT) yield an INTEGER across any two char widths (I.D.i(e)), so that result needs no door into an integer slot — and needs one back into a char slot.

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.

2e.ii boolean — the truth value (added 2026-09-19)

No conversion crosses the boolean boundary implicitly, and INTO/AS is not a door either (I.D.i(b.iii)). There is no conversion operator into a boolean from a number, a code point or an octet, and none out of one — in any position: declaration, assignment, argument or return. All four arms report the same code, E10096, so the crossing is never named two ways at two positions (until this ruling a declaration said E2002 while the other three said E10096, and boolean x = someInt128 said nothing at all).

The same ruling refuses the operator positions a crossing used to reach through: arithmetic with a boolean operand and unary minus are E2152 ("a boolean is not a number"), ordering is E2118, a boolean array subscript is E2144, and equality against anything but another boolean is E2025.

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 are REFUSED (E10096). 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) is a compile error — a code unit of one encoding is not the same unit in another. Every char-type pair, with no exemption, in every position (declaration, assignment, argument, return). It is the Envzn-native parallel to clang's -Wcharacter-conversion, and --no-clang-char-warnings silences clang's, not Envzn's. The refusal is exempt inside an OPERATOR AS/INTO body whose declared target is the destination width (that is where the conversion is defined).

Changed 2026-09-18 (Phase 8, I.D.i(d.i)). This was the warning W10095, with char16→char32 exempt on the grounds that a non-surrogate UTF-16 unit is the same UTF-32 scalar. Half of the char16 space — the surrogates 0xD800..0xDFFF — is not a UTF-32 scalar at all, which is the case a decoder exists to handle, and §2f already calls the reverse direction fallible. W10095 is retired; E10096 is the one code, and the ASSIGNMENT arm had been reporting it on all nine pairs all along.

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). The fallible inbound rows return the pipe-XOR shape, not a plain value — so decimal128 d = (f INTO decimal128) is E6064 and the consume is IF (f INTO decimal128) THEN { d = $= }. These pairs are compiler-ASSEMBLED rather than registry-declared, and until 2026-09-19 the exemption that kept them out of the "no operator" check returned before the fallibility was stamped, so the shape check never saw them and the emitted _EvTuple<Decimal128, _EvStatus> reached a bare Decimal128 slot (Phase 8 family #3, ruling R5). (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.)