C64-dev/newLang/planning/claims/E04-S03.md

---

story: E04-S03 owner: e04_scalar status: done started: 2026-11-09 depends-on: [E04-S02]

E04-S03 Claim

Intended change

Add the scalar instruction emitter in src/compiler/codegen.s and the provisional arithmetic helpers in src/runtime/arithmetic.s. The emitter writes documented 6502 instructions into a bounded code buffer, supports absolute loads/stores and arithmetic operands, immediates, calls, forward branches with checked fixups, and returns the byte length for golden tests.

The x128 fixture drives the emitter directly (parser integration is E04-S04) to build representative byte, word, integer, boolean, comparison, assignment, and short-circuit shapes, copies the golden byte stream, and executes it. It also calls the multiply/divide helpers, including unsigned and signed division, and verifies that division by zero sets a stable fault result.

File area

• src/compiler/codegen.s (new), src/runtime/arithmetic.s (new)
• src/common/codegen.inc, src/common/arithmetic.inc (new)
• tests/codegen/scalar-test.s
• tests/codegen/scalar.expected.dis, tests/codegen/scalar.expected.hex
• scripts/build-scalar-test.ps1, scripts/verify-scalar-test.ps1
• docs/decisions.md, docs/architecture.md
• planning/claims/E04-S03.md
• generated files under build/

Acceptance evidence

• Emits correct byte, word, integer, boolean, comparison, and assignment code: the fixture executes byte assignment/widening, word addition, integer subtraction, six comparisons, and boolean short-circuit shapes. Results: $5A, $0E, $2221, $ECBB.
• Short-circuit and/or avoids evaluating the unused operand: both shapes leave V_EVAL=0 while producing the correct V_FLAG.
• Division by zero faults predictably: the generated call to ar_div_u16 returns C=1, sets ar_fault=AR_FAULT_DIV0, and stores a zero result.
• Golden disassembly covers representative expression shapes: a reviewed 231-byte stream and canonical da65 listing are committed as tests/codegen/scalar.expected.hex and .dis; the verifier compares both.

Coordination notes

• E04-S02 is done; this story adds the scalar backend primitives but does not integrate them into the parser/control-flow shell.
• D130 records the provisional scalar emitter interface and arithmetic helper data flow.
• Runtime arithmetic faults use a provisional AR_FAULT_DIV0 value until E04-S05 freezes the R-code namespace.
• The fixture runs in the compiler mapping; its emitter buffer is writable BSS below $A000. Generated code is executed directly in that buffer.

Work log

• Added cg_* byte emitters, absolute operand forms, forward branch fixups, and a 256-byte bounded buffer.
• Added 16-bit unsigned multiply, restoring unsigned divide, and signed divide with truncation toward zero.
• Fixed ca65 operator precedence in the fixture macros: #>addr+1 became (>addr)+1, so high-byte operands pointed at $1Cxx instead of $1Bxx. Parenthesized #<(addr)/#>(addr) fixed word high bytes and the apparent OR-tail misalignment.
• Increased the fixup table to 32 entries because comparison branches remain recorded after patching.
• Corrected fixture expectations: widened $5A is $005A, and the short- circuit cases now set their left operands explicitly.

Completion

• Tests run:
  • scripts/build-scalar-test.ps1
  • scripts/verify-scalar-test.ps1 -Port 6530
  • scripts/verify-output-test.ps1 -Port 6530 -RunPort 6531
  • scripts/verify-frame-test.ps1 -Port 6530
  • scripts/verify-diag-test.ps1 -Port 6530
  • scripts/verify-parser-test.ps1 -Port 6530
  • git diff --check
• Results: scalar mailbox PASS, data 5A 0E 21 22 BB EC E0 01; golden 231 bytes; canonical disassembly and hex match committed files.
• Files changed: src/compiler/codegen.s, src/runtime/arithmetic.s, src/common/codegen.inc, src/common/arithmetic.inc, tests/codegen/scalar-test.s, golden expectations, scripts/build-scalar-test.ps1, scripts/verify-scalar-test.ps1, docs/decisions.md, docs/architecture.md, this claim.
• Remaining risks: parser/statement integration and long-branch expansion are E04-S04; the emitter buffer is 255 bytes and only forward branches are supported; signed remainder is a magnitude, not sign-extended; byte multiply/divide and integer comparisons are not separately exercised; the divide fault is provisional until E04-S05; generated code is currently executed in the compiler mapping, not installed by a generated startup.