hakorune/docs/development/current/main/phases/phase-274/P3-DECISIONS.md

Phase 274 P3 (decision): Coercion SSOT (truthiness / == / +)

Status: accepted (2025-12-22) / pending implementation

This document freezes what coercions mean at the language level, so runtime behavior cannot “emerge” from resolver/type-facts.

SSOT anchor (current executable behavior): docs/reference/language/types.md
Phase overview: docs/development/current/main/phases/phase-274/README.md Implementation phase: docs/development/current/main/phases/phase-275/README.md

---

1) Terms

In this doc, “coercion” means: when operands/types differ, do we:

• convert implicitly,
• return a deterministic result (e.g. false),
• or fail-fast (TypeError)?

Target constraints:

• Fail-Fast where it prevents silent bugs
• No “JS-style surprise coercion”
• Dynamic runtime remains (no static type system required)
• Backend parity (VM/LLVM) or explicit divergence, never accidental drift

---

2) Proposed SSOT (recommended)

Based on the project philosophy, the recommended SSOT choice is:

• truthiness: A1
• ==: B2 (Number-only)
• +: C2 (Number-only promotion)

The sections below define each choice precisely.

---

3) truthiness (boolean context)

Decision: A1 (Fail-Fast)

Void in condition is TypeError.

Allowed in boolean context:

• Bool → itself
• Integer → 0 false, non-zero true
• Float → 0.0 false, non-zero true
• String → empty false, otherwise true

Disallowed (TypeError):

• Void (always error)
• BoxRef (by default)
  • Exception: only explicit bridge boxes may be unboxed to the corresponding primitive for truthiness:
    • BoolBox / IntegerBox / StringBox
  • VoidBox is treated as Void → TypeError

Recommended explicit patterns:

• existence check: x != Void
• type check: x.is("T") / x.as("T")
• explicit conversion (if we add it): bool(x) (but bool(Void) remains TypeError)

Implementation impact (where to change):

• Rust VM: src/backend/abi_util.rs::to_bool_vm
• LLVM harness: must match the VM semantics used for branch conditions

---

4) == (equality)

Decision: B2 (Number-only)

Rules:

• Same-kind primitives compare normally.
• Int ↔ Float comparisons are allowed (Number-only).
• Bool is not a number: Bool ↔ Int/Float has no coercion.
• Other mixed kinds: deterministic false (not an error).
• BoxRef == BoxRef: identity only.

Precise rule for Int == Float (avoid “accidental true”)

To avoid float rounding making true incorrectly:

For Int == Float (or Float == Int):

1. If Float is NaN → false
2. If Float is finite, integral (fractional part is 0), and within i64 exact range:
   • convert Float → Int exactly, then compare Ints
3. Otherwise → false

Migration note:

• If legacy behavior existed for 1 == true, prefer a transition phase where it becomes TypeError first (to surface bugs), then settle to false if desired.

Implementation impact:

• Rust VM: src/backend/abi_util.rs::eq_vm (and any helpers)
• LLVM harness: must mirror the same decision for compare == lowering

---

5) + (add / concat)

Decision: C2 (Number-only promotion)

Rules:

• Int + Int → Int
• Float + Float → Float
• Int + Float / Float + Int → Float (promote Int→Float)
• String + String → concat
• String + non-string / non-string + String → TypeError (no implicit stringify)
• Other combos → TypeError

Implementation impact:

• Rust VM: src/backend/mir_interpreter/helpers.rs::eval_binop (BinaryOp::Add)
• LLVM harness: binop + lowering must follow the same coercion rules

---

6) Minimum test matrix (SSOT lock)

6.1 truthiness

• Bool: if true, if false
• Int: if 0, if 1, if -1
• Float: if 0.0, if 0.5, if NaN (define if NaN counts as truthy)
• String: if "", if "a"
• Void: if Void → TypeError (A1)
• BoxRef:
  • bridge: BoolBox(true), IntegerBox(0), StringBox("")
  • non-bridge: Foo() → TypeError

6.2 equality

• same-kind primitives
• Int↔Float:
  • 1 == 1.0 true
  • 1 == 1.1 false
  • NaN == NaN false
• Bool↔Int:
  • true == 1 (explicitly decide: TypeError during migration vs final false)
• BoxRef identity:
  • same handle true, different handles false

6.3 plus

• Int/Float add
• Int+Float promotion
• String+String concat
• String mixed TypeError

---

7) Migration plan (if changing behavior)

Recommended two-step approach:

1. Compatibility freeze (Phase 274)

• Document current behavior (already in types.md)
• Add warnings / diagnostics where possible (no new env sprawl)

2. Switch semantics (Phase 275 or later)

• Implement A1/B2/C2 in VM and LLVM
• Add fixtures to lock the SSOT
• Ensure error messages provide “fix-it” guidance (str(x), x != Void, etc.)