feat: implement CIE 9.1 text file handling (OPENFILE/READFILE/WRITEFILE/CLOSEFILE/EOF)

Front end: OPENFILE/READFILE/WRITEFILE/CLOSEFILE plus reserved mode
keywords READ/WRITE/APPEND (RANDOM reserved with a dedicated
not-implemented error); statement nodes in new FileAST.h, parsing in new
ParserFile.cc; EOF joins the Builtins table as the 12th builtin and
CallExprAST now carries a line number for its runtime diagnostics.

Runtime: new FileHandler (StringHandler-shaped leaf) lazily synthesizes
internal __cps_file_* helper functions and a 16-slot open-file table
keyed by filename content (strcmp — STRING '=' is pointer identity).
EOF is an fgetc/ungetc peek; READFILE grows a malloc/realloc line buffer
and strips a trailing CR; fopen uses text modes so mingw-w64 line
translation works. File-free programs get byte-identical IR. All misuse
(not open, wrong mode, reopen, fopen failure, read past EOF, table full)
dies with the existing "[Fatal] line N:" pattern via a new
RuntimeCheck::emitErrorAndExit overload taking runtime printf args.

Also fixes a pre-existing ArithmeticHandler hole surfaced by adversarial
review: mixed-width integer operands (i1 BOOLEAN / i8 CHAR vs i64) now
widen via ZExt instead of emitting invalid IR, and remaining type
mismatches get a clean diagnostic; -EOF(f) and -IS_NUM(x) compile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

1 files changed, 18 insertions, 5 deletions

diff --git a/AGENTS/PITFALLS.md b/AGENTS/PITFALLS.md
index 967d577..e24b4bc 100644
--- a/AGENTS/PITFALLS.md
+++ b/AGENTS/PITFALLS.md
@@ -30,11 +30,24 @@ test programs.
   loop direction is decided at run time from the STEP value's sign; STEP is evaluated
   exactly once, before the loop. (The TO expression is still re-evaluated every
   iteration.)
+- **File handling (§9.1) sharp edges.** `READ`/`WRITE`/`APPEND`/`RANDOM` are reserved
+  keywords now — `DECLARE READ : INTEGER` no longer compiles. `WRITEFILE f, a, b` takes
+  exactly two operands (the stray `, b` is a parse error, like multi-expression OUTPUT).
+  READFILE's target must be a plain STRING variable — no CHAR, no `arr[i]` (mirrors
+  INPUT). The CIE guide's empty-line test `IF LineOfText = ""` silently fails here
+  because STRING `=` is pointer identity — use `LENGTH(LineOfText) = 0`. At most 16
+  files open at once. All runtime misuse (not open, wrong mode, reopen, fopen failure,
+  READFILE past EOF) is a `[Fatal] line %d:` exit(1), by design — guard reads with
+  `WHILE NOT EOF(...)`. Caveat: the open-file table is keyed by the filename *string*
+  (per CIE semantics), so two spellings of one OS path (`"a.txt"` vs `"./a.txt"`) evade
+  the already-open check and get two independent buffered streams — reads through the
+  alias can see stale/empty data instead of a Fatal.
 
 ## Not implemented (9618 features)
 
-CASE OF, CONSTANT, TYPE/ENDTYPE (records/enums/pointers), file handling
-(OPENFILE/READFILE/WRITEFILE/CLOSEFILE/EOF), DATE, multi-expression OUTPUT, INPUT into
-array elements, string escape sequences. `README.md` lists `type` and `file` as the
-intended next work. No tests and no CI exist; verify changes by compiling sample
-programs end-to-end (command sequence in `ARCH.md`).
+CASE OF, CONSTANT, TYPE/ENDTYPE (records/enums/pointers), random files
+(OPENFILE...FOR RANDOM/SEEK/GETRECORD/PUTRECORD — blocked on TYPE; the RANDOM keyword
+is reserved and gives a dedicated parse error), DATE, multi-expression OUTPUT, INPUT
+into array elements, string escape sequences. `README.md` lists `type` as the intended
+next work. No tests and no CI exist; verify changes by compiling sample programs
+end-to-end (command sequence in `ARCH.md`).