fix: compare strings by content

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

4 files changed, 14 insertions, 9 deletions

diff --git a/AGENTS/CONVENTIONS.md b/AGENTS/CONVENTIONS.md
index 6681d1a..e2c6ebd 100644
--- a/AGENTS/CONVENTIONS.md
+++ b/AGENTS/CONVENTIONS.md
@@ -57,6 +57,13 @@ CHAR = `i8`, STRING = opaque `ptr` to a NUL-terminated buffer. Some code still i
 pseudocode types *backwards* from LLVM types (`getExprTypeInfo`'s fallback,
 `ArithmeticHandler`'s `isIntegerTy(64)` tests), so these widths are ABI.
 
+**Reference storage does not imply address comparison.** Compare values by content;
+only explicitly declared pointer types compare addresses. STRING's six comparison
+operators use `strcmp` in `StringHandler`, dispatched by pseudocode type in CodeGen
+before ArithmeticHandler. Ordering is case-sensitive byte lexicographic order;
+mixed STRING/non-STRING comparisons are errors. Whole-array and record comparisons
+remain unsupported.
+
 **Strings are malloc'd and never freed — by design.** Every string-producing operation
 (`&`, MID/LEFT/RIGHT/LCASE/UCASE, NUM_TO_STR, CHR, READFILE, CHAR/number→STRING
 coercion) mallocs a fresh buffer; string literals and BOOLEAN→STRING coercion instead
diff --git a/AGENTS/EXTENDING.md b/AGENTS/EXTENDING.md
index 0e12241..7a44281 100644
--- a/AGENTS/EXTENDING.md
+++ b/AGENTS/EXTENDING.md
@@ -25,8 +25,9 @@ branches do. Builtins are plain identifiers — nothing is needed in lexer/parse
 **New binary operator:** token (if multi-char) → one line in `BinopPrecedence`
 (Parser ctor; levels: OR=3, AND=5, comparisons=10, `+ - &`=20, `* / DIV MOD`=40;
 precedence must be > 0) → branch in `ArithmeticHandler::emitBinaryOp`, which dispatches
-on raw LLVM operand types. Exception: `&` is intercepted upstream in `CodeGen::emitExpr`
-(operands coerced to STRING, then `StringHandler::emitConcat`).
+on raw LLVM operand types. Exceptions in `CodeGen::emitExpr`: `&` coerces operands
+to STRING then calls `StringHandler::emitConcat`; STRING comparisons require two
+STRING operands by pseudocode type then call `StringHandler::emitCompare`.
 
 **New builtin type:** register in `TypeSystem::registerBuiltins` (sizes are derived —
 never hand-written) + `TypeKind` case in the **exhaustive, default-less switches**:
diff --git a/AGENTS/PITFALLS.md b/AGENTS/PITFALLS.md
index acf21d2..6d1b196 100644
--- a/AGENTS/PITFALLS.md
+++ b/AGENTS/PITFALLS.md
@@ -5,8 +5,6 @@
 Every bullet below was confirmed against the source, most also by compiling and running
 test programs.
 
-- **STRING `=` / `<>` compares pointer identity, not contents.** No strcmp anywhere;
-  two equal heap strings compare unequal.
 - **OUTPUT takes exactly one expression.** `OUTPUT a, ", ", b` prints `a`, then the
   stray `, ", ", b` produces parse errors (recovery resyncs at the next statement
   start, so following statements survive; the compile still fails). Concatenate with
@@ -48,10 +46,9 @@ test programs.
   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
+  INPUT). The CIE guide's empty-line test `IF LineOfText = ""` compares contents.
+  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
diff --git a/AGENTS/SUBSYSTEMS.md b/AGENTS/SUBSYSTEMS.md
index 9f243c2..0075222 100644
--- a/AGENTS/SUBSYSTEMS.md
+++ b/AGENTS/SUBSYSTEMS.md
@@ -67,7 +67,7 @@ line. On first file use, `ensureRuntime()` synthesizes the whole runtime once â€
 only module-level helper functions in the project: internal-linkage `__cps_file_find/
 open/read/write/close/eof` plus a 16-slot open-file table (`__cps_file_names/handles/
 modes` parallel globals; mode byte 0 = free). Files are keyed by filename *content*
-(strcmp scan) because STRING `=` is pointer identity; the name pointer is stored as-is
+(strcmp scan), consistent with STRING comparison; the name pointer is stored as-is
 (strings are immutable and never freed). EOF is an fgetc/ungetc peek; READFILE grows a
 malloc/realloc buffer per line and strips one trailing `\r`; fopen modes are text
 `"r"/"w"/"a"` (Windows CRT translates CRLF). File-free programs get byte-identical IR —