feat: whole arrays (and records) as FUNCTION/PROCEDURE parameters

- Parameter syntax lands end-to-end: ARRAY OF T (rank 1, bounds travel
  with the argument) and ARRAY[l:u,...] OF T (any rank, literal bounds as
  a checked contract). Element type and rank must match exactly.
- Flattened ABI: each rank-R array parameter becomes a data pointer plus
  kBoundArgsPerDim i64 bounds per dimension. The callee rebuilds
  ArrayMetadata from those bounds (ArrayHandler::bindArrayParameter via a
  binder callback injected by CodeGen, so FunctionGen stays ignorant of
  the array subsystem); the checked-indexing pipeline is reused unchanged.
- BYVAL (the CIE default) copies the whole buffer at callee entry
  (malloc+memcpy, never freed — consistent with the string policy) so
  callee writes stay invisible; BYREF binds the caller's buffer.
- Bounded-parameter contract: compile-time comparison when the caller's
  bounds are constants, else a runtime [Fatal] check
  (RuntimeCheck::emitArrayArgBoundsCheck).
- marshalCallArgs gains the array branch and a call-site line number
  (CallStmtAST now carries one); whole-array-to-scalar keeps a clear
  error, FUNCTION RETURNS ARRAY is a dedicated parse error.
- Verified: BYREF fill/sort-style mutation, BYVAL copy invisibility,
  2-D bounded params, ARRAY OF <record> with field writes through the
  parameter, bounds-contract mismatches at compile time and run time.

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

5 files changed, 76 insertions, 6 deletions

diff --git a/include/cps/ArrayHandler.h b/include/cps/ArrayHandler.h
index e4ccc51..f555ee9 100644
--- a/include/cps/ArrayHandler.h
+++ b/include/cps/ArrayHandler.h
@@ -40,6 +40,13 @@ class ArrayHandler {
     llvm::Value *getArrayBasePointer(const std::string &Name);
     llvm::Value *getElementPointer(const std::string &Name, llvm::Value *Offset);
     const ArrayMetadata *getMetadata(const std::string &Name) const;
+    // Shared bounds math: DimSize_i = (Upper_i - Lower_i) + 1, row-major
+    // multipliers back-to-front, TotalElements = product of the sizes.
+    void computeDimsAndMultipliers(const std::string &Name,
+                                   const std::vector<llvm::Value*> &Lows,
+                                   const std::vector<llvm::Value*> &Highs,
+                                   std::vector<llvm::Value*> &Multipliers,
+                                   llvm::Value *&TotalElements);
     bool emitCheckedIndices(const std::string &Name,
                             const std::vector<std::unique_ptr<ExprAST>> &IndexExprs,
                             int Line,
@@ -83,6 +90,30 @@ public:
     // Swap in a fresh table (function bodies get their own scope, mirroring
     // the Symbols save/clear/restore discipline); returns the previous table.
     std::map<std::string, ArrayMetadata> exchangeTable(std::map<std::string, ArrayMetadata> NewTable);
+
+    // Callee side of an array parameter: rebuild metadata from the incoming
+    // data pointer + per-dim bounds. MakeCopy (BYVAL) mallocs and memcpys the
+    // whole buffer so callee writes stay invisible to the caller.
+    void bindArrayParameter(const std::string &Name,
+                            const std::string &ElemTypeName,
+                            llvm::Value *DataPtr,
+                            const std::vector<llvm::Value*> &LBs,
+                            const std::vector<llvm::Value*> &UBs,
+                            bool MakeCopy,
+                            CodeGen &CG);
+
+    // Call side: validate a whole-array argument against the declared
+    // parameter (element type and rank exactly; bounded params check their
+    // bounds at compile time when constant, else at run time) and append the
+    // data pointer plus per-dim bounds to Out.
+    bool emitArrayArgument(ExprAST *ArgExpr,
+                           const std::string &ElemTypeName,
+                           int Rank,
+                           const std::vector<std::pair<int64_t, int64_t>> &DeclaredBounds,
+                           const std::string &Callee,
+                           int Line,
+                           CodeGen &CG,
+                           std::vector<llvm::Value*> &Out);
 };
 
 } // namespace cps
diff --git a/include/cps/CodeGen.h b/include/cps/CodeGen.h
index c0cbeb5..97765f0 100644
--- a/include/cps/CodeGen.h
+++ b/include/cps/CodeGen.h
@@ -81,6 +81,7 @@ class CodeGen {
     llvm::Value *loadFromLValue(const LValueInfo &LV);
     bool marshalCallArgs(const std::string &Callee,
                          const std::vector<std::unique_ptr<ExprAST>> &ArgExprs,
+                         int Line,
                          std::vector<llvm::Value*> &Out);
     void emitDeclareStmt(DeclareStmtAST *Stmt);
     void emitOutputValue(llvm::Value *Val, const TypeInfo *TypeInfo, bool AppendNewline = true);
diff --git a/include/cps/FunctionAST.h b/include/cps/FunctionAST.h
index f663867..66ac728 100644
--- a/include/cps/FunctionAST.h
+++ b/include/cps/FunctionAST.h
@@ -72,13 +72,15 @@ public:
 class CallStmtAST : public StmtAST {
     std::string Callee;
     std::vector<std::unique_ptr<ExprAST>> Args;
+    int Line;
 
 public:
-    CallStmtAST(const std::string &Callee, std::vector<std::unique_ptr<ExprAST>> Args)
-        : Callee(Callee), Args(std::move(Args)) {}
+    CallStmtAST(const std::string &Callee, std::vector<std::unique_ptr<ExprAST>> Args, int Line)
+        : Callee(Callee), Args(std::move(Args)), Line(Line) {}
 
     const std::string &getCallee() const { return Callee; }
     const std::vector<std::unique_ptr<ExprAST>> &getArgs() const { return Args; }
+    int getLine() const { return Line; }
 };
 
 
diff --git a/include/cps/FunctionGen.h b/include/cps/FunctionGen.h
index 9bb6eef..d914162 100644
--- a/include/cps/FunctionGen.h
+++ b/include/cps/FunctionGen.h
@@ -3,23 +3,50 @@
 #include "llvm/IR/Module.h"
 #include "cps/FunctionAST.h"
 #include "cps/TypeSystem.h"
+#include <cstdint>
 #include <map>
+#include <utility>
 #include <vector>
 #include <functional>
 #include <string>
-#include <tuple>
 
 namespace cps {
 
+// Array-parameter ABI: each rank-R array parameter is flattened into the
+// data pointer followed by kBoundArgsPerDim i64 bounds per dimension.
+inline constexpr unsigned kBoundArgsPerDim = 2; // lower, upper
+inline constexpr const char *kLowerBoundSuffix = ".lb";
+inline constexpr const char *kUpperBoundSuffix = ".ub";
+
+// Pseudocode-level signature of one FUNCTION/PROCEDURE parameter; for arrays
+// TypeName is the ELEMENT type and DeclaredBounds mirrors ParamDecl.
+struct ParamSig {
+    std::string TypeName;
+    bool IsByRef = false;
+    bool IsArray = false;
+    int Rank = 0;
+    std::vector<std::pair<int64_t, int64_t>> DeclaredBounds;
+};
+
 // Pseudocode-level signature of a FUNCTION/PROCEDURE, kept so call sites can
-// dispatch on declared parameter types and BYREF flags instead of inferring
-// them back from LLVM types.
+// dispatch on declared parameter types and modes instead of inferring them
+// back from LLVM types.
 struct FuncSig {
     std::string ReturnTypeName;
-    std::vector<std::pair<std::string, bool>> Params; // (TypeName, IsByRef)
+    std::vector<ParamSig> Params;
 };
 
 class FunctionGen {
+public:
+    // Injected by CodeGen (StmtEmitter inversion precedent) so array
+    // parameters can be bound into ArrayHandler without FunctionGen ever
+    // seeing it: (param, incoming data ptr, per-dim lower/upper bounds).
+    using ArrayParamBinder =
+        std::function<void(const ParamDecl &, llvm::Value *,
+                           const std::vector<llvm::Value*> &,
+                           const std::vector<llvm::Value*> &)>;
+
+private:
     llvm::LLVMContext &Context;
     llvm::Module &Module;
     llvm::IRBuilder<> &Builder;
@@ -29,6 +56,7 @@ class FunctionGen {
     bool &HadError;
 
     std::map<std::string, FuncSig> Signatures;
+    ArrayParamBinder BindArrayParam;
 
     void createArgumentAllocas(llvm::Function *F, const std::vector<ParamDecl> &Params);
 
@@ -43,6 +71,8 @@ public:
 
     llvm::Type *getLLVMType(const std::string &TypeName);
 
+    void setArrayParamBinder(ArrayParamBinder Binder) { BindArrayParam = std::move(Binder); }
+
     const FuncSig *getSignature(const std::string &Name) const;
 
     llvm::Function *emitPrototype(PrototypeAST *Proto);
diff --git a/include/cps/RuntimeCheck.h b/include/cps/RuntimeCheck.h
index 5996409..51a07aa 100644
--- a/include/cps/RuntimeCheck.h
+++ b/include/cps/RuntimeCheck.h
@@ -18,6 +18,7 @@ class RuntimeCheck {
     llvm::Value *OutOfBoundsMsg;
     llvm::Value *EnumRangeMsg;
     llvm::Value *NullDerefMsg;
+    llvm::Value *ArrayArgBoundsMsg;
 
     void setupExternalFunctions();
     void emitErrorAndExit(llvm::Value *Condition, llvm::Value *Msg, int Line);
@@ -35,6 +36,11 @@ public:
     // Dereferencing an unset (null) pointer dies instead of segfaulting.
     void emitNullDerefCheck(llvm::Value *Ptr, int Line);
 
+    // A bounded array parameter is a contract: the argument's runtime bounds
+    // must equal the declared ones.
+    void emitArrayArgBoundsCheck(llvm::Value *ActualLower, llvm::Value *ActualUpper,
+                                 int64_t DeclaredLower, int64_t DeclaredUpper, int Line);
+
     // Runtime-computed variant: FmtArgs are the printf varargs after Msg
     // (e.g. {i32 line, ptr filename}). Needed when the failure site is inside
     // a synthesized helper function, where the line number is an argument