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

Phase 274 (active): Type SSOT Alignment (local + dynamic runtime)

Status: active / design-first

Goal: make the language-level type semantics and the runtime behavior consistent and easy to reason about, without turning Nyash into a statically typed language.

This phase is about:

• clarifying SSOT docs,
• closing “frontend emits it but VM can’t run it” gaps,
• and preventing “type facts / resolver guessing” from silently becoming language semantics.

---

Background (why this exists)

Current state:

• Nyash is dynamic at runtime (VM executes tagged values).
• MIR builder attaches type metadata (value_types, value_origin_newbox) for routing/optimization.
• Some docs describe stricter semantics than the VM actually implements.
• TypeOp is emitted by the frontend for is/as.

Problems:

• Spec drift: quick docs vs runtime behavior differ (truthiness / equality / compare / +).
• Capability drift across backends: “VM is correct” but “LLVM harness differs” (TypeOp).
• Type metadata risks becoming implicit semantics via resolver fallback chains.

SSOT decisions should be expressed in:

• language docs (meaning),
• runtime (execution),
• and only then optimization facts (rewrite / routing).

---

SSOT references

• Language type semantics (SSOT): docs/reference/language/types.md
• VM semantics source: src/backend/abi_util.rs, src/backend/mir_interpreter/helpers.rs
• MIR type vocabulary: src/mir/types.rs
• Call certainty vocabulary: src/mir/definitions/call_unified.rs

---

Scope (P0/P1/P2/P3)

P0 (docs-only): establish SSOT and remove contradictions

Deliverables:

• docs/reference/language/types.md (SSOT)
• Quick-reference points to SSOT and stops contradicting runtime

Acceptance:

• docs no longer claim semantics that the Rust VM clearly violates.

P1 (impl): make TypeOp runnable on Rust VM

Goal:

• x.is("T") / x.as("T") lowering exists already; make it executable on the primary backend (Rust VM).

Acceptance (minimum):

• Rust VM implements MirInstruction::TypeOp { op: Check|Cast, value, ty }
• Add a small executable fixture/smoke that exercises is/as
• No new env vars; fail-fast errors on unsupported casts/checks

Implementation guide:

• docs/development/current/main/phases/phase-274/P1-INSTRUCTIONS.md

Status: ✅ done (2025-12-22)

Artifacts:

• Fixture: apps/tests/phase274_p1_typeop_is_as_min.hako
• Smoke: tools/smokes/v2/profiles/integration/apps/phase274_p1_typeop_is_as_vm.sh
• VM handler: src/backend/mir_interpreter/handlers/type_ops.rs

P2 (impl): align LLVM (llvmlite harness) TypeOp to SSOT

Goal:

• Make LLVM harness behavior match Rust VM (SSOT) for TypeOp(Check/Cast).

Current mismatch:

• src/llvm_py/instructions/typeop.py is stubbed:
  • is returns 0 for most types (special-cases IntegerBox as “non-zero”)
  • cast/as are pass-through

Acceptance (minimum):

• With NYASH_LLVM_USE_HARNESS=1 + --backend llvm, the P1 fixture has the same observable result as Rust VM.
• Unsupported cases fail-fast (TypeError), not silent 0/“passthrough”.
• No new environment-variable toggles; differences must be fixed or explicitly documented.

Implementation guide:

• docs/development/current/main/phases/phase-274/P2-INSTRUCTIONS.md

Status: ✅ done (2025-12-22)

Artifacts:

• Kernel type check helper: crates/nyash_kernel/src/lib.rs (nyash.any.is_type_h)
• LLVM TypeOp lowering: src/llvm_py/instructions/typeop.py
• MIR JSON emission fix (bin): src/runner/mir_json_emit/mod.rs (emit op:"typeop")
• Fixture (LLVM-safe): apps/tests/phase274_p2_typeop_primitives_only.hako
• Smoke (LLVM): tools/smokes/v2/profiles/integration/apps/phase274_p2_typeop_is_as_llvm.sh

P3 (decision + optional impl): tighten or document coercions

Decision points to settle (SSOT):

• Truthiness for arbitrary BoxRef (allow “any object is truthy” vs fail-fast)
• Equality cross-coercions (int↔bool, int↔float) — keep, restrict, or gate behind a profile
• + mixed numeric types (int+float) — keep TypeError or add explicit conversions

Acceptance:

• whichever behavior is chosen becomes consistent across backends and docs.

Decision memo (P3):

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

Status:

• P3 decisions are ✅ accepted; implementation is tracked in Phase 275.

---

Non-goals

• Full static typing / inference engine
• Widening the language surface area (new keywords) as the first move
• Adding more environment-variable toggles as a long-term solution