fix(arrays): free array buffers when their scope ends

Register every array as a stack object so its buffer is freed on scope
end, re-DECLARE, RETURN and unwinding; run the element-destroy loop only
for types that need destruction.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

4 files changed, 9 insertions, 5 deletions

diff --git a/AGENTS/PITFALLS/core-language.md b/AGENTS/PITFALLS/core-language.md
index 60fbd11..0ddba05 100644
--- a/AGENTS/PITFALLS/core-language.md
+++ b/AGENTS/PITFALLS/core-language.md
@@ -13,7 +13,7 @@ source, most also by compiling and running test programs.
 - **Arrays cross function boundaries only as parameters.** `ArrayTable` is scoped per
   function, so referencing another function's array fails cleanly as
   "Undeclared array". Whole arrays pass as `ARRAY OF T` / `ARRAY[l:u,...] OF T`
-  parameters (BYVAL copies the entire buffer and never frees it); a whole-array
+  parameters (BYVAL copies the entire buffer; the copy is freed when the callee ends); a whole-array
   argument against a scalar parameter is still a compile error. FUNCTIONs cannot
   RETURN arrays. A whole-array variable is also rejected as an operand or as a
   value of its element type.
diff --git a/AGENTS/PITFALLS/exceptions-and-c-interop.md b/AGENTS/PITFALLS/exceptions-and-c-interop.md
index 104be41..b057d18 100644
--- a/AGENTS/PITFALLS/exceptions-and-c-interop.md
+++ b/AGENTS/PITFALLS/exceptions-and-c-interop.md
@@ -12,8 +12,8 @@ Part of the [pitfalls index](../PITFALLS.md).
 - Uncaught exceptions also print the generic termination message and return 1.
 - Native compilation links the C++ runtime automatically; manually linking emitted
   `.ll` files must use LLVM 23's `clang++` (`clang++-23` on Debian/Ubuntu).
-- Owned STRING values follow class cleanup during unwinding; raw array buffers are
-  not freed and files are not automatically closed.
+- Owned STRING values follow class cleanup during unwinding; array buffers are freed
+  and files are not automatically closed.
 - Check the native nightly job results when changing platform-specific code
   (CI coverage: [ARCH/BUILD.md](../ARCH/BUILD.md)).
 
diff --git a/AGENTS/SUBSYSTEMS/CLASS_LIFETIME.md b/AGENTS/SUBSYSTEMS/CLASS_LIFETIME.md
index 727a1af..3b9ec58 100644
--- a/AGENTS/SUBSYSTEMS/CLASS_LIFETIME.md
+++ b/AGENTS/SUBSYSTEMS/CLASS_LIFETIME.md
@@ -37,6 +37,10 @@ Part of the [subsystem notes](../SUBSYSTEMS.md). Builds on [classes](CLASSES.md)
 - Each record retains the original address, an entry-initialized Alive flag and, for
   arrays, a runtime element count in an entry slot. Array buffer addresses also live in
   entry slots so deferred cleanup never references branch-local bound SSA values.
+- Every array registers, even when its elements need no destruction: cleanup runs the
+  element-destroy loop only when needed, then `free`s the buffer and nulls the slot, so
+  re-DECLARE, RETURN, unwinding and BYVAL copies all release it. BYREF arrays are never
+  registered.
 - Repeated DECLARE destroys its previous live incarnation first. Alive becomes true only
   after construction or copy completes and is cleared before destruction.
 - Rebinding a reference slot with NEW does not change the original address tracked for
diff --git a/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md b/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md
index fdd10fb..0d14d3a 100644
--- a/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md
+++ b/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md
@@ -43,8 +43,8 @@ Part of the [subsystem notes](../SUBSYSTEMS.md). Related: [class lifetime](CLASS
   propagates and interrupts remaining cleanup instead of terminating.
 - Main records only its normal return, leaving its final uncaught-exception handler free
   of automatic object destruction.
-- Owned STRING values follow class cleanup. Raw array buffers are not freed and files
-  are not automatically closed.
+- Owned STRING values follow class cleanup. Array buffers are freed with their
+  scope (also when unwinding) and files are not automatically closed.
 
 ### Runtime and platforms