showcase22 + summary: forward variables, result suffixes, wrappers

Showcase22 tours forward module-level variables, expression result
suffixes, and the new wrapper/time library (StdChans, TimeString,
wrapclock, wraptime, wrapc).  Writes "showcase22 total=42", exit 42;
added to the suite.  docs/summary_wrap-modules.md records the step.

Suite 177/177; fixpoint OK (2,899,706 bytes).

compiler/run_tests.sh

@@ -265,6 +265,15 @@ expect_run_files WrapProg 42 \
   ../stdlib/wraptime.def ../stdlib/wraptime.mod \
   ../stdlib/wrapc.def ../stdlib/wrapc.mod \
   wrapprog.mod
+expect_run_files_out Showcase22 42 "showcase22 total=42" \
+  ../runtime/syslib/SysShim.def ../runtime/syslib/SysShim.mod \
+  ../stdlib/iochan.def ../stdlib/iochan.mod \
+  ../stdlib/stdchans.def ../stdlib/stdchans.mod \
+  ../stdlib/timestring.def ../stdlib/timestring.mod \
+  ../stdlib/wrapclock.def ../stdlib/wrapclock.mod \
+  ../stdlib/wraptime.def ../stdlib/wraptime.mod \
+  ../stdlib/wrapc.def ../stdlib/wrapc.mod \
+  showcase22.mod
 expect_run_files Library1 42 \
   ../runtime/syslib/SysShim.def ../runtime/syslib/SysShim.mod \
   ../stdlib/convtypes.def ../stdlib/convtypes.mod \

compiler/tests/showcase22.mod

@@ -0,0 +1,109 @@
+MODULE Showcase22;
+// Tour of this step's additions:
+//
+//   * forward module-level variables — the procedures below use
+//     `total`, `done` and `label`, all declared after them;
+//   * expression result suffixes — GetRec()^.a, GetArr()^[i];
+//   * the channel/time wrapper library — StdChans (current output
+//     channel), wrapclock (opaque timespec), wraptime (timeval/tm),
+//     wrapc (rand/signbit/isfinite) and TimeString.
+//
+// Writes "showcase22 total=42"; expected ExitCode: 42.
+IMPORT IOChan, StdChans, TimeString, wrapclock, wraptime, wrapc;
+FROM SYSTEM IMPORT ADDRESS;
+
+TYPE
+  Rec    = RECORD a, b : INTEGER END;
+  RecPtr = POINTER TO Rec;
+  Arr    = ARRAY [0..3] OF INTEGER;
+  ArrPtr = POINTER TO Arr;
+
+VAR ExitCode : INTEGER;
+VAR r : RecPtr;
+VAR s : ArrPtr;
+VAR ok : INTEGER;
+VAR out : IOChan.ChanId;
+VAR stamp : ARRAY [0..63] OF CHAR;
+
+(* --- forward references: these globals are declared further down --- *)
+PROCEDURE Bump;
+BEGIN
+  total := total + 1;
+  IF total >= 3 THEN done := TRUE END
+END Bump;
+(* ------------------------------------------------------------------ *)
+
+PROCEDURE GetRec () : RecPtr;
+BEGIN RETURN r END GetRec;
+
+PROCEDURE GetArr () : ArrPtr;
+BEGIN RETURN s END GetArr;
+
+VAR total : INTEGER;
+VAR done  : BOOLEAN;
+VAR label : ARRAY [0..15] OF CHAR;
+
+PROCEDURE SetLabel;
+BEGIN
+  label[0] := "o"; label[1] := "k"; label[2] := CHR(0)
+END SetLabel;
+
+VAR ts : wrapclock.timespec;
+VAR tv : wraptime.timeval;
+VAR tm : wraptime.tm;
+VAR sec, nano : LONGCARD;
+VAR nrand : INTEGER;
+
+BEGIN
+  ExitCode := 0;
+  out := StdChans.OutChan();
+
+  (* --- forward variables: Bump uses total/done before their VAR --- *)
+  NEW(r); NEW(s);
+  r^.a := 40; r^.b := 2;
+  s^[0] := 1; s^[1] := 2; s^[2] := 2; s^[3] := 4;
+  Bump;                                   (* total = 1 *)
+  Bump;                                   (* total = 2 *)
+  Bump;                                   (* total = 3, done = TRUE *)
+  total := total + r^.a - r^.b;           (* 3 + 40 - 2 = 41 *)
+  SetLabel;
+
+  (* --- expression result suffixes --- *)
+  total := total + GetRec()^.b - GetArr()^[2];   (* 41 + 2 - 2 = 41 *)
+  IF GetRec()^.a + GetRec()^.b = 42 THEN INC(ok) END;
+  IF GetArr()^[1] + GetArr()^[2] = 4 THEN INC(ok) END;
+  IF done AND (label[0] = "o") THEN total := total + 1 END;  (* 42 *)
+
+  (* --- wrappers --- *)
+  ts := wrapclock.InitTimespec();
+  ok := ok + wrapclock.SetTimespec(ts, 42, 0);
+  ok := ok + wrapclock.GetTimespec(ts, sec, nano);
+  IF (sec = 42) AND (nano = 0) THEN INC(ok) END;
+  ts := wrapclock.KillTimespec(ts);
+
+  tv := wraptime.InitTimeval();
+  tm := wraptime.InitTM();
+  wraptime.SetTimeval(tv, 0, 0);
+  IF wraptime.LocalTime(tv, tm) # NIL THEN INC(ok) END;
+  tm := wraptime.KillTM(tm);
+  tv := wraptime.KillTimeval(tv);
+
+  nrand := wrapc.getrand(10);
+  IF (nrand >= 0) AND (nrand < 10) THEN INC(ok) END;
+  IF wrapc.signbit(-1.0) = 1 THEN INC(ok) END;
+  IF wrapc.isfinite(1.0) = 1 THEN INC(ok) END;
+
+  TimeString.GetTimeString(stamp);
+  IF stamp[0] # CHR(0) THEN INC(ok) END;
+
+  (* --- report --- *)
+  IOChan.WriteString(out, "showcase22 total=");
+  IOChan.WriteInt(out, total);
+  IOChan.WriteLn(out);
+
+  IF (total = 42) AND (ok >= 5) THEN
+    ExitCode := 42
+  ELSE
+    ExitCode := 1
+  END
+END Showcase22.

docs/summary_wrap-modules.md

@@ -0,0 +1,84 @@
+# Session summary — 2026-10-01 (d): wrapper/time library + showcase22
+
+Suite **177/177**; self-hosting fixpoint **OK** (image
+**2,899,706 bytes**).  Tag `v3-wrap-modules`.
+
+This step added the gm2/ISO channel-and-time wrapper modules that the
+current dialect can express, plus a showcase touring them alongside the
+session's earlier work.
+
+## Steps, tags and headline commits
+
+| Step | Tag | Commit | What |
+| --- | --- | --- | --- |
+| wrappers | `v3-wrap-modules` | `05d9bd0` | StdChans, TimeString, wrapclock, wraptime, wrapc |
+| Showcase + docs | `v3-wrap-modules` | (this commit) | showcase22, this summary |
+
+(The same tag covers both, since the showcase is documentation of the
+step.)
+
+## 1. Modules added
+
+| Module | What |
+| --- | --- |
+| `StdChans` | settable current channels (`InChan`/`OutChan`/`ErrChan` + setters) over `IOChan`; `NullChan` is a closed channel |
+| `TimeString` | `GetTimeString` — local time as `strftime("%c")` |
+| `wrapclock` | opaque `timespec`; `timezone`/`istimezone`/`daylight`/`isdst`/`tzname`; `InitTimespec`/`KillTimespec`, get/set fields, `GetTimeRealtime`/`SetTimeRealtime` |
+| `wraptime` | opaque `timeval`/`timezone`/`tm`; `gettimeofday`/`settimeofday`, `GetFractions`, `LocalTime`, field accessors, `SetTimeval`/`SetTimezone` |
+| `wrapc` | `getrand`, `signbit`/`isfinite`/`isnan` (f/l variants), `SeekSet`/`SeekEnd`, `ReadOnly`/`WriteOnly`, `filesize`/`fileinode`/`filemtime`, `getusername`, `getnameuidgid`, `strtime` |
+
+The shim gains `m2timestring` and underscore-free `m2wc*`/`m2wt*`/
+`m2c*` helpers (classic Modula-2 identifiers have no `_`, so the
+helper names avoid it while the Modula-2-facing names match gm2).
+
+## 2. Deliberate deviations
+
+- `wrapc.ReadOnly`/`WriteOnly` return **`CARDINAL`**, not `BITSET`:
+  `BITSET` is not accepted as a **function-result type** in V3 (nor is
+  `VAL(BITSET, n)`).
+- `wraptime.localtime_r` is spelled **`LocalTime`** — the `_` is illegal
+  in a classic identifier.
+
+## 3. Not included
+
+`ChanConsts` and `StreamFile` are written but **not committed**: their
+`read = FlagSet{readFlag}` constants need **typed set constructors**
+(`T{lit}`), which the frontend reports as `not supported yet`
+(untyped literals with an inferred base, `b := {r, w}`, do work).  Both
+files remain on disk for the next step, which is a frontend change.
+
+`GenDevIF` and `DeviceTablePtr` are **not real gaps**: they are not
+present in the installed gm2 library set.
+
+## 4. Showcase
+
+`compiler/tests/showcase22.mod` (`Showcase22`, exit 42) tours:
+
+- **forward module-level variables** — `Bump` uses `total`/`done`
+  before their `VAR` declaration;
+- **expression result suffixes** — `GetRec()^.a`, `GetArr()^[i]`;
+- **the wrapper library** — `StdChans.OutChan`, a `wrapclock` timespec
+  roundtrip, a `wraptime` timeval+`LocalTime`, `wrapc.getrand` range and
+  `signbit`/`isfinite`, and `TimeString`.
+
+```
+showcase22 total=42
+```
+
+## Tests (177, was 176)
+
+New: `wrapprog.mod` (the five modules, exit 42) and `Showcase22`.
+
+## Resume
+
+```sh
+cd .../m2compiler-V3
+./bootstrap/fixpoint.sh                       # FIXPOINT OK
+cd compiler && ./build.sh && ./run_tests.sh   # 177/177
+```
+
+## Remaining
+
+`ChanConsts` + `StreamFile` (typed set constructors); `GOTO`/labels;
+generics; statement-context result suffixes; multiple inheritance
+(deliberate).