# Step: UString assignment + Files on IOChan

Tag `v3-ustring-files`. Suite **135/135**; fixpoint **OK**
(image **2,142,363 bytes**).

## UString assignment

`a := U"…"` (a 1-D `ARRAY OF UCHAR`) is now a **content copy**, like
`a := "…"` for `CHAR` arrays:

- `SymTab.IsUCharArray(t)` (exported) recognises a 1-D `ARRAY OF
  UCHAR`; `Assignable`/`VarParamOk` already allowed a `ClUStr`
  literal for it.
- `QbeGen.UAssign` emits `call $m2uassign(l dst, l src)`.
- `shim.c m2uassign`: copies `min(count, capacity)` codepoints
  followed by a `0` codepoint terminator. **Note**: the descriptor is
  `{ l count, w codepoints… }`, so the body reads/writes 32-bit
  elements off a 64-bit header (a first cut using `long*` read past
  the data).
- UCHAR arrays now reserve a terminator slot, like CHAR arrays:
  `ArrBodyItems` emits `z (n+1)*4` bytes, `HeapSize`/`InitHeap`
  reserve and zero it, and the fixed/open bounds checks allow index
  `n` (`ArrayHi + 1`, `OpenHiChar`).
- A `U"…"` literal and a `UCHAR` array both pass to an open
  `VAR ARRAY OF UCHAR` formal.

## Files layered on IOChan

`Files` no longer binds the shim directly; it sits on `IOChan`:

- `IOChan` gained a bridge for layered libraries:
  `Handle(cid) : ADDRESS` and `MakeChan(h : ADDRESS) : ChanId`.
- `Files.FileRec` holds an `IOChan.ChanId`; `OpenRead`/`OpenWrite`
  `NEW` a record around the channel, `Close` closes and `DISPOSE`s.
  All I/O delegates to `IOChan` (`ReadChar`/`ReadString`/`ReadInt`,
  `WriteChar`/`WriteString`/`WriteInt`/`WriteLn`), with `NIL`
  guards.
- `Files` gained `ReadString` (one line), matching `IOChan`.

The public `Files` API is unchanged apart from the added `ReadString`.

## Showcase

`compiler/tests/showcase16.mod` (`Showcase16`, exit 42) ties the
session together: a `Shape` variant record (`id` + `CASE k OF
circle|square|rect`), a `U"ok✓"` content copy into a `UCHAR` array,
and a write/read round-trip through a `Files` handle (itself an
`IOChan` channel). Output:

```
showcase16: id=3 total=42
```

## Tests

- `t_ustrassign.mod` (63): content copy, truncation to capacity,
  terminator, non-ASCII round-trip.
- `t_ustrformal.mod` (3): array and literal to an open `VAR ARRAY OF
  UCHAR`.
- `Showcase16` (42).
- Suite file lists for `FilesProg`/`TBadFile`/`MixProg`/`Showcase11`
  now include `SysShim` + `IOChan` (the new `Files` base layer).

## Files

`compiler/src/{SymTab.def,SymTab.mod}` (`IsUCharArray`),
`compiler/src/{QbeGen.def,QbeGen.mod}` (`UAssign`, UCHAR terminator
layout), `compiler/src/M2.atg` (UCHAR assignment branch, bounds),
`runtime/syslib/shim.c` (`m2uassign`),
`stdlib/{iochan,files}.def`/`.mod`,
`compiler/tests/{t_ustrassign,t_ustrformal,showcase16}.mod`,
`compiler/run_tests.sh`, `docs/features.md`.