fix: close type-safety holes found by adversarial review; update docs

Review findings (all reproduced, then fixed and re-verified):
- '^x' leaked as a raw address into any builtin context (s <- ^x printed
  the variable's bytes as a C string; NOT ^x, '&', and ^x = ^x compiled).
  Address-of is now rejected everywhere except a pointer-typed target.
- A whole-array variable passed the nominal gate as a value of its
  ELEMENT type (s <- arrayOfSeason stored the raw data pointer; = on it
  emitted invalid IR). Whole arrays are now rejected as operands and as
  coercion sources; array parameters are unaffected.
- Enum values smuggled into INTEGER through array subscripts and DECLARE
  bounds (a[Autumn], ARRAY[Spring:Winter]); both now go through
  emitCoercedExpr like every other INTEGER context.
- An array DECLAREd inside an IF/WHILE/REPEAT/FOR body and used after the
  block was a wild-pointer write (constant bounds) or a verifier dump
  (runtime bounds). Arrays are now block-scoped: control-flow bodies
  snapshot and restore the ArrayTable, so escape is a clean compile error.
- Duplicate parameter names silently shadowed (BYREF write-back defeated);
  now a parse error. Trailing comma in parameter lists accepted; now a
  parse error consistent with every other list.
- A variable/array/parameter/function could reuse a TYPE name; reserved.
- RETURN with a value inside a PROCEDURE was silently discarded (control
  did not return); now an error, as is a bare RETURN in a FUNCTION.
- INPUT r.f mis-parsed into a three-error cascade; now one clear error.
- Assigning to an enum constant now says so instead of 'Unknown variable'.

Docs: ARCH/CONVENTIONS/EXTENDING/SUBSYSTEMS/PITFALLS rewritten for the
TYPE system (ABI additions, nominal-typing invariants, admission-gate
doors, array-parameter ABI, new recipes, new sharp edges); README
features/TODO updated — random files are unblocked.

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

1 files changed, 12 insertions, 5 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index cbf4b65..4ed2404 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -11,7 +11,12 @@ stdin ──> Lexer ──> Parser ──> vector<unique_ptr<StmtAST>> ──> C
 
 Fixed value representation (ABI — much code infers types backwards from these):
 INTEGER = `i64`, REAL = `double`, BOOLEAN = `i1`, CHAR = `i8`, STRING = opaque `ptr`
-to a NUL-terminated buffer.
+to a NUL-terminated buffer. User-defined types (§4): enum = `i64` (0-based ordinal),
+pointer = opaque `ptr`, record = named struct `%record.NAME`. Enum/pointer are
+LLVM-identical to INTEGER/STRING **by design** — their identity lives in the type
+*name*, enforced upstream (see CONVENTIONS.md). Byte sizes are never computed
+host-side: the module has no DataLayout string, so every size is a null-GEP
+`sizeof` constant (`TypeSystem::getSizeOfConstant`) folded by the backend.
 
 ## Build & run
 
@@ -45,15 +50,17 @@ untested.)
 |---|---|
 | `include/cps/` | All headers, included as `"cps/Foo.h"` |
 | `lib/Lexer/Lexer.cc` | Entire lexer: one function, `Lexer::gettok()` |
-| `lib/Parser/Parser.cc` | Statements, expressions, precedence table |
-| `lib/Parser/ParserFunction.cc` | FUNCTION/PROCEDURE/CALL/RETURN parsing |
+| `lib/Parser/Parser.cc` | Statements, expressions, designators, precedence table |
+| `lib/Parser/ParserFunction.cc` | FUNCTION/PROCEDURE/CALL/RETURN + parameter-list parsing |
 | `lib/Parser/ParserFile.cc` | OPENFILE/READFILE/WRITEFILE/CLOSEFILE parsing |
+| `lib/Parser/ParserType.cc` | TYPE/ENDTYPE declarations, SET/DEFINE reserved stubs |
 | `lib/CodeGen/CodeGen.cc` | Hub: dispatch, coercion, control flow, INPUT/OUTPUT, main() |
+| `lib/CodeGen/Designator.cc` | CodeGen methods for the TYPE system: type pre-pass, `emitLValue`/`loadFromLValue`, `emitCoercedExpr` gate, user-kind binary-op interception |
 | `lib/CodeGen/*Handler.cc`, `FunctionGen.cc`, `RuntimeCheck.cc`, `TypeSystem.cc` | Helpers owned by CodeGen |
 | `CMakeLists.txt` | 3 static libs (CPSLexer, CPSParser, CPSCodeGen) + `cpsc`. **New .cc files must be added to the source lists here** |
 
-AST nodes live in `include/cps/AST.h` (+ `FunctionAST.h`, `FileAST.h`); they are pure
-data with virtual destructors only — no codegen/visitor methods.
+AST nodes live in `include/cps/AST.h` (+ `FunctionAST.h`, `FileAST.h`, `TypeAST.h`);
+they are pure data with virtual destructors only — no codegen/visitor methods.
 
 ## Detail docs