showcase: add showcase26 and update compiler documentation

README.md

@@ -93,15 +93,17 @@ vendor/            qbe toolchain pin
 docs/              STATUS.md, plan.md, plan-*.md, analysis_*.md, summary_*.md
 ```
 
-## Status (2026-10-24)
+## Status (2026-10-28)
 
-- Suite **310/310**; self-hosting **fixpoint OK** (byte-identical
-  stage2/stage3, 3,845,439 bytes); corpus **521/612 compile-OK,
-  0 crashes** (`tools/v3-corpus`; the corpus is gm2's testsuite, so it
-  mixes conforming Modula-2 with gm2 leniencies — see `docs/gaps/`).
+- Suite **333/333**; self-hosting **fixpoint OK** (byte-identical
+  stage2/stage3, 3,671,466 bytes); per-object fixpoint **OK**
+  (11 objects); corpus **521/612 compile-OK, 0 crashes**
+  (`tools/v3-corpus`; the corpus is gm2's testsuite, so it mixes
+  conforming Modula-2 with gm2 leniencies — see `docs/gaps/`).
   The remaining `except*`/`onebyte*`-style corpus files still hit V3's
   declaration-order policy.
-- Active branch **`master`**, feature state **`v3-dynamic-sets`**.
+- Active branch **`master`**, feature state
+  **`v3-address-arith-2026-10-28`**.
   Recent milestones: `PACKEDSET`, ISO exceptions (`EXCEPT`/`RETRY`,
   `EXCEPTIONS`, `M2EXCEPTION`, catchable language traps including
   `functionException`, module `FINALLY`), self-referential pointer
@@ -110,12 +112,17 @@ docs/              STATUS.md, plan.md, plan-*.md, analysis_*.md, summary_*.md
   payload `SIZE`/view `ADR`, flat multi-dimensional record fields and
   constructors, pointer-based 1-D open views, an `LFLOAT` builtin,
   dialect library folders (`lib/pim`, `lib/iso`, `lib/common`,
-  `lib/gm2`), and **separate compilation** (`M2 -c` objects,
-  `M2make --separate`).
+  `lib/gm2`), **separate compilation** (`M2 -c` objects,
+  `M2make --separate`), **ISO address arithmetic**
+  (`ADDADR`/`SUBADR`/`DIFADR`), module/local **absolute variables**
+  with 64-bit addresses, **4 KiB-class string literals**, and the
+  broad **SQLite binding** under `bindings/sqlite3`.
 
 Lowers today: program modules; `CONST`/`VAR`/`TYPE` (scalars,
 subranges, enums, arrays, records incl. variants and self-referential
-pointer records, sets incl. `PACKEDSET`, pointers);
+pointer records, sets incl. `PACKEDSET`, pointers); module and local
+absolute variables (`VAR x [0x...] : T`); `SYSTEM` byte-address
+arithmetic (`ADDADR`/`SUBADR`/`DIFADR`);
 `ARRAY`/`RECORD`/`SET`/`POINTER`, `WITH`, `IN`; fixed and open
 multi-dimensional arrays (view descriptors, row/subarray conversion,
 payload `SIZE`/`ADR`); whole array/record copy; `NEW`/`DISPOSE`; all

TUTORIAL.md

@@ -10,7 +10,7 @@ From the repository root:
 ```sh
 cd compiler
 ./build.sh          # M2.atg -> scanner/parser/driver -> ./M2
-./run_tests.sh      # 310/310
+./run_tests.sh      # 333/333
 ```
 
 `M2` reads Modula-2 sources and writes QBE IR to `gen_ssa/`.
@@ -140,7 +140,65 @@ M2make --dialect iso ... main.mod
 or add the folders explicitly with `-I lib/iso -I lib/common -I
 runtime/syslib`.  Do not mix `lib/pim` and `lib/iso` in one session.
 
-## 6. Useful checks
+## 6. Address arithmetic, absolute variables, long literals
+
+`SYSTEM` provides ISO byte-address arithmetic:
+
+```modula2
+FROM SYSTEM IMPORT ADDRESS, ADR, ADDADR, SUBADR, DIFADR, VAL;
+
+VAR
+  buf : ARRAY [0..15] OF CHAR;
+  p, q : ADDRESS;
+  diff : INTEGER;
+BEGIN
+  p := ADR(buf[0]);       (* raw data address, not the descriptor *)
+  q := ADDADR(p, 5);
+  diff := DIFADR(q, p);   (* 5 *)
+  IF SUBADR(q, 5) = p THEN ... END
+END
+```
+
+Absolute variables use a constant address and emit no storage:
+
+```modula2
+VAR
+  port [0x1000] : CARDINAL;
+
+PROCEDURE P;
+VAR
+  slot [0x2000] : CARDINAL;
+END P;
+```
+
+`ADR(port)` is `0x1000`; the same syntax works locally.  Addresses
+above `0x7FFFFFFF` use the 64-bit path.  The tests only check `ADR` for
+arbitrary addresses; dereferencing an unmapped page will fault.  There is
+no `VOLATILE` pragma yet.
+
+String literals up to the 4 KiB class now survive parsing and lowering:
+
+```modula2
+CONST Text = "....";   (* up to 4095 characters including quotes *)
+```
+
+The new showcase demonstrates all three features:
+
+```sh
+cd compiler
+./M2 ../lib/common/sysio.def ../lib/common/sysio.mod tests/showcase26.mod
+qbe -o gen_ssa/Showcase26.s gen_ssa/Showcase26.ssa
+cc gen_ssa/Showcase26.s ../runtime/syslib/shim.c -o /tmp/showcase26 -lm
+/tmp/showcase26
+```
+
+Expected output:
+
+```text
+showcase26 arith=ok abs=ok local=ok text=3000
+```
+
+## 7. Useful checks
 
 ```sh
 cd compiler && ./run_tests.sh
@@ -149,10 +207,11 @@ TMP="$PWD/.scratch/fixpoint-separate" ./bootstrap/fixpoint-separate.sh
 tools/v3-corpus/corpus.sh
 ```
 
-Current gates: suite **310/310**, fixpoint **OK (3,845,439 bytes)**,
-corpus **521/612 compile-OK, 0 crashes**.
+Current gates: suite **333/333**, one-shot fixpoint **OK
+(3,671,466 bytes)**, per-object fixpoint **OK (11 objects)**, corpus
+**521/612 compile-OK, 0 crashes**.
 
-## 7. Current limits
+## 8. Current limits
 
 - `M2 -I` transitive interface scanning is implemented.
 - `M2make --separate` rebuilds only stale objects, relinks when an object,
@@ -164,6 +223,11 @@ corpus **521/612 compile-OK, 0 crashes**.
 - Per-object self-hosting is a green gate via
   `bootstrap/fixpoint-separate.sh`; compiler units use
   `-legacyopen1d`, while user programs keep pointer views.
+- Address arithmetic has no general `ADDRESS +/-` operator and no
+  `MAKEADR` yet.  `DIFADR` narrows to `INTEGER`; there is no 64-bit or
+  range-checked result form.
+- Absolute variables are not `VOLATILE`; memory-mapped I/O needs a
+  pragma and backend support that are still future work.
 
 For details, see `docs/separate-compilation.md` and
 `docs/plan-separate-compilation.md`.

compiler/run_tests.sh

@@ -467,6 +467,8 @@ expect_run_files_out Showcase24 42 "showcase24 total=42" \
   showcase24.mod
 expect_run_files_out Showcase25 42 "showcase25 sets=42 addr=ok" \
   ../lib/common/sysio.def ../lib/common/sysio.mod showcase25.mod
+expect_run_files_out Showcase26 42 "showcase26 arith=ok abs=ok local=ok text=3000" \
+  ../lib/common/sysio.def ../lib/common/sysio.mod showcase26.mod
 expect_run_files TImportProc 7 pvi.def pvi.mod t_importproc.mod
 expect_run_files_out Showcase22 42 "showcase22 total=42" \
   ../runtime/syslib/SysShim.def ../runtime/syslib/SysShim.mod \

docs/INDEX.md

@@ -76,9 +76,12 @@ bisecting *why* a decision was made, not for reading end-to-end).
 
 ## Recent session summaries (newest first)
 
-- **`session-2026-10-28-address-4k.md`** — ISO `ADDADR`/`SUBADR`/
-  `DIFADR`, module/local absolute variables with 64-bit addresses, and
-  4 KiB-class string literals; tag `v3-address-arith-2026-10-28`.
+- **`summary_session-2026-10-28-address-4k.md`** — tagged summary for
+  ISO `ADDADR`/`SUBADR`/`DIFADR`, module/local absolute variables with
+  64-bit addresses, 4 KiB-class string literals, and showcase26; tag
+  `v3-address-arith-2026-10-28`.
+- **`session-2026-10-28-address-4k.md`** — detailed implementation notes
+  for the same session.
 - **`session-2026-10-27-sqlite-binding.md`** — SQLite binding surface
   and tests, compiler FFI fixes (long literals, EXPORT diagnostic,
   64-bit CSIZE_T, pointer sentinels, module-level absolute variables);

docs/STATUS.md

@@ -4,7 +4,7 @@ This answers "where are we now?".
 
 ## Numbers
 
-- Suite **332/332** (`compiler/run_tests.sh`).
+- Suite **333/333** (`compiler/run_tests.sh`).
 - Self-hosting **FIXPOINT OK** — stage2 and stage3 images are
   byte-identical (3,671,466 bytes); per-object fixpoint **OK**
   (11 objects).
@@ -118,6 +118,10 @@ and `COMPLEX*` is a declaration-compatible `REAL` placeholder.
   `ADDRESS +/-` operator was added.
 - `VOLATILE` remains intentionally unimplemented; it needs a pragma and
   backend support together.
+- New tour: `compiler/tests/showcase26.mod` covers byte-address
+  arithmetic, module/local absolute variables with a 64-bit address, and
+  a 3000-character literal.  Expected first line:
+  `showcase26 arith=ok abs=ok local=ok text=3000`.
 
 ## 2026-10-27 — SQLite binding + compiler FFI fixes
 

docs/features.md

@@ -1,4 +1,4 @@
-# m2compiler-V3 — feature status (2026-10-24; suite 310/310 green)
+# m2compiler-V3 — feature status (2026-10-28; suite 333/333 green)
 
 Pipeline: Coco/R `M2.atg` (1748 lines, 73 productions) → `gm2`-built
 `M2` → QBE `.ssa` → `qbe` → `cc` → run. `SymTab.mod` 1623 lines,

docs/future-work-2026-10-25.md

@@ -30,7 +30,7 @@ work completed since this note:
 - absolute variables (`VAR x [addr] : T`) are implemented at module level;
   see section 2.1 below.
 
-**Progress update 2026-10-28:** suite 332/332; one-shot fixpoint
+**Progress update 2026-10-28:** suite 333/333; one-shot fixpoint
 3,671,466 bytes; per-object fixpoint OK (11 objects).  Completed:
 
 - `SYSTEM.ADDADR`/`SUBADR`/`DIFADR` byte-address builtins;

docs/session-2026-10-28-address-4k.md

@@ -99,10 +99,21 @@ and terminators.
 Memory note: `QbeGen.strTexts` is now about 16 MiB of static storage.
 The self-hosted compiler still builds and reaches fixpoint.
 
+## Showcase
+
+`compiler/tests/showcase26.mod` combines the three features: byte-address
+arithmetic on a real array element, a module-level absolute variable at
+`0x100000000`, a procedure-local absolute variable at `0x2000`, and a
+3000-character literal.  Expected first line:
+
+```text
+showcase26 arith=ok abs=ok local=ok text=3000
+```
+
 ## Verification
 
 ```text
-compiler suite:                 332/332
+compiler suite:                 333/333
 one-shot fixpoint:              OK, 3,671,466 bytes
 separate-object fixpoint:       OK, 11 objects
 ```

docs/summary_session-2026-10-28-address-4k.md

@@ -0,0 +1,107 @@
+# Session summary — 2026-10-28 address arithmetic, absolute variables, 4 KiB literals
+
+**Tag:** `v3-address-arith-2026-10-28`
+
+**Gates:** compiler suite **333/333**, one-shot fixpoint **OK
+(3,671,466 bytes)**, per-object fixpoint **OK (11 objects)**, SQLite
+binding tests **pass**.
+
+## Landed
+
+### 1. ISO SYSTEM address arithmetic
+
+```modula2
+ADDADR(addr: ADDRESS; offset: CARDINAL) : ADDRESS
+SUBADR(addr: ADDRESS; offset: CARDINAL) : ADDRESS
+DIFADR(addr1, addr2: ADDRESS) : INTEGER
+```
+
+- registered as `SYSTEM` procedures for import/type checking;
+- lowered as builtins, with no runtime C helper;
+- `ADDADR`/`SUBADR` are 64-bit byte-address operations;
+- `DIFADR` subtracts addresses and narrows to `INTEGER`;
+- `MAKEADR`, general `ADDRESS +/-` and C-style pointer arithmetic are
+  still future work.
+
+### 2. Absolute variables
+
+```modula2
+VAR port [0x1000] : CARDINAL;      (* module level *)
+
+PROCEDURE P;
+VAR scratch [0x2000] : CARDINAL;  (* procedure local *)
+```
+
+- module and local absolute variables are supported;
+- no data object or stack slot is emitted;
+- `ADR(v)` returns the fixed address;
+- 64-bit addresses above `0x7FFFFFFF` use `QbeGen.LongIntStr`;
+- Lower carries the address in its own symbol table so local scopes
+  still resolve after parsing;
+- `VOLATILE` is not implemented; mapped I/O needs careful review.
+
+### 3. 4 KiB-class string literals
+
+- `AST.MaxTxtLen = 4095` (exported);
+- scanner/parser literal buffers are 4095;
+- `Lower` uses `AST.MaxTxtLen`;
+- `QbeGen.strTexts` inner dimension is 4095.
+
+The old 64-byte lowering truncation and the 255-byte practical buffer
+cap are gone.
+
+## Tests
+
+New regressions:
+
+```text
+compiler/tests/t_addarith.mod
+compiler/tests/t_varaddress64.mod
+compiler/tests/t_localaddress.mod
+compiler/tests/t_longstr4k.mod
+```
+
+## Showcase
+
+```text
+compiler/tests/showcase26.mod
+```
+
+It combines:
+
+- byte-address arithmetic on a real array element;
+- a module-level absolute variable at `0x100000000`;
+- a procedure-local absolute variable at `0x2000`;
+- a 3000-character string literal with compile-time `LEN`/`HIGH`.
+
+Expected output:
+
+```text
+showcase26 arith=ok abs=ok local=ok text=3000
+```
+
+Exit code: **42**.
+
+## Main files changed
+
+```text
+compiler/src/AST.def/.mod
+compiler/src/QbeGen.def/.mod
+compiler/src/SymTab.def/.mod
+compiler/src/Lower.mod
+compiler/src/M2.atg
+compiler/run_tests.sh
+compiler/tests/t_addarith.mod
+compiler/tests/t_varaddress64.mod
+compiler/tests/t_localaddress.mod
+compiler/tests/t_longstr4k.mod
+compiler/tests/showcase26.mod
+```
+
+## Remaining work
+
+- `MAKEADR`
+- `ADDRESS +/-` and C-style pointer arithmetic
+- range-checked or 64-bit `DIFADR`
+- `VOLATILE` pragma and volatile backend loads/stores
+- runtime read/write tests for absolute variables using a mapped page