numtypes 0.0.0

package/docs/lowering-optimization-spec.md

@@ -0,0 +1,1020 @@
+# Coercion Optimization Spec
+
+This document defines the cleanup pass for removing redundant numeric coercions
+that were generated by the numtypes lowering and for propagating local
+numeric-domain proofs.
+
+The transform spec in `docs/transform-spec.md` defines the conservative
+correctness lowering. This document defines a later proof-based optimization
+layer over the generated JavaScript AST. The pass may use ordinary JavaScript
+coercion expressions as proof sources, but it may remove only coercion
+expressions that the numtypes lowering generated. The optimization must never
+be required for correctness.
+
+The intended pipeline is deliberately two-step:
+
+1. The early transform aggressively inserts coercions wherever a domain boundary
+   might need one.
+2. The later optimization pass analyzes the resulting JavaScript and removes
+   generated coercions that are statically proven redundant.
+
+This design keeps correctness simple. The first pass is allowed to be
+over-conservative. The second pass is allowed to be purely local and
+proof-driven.
+
+The implementation tracks symbol-based local proofs inside function-like bodies,
+handles straight-line statements, branches, loops, `switch`, and `try` joins,
+recognizes the core coercion idioms plus `Math.imul`, sinks some redundant u32
+closures through low32 bit-pattern locals, and invalidates only captured mutable
+local proofs at possible reentry points such as unknown calls, getters, setters,
+and computed element access. More aggressive range analysis, heap alias
+analysis, async/generator suspension modeling, and closure escape precision can
+be added without changing the correctness lowering.
+
+## Motivation
+
+The conservative numtypes lowering closes every typed operation at the operand
+and result boundaries:
+
+```typescript
+function add(a: f64, b: f64): f64 {
+    a = f64(a);
+    b = f64(b);
+
+    return f64(a + b);
+}
+```
+
+Naive lowering may produce:
+
+```javascript
+function add(a, b) {
+    a = +a;
+    b = +b;
+
+    return +(+a + +b);
+}
+```
+
+After `a = +a` and `b = +b`, the pass can prove that both local variables hold
+primitive number values. For `f64`, JavaScript arithmetic over primitive numbers
+already produces a Number value, so the return can be simplified:
+
+```javascript
+function add(a, b) {
+    a = +a;
+    b = +b;
+
+    return a + b;
+}
+```
+
+The same idea applies to `i32`, `u32`, and `f32`, but each domain has different
+closure rules. In particular, proving that operands are already closed does not
+always prove that the next operation result is closed.
+
+This proof does not have to come from numtypes types. It can come from ordinary
+JavaScript syntax:
+
+```javascript
+function add(a, b) {
+    a = +a;
+    b = +b;
+
+    return +(a + b);
+}
+```
+
+The assignments prove that `a` and `b` are primitive Number values for later
+uses in the same control-flow region. If the final unary plus was generated by
+numtypes lowering, it is redundant and can be removed. If the final unary plus
+was written by the user, it must remain. This is similar in spirit to constant
+folding, but the rewrite authority is limited to generated coercions.
+
+The important design point is that the optimizer is not a numtypes type pass.
+It is a generated-coercion cleanup pass with JavaScript proof facts. Numtypes
+lowering produces the removable coercion idioms; user-authored JavaScript can
+produce proof facts, but its coercion expressions are not removed.
+
+## Goals
+
+- remove generated coercions that are provably redundant;
+- use JavaScript AST shapes as proof sources, regardless of whether they came
+  from numtypes lowering or user-authored JavaScript;
+- preserve user-authored coercion expressions even when they are redundant;
+- allow the early transform to insert redundant coercions freely;
+- keep the conservative numtypes transform as the correctness baseline;
+- operate with symbol identity and control-flow facts, not name-based maps;
+- preserve all observable JavaScript behavior of coercions;
+- support function-level reasoning for locals, parameters, branches, loops,
+  closures, async functions, and generators;
+- keep diagnostics independent from optimization.
+
+## Non-Goals
+
+- no range analysis in the first implementation;
+- no interprocedural proof propagation across function calls;
+- no property, ordinary array, object-shape, or heap alias analysis in the first
+  implementation;
+- no semantic rewrite that inserts new normalization assignments unless a later
+  explicit hoisting phase defines it separately.
+
+## Terminology
+
+`Correctness lowering` means the numtypes transform that inserts the full
+coercion shape required by `docs/transform-spec.md`.
+
+`Optimization pass` means a function-scoped JavaScript AST pass that removes
+redundant coercions when a proof exists.
+
+`Runtime proof` means a static fact that a local expression is already closed
+over a numeric domain at runtime.
+
+`Storage domain` means the TypeScript/numtypes domain used for operation
+dispatch. A storage domain is not a runtime proof.
+
+`Closed value` means a value that has already passed through the domain closure
+operation:
+
+```text
+i32: x | 0
+u32: x >>> 0
+f32: Math.fround(x)
+f64: +x
+```
+
+`Low32 bit-pattern value` means a JavaScript Number whose low 32 bits are known
+to match the corresponding u32 value, even if the Number itself is a signed
+int32 result. For example, `x ^ y` and `Math.imul(x, y)` can produce negative
+Numbers, but their low 32 bits are exactly what a later `>>> 0` observes.
+
+`Coercion expression` means a JavaScript expression that closes its input over a
+numeric domain:
+
+```text
+i32: expr | 0
+u32: expr >>> 0
+f32: Math.fround(expr)
+f64: +expr
+```
+
+The optimizer may reason about any such expression, whether it was emitted by
+numtypes lowering or written directly by the user. It may remove only coercion
+expressions marked as generated by the numtypes lowering. It must use
+JavaScript semantics, not TypeScript types, to decide whether a generated
+rewrite is valid.
+
+`Closed producer expression` means an expression that produces a closed value
+without being a direct one-argument coercion. The initial producer set is:
+
+```text
+i32: Math.imul(left, right)
+```
+
+`Math.imul` returns a signed int32 Number, so a following `| 0` is redundant when
+the `Math.imul` call is the expression being closed.
+
+`Math.fround` and `Math.imul` are recognized only as ECMAScript intrinsics. A
+lexically shadowed `Math` binding must not be treated as a numeric coercion
+source. The optimization assumes these built-ins are not monkey-patched; code
+that replaces `Math.fround` or `Math.imul` is outside the supported optimization
+semantic model.
+
+## Fundamental Constraint
+
+Numtypes annotations do not prove runtime value shape.
+
+```typescript
+function f(a: i32, b: i32): i32 {
+    return i32(a + b);
+}
+```
+
+The annotations tell the transformer to dispatch `a + b` as an `i32`
+operation. They do not prove that callers pass values already closed to i32.
+Therefore this cannot be optimized to:
+
+```javascript
+function f(a, b) {
+    return a + b; // wrong
+}
+```
+
+The optimizer may use a runtime proof only after it sees a dominating coercion
+expression or assignment from a proven closed expression:
+
+```typescript
+function f(a: i32, b: i32): i32 {
+    a = i32(a);
+    b = i32(b);
+
+    return i32(a + b);
+}
+```
+
+can become:
+
+```javascript
+function f(a, b) {
+    a = a | 0;
+    b = b | 0;
+
+    return (a + b) | 0;
+}
+```
+
+The operand coercions are redundant. The result coercion is still required
+because i32 addition can overflow.
+
+Plain JavaScript can provide proof facts, but user-authored coercions are not
+removed:
+
+```javascript
+function f(a, b) {
+    a = a | 0;
+    b = b | 0;
+
+    return ((a | 0) + (b | 0)) | 0;
+}
+```
+
+must remain:
+
+```javascript
+function f(a, b) {
+    a = a | 0;
+    b = b | 0;
+
+    return ((a | 0) + (b | 0)) | 0;
+}
+```
+
+If a later numtypes-generated coercion uses the same proven locals, that
+generated coercion may be removed. The hand-written coercions above still stay
+in the output.
+
+## Proof Domain
+
+The pass tracks facts for local bindings and temporary expressions:
+
+```text
+unknown
+closed-i32
+closed-u32
+closed-f32
+closed-f64
+```
+
+`closed-f64` means the value is known to be a primitive JavaScript Number. It is
+not a stronger machine-level guarantee such as "stored as a V8 HeapNumber".
+
+The implementation tracks local bindings whose symbol is local to the current
+function-like body:
+
+- parameters;
+- `let` and `const` locals;
+- compiler-created temporaries, if present;
+- `var` locals, if their function scope and hoisting behavior are modeled
+  conservatively.
+
+The implementation does not track:
+
+- object properties;
+- element accesses;
+- globals;
+- imports;
+- exported mutable bindings;
+- captured mutable bindings after a possible external reentry point.
+
+### Opt-In TypedArray Element Proofs
+
+TypedArray element reads are not treated as closed values by default. A type
+annotation such as `Float64Array` or `Int32Array` can be wrong at runtime, and
+out-of-bounds reads return `undefined`:
+
+```javascript
++values[index] // Number conversion: undefined becomes NaN
+values[index]  // raw read: undefined
+```
+
+Therefore removing a generated coercion around a typed-array element read is
+allowed only when the user enables `optimizeTypedArrayElementAccess` and the
+optimizer also proves an in-bounds access.
+
+The option is an explicit runtime invariant: the user is asserting that values
+typed as numeric TypedArrays are actually the corresponding intrinsic
+TypedArray objects for the optimized region, and that their buffers are not
+detached while the proof is used. Without that opt-in, generated coercions
+around typed-array reads are preserved.
+
+The initial bounds proof is deliberately narrow. It recognizes simple counted
+loops such as:
+
+```typescript
+for (let i = 0; i < values.length; i += 1) {
+    out[i] = i32(values[i]);
+}
+
+for (let i = 0; i + 3 < values.length; i += 4) {
+    out[i / 4] = f64(values[i] + values[i + 1]);
+}
+```
+
+When the proof holds, element reads are treated as:
+
+```text
+Int8Array, Int16Array, Int32Array         -> closed-i32
+Uint8Array, Uint8ClampedArray, Uint16Array,
+Uint32Array                              -> closed-u32
+Float32Array                             -> closed-f32
+Float64Array                             -> closed-f64
+```
+
+This proof removes only generated coercions. A user-authored coercion around a
+typed-array read is still preserved.
+
+Property and element reads/writes may execute arbitrary code through getters,
+setters, proxies, computed keys, or iterator machinery. They do not by
+themselves mutate a non-captured local primitive binding in the current
+activation record. Therefore they preserve proofs for non-captured locals and
+invalidate proofs for mutable locals captured by nested functions.
+
+Expression statements do not create local binding proofs by themselves:
+
+```javascript
++a; // converts the current value, but does not assign it back to a
+```
+
+The next read of `a` is not proven `closed-f64`. A proof is created by a write
+or declaration that stores the coerced value:
+
+```javascript
+a = +a;       // a becomes closed-f64
+const x = +a; // x becomes closed-f64
+```
+
+## Pass Placement
+
+The preferred architecture is:
+
+```text
+source analysis
+  -> aggressive correctness lowering
+  -> function-level JavaScript coercion optimization
+  -> final emit
+```
+
+The optimization pass can also run on already-emitted JavaScript before final
+printing. It does not require numtypes metadata. Numtypes lowering metadata may
+help preserve source maps or debugging information, but it is not part of the
+proof model.
+
+The optimizer should recognize coercion idioms structurally from the AST. It
+must still preserve observable JavaScript behavior. A generated coercion may be
+removed only when evaluating the replacement expression has the same effects
+and value as evaluating the original expression. A user-authored coercion must
+not be removed.
+
+## Domain-Specific Elision Rules
+
+### f64
+
+For `f64`, the closure operation is unary `+`, which performs `ToNumber`.
+
+Generated `+expr` may be removed only when `expr` is already proven
+`closed-f64`. User-authored `+expr` is preserved.
+
+If both operands of a numeric operation are proven `closed-f64`, the result of
+ordinary JavaScript arithmetic is also `closed-f64`.
+
+```javascript
+a        // removable when a is proven closed-f64
+(a + b)  // removable when a + b is proven closed-f64
+```
+
+Example:
+
+```javascript
+a;
++a;
+```
+
+can become:
+
+```javascript
+a;
+```
+
+only if `a` is already proven `closed-f64`.
+
+Without proof, `+a` must stay. Removing it can change observable behavior:
+
+```javascript
++"1"      // 1
+"1"       // "1"
++1n       // throws
+1n        // 1n
+```
+
+### f32
+
+For `f32`, the closure operation is `Math.fround`.
+
+Generated `Math.fround(expr)` may be removed only when `expr` is already proven
+`closed-f32`. User-authored `Math.fround(expr)` is preserved.
+
+If both operands are proven `closed-f32`, JavaScript still evaluates arithmetic
+in Number precision. The operation result is not automatically `closed-f32`.
+The result closure must remain unless a future exactness or range analysis
+proves it unnecessary.
+
+```javascript
+Math.fround(Math.fround(a) + Math.fround(b))
+```
+
+can become:
+
+```javascript
+Math.fround(a + b)
+```
+
+when `a` and `b` are proven `closed-f32`.
+
+It cannot become:
+
+```javascript
+a + b
+```
+
+because `a + b` is computed as a JavaScript Number.
+
+### i32
+
+For `i32`, the closure operation is `| 0`.
+
+Generated operand closures may be removed when the operand is proven
+`closed-i32`.
+
+Result closures for arithmetic operators must usually remain:
+
+```javascript
+((a | 0) + (b | 0)) | 0
+```
+
+can become:
+
+```javascript
+(a + b) | 0
+```
+
+when `a` and `b` are proven `closed-i32`.
+
+It cannot become:
+
+```javascript
+a + b
+```
+
+because i32 addition can overflow:
+
+```javascript
+2147483647 + 1        // 2147483648
+(2147483647 + 1) | 0 // -2147483648
+```
+
+Some operators are closure-preserving for i32:
+
+```text
+~x
+x | y
+x & y
+x ^ y
+x << y
+x >> y
+```
+
+For these operators, a generated i32 result closure is redundant when every
+required operand is proven closed and the shift count has been safely coerced.
+
+Unsigned right shift `>>>` produces a u32-style result, not an i32 result. An
+i32 boundary after `>>>` must not be removed unless the target domain proof is
+explicitly re-established.
+
+`Math.imul(left, right)` is an i32 producer. If `left` or `right` are already
+proven `closed-i32`, generated operand coercions may be removed. The call
+result is itself proven `closed-i32`, so a generated direct result closure is
+redundant:
+
+```javascript
+Math.imul(a | 0, b | 0) | 0
+```
+
+can become:
+
+```javascript
+Math.imul(a, b)
+```
+
+when `a` and `b` are proven `closed-i32`.
+
+### u32
+
+For `u32`, the closure operation is `>>> 0`.
+
+Generated operand closures may be removed when the operand is proven
+`closed-u32`.
+
+Result closures for arithmetic operators must usually remain:
+
+```javascript
+((a >>> 0) + (b >>> 0)) >>> 0
+```
+
+can become:
+
+```javascript
+(a + b) >>> 0
+```
+
+when `a` and `b` are proven `closed-u32`.
+
+Most JavaScript bitwise operators return signed int32 results. Therefore u32
+result closures usually remain for:
+
+```text
+|
+&
+^
+<<
+>>
+~
+```
+
+Unsigned right shift `>>>` produces a non-negative uint32-range Number, so a
+u32 result closure after `x >>> y` can be redundant when the operands and shift
+count are proven safe.
+
+Bitwise `&` with a non-negative int31 literal mask also produces a non-negative
+int32 Number. Therefore a generated u32 closure around expressions such as
+`input[i] & 0xff` may be removed:
+
+```javascript
+(input[i] & 0xff) >>> 0
+```
+
+can become:
+
+```javascript
+input[i] & 0xff
+```
+
+Only masks in `0..0x7fffffff` qualify. A mask with the high signed bit set can
+produce a negative int32 Number and must not be treated as closed-u32.
+
+Modulo by a positive integer literal is a u32 producer when the left operand is
+already proven closed-u32. The result is in `0..modulus - 1`, so a generated
+closure around the modulo result is redundant:
+
+```javascript
+((x >>> 0) % 65521) >>> 0
+```
+
+can become:
+
+```javascript
+(x >>> 0) % 65521
+```
+
+`Math.imul` returns signed int32. A u32 multiplication boundary still needs
+`>>> 0`.
+
+The optimizer may sink a u32 result closure from a local assignment when all of
+these are true:
+
+- the assignment target is a tracked local binding;
+- the target is already known to hold a u32/low32 value, or the target is a new
+  local initialized by the assignment;
+- the expression being closed is a low32 producer such as a bitwise expression,
+  an unshadowed `Math.imul(...)`, a u32 numeric literal, or another tracked
+  low32 local;
+- later reads that observe the numeric value, such as returns, ordinary call
+  arguments, property/index keys, or array/property stores, are re-closed with
+  `>>> 0`.
+
+Example:
+
+```javascript
+let x = 0x9e3779b9;
+for (let i = 0; i < count; i += 1) {
+    x = (x ^ (x << 13)) >>> 0;
+    x = (x ^ (x >>> 17)) >>> 0;
+    x = (x ^ (x << 5)) >>> 0;
+    out[i] = x;
+}
+```
+
+can become:
+
+```javascript
+let x = 0x9e3779b9;
+for (let i = 0; i < count; i += 1) {
+    x = x ^ (x << 13);
+    x = x ^ (x >>> 17);
+    x = x ^ (x << 5);
+    out[i] = x >>> 0;
+}
+```
+
+The intermediate signedness is not observable because subsequent bitwise
+operators and `Math.imul` consume only the low 32 bits. The store to `out[i]`
+is a value observation, so the closure is restored there. This is intentionally
+different from proving `closed-u32`: the local may no longer be a non-negative
+u32 Number between the sunk assignment and the next observation.
+
+This sinking is not applied to unbounded arithmetic producers such as
+`(x + c) >>> 0` across loop back edges. Repeatedly removing those closures can
+let the JavaScript Number grow past the exact integer range and corrupt low
+bits before the eventual `>>> 0`.
+
+## Transfer Rules
+
+### Coercions
+
+A coercion expression creates a runtime proof for its result:
+
+```javascript
+const x = +value;
+const y = value | 0;
+const z = value >>> 0;
+const w = Math.fround(value);
+```
+
+After these declarations:
+
+- `x` is proven `closed-f64`;
+- `y` is proven `closed-i32`;
+- `z` is proven `closed-u32`;
+- `w` is proven `closed-f32`.
+
+Checked numtypes casts participate only after they have been lowered into these
+JavaScript coercion expressions.
+
+If the argument expression is already proven closed in the same domain, the
+coercion can be removed:
+
+```javascript
+const y = +x;
+```
+
+can become:
+
+```javascript
+const y = x;
+```
+
+only when `x` is proven `closed-f64`.
+
+### Assignments
+
+An assignment to a tracked local binding updates that binding's proof:
+
+```javascript
+a = +a;     // a becomes closed-f64
+a = a + b;  // a becomes closed-f64 only if a + b is proven closed-f64
+a = read(); // a becomes unknown
+```
+
+Compound assignments and updates are treated as read-modify-write operations.
+The initial implementation invalidates the target proof for compound
+assignments and updates. A later implementation may preserve a proof when it can
+model the exact lowered write expression and result domain.
+
+### Branches
+
+At control-flow joins, facts are merged by intersection:
+
+```text
+closed-i32 + closed-i32 -> closed-i32
+closed-i32 + unknown    -> unknown
+closed-i32 + closed-u32 -> unknown
+```
+
+Example:
+
+```javascript
+if (flag) {
+    a = a | 0;
+}
+
+return +a;
+```
+
+`a` is not proven closed after the branch because the false path does not close
+it.
+
+### Loops
+
+Loop body optimization uses the facts available at the loop header. After a
+`for`, `while`, `for...in`, or `for...of` loop, surviving facts are the
+intersection of the zero-iteration entry facts and the facts after one optimized
+iteration. After a `do...while` loop, surviving facts are the facts after the
+optimized body and condition, because the body runs at least once.
+
+This is not a full fixed-point CFG. It is deliberately a pragmatic local loop
+summary: a fact may survive only when the visible loop body preserves the same
+domain. Unknown calls, getters, setters, iterator reentry, and computed element
+access still invalidate captured mutable locals.
+
+### Calls
+
+Function calls are arbitrary user code.
+
+Unknown calls preserve proofs for non-captured local primitive bindings, because
+arbitrary called code cannot reassign those bindings in the current activation
+record. Unknown calls invalidate mutable locals captured by nested functions,
+because a reentrant call may invoke an escaped closure that mutates them.
+
+Method calls whose callee is a property or element access are treated as a
+property/element read before argument evaluation. That reentry point preserves
+non-captured local proofs and invalidates captured mutable local proofs unless
+the callee is a recognized intrinsic such as unshadowed `Math.fround` or
+`Math.imul`.
+
+The pass must invalidate:
+
+- property and element proofs;
+- globals and imports;
+- captured mutable locals when a call, getter, setter, iterator, `await`, or
+  `yield` might invoke or expose a closure that can mutate them;
+- any proof derived from values that can be affected by user-defined coercion.
+
+Call arguments are still evaluated before the call. If a coercion has observable
+`ToNumber`, `ToInt32`, `ToUint32`, or `Math.fround` effects, it cannot be
+removed without proof.
+
+### Closures
+
+Each function-like body is analyzed independently.
+
+Captured immutable values:
+
+- a `const` local initialized from a proven closed expression can be used as a
+  proof inside nested functions if it cannot be reassigned;
+- this is safe only for primitive local bindings, not object properties.
+
+Captured mutable values:
+
+- a `let` or `var` local referenced by a nested function is unstable;
+- the outer analysis must invalidate it at any point where the nested function
+  may have run;
+- the nested function analysis must treat the captured binding as unknown unless
+  it can prove all writes itself.
+
+Escaped closures:
+
+- if a nested function is returned, stored, passed, or otherwise escapes, any
+  mutable binding it captures must be treated as externally mutable after the
+  escape point.
+
+### Switch And Try
+
+`switch` clauses are optimized independently from the facts available after the
+discriminant expression. Clause exit facts are merged by intersection. Case
+expression side effects participate in the clause-local facts, but the
+implementation does not rely on fallthrough-sensitive proof propagation.
+
+`try` and `catch` blocks are optimized from the incoming facts and joined by
+intersection. A `finally` block is optimized from that join and its exit facts
+become the facts after the whole `try` statement.
+
+### Async Functions
+
+`await` is a suspension point. Other code may run before the function resumes.
+
+Across `await`, proofs for non-captured local primitive bindings may survive.
+Proofs for captured mutable locals, properties, elements, globals, imports, and
+heap state must be invalidated.
+
+The awaited expression itself can run arbitrary code through thenable
+resolution, so coercions inside or around the awaited expression may be removed
+only with local expression proof.
+
+### Generators
+
+`yield` and `yield*` are suspension points.
+
+The same invalidation rules as `await` apply. Additionally, `yield*` interacts
+with arbitrary iterators and must be treated as an unknown call plus a
+suspension point.
+
+### Exceptions and Finally Blocks
+
+Exceptional control flow participates in joins.
+
+If a coercion can throw and a surrounding `try`/`catch` observes that throw, the
+coercion cannot be removed unless the input is already proven closed.
+
+`finally` blocks must be modeled as writes that occur on both normal and
+exceptional exits.
+
+## Function-Level Algorithm
+
+The implementation should analyze one function-like body at a time.
+
+Suggested stages:
+
+1. Build a symbol-based local binding table.
+2. Mark captured bindings and escaped closures.
+3. Build or approximate a control-flow graph.
+4. Seed entry facts:
+   - parameters start as `unknown`, even when annotated as numtypes;
+   - locals start as `unknown` until their initializer is analyzed;
+   - compiler-created temporaries may start with the proof of their initializer.
+5. Run forward data-flow analysis to a fixed point.
+6. Record expression proofs for coercion expressions and ordinary operations.
+7. Rewrite coercions whose input expression proof makes them redundant.
+
+The pass may be implemented with a conservative AST walk before a full CFG is
+available, but every unsupported control-flow construct must fall back to
+keeping the coercion.
+
+## Examples
+
+### f64 Parameter Normalization
+
+Input:
+
+```typescript
+function dot(a: f64, b: f64, c: f64): f64 {
+    a = f64(a);
+    b = f64(b);
+    c = f64(c);
+
+    return f64(a * b + c);
+}
+```
+
+Correctness lowering:
+
+```javascript
+function dot(a, b, c) {
+    a = +a;
+    b = +b;
+    c = +c;
+
+    return +(+((+a * +b)) + +c);
+}
+```
+
+Optimized lowering:
+
+```javascript
+function dot(a, b, c) {
+    a = +a;
+    b = +b;
+    c = +c;
+
+    return a * b + c;
+}
+```
+
+### i32 Operand Elision Only
+
+Input:
+
+```typescript
+function add(a: i32, b: i32): i32 {
+    a = i32(a);
+    b = i32(b);
+
+    return i32(a + b);
+}
+```
+
+Optimized lowering:
+
+```javascript
+function add(a, b) {
+    a = a | 0;
+    b = b | 0;
+
+    return (a + b) | 0;
+}
+```
+
+The final `| 0` remains because addition can overflow.
+
+### f32 Operand Elision Only
+
+Input:
+
+```typescript
+function add(a: f32, b: f32): f32 {
+    a = f32(a);
+    b = f32(b);
+
+    return f32(a + b);
+}
+```
+
+Optimized lowering:
+
+```javascript
+function add(a, b) {
+    a = Math.fround(a);
+    b = Math.fround(b);
+
+    return Math.fround(a + b);
+}
+```
+
+The final `Math.fround` remains because JavaScript computes `a + b` as Number.
+
+### Branch Join
+
+Input:
+
+```typescript
+function maybe(flag: boolean, a: f64, b: f64): f64 {
+    if (flag) {
+        a = f64(a);
+    }
+
+    b = f64(b);
+
+    return f64(a + b);
+}
+```
+
+`b` is proven `closed-f64`, but `a` is not. The result cannot be simplified to
+`a + b`.
+
+### Captured Mutable Binding
+
+Input:
+
+```typescript
+function outer(a: f64): () => f64 {
+    a = f64(a);
+
+    function mutate(): void {
+        a = readUnknown() as f64;
+    }
+
+    escape(mutate);
+
+    return function inner(): f64 {
+        return f64(a + f64(1));
+    };
+}
+```
+
+After `mutate` escapes, `a` is no longer stable. The nested `inner` analysis
+must treat `a` as unknown and keep the required coercions.
+
+### Await Suspension
+
+Input:
+
+```typescript
+async function run(a: f64): Promise<f64> {
+    a = f64(a);
+
+    await task();
+
+    return f64(a + f64(1));
+}
+```
+
+If `a` is a non-captured local primitive binding, the proof for `a` may survive
+the `await`. If `a` is captured by an escaped closure, it must be invalidated at
+the `await`.
+
+## Safety Checklist
+
+Before removing a coercion, the optimizer must prove all of the following:
+
+- the input expression is already closed in the same domain;
+- removing the coercion does not remove observable conversion or throw behavior;
+- all control-flow paths reaching the coercion carry the proof;
+- no alias, closure, call, `await`, `yield`, or exceptional edge invalidates the
+  proof;
+- the replacement preserves the required target domain for the enclosing
+  operation.
+
+If any item is uncertain, keep the coercion.
+
+## Future Work
+
+Potential later optimizations:
+
+- range analysis for arithmetic result closure elision;
+- safe prologue normalization hoisting for repeated parameter coercions;
+- local temporary introduction to avoid repeated operand coercions;
+- property and element proof for freshly allocated objects that do not escape;
+- broader typed-array, DataView-aware, and alias-aware proof rules;
+- interprocedural summaries for private helper functions;
+- full fixed-point CFG instead of the current local branch and loop summaries;
+- closure escape precision beyond the current captured-mutable invalidation;
+- trace-driven verification that optimized output still produces expected V8
+  lowering tokens.