refactor: centralize libc declarations, move '&' concat into StringHandler

CodeGen declares its own MallocFunc in SetupExternalFunctions and uses
it for char->STRING coercion and INPUT STRING buffers, removing two bare
getFunction("malloc") calls that null-deref'd if no handler happened to
declare malloc first. The CHR branch reuses the char->STRING coercion
path instead of a second hand-rolled heap wrapper.

String concatenation moves from ArithmeticHandler (which re-declared
four externs per '&' and was the LLVM 19 build-pin root cause) to
StringHandler::emitConcat; ArithmeticHandler no longer touches the
Module. Dead FreeFunc declarations removed.

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

9 files changed, 47 insertions, 62 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index a23297b..cad017f 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -34,9 +34,10 @@ Facts about the driver (`tools/driver/main.cc`) that break naive automation:
   `verifyModule`, so invalid IR flips the exit code too. Check the exit code — do not
   grep stderr.
 
-Build pin: **LLVM 18 only.** LLVM 19 breaks compilation (`ArithmeticHandler.cc` uses
-`llvm::Module` methods relying on LLVM 18's transitive `#include`; fix would be adding
-`llvm/IR/Module.h`).
+Build pin: developed and tested against **LLVM 18**. (The historical LLVM 19 breakage —
+`ArithmeticHandler.cc` touching `llvm::Module` through a transitive include — is gone
+now that string concatenation lives in `StringHandler`, but newer LLVM versions remain
+untested.)
 
 ## Layout
 
diff --git a/AGENTS/CONVENTIONS.md b/AGENTS/CONVENTIONS.md
index 753be57..cd1adfc 100644
--- a/AGENTS/CONVENTIONS.md
+++ b/AGENTS/CONVENTIONS.md
@@ -33,8 +33,12 @@ pseudocode types *backwards* from LLVM types (`getExprTypeInfo`, `ArithmeticHand
 **Strings are malloc'd and never freed — by design.** Every string-producing operation
 (`&`, MID/LEFT/RIGHT/LCASE/UCASE, NUM_TO_STR, CHR, CHAR/number→STRING coercion) mallocs
 a fresh buffer; string literals and BOOLEAN→STRING coercion instead return pointers to
-shared module globals, so a STRING value may alias a global. `free` is declared but has
-zero call sites. Don't "fix" leaks piecemeal; it's a global design decision.
+shared module globals, so a STRING value may alias a global. `free` is never declared or
+called. Don't "fix" leaks piecemeal; it's a global design decision. All heap-string
+operations (including `&` concatenation, `StringHandler::emitConcat`) live in
+`StringHandler`; `CodeGen` also keeps its own `MallocFunc` for the char→STRING coercion
+and INPUT STRING buffers — declared in `SetupExternalFunctions`, never fetched with a
+bare `getFunction("malloc")`.
 
 **One flat symbol namespace.** Two parallel maps in CodeGen — `NamedValues`
 (name → storage `Value*`) and `Symbols` (name → `SymbolInfo{Storage, TypeName,
diff --git a/include/cps/ArrayHandler.h b/include/cps/ArrayHandler.h
index 6f563b7..e8a57fb 100644
--- a/include/cps/ArrayHandler.h
+++ b/include/cps/ArrayHandler.h
@@ -36,7 +36,6 @@ class ArrayHandler {
     RuntimeCheck &RuntimeChecker;
 
     llvm::FunctionCallee MallocFunc;
-    llvm::FunctionCallee FreeFunc;
 
     llvm::Value *computeFlatIndex(const std::string &Name, const std::vector<llvm::Value*> &Indices);
     llvm::Value *getArrayBasePointer(const std::string &Name);
diff --git a/include/cps/CodeGen.h b/include/cps/CodeGen.h
index b1d3831..def7395 100644
--- a/include/cps/CodeGen.h
+++ b/include/cps/CodeGen.h
@@ -45,6 +45,7 @@ class CodeGen {
 
     llvm::FunctionCallee PrintfFunc;
     llvm::FunctionCallee ScanfFunc;
+    llvm::FunctionCallee MallocFunc;
     
     llvm::Value *PrintfFormatStr;       // %lld\n
     llvm::Value *PrintfFloatFormatStr;  // %f\n
diff --git a/include/cps/StringHandler.h b/include/cps/StringHandler.h
index a31fd2b..7226b85 100644
--- a/include/cps/StringHandler.h
+++ b/include/cps/StringHandler.h
@@ -14,9 +14,10 @@ class StringHandler {
     std::map<std::string, llvm::Value*> &NamedValues;
 
     llvm::FunctionCallee MallocFunc;
-    llvm::FunctionCallee FreeFunc;
     llvm::FunctionCallee StrLenFunc;
     llvm::FunctionCallee MemCpyFunc;
+    llvm::FunctionCallee StrCpyFunc;
+    llvm::FunctionCallee StrCatFunc;
     llvm::FunctionCallee ToUpperFunc;
     llvm::FunctionCallee ToLowerFunc;
 
@@ -29,6 +30,7 @@ public:
     llvm::Value *createLiteral(const std::string &Val);
     
     llvm::Value *emitLength(llvm::Value *Str);
+    llvm::Value *emitConcat(llvm::Value *LHS, llvm::Value *RHS);
     llvm::Value *emitMid(llvm::Value *Str, llvm::Value *Start, llvm::Value *Len);
     llvm::Value *emitRight(llvm::Value *Str, llvm::Value *Len);
     llvm::Value *emitLeft(llvm::Value *Str, llvm::Value *Len);
diff --git a/lib/CodeGen/ArithmeticHandler.cc b/lib/CodeGen/ArithmeticHandler.cc
index b909abc..bfee395 100644
--- a/lib/CodeGen/ArithmeticHandler.cc
+++ b/lib/CodeGen/ArithmeticHandler.cc
@@ -11,32 +11,6 @@ Value *ArithmeticHandler::emitBinaryOp(int Op, Value *LHS, Value *RHS, int Line)
     bool LIsDouble = LHS->getType()->isDoubleTy();
     bool RIsDouble = RHS->getType()->isDoubleTy();
 
-    if (Op == '&') {
-        Module *M = Builder.GetInsertBlock()->getParent()->getParent();
-
-        FunctionType *StrLenTy = FunctionType::get(Type::getInt64Ty(Context), {PointerType::getUnqual(Context)}, false);
-        FunctionCallee StrLenF = M->getOrInsertFunction("strlen", StrLenTy);
-
-        FunctionType *MallocTy = FunctionType::get(PointerType::getUnqual(Context), {Type::getInt64Ty(Context)}, false);
-        FunctionCallee MallocF = M->getOrInsertFunction("malloc", MallocTy);
-
-        FunctionType *StrCpyTy = FunctionType::get(PointerType::getUnqual(Context), {PointerType::getUnqual(Context), PointerType::getUnqual(Context)}, false);
-        FunctionCallee StrCpyF = M->getOrInsertFunction("strcpy", StrCpyTy);
-        FunctionCallee StrCatF = M->getOrInsertFunction("strcat", StrCpyTy);
-
-        Value *LLen = Builder.CreateCall(StrLenF, {LHS}, "llen");
-        Value *RLen = Builder.CreateCall(StrLenF, {RHS}, "rlen");
-        Value *TotalLen = Builder.CreateAdd(LLen, RLen, "totallen");
-        Value *AllocSize = Builder.CreateAdd(TotalLen, ConstantInt::get(Type::getInt64Ty(Context), 1), "allocsize");
-
-        Value *NewStr = Builder.CreateCall(MallocF, {AllocSize}, "concat_str");
-
-        Builder.CreateCall(StrCpyF, {NewStr, LHS});
-        Builder.CreateCall(StrCatF, {NewStr, RHS});
-
-        return NewStr;
-    }
-
     if (Op == '/') {
         Value *LVal = LHS;
         Value *RVal = RHS;
diff --git a/lib/CodeGen/ArrayHandler.cc b/lib/CodeGen/ArrayHandler.cc
index aa7230a..af16692 100644
--- a/lib/CodeGen/ArrayHandler.cc
+++ b/lib/CodeGen/ArrayHandler.cc
@@ -32,11 +32,6 @@ void ArrayHandler::setupExternalFunctions() {
 
     FunctionType *MallocType = FunctionType::get(PointerType::getUnqual(*TheContext), MallocArgs, false);
     MallocFunc = TheModule->getOrInsertFunction("malloc", MallocType);
-
-    std::vector<Type*> FreeArgs;
-    FreeArgs.push_back(PointerType::getUnqual(*TheContext));
-    FunctionType *FreeType = FunctionType::get(Type::getVoidTy(*TheContext), FreeArgs, false);
-    FreeFunc = TheModule->getOrInsertFunction("free", FreeType);
 }
 
 const ArrayMetadata *ArrayHandler::getMetadata(const std::string &Name) const {
diff --git a/lib/CodeGen/CodeGen.cc b/lib/CodeGen/CodeGen.cc
index 1c019d9..de64a15 100644
--- a/lib/CodeGen/CodeGen.cc
+++ b/lib/CodeGen/CodeGen.cc
@@ -99,6 +99,11 @@ void CodeGen::SetupExternalFunctions() {
     FunctionType *ScanfType = FunctionType::get(Type::getInt32Ty(*TheContext), PrintfArgs, true);
     ScanfFunc = TheModule->getOrInsertFunction("scanf", ScanfType);
 
+    FunctionType *MallocType = FunctionType::get(PointerType::getUnqual(*TheContext),
+                                                 {Type::getInt64Ty(*TheContext)},
+                                                 false);
+    MallocFunc = TheModule->getOrInsertFunction("malloc", MallocType);
+
     PrintfFormatStr = Builder->CreateGlobalStringPtr("%lld\n", "fmt_nl", 0, TheModule.get());
     PrintfFloatFormatStr = Builder->CreateGlobalStringPtr("%f\n", "fmt_flt", 0, TheModule.get());
     PrintfStringFormatStr = Builder->CreateGlobalStringPtr("%s\n", "fmt_str", 0, TheModule.get());
@@ -291,17 +296,7 @@ Value *CodeGen::coerceValueToType(Value *Val, const TypeInfo *TargetInfo) {
                 return StrConvHandler->emitNumToStr(Val, true);
             }
             if (Val->getType()->isIntegerTy(8)) {
-                Function *MallocF = TheModule->getFunction("malloc");
-                if (!MallocF) {
-                    FunctionType *MallocTy = FunctionType::get(PointerType::getUnqual(*TheContext),
-                                                               {Type::getInt64Ty(*TheContext)},
-                                                               false);
-                    MallocF = Function::Create(MallocTy,
-                                               Function::ExternalLinkage,
-                                               "malloc",
-                                               TheModule.get());
-                }
-                Value *Mem = Builder->CreateCall(MallocF,
+                Value *Mem = Builder->CreateCall(MallocFunc,
                                                  ConstantInt::get(*TheContext, APInt(64, 2)),
                                                  "char_str");
                 Builder->CreateStore(Val, Mem);
@@ -511,6 +506,9 @@ Value *CodeGen::emitExpr(ExprAST *Expr) {
         Value *L = emitExpr(Bin->getLHS());
         Value *R = emitExpr(Bin->getRHS());
         if (!L || !R) return nullptr;
+        if (Bin->getOp() == '&') {
+            return StrHandler->emitConcat(L, R);
+        }
         return ArithHandler->emitBinaryOp(Bin->getOp(), L, R, Bin->getLine());
     }
 
@@ -565,14 +563,7 @@ Value *CodeGen::emitExpr(ExprAST *Expr) {
         if (Name == "CHR") {
             Value *IntVal = coerceValueToType(emitExpr(Call->getArgs()[0].get()), resolveType("INTEGER"));
             Value *CharVal = ChrHandler->emitChr(IntVal);
-            Function *MallocF = TheModule->getFunction("malloc");
-            Value *Mem = Builder->CreateCall(MallocF, ConstantInt::get(*TheContext, APInt(64, 2)));
-            Builder->CreateStore(CharVal, Mem);
-            Value *NullPtr = Builder->CreateInBoundsGEP(Type::getInt8Ty(*TheContext),
-                                                        Mem,
-                                                        ConstantInt::get(*TheContext, APInt(64, 1)));
-            Builder->CreateStore(ConstantInt::get(Type::getInt8Ty(*TheContext), 0), NullPtr);
-            return Mem;
+            return coerceValueToType(CharVal, resolveType("STRING"));
         }
         if (Name == "IS_NUM") {
             return StrConvHandler->emitIsNum(emitExpr(Call->getArgs()[0].get()));
@@ -873,8 +864,7 @@ void CodeGen::emitStmt(StmtAST *Stmt) {
             Value *BoolVal = Builder->CreateICmpNE(Val, ConstantInt::get(*TheContext, APInt(64, 0)), "bool_cast");
             Builder->CreateStore(BoolVal, Info->Storage);
         } else if (TypeInfo->isString()) {
-            Function *MallocF = TheModule->getFunction("malloc");
-            Value *Mem = Builder->CreateCall(MallocF, ConstantInt::get(*TheContext, APInt(64, 1024)), "input_str");
+            Value *Mem = Builder->CreateCall(MallocFunc, ConstantInt::get(*TheContext, APInt(64, 1024)), "input_str");
             Args.push_back(ScanfStringFormatStr);
             Args.push_back(Mem);
             Builder->CreateCall(ScanfFunc, Args);
diff --git a/lib/CodeGen/StringHandler.cc b/lib/CodeGen/StringHandler.cc
index e5971d0..56b5aea 100644
--- a/lib/CodeGen/StringHandler.cc
+++ b/lib/CodeGen/StringHandler.cc
@@ -16,9 +16,6 @@ void StringHandler::setupExternalFunctions() {
     FunctionType *MallocType = FunctionType::get(PointerType::getUnqual(Context), {Type::getInt64Ty(Context)}, false);
     MallocFunc = Module.getOrInsertFunction("malloc", MallocType);
 
-    FunctionType *FreeType = FunctionType::get(Type::getVoidTy(Context), {PointerType::getUnqual(Context)}, false);
-    FreeFunc = Module.getOrInsertFunction("free", FreeType);
-
     FunctionType *StrLenType = FunctionType::get(Type::getInt64Ty(Context), {PointerType::getUnqual(Context)}, false);
     StrLenFunc = Module.getOrInsertFunction("strlen", StrLenType);
 
@@ -26,6 +23,12 @@ void StringHandler::setupExternalFunctions() {
     FunctionType *MemCpyType = FunctionType::get(PointerType::getUnqual(Context), MemCpyArgs, false);
     MemCpyFunc = Module.getOrInsertFunction("memcpy", MemCpyType);
 
+    FunctionType *StrCpyType = FunctionType::get(PointerType::getUnqual(Context),
+                                                 {PointerType::getUnqual(Context), PointerType::getUnqual(Context)},
+                                                 false);
+    StrCpyFunc = Module.getOrInsertFunction("strcpy", StrCpyType);
+    StrCatFunc = Module.getOrInsertFunction("strcat", StrCpyType);
+
     FunctionType *CharCaseType = FunctionType::get(Type::getInt32Ty(Context), {Type::getInt32Ty(Context)}, false);
     ToUpperFunc = Module.getOrInsertFunction("toupper", CharCaseType);
     ToLowerFunc = Module.getOrInsertFunction("tolower", CharCaseType);
@@ -50,6 +53,22 @@ Value *StringHandler::emitLength(Value *Str) {
     return Builder.CreateCall(StrLenFunc, Str, "len");
 }
 
+Value *StringHandler::emitConcat(Value *LHS, Value *RHS) {
+    if (!LHS || !RHS) return nullptr;
+
+    Value *LLen = Builder.CreateCall(StrLenFunc, {LHS}, "llen");
+    Value *RLen = Builder.CreateCall(StrLenFunc, {RHS}, "rlen");
+    Value *TotalLen = Builder.CreateAdd(LLen, RLen, "totallen");
+    Value *AllocSize = Builder.CreateAdd(TotalLen, ConstantInt::get(Type::getInt64Ty(Context), 1), "allocsize");
+
+    Value *NewStr = Builder.CreateCall(MallocFunc, {AllocSize}, "concat_str");
+
+    Builder.CreateCall(StrCpyFunc, {NewStr, LHS});
+    Builder.CreateCall(StrCatFunc, {NewStr, RHS});
+
+    return NewStr;
+}
+
 Value *StringHandler::emitMid(Value *Str, Value *Start, Value *Len) {
     
     Value *FullLen = emitLength(Str);