Define lowered-HFIR ABI v1 and core conformance suite (#90 phase 1)

[howlcipher]

Summary

Phase 1 of improvement #90. This does not move execution onto HFIR. -compile-bc is still runHFIRGate and then bytecode.CompileToBytecode on the AST. -compile-hfir-bc stays the experimental lowerer.

The contract is docs/reference/lowered_hfir_abi_v1.md (lowered-hfir-abi/v1). It covers typed values, the call shape the hosts already share, the lack of a linear-memory import, error classes, pure effects versus env, and Wasm feasibility. CFG/SSA is specified as the later shape. LowerAST still leaves ControlEdges empty, and defun, call, and while still fail LowerToBytecode with HFIR_BYTECODE_UNSUPPORTED.

The suite is tests/conformance/lowered_hfir_abi_v1.json, run by the existing tools/difftest harness:

• Exact integer arithmetic and if, under an empty grant
• map_keys (including the #109 UTF-8 byte-order fixtures) and map_get absence (#103)
• Dynamic map_keys TYPE_ERROR (#108)
• env denial on the interpreter and the bytecode VM, and env granted on those hosts plus Go
• A seeded property check of eight arithmetic expressions

JavaScript runs the same cli_app body with the root rewritten to web_app. Wasm is not executed. Its v1 rejection set is exactly exec, spawn_agent, and http_server_start (HFIR_TARGET_INFEASIBLE), via hfir.WasmInfeasibleKinds. No new opcode, no module linker, no Wasm collection growth.

Phase 2 (not this PR)

One lowered graph consumed by every host. That includes calls and while, populated control edges, capability mediation on Go and JavaScript, one feasibility table for every target, and any Wasm growth (#73 / #84 stay behind that).

Generated Go still calls os.Getenv with no grant check. JavaScript has no env. Those hosts are intentionally absent from the denial case.

Review notes for Motoko

• Status in improvements.md is Partial — Phase 1, not Done.
• Journal: docs/journals/2026-09-30_lowered_hfir_abi_phase1.md.
• go test ./... passed, including ./tools/difftest and ./internal/hfir.

Please comment. Do not merge.

  

[howlcipher]

COMMENT OK (approve-quality) — same-account; formal APPROVE unavailable.

Verdict: Ready to undraft + squash-merge when CI is green on 65d37cd.

What this gets right

• Honest Partial — Phase 1, not Done. Production stays AST → runHFIRGate → bytecode; -compile-hfir-bc remains experimental; empty ControlEdges / non-executable defun/call/while are stated, not papered over.
• Contract lowered-hfir-abi/v1 + tests/conformance/lowered_hfir_abi_v1.json via tools/difftest is the right Phase-1 shape: prove hosts that already run the core agree before flipping the graph.
• Core cases cover arith/if, #109 UTF-8 map_keys (incl. non-BMP via stdout_keys → sort.Strings), #103 absence, #108 TYPE_ERROR, #107 empty-grant purity, and env denial only on hosts that mediate (interp+VM). Go/JS absence from denial is correct and guarded.
• Wasm: closed WasmInfeasibleKinds only; no collections/opcodes/imports. #73/#84 deferred to Phase 2.

Hard nos: clean — no linker / HFIR module smuggle / new feature opcodes / Factory under the ABI banner.

Nit (non-blocking): manifest stdout_keys for non-BMP are listed in fixture insertion order; harness re-sorts, so behavior is fine — sorting the JSON list would just read clearer.

CI: build still in progress at review time — merge only after green.