C64-dev/newLang/planning/claims/E05-S02.md

---

story: E05-S02 owner: e05_objects status: done started: 2026-11-09 depends-on: [E03-S05, E05-S01]

E05-S02 Claim

Intended change

Freeze the object/class descriptor ABI and make it visible in generated MAP output. A class descriptor is an 8-byte packed record containing the instance size, an optional destructor address, an interface count, a pointer to an interface-directory array, and reserved flags that must be zero. Objects start with a two-byte pointer to their descriptor; fields follow at offset 2.

Add src/runtime/objects.s helpers to read an object's descriptor, size, destructor, and interface directory. Extend output.s with out_class records and deterministic CLASS name size destroy count ifdir MAP lines. There is no parent-class slot and no inheritance path.

File area

• src/common/class.inc, src/runtime/objects.s (new)
• src/common/formats.inc, src/compiler/output.s
• tests/runtime/class-test.s
• scripts/build-class-test.ps1, scripts/verify-class-test.ps1
• docs/decisions.md, docs/architecture.md, docs/memory-map.md
• planning/claims/E05-S02.md
• generated files under build/

Acceptance evidence

• Descriptor identifies instance size and optional destructor: the EMPTY descriptor reports size 7 and destructor 0; BOX reports size 35 and a nonzero destructor. obj_size/obj_destroy read both values from the descriptor.
• Every object begins with a valid descriptor pointer: both fixture objects store their descriptor at +0; obj_class rejects a null object/pointer and returns the descriptor for both real objects.
• Descriptor/MAP output is deterministic: the fixture emits CLASS EMPTY 0007 0000 00 0000 and CLASS BOX 0023 <destroy> 01 <dir> after the section records, with actual label addresses supplied by the linker. The verifier compares the complete MAP and the host reruns the fixture on a freshly built disk.
• Format reserves a documented path to interface-directory data without introducing class inheritance: descriptor offset +4 is the interface count, +5..6 points to 4-byte interface/method-table entries, and +7 flags must be zero. There is no parent-class slot; class.inc records this ABI.

Work log

• Selected E05-S02 after E05-S01; no other claim was active.
• Added the 8-byte descriptor and object header constants, plus read-only descriptor accessors for size, destructor, and interface directory.
• Extended output.s with out_class, initialized class-record storage, and appended deterministic CLASS MAP lines after sections. Converted the new writer's long error branches to short branches plus JMP trampolines.
• Added the x128 fixture with a static EMPTY object and a BOX object whose descriptor has a destructor and one interface-directory entry. It writes CLASSTEST.PRG/MAP through the real writer.
• Corrected the fixture's mailbox producer to MB_PROD_PROGRAM; corrected the verifier to use the drive's lowercase classtest.map name.

Completion

• Tests run:
  • scripts/build-class-test.ps1
  • scripts/verify-class-test.ps1 -Port 6552 (repeated on fresh disks)
  • scripts/verify-output-test.ps1 -Port 6530 -RunPort 6531
  • git diff --check
• Results: the class fixture reports producer 3, status $A5, code 0, and all eight descriptor/object/MAP flags set. The screen shows NOVA128 CLASS TEST OK. The complete MAP is identical to the expected six-line record, including CLASS EMPTY 0007 0000 00 0000 and CLASS BOX 0023 <destroy_b> 01 <iface_dir>. The existing output test still passes with its 133-byte PRG and unchanged section MAP.
• Files changed: src/common/class.inc, src/runtime/objects.s, src/common/formats.inc, src/compiler/output.s, tests/runtime/class-test.s, scripts/build-class-test.ps1, scripts/verify-class-test.ps1, docs/decisions.md, docs/architecture.md, docs/memory-map.md, this claim.
• Remaining risks: production parser/codegen does not yet call out_class or emit class descriptors; the MAP exposes descriptor records but not field-by-field offset lines, which remain the parser layout record until codegen pass 3. The descriptor flags, interface descriptor pointer, and method-table pointer are reserved for later interface work. The fixture uses static synthetic objects, so construction/deletion remains E05-S03. Tests run against a fresh true-drive D81.