From e723961bf8e181b13445046efa05f0947bdc5bcf Mon Sep 17 00:00:00 2001 From: Daniel Covington Date: Tue, 10 Nov 2026 14:51:22 -0500 Subject: [PATCH] Claim E07-S05 with the driver contract and its module set. Records the initialisation order the parser fixture establishes and the three output paths output.s already provides, so the driver is wiring rather than new file handling; no driver source has landed yet. Generated with Codebuff Co-Authored-By: Codebuff --- newLang/planning/claims/E07-S05.md | 111 +++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 newLang/planning/claims/E07-S05.md diff --git a/newLang/planning/claims/E07-S05.md b/newLang/planning/claims/E07-S05.md new file mode 100644 index 0000000..06ae28c --- /dev/null +++ b/newLang/planning/claims/E07-S05.md @@ -0,0 +1,111 @@ +--- +story: E07-S05 +owner: codebuff +status: in-progress +started: 2026-11-10 +depends-on: [E07-S01, E04-S01, E04-S06, E02-S04] +--- + +# E07-S05 Claim + +## Intended change + +A `n128c` PRG that runs on `x128` and is the compiler the launcher and disk +builder already assume: it takes a source name from the keyboard, loads that SEQ +file from drive 8 through the buffered PETSCII reader, runs lexer, parser and +pass-2 emission, writes `NAME.PRG` and `NAME.MAP` through `output.s`, and prints +a one-screen summary with the source name, the output name and the diagnostic +count. Failures print a stable message, write diagnostics to `NAME.ERR`, and +leave any previous output untouched. + +## File area + +- `src/compiler/driver.s` (new): prompt, load, compile, output, summary +- `cfg/driver.cfg` (new, or `cfg/compiler.cfg` plus `output.s` if the extra + section fits): link layout for the whole compiler +- `scripts/build-driver.ps1` (new): builds `build/n128c.prg` +- `tests/driver/driver.n8`, `tests/driver/fail.n8` (new fixtures) +- `scripts/verify-driver-test.ps1` (new): drives the PRG through `x128` + `keybuf` on a copied image and checks the PRG, ERR, MAP and summary +- `docs/editor-workflow.md`, `docs/architecture.md`, `docs/decisions.md` +- `planning/claims/E07-S05.md` +- generated files under `build/driver-test/` + +## Acceptance criteria (from the story) + +- [ ] `build/n128c.prg` is built by a documented script and is the file + `prepare-disk.ps1` injects and `launch-compiler.ps1` autostarts. +- [ ] The driver takes one source name, loads it from the session disk with no + host conversion, compiles, and writes the PRG named after the source. +- [ ] ERR and MAP outputs are written for the same run, with a one-screen + summary naming source, output and diagnostic count. +- [ ] A clean source produces a PRG that runs on `x128`; a failing source + produces the catalogued diagnostics, a non-zero count, and no PRG. +- [ ] Missing source, unreadable source and an existing output each end with + the documented message and leave the previous output intact. +- [ ] A test drives the driver through `scripts/launch-compiler.ps1` on a copied + development image and checks the artifacts. +- [ ] `docs/editor-workflow.md` documents the command and the recovery steps, + and E07-S04 can be completed with no undocumented command. + +## Coordination notes + +- The pieces exist and are individually proven: `src_load`, `names_init`, + `diag_init`/`diag_finish`, `parse_file` and `sizing`; `output.s` already + implements `out_begin` (refuses an existing `NAME.PRG`/`NAME.MAP`), + `out_startup`, `out_section`, `out_byte`, `out_finish` and `out_abort`. + `tests/parser/parser-test.s` shows the exact compiler initialisation order: + `mmu_init`, `mmu_bank0`, then per file `src_load`, `names_init`, `diag_init`, + `parse_file`, `diag_finish`. +- `scripts/build-parser-test.ps1` links every compiler module against + `cfg/compiler.cfg`, so the driver's link set is that list plus `output.s` and + the runtime startup/print modules. The map has `MAIN` to `$B7FF` + (about 40 KB) and `BANK1` to `$BFFF`; `output.s` keeps its section, class, + method and table records in BSS, so the remaining budget must be measured + after the first link, not assumed. +- `out_begin` derives `NAME.PRG`/`NAME.MAP`/`NAME.ERR` by stripping a trailing + `.N8` from the source name and caps the base at 12 characters, which matches + the 16-character limit VICE's directory allows; the driver must validate the + typed name before calling it. +- `parse_file` only emits when `em_on` is set; the fixture path sets it, so the + driver has to set it for pass 2 and must call `parse_file_base` (not + `parse_file`) when pass-3 absolute addresses are known. That decision is part + of the driver, not the parser. +- Launching the PRG needs the same rule the editor learned in D151: it must be + started from the session disk (`n128c`), not from a host path, so its file + naming and drive device are the ones the session uses. + +## Work log + +- Read `output.s`, the parser initialisation path, `cfg/compiler.cfg` and the + parser fixture's link and startup code to fix the driver's contract and the + module set it must link. +- Confirmed `output.s` already refuses to overwrite and scratches only files it + created, so the story's "leave the previous output intact" criterion is a + matter of aborting on `out_err` rather than adding new file logic. +- No driver source, config, build script or fixture has been written yet, so no + behaviour exists to verify. + +## Completion + +- Tests run: none. The claim records the design and the discovered contracts; + nothing has landed, so it stays `in-progress`. +- Results: not applicable. +- Remaining risks: the whole compiler plus `output.s` plus the runtime print + module may not fit `MAIN`/`BANK1`; if it does not, the driver needs a section + split or `output.s` record limits reduced, which is a decision, not a tweak. + The summary must not use the compiler's own zero page while a compile is in + progress, and a source name longer than 12 base characters has to be rejected + before `out_begin` builds both names. + +## Next steps + +1. Write `src/compiler/driver.s` with the initialisation order above, a + `source:` prompt, name validation, `parse_file`/`parse_file_base`, and the + `out_*` calls; build it with a copy of `cfg/compiler.cfg`. +2. Measure the link (`MAIN`/`BANK1` free bytes) and record the result; adjust or + raise a decision if it does not fit. +3. Add `scripts/build-driver.ps1` producing `build/n128c.prg`, then the + verifier that copies a disk, injects the driver, types a fixture name, and + checks `NAME.PRG`, `NAME.MAP`, `NAME.ERR` and the summary. +4. Update `docs/editor-workflow.md` and unblock E07-S04.