numtypes 0.0.0

package/docs/transform-spec.md

@@ -0,0 +1,2114 @@
+# Transform Spec
+
+This document defines the arithmetic closure transform for the branded numeric
+types described in `docs/lib-implementation.md`.
+
+The transformer erases every branded numeric value to JavaScript `number` at
+runtime, then inserts JavaScript coercion idioms so that the generated
+expression remains closed over the requested numeric domain.
+
+Redundant coercions generated by numtypes lowering may be removed by the
+proof-based coercion optimization pass defined in
+`docs/lowering-optimization-spec.md`. User-authored coercions are preserved. The
+rules in this document remain the conservative correctness baseline.
+
+## Core Rules
+
+The four checked cast calls are:
+
+```typescript
+// signed int32
+i32(x) => x | 0
+
+// unsigned int32
+u32(x) => x >>> 0
+
+// single precision float
+f32(x) => Math.fround(x)
+
+// double precision float
+f64(x) => +x
+```
+
+The function symbols are erased cast markers, not runtime utilities. A checked
+cast marker must appear as a direct call with exactly one argument. The callee
+may be either a numtypes imported identifier or a property access whose receiver
+is exactly a numtypes namespace import and whose property is one of `i32`, `u32`,
+`f32`, or `f64`. It must not be aliased, destructured, stored, passed, put into
+an object, parenthesized as the callee, optional-called, optional-accessed,
+spread-called, called with type arguments, or re-exported as a value.
+
+```typescript
+i32(value);                    // ok
+nt.i32(value);                 // ok when nt is imported from "numtypes"
+i32();                         // error
+i32(...tuple);                 // error
+i32<number>(value);            // error
+const cast = i32;              // error
+const cast = nt.i32;           // error
+const box = { i32 };           // error
+(i32)(value);                  // error
+(nt.i32)(value);               // error
+export { i32 } from "numtypes"; // error
+export type { i32 } from "numtypes"; // ok
+```
+
+TypeScript assertions are unchecked domain assertions. They erase like normal
+TypeScript assertions and do not insert a coercion by themselves.
+
+```typescript
+x as i32 => x
+<i32>x => x
+```
+
+Use a checked cast call when the expression boundary must perform the runtime
+coercion. Use `as` only when the value is already trusted and the user wants to
+choose the domain for later numtypes operations.
+
+Unchecked assertions have no retroactive coercion effect. They can choose the
+domain seen by later transformer analysis, but the asserted expression itself is
+emitted unchanged unless its own operands already form a typed operation.
+
+```typescript
+function trusted(a: i32, b: i32): i32 {
+    return (a + b) as i32;
+}
+```
+
+should be transformed to:
+
+```typescript
+function trusted(a: number, b: number): number {
+    return ((a | 0) + (b | 0)) | 0;
+}
+```
+
+The operation is lowered because `a + b` is an `i32` operation. The assertion
+only satisfies the branded TypeScript boundary.
+
+```typescript
+function unchecked(a: number, b: number): i32 {
+    return (a + b) as i32;
+}
+```
+
+should be transformed to:
+
+```typescript
+function unchecked(a: number, b: number): number {
+    return a + b;
+}
+```
+
+Here the operands are plain numbers, so the assertion does not add `| 0`. Use a
+checked cast when boundary coercion is required:
+
+```typescript
+function checked(a: number, b: number): i32 {
+    return i32(a + b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function checked(a: number, b: number): number {
+    return (a + b) | 0;
+}
+```
+
+Typed operations close ordinary domain operands before the operation and close
+the result after the operation. Unchecked assertion operands are trusted as-is:
+they choose the operation domain but do not receive an operand coercion from the
+assertion itself. For nested expressions, every typed operation result is closed
+at its own operator boundary.
+
+The coercion in `i32(0.1)` comes from the checked cast call. The final coercion
+in `(a: i32) + (b: i32)` comes from the `+` operation being dispatched as an
+`i32` operation.
+
+The transformer must track numeric domains separately from TypeScript's own
+expression types. TypeScript widens arithmetic over branded numbers back to
+plain `number`, so the transformer cannot use `checker.getTypeAtLocation` alone
+to decide whether an expression is still `i32`, `u32`, `f32`, or `f64`.
+
+That TypeScript widening must not silently escape into inferred storage. For
+example, `const x = a + b` with `a: i32` and `b: i32` is a transformer error
+because the inferred storage type of `x` is plain `number`. If the user really
+wants to leave the numtypes domain, the escape must be explicit. Assertions to
+non-numtypes types such as `number`, `unknown`, or `any` are explicit escapes:
+
+```typescript
+const x = (a + b) as number;
+const y = (a + b) as unknown;
+const z = (a + b) as any;
+```
+
+The inner `a + b` operation is still lowered as an `i32` operation, but the
+result is allowed to leave domain storage because the escape is explicit in the
+source.
+
+Non-null assertions and `satisfies` clauses are not explicit escapes. They do
+not change the value domain and must not suppress domain-leak diagnostics:
+
+```typescript
+const x = (a + b)!;
+const y = (a + b) satisfies number;
+```
+
+should both be compile errors unless the surrounding storage preserves the
+numtypes domain or the expression is explicitly asserted to a non-numtypes type.
+
+Because the public aliases are branded, TypeScript also rejects a raw arithmetic
+result when it crosses back into branded storage. For example, `a / b` has
+TypeScript type `number` even when both operands are `f64`, so `return a / b`
+from a function declared as `(): f64` is a TypeScript error. Users must write a
+checked cast at that boundary:
+
+```typescript
+function x(a: f64, b: f64): f64 {
+    return f64(a / b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return +((+a) / (+b));
+}
+```
+
+This rule applies to every branded storage boundary: annotated variables,
+assignments, object properties, array elements, call arguments, and returns. A
+typed operation may still be lowered internally, but the user source must be
+valid TypeScript before the transformer runs. A checked cast call is the normal
+way to turn a `number`-typed operation result back into a branded TypeScript
+value.
+
+An unchecked assertion such as `(a / b) as f64` may satisfy TypeScript, but it
+does not perform the boundary coercion. Use it only when the user intentionally
+asserts that no runtime coercion should be inserted at that boundary.
+
+A checked cast call is a boundary conversion, not a free contextual domain for
+every nested operation. The argument expression is still analyzed normally. A
+plain `number` expression can be cast directly, but a mixed operation involving
+branded operands and plain `number` operands must cast the plain operand first.
+
+```typescript
+declare const a: i32;
+declare const b: number;
+declare function read(): number;
+
+i32(read());       // ok: whole plain-number expression is cast
+i32(a + b);        // error: i32 and number are mixed inside the operation
+i32(a + i32(b));   // ok
+```
+
+### Diagnostic Ownership
+
+Examples in this document use "compile error" for both TypeScript diagnostics
+and numtypes diagnostics. The ownership rule is:
+
+- TypeScript diagnostics are authoritative for ordinary branded assignability.
+  For example, `return a / b` from a function returning `f64` is rejected by
+  TypeScript before the transformer can make it valid.
+- Numtypes diagnostics cover transformer-specific semantics that TypeScript
+  cannot express, such as domain leaks into inferred `number` storage, ambiguous
+  numeric unions, mixed numeric domains, and erased cast misuse.
+- If both can apply, the source should be fixed at the TypeScript boundary first,
+  usually by adding a checked cast such as `f64(a / b)`.
+
+When a checked cast call converts from one branded type to another, the source
+value is closed first, then the target coercion is applied. For example,
+`i32(a: f32)` lowers as `Math.fround(a) | 0`, not just `a | 0`.
+
+When an unchecked assertion changes the apparent domain, the assertion itself
+does not close the source value. For example, `a as i32` lowers as `a`. If that
+asserted value later participates in an `i32` operation, it chooses the `i32`
+operation and the operation result is closed, but the asserted operand itself is
+still emitted as-is.
+
+## Declaration Type Surface
+
+JavaScript emit always erases the runtime representation to `number`. Declaration
+emit is configurable because projects have different public API goals.
+
+The transformer option is:
+
+```typescript
+interface NumtypesTransformerOptions {
+    declarationTypes?: "preserve" | "erase";
+}
+
+interface NumtypesSourceTransformerOptions {
+    declarationTypes?: "preserve";
+}
+```
+
+The default is `"preserve"`. In this mode, generated `.d.ts` files keep
+`i32`, `u32`, `f32`, and `f64` in the public type surface.
+
+```typescript
+// input
+export declare function read(value: i32): f32;
+export declare const values: i32[];
+export declare const mixed: i32 | f32;
+```
+
+should emit declarations like:
+
+```typescript
+export declare function read(value: i32): f32;
+export declare const values: i32[];
+export declare const mixed: i32 | f32;
+```
+
+When `declarationTypes` is `"erase"`, generated `.d.ts` files replace every
+numtypes type reference with `number`, replace numtypes cast-function value type
+queries with the erased cast signature `(value: number) => number`, remove
+now-unused numtypes imports, and collapse duplicate numeric union members.
+Re-exports that expose numtypes symbols are removed from the declaration
+surface. Re-exports from other modules are preserved even when their exported
+names overlap with local numtypes import aliases.
+
+Only references that still resolve to the imported numtypes type or cast marker
+surface are erased. Local declarations that shadow imported names remain local
+declarations. Value-side type queries such as `typeof i32`, `typeof nt.i32`, and
+`typeof import("numtypes").i32` are erased so declaration emit does not keep a
+numtypes import solely to describe erased cast marker values.
+
+```typescript
+// input
+export declare function read(value: i32): f32;
+export declare const values: i32[];
+export declare const maybe: i32 | null;
+export declare const mixed: i32 | f32;
+export type Cast = typeof import("numtypes").i32;
+```
+
+should emit declarations like:
+
+```typescript
+export declare function read(value: number): number;
+export declare const values: number[];
+export declare const maybe: number | null;
+export declare const mixed: number;
+export type Cast = (value: number) => number;
+```
+
+Use `"preserve"` when downstream TypeScript users should see and enforce the
+branded API. Use `"erase"` when the emitted declarations should expose only the
+runtime JavaScript contract.
+
+For declaration emit, use the combined transformer factory so the before
+transformer and declaration transformer are both installed:
+
+```typescript
+import { createTransformers } from "numtypes/transformer";
+
+program.emit(
+    undefined,
+    writeFile,
+    undefined,
+    false,
+    createTransformers(program, { declarationTypes: "erase" })
+);
+```
+
+Calling `createTransformer(program, { declarationTypes: "erase" })` is a
+TypeScript type error and a runtime configuration error because a source
+transformer cannot rewrite declaration emit. Use `createTransformers()` for full
+emit integration.
+
+`optimizeTypedArrayElementAccess` defaults to `false`. When enabled, the
+optimization pass may remove generated coercions around numeric TypedArray
+element reads only when it proves a matching loop bounds check. This option is a
+runtime trust boundary: code typed as `Float64Array`, `Int32Array`, and other
+numeric TypedArrays must actually receive those intrinsic objects for the
+optimized region. See `docs/lowering-optimization-spec.md` for the exact proof
+rules.
+
+## Container And Generic Type Arguments
+
+Numtypes annotations are allowed inside container and generic type syntax. This
+includes array shorthand, generic array forms, tuples, object properties, and
+application-specific generic types.
+
+```typescript
+type Values = i32[];
+type ReadonlyValues = ReadonlyArray<i32>;
+type Pair = [i32, f32];
+type Boxed = Box<i32>;
+type Lookup = Map<string, i32>;
+type Deferred = Promise<i32>;
+```
+
+The transformer may use these type surfaces for declaration preservation/erasure
+and for direct storage boundaries that TypeScript exposes, such as object
+properties or array element assignments. It does not assign special runtime
+semantics to arbitrary generic types or methods. `Promise<i32>` does not mean the
+transformer traces promise resolution, and `Map<string, i32>` does not mean the
+transformer interprets `Map.prototype.set`.
+
+Call and method boundaries are governed by their TypeScript signatures. When a
+number-typed operation result crosses into a branded generic slot, the user must
+write a checked cast at that boundary.
+
+```typescript
+function arrayPush(a: i32, b: i32, values: i32[]): void {
+    values.push(a + b);
+}
+```
+
+is rejected by TypeScript because `a + b` has TypeScript type `number`.
+
+```typescript
+function arrayPush(a: i32, b: i32, values: i32[]): void {
+    values.push(i32(a + b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function arrayPush(a: number, b: number, values: number[]): void {
+    values.push(((a | 0) + (b | 0)) | 0);
+}
+```
+
+The same rule applies to user generics and standard library generics.
+
+```typescript
+declare function resolveI32(value: i32): Promise<i32>;
+
+function x(a: i32, b: i32): Promise<i32> {
+    return resolveI32(i32(a + b));
+}
+```
+
+The transformer should not infer an implicit cast merely because a generic type
+argument contains a numtypes domain.
+
+When a domain-bound operation result crosses into a plain `number` call slot, the
+escape must also be explicit. This includes rest parameters and standard library
+methods whose parameter is a rest `number[]` element.
+
+```typescript
+declare function take(...values: number[]): void;
+
+function x(a: i32, b: i32, values: number[]): void {
+    take(a + b);
+    values.push(a + b);
+}
+```
+
+should be a compile error:
+
+```bash
+error: result of i32 operation is passed to number parameter without explicit cast
+```
+
+The same rule applies when the call slot is a union containing a plain `number`
+branch, such as `number | i32`. The plain `number` branch would otherwise allow a
+domain-bound operation result to leave the numtypes domain implicitly.
+
+Use an explicit non-numtypes escape when plain number storage is intended.
+
+```typescript
+declare function take(...values: number[]): void;
+
+function x(a: i32, b: i32, values: number[]): void {
+    take((a + b) as number);
+    values.push((a + b) as number);
+}
+```
+
+```typescript
+function x(a: i32, b: i32, c: i32): i32 {
+    return i32(a + b + c);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number, c: number): number {
+    return ((((a | 0) + (b | 0)) | 0) + (c | 0)) | 0;
+}
+```
+
+The transformer should reject implicit mixing between branded numeric types and
+plain `number` values. Use an explicit constructor cast when a domain-changing
+conversion is intended.
+
+Numeric literals may be contextually coerced by the transformer only when the
+target domain is already known from a checked cast call or from a typed
+operation. A declaration annotation alone does not make `const x: i32 = 1`
+valid TypeScript; use `const x: i32 = i32(1)`. Plain `number` variables must be
+explicitly cast.
+
+```typescript
+function x(a: i32, b: number): i32 {
+    return a + b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot add i32 and number without explicit cast
+```
+
+```typescript
+function x(a: i32, b: number): i32 {
+    return i32(a + i32(b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return ((a | 0) + (b | 0)) | 0;
+}
+```
+
+## i32
+
+An `i32` expression is closed by `| 0`. Arithmetic multiplication must use
+`Math.imul` when both operands are in the i32/u32 integer domain. Rewriting
+integer multiplication to normal `*` is not equivalent for all 32-bit values.
+
+### i32 Casts
+
+Checked cast calls perform the `ToInt32` coercion at the call boundary.
+
+```typescript
+function x(a: number): i32 {
+    return i32(a);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return a | 0;
+}
+```
+
+```typescript
+function x(): i32 {
+    return i32(1.2);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(): number {
+    return 1.2 | 0;
+}
+```
+
+Unchecked assertions do not perform that coercion.
+
+```typescript
+function x(): i32 {
+    return 1.2 as i32;
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(): number {
+    return 1.2;
+}
+```
+
+Asserted operands choose the later operation domain, but the operands themselves
+remain unchecked. TypeScript assertion syntax is erased, but parentheses around
+the asserted operand are ordinary expression wrappers and may be preserved by the
+printer.
+
+```typescript
+function x(): i32 {
+    return i32((0.1 as i32) + (0.2 as i32));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(): number {
+    return ((0.1) + (0.2)) | 0;
+}
+```
+
+### i32 Unary Arithmetic
+
+```typescript
+function plus(a: i32): i32 {
+    return i32(+a);
+}
+
+function neg(a: i32): i32 {
+    return i32(-a);
+}
+```
+
+should be transformed to:
+
+```typescript
+function plus(a: number): number {
+    return (+(a | 0)) | 0;
+}
+
+function neg(a: number): number {
+    return (-(a | 0)) | 0;
+}
+```
+
+### i32 Binary Arithmetic
+
+The binary arithmetic operators `+`, `-`, `*`, `/`, `%`, and `**` are closed as
+follows:
+
+```typescript
+function add(a: i32, b: i32): i32 {
+    return i32(a + b);
+}
+
+function sub(a: i32, b: i32): i32 {
+    return i32(a - b);
+}
+
+function mul(a: i32, b: i32): i32 {
+    return i32(a * b);
+}
+
+function div(a: i32, b: i32): i32 {
+    return i32(a / b);
+}
+
+function rem(a: i32, b: i32): i32 {
+    return i32(a % b);
+}
+
+function pow(a: i32, b: i32): i32 {
+    return i32(a ** b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function add(a: number, b: number): number {
+    return ((a | 0) + (b | 0)) | 0;
+}
+
+function sub(a: number, b: number): number {
+    return ((a | 0) - (b | 0)) | 0;
+}
+
+function mul(a: number, b: number): number {
+    return Math.imul(a | 0, b | 0) | 0;
+}
+
+function div(a: number, b: number): number {
+    return ((a | 0) / (b | 0)) | 0;
+}
+
+function rem(a: number, b: number): number {
+    return ((a | 0) % (b | 0)) | 0;
+}
+
+function pow(a: number, b: number): number {
+    return ((a | 0) ** (b | 0)) | 0;
+}
+```
+
+`/`, `%`, and `**` are closed by final `ToInt32` coercion. They do not imply a
+native int32 division, remainder, or exponentiation instruction. Their runtime
+semantics remain JavaScript number semantics followed by `| 0`.
+
+### i32 Nested Arithmetic
+
+```typescript
+function x(a: i32, b: i32, c: i32, d: i32): i32 {
+    return i32(a + b * c - d);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number, c: number, d: number): number {
+    return ((((a | 0) + (Math.imul(b | 0, c | 0) | 0)) | 0) - (d | 0)) | 0;
+}
+```
+
+### i32 With Numeric Literals
+
+Integer literals can be contextually coerced to `i32`.
+
+```typescript
+function x(a: i32): i32 {
+    return i32(a + 1);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return ((a | 0) + (1 | 0)) | 0;
+}
+```
+
+Fractional literals should require an explicit cast when the target is an
+integer domain.
+
+```typescript
+function x(a: i32): i32 {
+    return a * 1.2;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot multiply i32 by number without explicit cast
+```
+
+```typescript
+function x(a: i32): i32 {
+    return i32(a * i32(1.2));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return Math.imul(a | 0, 1.2 | 0) | 0;
+}
+```
+
+### i32 Explicit Promotion
+
+```typescript
+function x(a: i32, b: i32): f64 {
+    return f64(f64(a) + f64(b) * 1.2);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return +((+(a | 0)) + (+((+(b | 0)) * (+1.2))));
+}
+```
+
+The `a | 0` and `b | 0` coercions preserve the source argument type. The `+`
+coercions then promote the values into the f64 expression domain.
+
+### i32 Bitwise Operators
+
+Bitwise operators are already int32-oriented in JavaScript. The transformer
+still closes the result to the declared target type.
+
+```typescript
+function band(a: i32, b: i32): i32 {
+    return i32(a & b);
+}
+
+function bor(a: i32, b: i32): i32 {
+    return i32(a | b);
+}
+
+function bxor(a: i32, b: i32): i32 {
+    return i32(a ^ b);
+}
+
+function shl(a: i32, b: i32): i32 {
+    return i32(a << b);
+}
+
+function shr(a: i32, b: i32): i32 {
+    return i32(a >> b);
+}
+
+function ushr(a: i32, b: i32): i32 {
+    return i32(a >>> b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function band(a: number, b: number): number {
+    return ((a | 0) & (b | 0)) | 0;
+}
+
+function bor(a: number, b: number): number {
+    return ((a | 0) | (b | 0)) | 0;
+}
+
+function bxor(a: number, b: number): number {
+    return ((a | 0) ^ (b | 0)) | 0;
+}
+
+function shl(a: number, b: number): number {
+    return ((a | 0) << (b | 0)) | 0;
+}
+
+function shr(a: number, b: number): number {
+    return ((a | 0) >> (b | 0)) | 0;
+}
+
+function ushr(a: number, b: number): number {
+    return ((a | 0) >>> (b | 0)) | 0;
+}
+```
+
+`>>>` naturally produces a uint32 bit pattern. If the declared target is `i32`,
+the final `| 0` interprets that bit pattern as signed int32.
+
+## u32
+
+A `u32` expression is closed by `>>> 0`. Arithmetic multiplication should use
+`Math.imul`, then reinterpret the low 32 bits with `>>> 0`.
+
+### u32 Casts
+
+```typescript
+function x(a: number): u32 {
+    return u32(a);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return a >>> 0;
+}
+```
+
+```typescript
+function x(): u32 {
+    return u32(-1);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(): number {
+    return (-1) >>> 0;
+}
+```
+
+### u32 Unary Arithmetic
+
+```typescript
+function plus(a: u32): u32 {
+    return u32(+a);
+}
+
+function neg(a: u32): u32 {
+    return u32(-a);
+}
+```
+
+should be transformed to:
+
+```typescript
+function plus(a: number): number {
+    return (+(a >>> 0)) >>> 0;
+}
+
+function neg(a: number): number {
+    return (-(a >>> 0)) >>> 0;
+}
+```
+
+### u32 Binary Arithmetic
+
+```typescript
+function add(a: u32, b: u32): u32 {
+    return u32(a + b);
+}
+
+function sub(a: u32, b: u32): u32 {
+    return u32(a - b);
+}
+
+function mul(a: u32, b: u32): u32 {
+    return u32(a * b);
+}
+
+function div(a: u32, b: u32): u32 {
+    return u32(a / b);
+}
+
+function rem(a: u32, b: u32): u32 {
+    return u32(a % b);
+}
+
+function pow(a: u32, b: u32): u32 {
+    return u32(a ** b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function add(a: number, b: number): number {
+    return ((a >>> 0) + (b >>> 0)) >>> 0;
+}
+
+function sub(a: number, b: number): number {
+    return ((a >>> 0) - (b >>> 0)) >>> 0;
+}
+
+function mul(a: number, b: number): number {
+    return Math.imul(a >>> 0, b >>> 0) >>> 0;
+}
+
+function div(a: number, b: number): number {
+    return ((a >>> 0) / (b >>> 0)) >>> 0;
+}
+
+function rem(a: number, b: number): number {
+    return ((a >>> 0) % (b >>> 0)) >>> 0;
+}
+
+function pow(a: number, b: number): number {
+    return ((a >>> 0) ** (b >>> 0)) >>> 0;
+}
+```
+
+As with `i32`, `/`, `%`, and `**` are JavaScript number operations followed by
+`ToUint32` coercion.
+
+### u32 Nested Arithmetic
+
+```typescript
+function x(a: u32, b: u32, c: u32, d: u32): u32 {
+    return u32(a + b * c - d);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number, c: number, d: number): number {
+    return ((((a >>> 0) + (Math.imul(b >>> 0, c >>> 0) >>> 0)) >>> 0) - (d >>> 0)) >>> 0;
+}
+```
+
+### u32 With Numeric Literals
+
+Integer literals in the uint32 range can be contextually coerced to `u32`.
+
+```typescript
+function x(a: u32): u32 {
+    return u32(a + 1);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return ((a >>> 0) + (1 >>> 0)) >>> 0;
+}
+```
+
+Negative or fractional literals should require an explicit cast in a `u32`
+expression.
+
+```typescript
+function x(a: u32): u32 {
+    return a + -1;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot add u32 and number without explicit cast
+```
+
+```typescript
+function x(a: u32): u32 {
+    return u32(a + u32(-1));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return ((a >>> 0) + ((-1) >>> 0)) >>> 0;
+}
+```
+
+### u32 Explicit Promotion
+
+```typescript
+function x(a: u32, b: u32): f32 {
+    return f32(f32(a) / f32(b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return Math.fround(Math.fround(a >>> 0) / Math.fround(b >>> 0));
+}
+```
+
+### u32 Bitwise Operators
+
+```typescript
+function band(a: u32, b: u32): u32 {
+    return u32(a & b);
+}
+
+function bor(a: u32, b: u32): u32 {
+    return u32(a | b);
+}
+
+function bxor(a: u32, b: u32): u32 {
+    return u32(a ^ b);
+}
+
+function shl(a: u32, b: u32): u32 {
+    return u32(a << b);
+}
+
+function shr(a: u32, b: u32): u32 {
+    return u32(a >> b);
+}
+
+function ushr(a: u32, b: u32): u32 {
+    return u32(a >>> b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function band(a: number, b: number): number {
+    return ((a >>> 0) & (b >>> 0)) >>> 0;
+}
+
+function bor(a: number, b: number): number {
+    return ((a >>> 0) | (b >>> 0)) >>> 0;
+}
+
+function bxor(a: number, b: number): number {
+    return ((a >>> 0) ^ (b >>> 0)) >>> 0;
+}
+
+function shl(a: number, b: number): number {
+    return ((a >>> 0) << (b >>> 0)) >>> 0;
+}
+
+function shr(a: number, b: number): number {
+    return ((a >>> 0) >> (b >>> 0)) >>> 0;
+}
+
+function ushr(a: number, b: number): number {
+    return ((a >>> 0) >>> (b >>> 0)) >>> 0;
+}
+```
+
+`>>` is signed arithmetic right shift followed by uint32 reinterpretation. Use
+`>>>` for logical uint32 right shift.
+
+## f32
+
+An `f32` expression is closed by `Math.fround`. The JavaScript operation itself
+still executes in the Number domain unless the engine recognizes the fround
+pattern and lowers it.
+
+### f32 Casts
+
+```typescript
+function x(a: number): f32 {
+    return f32(a);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return Math.fround(a);
+}
+```
+
+```typescript
+function x(): f32 {
+    return f32(1.2);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(): number {
+    return Math.fround(1.2);
+}
+```
+
+### f32 Unary Arithmetic
+
+```typescript
+function plus(a: f32): f32 {
+    return f32(+a);
+}
+
+function neg(a: f32): f32 {
+    return f32(-a);
+}
+```
+
+should be transformed to:
+
+```typescript
+function plus(a: number): number {
+    return Math.fround(+Math.fround(a));
+}
+
+function neg(a: number): number {
+    return Math.fround(-Math.fround(a));
+}
+```
+
+### f32 Binary Arithmetic
+
+```typescript
+function add(a: f32, b: f32): f32 {
+    return f32(a + b);
+}
+
+function sub(a: f32, b: f32): f32 {
+    return f32(a - b);
+}
+
+function mul(a: f32, b: f32): f32 {
+    return f32(a * b);
+}
+
+function div(a: f32, b: f32): f32 {
+    return f32(a / b);
+}
+
+function rem(a: f32, b: f32): f32 {
+    return f32(a % b);
+}
+
+function pow(a: f32, b: f32): f32 {
+    return f32(a ** b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function add(a: number, b: number): number {
+    return Math.fround(Math.fround(a) + Math.fround(b));
+}
+
+function sub(a: number, b: number): number {
+    return Math.fround(Math.fround(a) - Math.fround(b));
+}
+
+function mul(a: number, b: number): number {
+    return Math.fround(Math.fround(a) * Math.fround(b));
+}
+
+function div(a: number, b: number): number {
+    return Math.fround(Math.fround(a) / Math.fround(b));
+}
+
+function rem(a: number, b: number): number {
+    return Math.fround(Math.fround(a) % Math.fround(b));
+}
+
+function pow(a: number, b: number): number {
+    return Math.fround(Math.fround(a) ** Math.fround(b));
+}
+```
+
+`**` remains JavaScript exponentiation followed by f32 rounding. It should be
+considered closed over the f32 branded type, but not guaranteed to lower to a
+native f32 pow instruction.
+
+### f32 Nested Arithmetic
+
+```typescript
+function x(a: f32, b: f32, c: f32, d: f32): f32 {
+    return f32(a + b * c - d);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number, c: number, d: number): number {
+    return Math.fround(
+        Math.fround(
+            Math.fround(a) +
+            Math.fround(Math.fround(b) * Math.fround(c))
+        ) -
+        Math.fround(d)
+    );
+}
+```
+
+A minifier may format this as a single expression. The important property is
+that every typed operation result is wrapped with `Math.fround`.
+
+### f32 With Numeric Literals
+
+Numeric literals can be contextually coerced to `f32`.
+
+```typescript
+function x(a: f32): f32 {
+    return f32(a * 1.2);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return Math.fround(Math.fround(a) * Math.fround(1.2));
+}
+```
+
+Plain `number` variables still require explicit casts.
+
+```typescript
+function x(a: f32, b: number): f32 {
+    return a * b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot multiply f32 by number without explicit cast
+```
+
+```typescript
+function x(a: f32, b: number): f32 {
+    return f32(a * f32(b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return Math.fround(Math.fround(a) * Math.fround(b));
+}
+```
+
+### f32 Integer Promotion
+
+```typescript
+function x(a: i32, b: u32): f32 {
+    return f32(f32(a) + f32(b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return Math.fround(Math.fround(a | 0) + Math.fround(b >>> 0));
+}
+```
+
+### f32 Disallowed Bitwise Operators
+
+Bitwise operators on `f32` should be rejected unless the value is explicitly
+converted to an integer type.
+
+```typescript
+function x(a: f32, b: f32): f32 {
+    return a & b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot apply bitwise operator '&' to f32
+```
+
+```typescript
+function x(a: f32, b: f32): i32 {
+    return i32(i32(a) & i32(b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return ((Math.fround(a) | 0) & (Math.fround(b) | 0)) | 0;
+}
+```
+
+## f64
+
+An `f64` expression is closed by unary `+`. JavaScript Number arithmetic is
+already binary64, so `f64` primarily prevents accidental non-number inputs and
+documents the numeric domain in the type system.
+
+### f64 Casts
+
+```typescript
+function x(a: number): f64 {
+    return f64(a);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return +a;
+}
+```
+
+```typescript
+function x(): f64 {
+    return f64(1.2);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(): number {
+    return +1.2;
+}
+```
+
+### f64 Unary Arithmetic
+
+```typescript
+function plus(a: f64): f64 {
+    return f64(+a);
+}
+
+function neg(a: f64): f64 {
+    return f64(-a);
+}
+```
+
+should be transformed to:
+
+```typescript
+function plus(a: number): number {
+    return +(+a);
+}
+
+function neg(a: number): number {
+    return +(-(+a));
+}
+```
+
+### f64 Binary Arithmetic
+
+```typescript
+function add(a: f64, b: f64): f64 {
+    return f64(a + b);
+}
+
+function sub(a: f64, b: f64): f64 {
+    return f64(a - b);
+}
+
+function mul(a: f64, b: f64): f64 {
+    return f64(a * b);
+}
+
+function div(a: f64, b: f64): f64 {
+    return f64(a / b);
+}
+
+function rem(a: f64, b: f64): f64 {
+    return f64(a % b);
+}
+
+function pow(a: f64, b: f64): f64 {
+    return f64(a ** b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function add(a: number, b: number): number {
+    return +((+a) + (+b));
+}
+
+function sub(a: number, b: number): number {
+    return +((+a) - (+b));
+}
+
+function mul(a: number, b: number): number {
+    return +((+a) * (+b));
+}
+
+function div(a: number, b: number): number {
+    return +((+a) / (+b));
+}
+
+function rem(a: number, b: number): number {
+    return +((+a) % (+b));
+}
+
+function pow(a: number, b: number): number {
+    return +((+a) ** (+b));
+}
+```
+
+### f64 Nested Arithmetic
+
+```typescript
+function x(a: f64, b: f64, c: f64, d: f64): f64 {
+    return f64(a + b * c - d);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number, c: number, d: number): number {
+    return +((+((+a) + (+((+b) * (+c))))) - (+d));
+}
+```
+
+The extra unary `+` calls are intentionally redundant from a pure JavaScript
+runtime perspective. They keep the generated code shaped like the declared f64
+domain and prevent string concatenation from being introduced through untyped
+inputs.
+
+### f64 With Numeric Literals
+
+Numeric literals can be contextually coerced to `f64`.
+
+```typescript
+function x(a: f64): f64 {
+    return f64(a / 1.2);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number): number {
+    return +((+a) / (+1.2));
+}
+```
+
+Plain `number` variables require explicit casts.
+
+```typescript
+function x(a: f64, b: number): f64 {
+    return a / b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot divide f64 by number without explicit cast
+```
+
+```typescript
+function x(a: f64, b: number): f64 {
+    return f64(a / f64(b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return +((+a) / (+b));
+}
+```
+
+### f64 Integer And f32 Promotion
+
+```typescript
+function x(a: i32, b: u32, c: f32): f64 {
+    return f64(f64(a) + f64(b) + f64(c));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number, c: number): number {
+    return +((+((+(a | 0)) + (+(b >>> 0)))) + (+Math.fround(c)));
+}
+```
+
+### f64 Disallowed Bitwise Operators
+
+Bitwise operators on `f64` should be rejected unless the value is explicitly
+converted to an integer type.
+
+```typescript
+function x(a: f64, b: f64): f64 {
+    return a | b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot apply bitwise operator '|' to f64
+```
+
+```typescript
+function x(a: f64, b: f64): u32 {
+    return u32(u32(a) | u32(b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return (((+a) >>> 0) | ((+b) >>> 0)) >>> 0;
+}
+```
+
+## Mixed Typed Arithmetic
+
+Operations between different branded numeric domains should require an explicit
+cast. This keeps the transform predictable and prevents accidental precision or
+signedness changes.
+
+```typescript
+function x(a: i32, b: u32): i32 {
+    return a + b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot add i32 and u32 without explicit cast
+```
+
+```typescript
+function x(a: i32, b: u32): i32 {
+    return i32(a + i32(b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return ((a | 0) + ((b >>> 0) | 0)) | 0;
+}
+```
+
+```typescript
+function x(a: i32, b: u32): u32 {
+    return u32(u32(a) + b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return (((a | 0) >>> 0) + (b >>> 0)) >>> 0;
+}
+```
+
+```typescript
+function x(a: i32, b: f32): f32 {
+    return f32(f32(a) + b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return Math.fround(Math.fround(a | 0) + Math.fround(b));
+}
+```
+
+### Storage Unions And Operation Unions
+
+Any union type that contains a numtypes domain is allowed as storage. This
+includes pure numtypes unions such as `i32 | f32`, nullable storage such as
+`i32 | null`, optional storage such as `i32 | undefined`, and mixed application
+unions such as `Promise<void> | i32`. The storage may be written explicitly, or
+it may be inferred by TypeScript when TypeScript preserves the branded union.
+
+Storage acceptance does not make the union a single arithmetic domain. A union
+value containing a numtypes domain is not a valid operand for typed arithmetic,
+bitwise, unary arithmetic, or update operations until the user narrows it or
+uses an explicit cast.
+
+```typescript
+function x(a: i32 | u32, b: i32): i32 {
+    return a + b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot add union containing i32 | u32; narrow or explicitly cast before the operation
+```
+
+Nullable storage is valid.
+
+```typescript
+function store(a: i32): i32 | null {
+    const value: i32 | null = a;
+    return value;
+}
+```
+
+should be transformed to:
+
+```typescript
+function store(a: number): number | null {
+    const value: number | null = a | 0;
+    return value;
+}
+```
+
+But nullable values must be narrowed or explicitly cast before arithmetic.
+
+```typescript
+function x(a: i32 | null, b: i32): i32 {
+    return a + b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot add union containing i32; narrow or explicitly cast before the operation
+```
+
+TypeScript control-flow narrowing is respected. Once a nullable value has been
+narrowed to the branded member, it can participate in the branded operation.
+
+```typescript
+function x(a: i32 | null, b: i32): i32 {
+    if (a != null) {
+        return i32(a + b);
+    }
+
+    return b;
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number | null, b: number): number {
+    if (a != null) {
+        return ((a | 0) + (b | 0)) | 0;
+    }
+
+    return b | 0;
+}
+```
+
+This same operation rule applies to any mixed union containing a numtype.
+
+```typescript
+declare function read(): Promise<void> | i32;
+
+function x(b: i32): i32 {
+    return read() + b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot add union containing i32; narrow or explicitly cast before the operation
+```
+
+The user must narrow the value or use an explicit cast before the operation.
+
+```typescript
+function x(a: i32 | u32, b: i32): i32 {
+    return i32(i32(a) + b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return ((a | 0) + (b | 0)) | 0;
+}
+```
+
+### Conditional Numeric Unions
+
+A conditional expression may produce a numeric-union expression when possible
+branches are closed over different numtypes domains, or when a closed numtypes
+branch is selected with a non-numtypes branch such as `null`, `undefined`, or an
+application object. The result must be stored in a matching union annotation,
+returned from a matching union return type, preserved by TypeScript's inferred
+storage type, or explicitly cast before it is used as a single-domain value.
+
+```typescript
+function x(cond: boolean, a: i32, b: f32) {
+    const value = cond ? a : b * f32(1);
+    return value;
+}
+```
+
+should be a compile error:
+
+```bash
+error: result of i32 | f32 expression is assigned to untyped variable 'value'; use a matching union annotation with checked casts for number-typed branches or explicitly escape to a non-numtypes type
+```
+
+The lvalue must preserve the union explicitly, and branches whose TypeScript
+expression type widens to `number` must be closed with checked casts.
+
+```typescript
+function x(cond: boolean, a: i32, b: f32): i32 | f32 {
+    const value: i32 | f32 = cond ? a : f32(b * f32(1));
+    return value;
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(cond: boolean, a: number, b: number): number {
+    const value: number = cond ? a | 0 : Math.fround(Math.fround(b) * Math.fround(1));
+    return value;
+}
+```
+
+The transformer closes each branch independently. It must not apply one final
+coercion to the whole conditional, because `i32 | f32` is not one numeric
+domain.
+
+A numeric-union conditional is still not a valid operand without narrowing or
+an explicit cast.
+
+```typescript
+function x(cond: boolean, a: i32, b: f32): i32 {
+    return (cond ? a : b) + i32(1);
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot add union containing i32 | f32; narrow or explicitly cast before the operation
+```
+
+A conditional that selects nullable storage remains a union operand until it is
+narrowed. Even if every numtypes-bearing branch contains only `i32`, the
+presence of `null` means the whole conditional is not an `i32` operand.
+
+```typescript
+function x(cond: boolean, a: i32 | null, b: i32): i32 {
+    return (cond ? a : b) + b;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot add union containing i32; narrow or explicitly cast before the operation
+```
+
+When an operation result is unioned with a non-numtypes branch, TypeScript would
+infer a plain `number` union such as `number | null`. The transformer must treat
+that as a domain leak unless the lvalue preserves the branded member with a
+matching union annotation.
+
+```typescript
+function x(cond: boolean, a: i32, b: i32) {
+    const value = cond ? a + b : null;
+    return value;
+}
+```
+
+should be a compile error:
+
+```bash
+error: result of union containing i32 expression is assigned to untyped variable 'value'; use a matching union annotation with checked casts for number-typed branches or explicitly escape to a non-numtypes type
+```
+
+```typescript
+function x(cond: boolean, a: i32, b: i32): i32 | null {
+    const value: i32 | null = cond ? i32(a + b) : null;
+    return value;
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(cond: boolean, a: number, b: number): number | null {
+    const value: number | null = cond ? ((a | 0) + (b | 0)) | 0 : null;
+    return value;
+}
+```
+
+Plain `number` branches do not become part of a numeric union. They require an
+explicit cast to one of the union domains.
+
+```typescript
+function x(cond: boolean, a: i32, n: number): i32 | f32 {
+    return cond ? a : n;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot select i32 and number without explicit cast
+```
+
+The same rule applies when the numtypes branch is already stored in a union.
+
+```typescript
+function x(cond: boolean, a: i32 | null, n: number) {
+    return cond ? a : n;
+}
+```
+
+should be a compile error:
+
+```bash
+error: cannot select union containing i32 and number without explicit cast
+```
+
+```typescript
+function x(a: f32, b: f64): f64 {
+    return f64(f64(a) + b);
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    return +((+Math.fround(a)) + (+b));
+}
+```
+
+## Assignments And Updates
+
+When assigning to a typed local, parameter, property, or array element, the user
+source must still satisfy TypeScript's branded type system. If the right-hand
+side is a raw operation result, it must be wrapped in the checked cast for the
+target storage domain. The transformer then erases that checked cast into the
+closed operation.
+
+```typescript
+function x(a: i32, b: i32): i32 {
+    let c: i32 = i32(a + b);
+    c = i32(c * 2);
+    return c;
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    let c: number = ((a | 0) + (b | 0)) | 0;
+    c = Math.imul(c, 2 | 0);
+    return c;
+}
+```
+
+A domain-bound expression must not initialize unannotated storage if TypeScript
+would infer that storage as plain `number`.
+
+```typescript
+function x(a: i32, b: i32) {
+    const c = a + b;
+    return c;
+}
+```
+
+should be a compile error:
+
+```bash
+error: result of i32 operation is assigned to untyped variable 'c'; use a checked cast such as i32(...) at the boundary or explicitly escape to a non-numtypes type
+```
+
+If non-domain storage is intentional, the user must write an explicit escape:
+
+```typescript
+function x(a: i32, b: i32) {
+    const c = (a + b) as number;
+    return c;
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number) {
+    const c = ((a | 0) + (b | 0)) | 0;
+    return c;
+}
+```
+
+The user must preserve the domain at the lvalue boundary with an annotation and,
+when TypeScript sees the expression as `number`, with a checked cast.
+
+```typescript
+function x(a: i32, b: i32): i32 {
+    const c: i32 = i32(a + b);
+    return c;
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    const c: number = ((a | 0) + (b | 0)) | 0;
+    return c;
+}
+```
+
+Object literal properties and array literal elements are also lvalue boundaries.
+If a domain-bound operation is placed into an untyped aggregate, TypeScript will
+infer a plain `number` property or element type, so the transformer must reject
+it.
+
+```typescript
+function objectValue(a: i32, b: i32) {
+    const box = { value: a + b };
+    return box;
+}
+
+function arrayValue(a: i32, b: i32) {
+    const values = [a + b];
+    return values;
+}
+```
+
+should be compile errors:
+
+```bash
+error: result of i32 operation initializes object property 'value' without a checked cast
+error: result of i32 operation initializes an array element without a checked cast
+```
+
+Typed aggregate storage records the domain, but operation results still need a
+checked cast at the branded element or property boundary.
+
+```typescript
+function objectValue(a: i32, b: i32): { value: i32 } {
+    return { value: i32(a + b) };
+}
+
+function arrayValue(a: i32, b: i32): i32[] {
+    const values: i32[] = [i32(a + b)];
+    values[0] = i32(a + b);
+    return values;
+}
+```
+
+should be transformed to:
+
+```typescript
+function objectValue(a: number, b: number): { value: number } {
+    return { value: ((a | 0) + (b | 0)) | 0 };
+}
+
+function arrayValue(a: number, b: number): number[] {
+    const values: number[] = [((a | 0) + (b | 0)) | 0];
+    values[0] = ((a | 0) + (b | 0)) | 0;
+    return values;
+}
+```
+
+Array methods and ordinary function calls are not implicit domain contexts. For
+branded call slots, the transformer relies on TypeScript to reject `number`
+arguments where a branded type is required, and the user must cross the call
+boundary with an explicit cast.
+
+```typescript
+function arrayPush(a: i32, b: i32, values: i32[]) {
+    values.push(a + b);
+}
+```
+
+is rejected by TypeScript because `a + b` has TypeScript type `number`.
+
+```typescript
+function arrayPush(a: i32, b: i32, values: i32[]) {
+    values.push(i32(a + b));
+}
+```
+
+should be transformed to:
+
+```typescript
+function arrayPush(a: number, b: number, values: number[]) {
+    values.push(((a | 0) + (b | 0)) | 0);
+}
+```
+
+For plain `number` call slots, TypeScript allows the operation result, so the
+transformer owns the explicit-escape diagnostic.
+
+```typescript
+declare function take(...values: number[]): void;
+
+function arrayPush(a: i32, b: i32, values: number[]) {
+    take(a + b);
+    values.push(a + b);
+}
+```
+
+should be compile errors unless the operation result is explicitly escaped, for
+example with `(a + b) as number`.
+
+An explicit cast call can also make the inferred variable type branded before
+the transformer erases the call.
+
+```typescript
+function x(a: i32, b: i32) {
+    const c = i32(a + b);
+    return c;
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    const c: number = ((a | 0) + (b | 0)) | 0;
+    return c;
+}
+```
+
+Compound assignment to branded storage is not valid TypeScript. The operation
+result has TypeScript type `number`, and TypeScript rejects assigning that result
+back into an `i32`, `u32`, `f32`, or `f64` lvalue. Users should write the
+equivalent checked assignment explicitly.
+
+```typescript
+function x(a: i32, b: i32): i32 {
+    a = i32(a + b);
+    a = i32(a * 3);
+    return a;
+}
+```
+
+should be transformed to:
+
+```typescript
+function x(a: number, b: number): number {
+    a = ((a | 0) + (b | 0)) | 0;
+    a = Math.imul(a, 3 | 0);
+    return a;
+}
+```
+
+The same source rule applies to every operation that would otherwise be written
+as a compound assignment:
+
+| Target | Explicit checked assignment form |
+| --- | --- |
+| `i32` | `x = i32(x + y)`, `x = i32(x * y)`, `x = i32(x & y)`, etc. |
+| `u32` | `x = u32(x + y)`, `x = u32(x * y)`, `x = u32(x >>> y)`, etc. |
+| `f32` | `x = f32(x + y)`, `x = f32(x * y)`, etc. |
+| `f64` | `x = f64(x + y)`, `x = f64(x * y)`, etc. |
+
+Prefix and postfix updates should preserve JavaScript value-result semantics,
+but the stored value must be closed. Standalone updates are valid operation
+sites. If the update result itself crosses a branded boundary, wrap that update
+expression in the checked cast for the target domain.
+
+```typescript
+function pre(a: i32): i32 {
+    return i32(++a);
+}
+
+function post(a: i32): i32 {
+    return i32(a++);
+}
+
+function dec(a: i32): i32 {
+    return i32(--a);
+}
+```
+
+can be transformed conceptually to:
+
+```typescript
+function pre(a: number): number {
+    a = ((a | 0) + (1 | 0)) | 0;
+    return a | 0;
+}
+
+function post(a: number): number {
+    const old: number = a | 0;
+    a = ((a | 0) + (1 | 0)) | 0;
+    return old | 0;
+}
+
+function dec(a: number): number {
+    a = ((a | 0) - (1 | 0)) | 0;
+    return a | 0;
+}
+```
+
+For complex left-hand sides, the actual implementation must preserve single
+evaluation of the receiver, property key, and index expression.
+
+## Operator Coverage Summary
+
+The arithmetic closure surface is:
+
+| Type | Unary | Binary arithmetic | Integer bitwise |
+| --- | --- | --- | --- |
+| `i32` | `+`, `-` | `+`, `-`, `*`, `/`, `%`, `**` | `&`, `|`, `^`, `<<`, `>>`, `>>>` |
+| `u32` | `+`, `-` | `+`, `-`, `*`, `/`, `%`, `**` | `&`, `|`, `^`, `<<`, `>>`, `>>>` |
+| `f32` | `+`, `-` | `+`, `-`, `*`, `/`, `%`, `**` | explicit integer cast required |
+| `f64` | `+`, `-` | `+`, `-`, `*`, `/`, `%`, `**` | explicit integer cast required |
+
+The transformer should not change comparison, logical, or conditional expression
+truthiness semantics. If a branch or condition returns a branded numeric value,
+only the selected result expression should be closed to the contextual target
+type.