C64-dev/newLang/planning/claims/E03-S05.md

---

story: E03-S05 owner: e03_layout status: done started: 2026-11-09 depends-on: [E03-S02, E03-S04]

E03-S05 Claim

Intended change

Compute every class's instance size and every field's byte offset after pass 1, when forward type references have a kind at last, and report E096 when an instance would exceed 65535 bytes. Instances begin with the two-byte class descriptor pointer and keep fields in declaration order with no padding. Add the size and offset columns to the bank-1 type and member tables, and make the parser harness emit a deterministic layout record so a fixture can list each class's size and its fields’ offsets in declaration order.

File area

• src/common/parser.inc, src/compiler/parser.s
• src/common/diagcat.inc, docs/diagnostics.md (E096)
• tests/parser/parser-test.s, scripts/build-parser-test.ps1, scripts/verify-parser-test.ps1
• tests/semantic/layout.n8, layout.expect, too_big.n8, too_big.expect
• docs/architecture.md, docs/memory-map.md
• planning/claims/E03-S05.md
• generated files under build/

Acceptance evidence

• Field offsets begin after the class-descriptor pointer and are deterministic: layout.n8 declares one field of every ABI size and two arrays; layout.expect records box size 35 with offsets 2, 3, 4, 5, 7, 9, 15, 17, 21, 23, and 31 in declaration order, and empty size 2. The verifier compares the whole $FA layout list; all 39 parser fixtures pass.
• Instance size overflow/capacity is diagnosed: too_big.n8 (word[40000] = 80,000 bytes) is rejected with E096 at 1:1, matching too_big.expect; the size columns saturate at $FFFF rather than wrapping.
• Field default privacy and method default publicity match the specification: layout.n8 uses bare fields and one bare public method; the independent source oracle in verify-parser-test.ps1 derives every member's access (fields private, methods public) and compares it against the parser's 13 member rows for the fixture. The same check covers all accepted fixtures.
• MAP fixture lists sizes and offsets in declaration order: layout.n8/layout.expect is that listing. The harness's $FA record is the deterministic layout listing the future NAME.MAP writer will consume; the MAP writer itself belongs to E05-S02 (output.s), so no NAME.MAP file exists to compare yet. This is recorded under remaining risks.

Coordination notes

• No other claim is active. No new decision: the sizes are the approved architecture ABI (1 for boolean/byte/char, 2 for integer/word/class reference, 4 for interface reference, element size times length for arrays) and object layout is the approved two-byte descriptor followed by fields. D124-D127 from E03-S04 remain proposed.
• The layout pass runs between pass 1 and pass 2, so it only uses recorded table rows and never depends on source order or pass-2 typing.

Work log

• parser.inc: added C_TYPE_SIZE_LO/HI (22/23) and C_MEM_OFFSET_LO/HI (24/25); TABLE_COLUMNS is now 26. docs/memory-map.md records the parser tables as 6,656 bytes.
• parser.s: parse_file calls layout_classes after pass 1. Helpers field_size_mem, field_size, and elem_size compute a member's size from its recorded type, and store_field_offset writes the current offset into the member row. A class starts at 2; methods are skipped; overflow sets the size to $FFFF, records the failure, and reports E096 once at the class's declaration line and column 1. The pass loops over name IDs and member rows, so classes and fields are laid out in declaration order.
• parser-test.s: dump_layout emits $FA, then per class its name, size lo/hi, field count, and each field's name and offset lo/hi. count_fields counts non-method member rows owned by the class. FIXTURE_COUNT is 39.
• verify-parser-test.ps1: decodes $FA until $FD/$FB and compares the layout lines against layout.expect; the member loop now also stops at $FA, because dump_layout always emits its marker before $FD.
• diagcat.inc: appended TYP_INSTANCE_TOO_LARGE, 96; the catalog now has 68 entries and docs/diagnostics.md was regenerated.
• First build exposed four 6502 branch-range errors in layout_classes and three in dump_layout; they are now short branches to nearby jmp trampolines. The verifier edit had also joined $p += 5 and while on one line; fixed.

Completion

• Tests run: scripts/build-parser-test.ps1, scripts/verify-parser-test.ps1 -Port 6530, scripts/build-lexer-test.ps1, scripts/verify-lexer-test.ps1, scripts/build-diag-test.ps1 -UpdateDocs, scripts/verify-diag-test.ps1, scripts/demo-write-check.ps1.
• Results: all 39 parser fixtures pass (lowest expression SP $A7); layout.n8 matches 13 layout lines and too_big.n8 reports E096 at 1:1. The lexer matches 10 fixtures / 6,733 dump bytes; the 68-entry diagnostic catalog and its screen/ERR expectations match with docs in sync; the demo saves good.n8 and bad.n8 byte-for-byte, good.n8 reports no errors, and bad.n8 reports E151, E152, E120, and E061. vim/work.d81 was not touched.
• Files changed: as listed under File area.
• Remaining risks: the NAME.MAP text writer is E05-S02, so the declaration order and layout listing are verified through the harness record rather than a real .map file. E096 reports the instance's saturated $FFFF size in the table; consumers must treat that as “too large”. Any future padding or alignment rule would change layout.expect and the offsets.