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

---

story: E03-S01 owner: e03_toplevel_parser status: done started: 2026-11-07 depends-on: [E02-S02, E02-S03, E02-S04]

E03-S01 Claim

Intended change

Add src/compiler/parser.s: a two-pass declaration-level parser. Pass 1 parses interfaces, classes (with implements lists, fields, and method headers), and exactly one program, records top-level types in a bank-1 table, tracks block structure inside method and program bodies, and reports syntax and duplicate-name errors with recovery. Pass 2 replays the source and reports type references that name no declared interface or class, so forward references work.

File area

• src/compiler/parser.s, src/common/parser.inc
• src/common/diagcat.inc (appended entries), docs/diagnostics.md
• tests/parser/
• scripts/build-parser-test.ps1, scripts/verify-parser-test.ps1
• docs/architecture.md, docs/memory-map.md
• planning/claims/E03-S01.md
• generated files under build/

Acceptance evidence

• Parses interfaces, classes, implements lists, and exactly one program: all 7 accepted fixtures give no diagnostics and the type table matches every interface/class/program declaration and line; noprog.n8 reports PROGRAM EXPECTED; a second or late declaration is an ordering error.
• Supports forward top-level type references: forward.n8 and decls.n8 use types before declaring them and pass; unknown.n8 reports exactly its four truly unknown names. Swapping the pass order (checking references first) fails 6 accepted fixtures, so pass 2 is what makes forward references work.
• Rejects duplicate names and invalid ordering with recovery to later lines: order.n8 (late class, late duplicate interface) and recover.n8 (five independent errors) match their full expected diagnostic lists exactly; eofclass.n8 shows end-of-file errors are not cascaded.
• Accepted/rejected fixtures from E00-S02 pass: 7/7 accepted; 10/12 rejected report their sidecar diagnostic at the sidecar line (and column where given). line_cont.n8 and multi_stmt.n8 need expression and statement parsing, which E03-S03's own criteria cover; the test lists them as pending and confirms they raise no false diagnostics meanwhile.

Coordination notes

• Statement and expression bodies are skimmed line by line here (block keywords tracked). line_cont.n8 and multi_stmt.n8 need the statement and expression grammar that E03-S03 owns (“Rejects multiple statements per line and cross-line expressions”); the test lists them as pending E03-S03 and checks that they raise no false diagnostics meanwhile.
• Member-name uniqueness and access rules are E03-S02. Parameters and var locals already share one duplicate-checked scope here because dup_decl.n8 needs it.

Work log

• Appended diagnostics E031-E037 and E222 to the catalog; docs regenerated.
• First x128 runs found: the bank-1 type table was never cleared (power-on bytes looked like declarations); the test's PASS branch fell through when ok_msg - messages was 0; and method print() was rejected because print is a keyword. The last is a spec conflict, resolved by D121 (proposed).
• Verifier fix: PowerShell unrolls a one-element array returned from a function, so single-line ERR files read as one string.

Completion

• Tests run: scripts/verify-parser-test.ps1 (pass plus pass-order mutation), scripts/build-diag-test.ps1 catalog check.
• Results: 24 fixtures as expected (2 pending E03-S03); mutation caught.
• Files changed: src/compiler/parser.s, src/common/parser.inc, src/common/diagcat.inc, docs/diagnostics.md, tests/parser/, scripts/build-parser-test.ps1, scripts/verify-parser-test.ps1, docs/architecture.md, docs/memory-map.md, docs/decisions.md (D121), this claim.
• Remaining risks: D121 awaits approval; pass-2 diagnostics come after all pass-1 diagnostics in NAME.ERR (not sorted by line); implements accepts a class name until interface conformance (E03-S06); statement lines are only skimmed, so a block keyword inside a skimmed expression is not possible today but must stay so when E03-S03 lands.