fix: DESTROY timing, DBI lifecycle, and DBIx::Class compatibility

AGENTS.md

@@ -20,6 +20,18 @@
 
 ---
 
+## ⚠️ Resource Management: Avoid Fork Exhaustion ⚠️
+
+**Do NOT spawn excessive parallel processes.** Running too many background shells, subagents, or parallel builds at once can exhaust the system's process table (fork bomb), forcing a reboot and losing work.
+
+- **Limit parallel operations**: Run at most 2-3 concurrent processes at a time
+- **Avoid unnecessary background shells**: Use foreground execution when you don't need parallelism
+- **Wait for processes to finish** before starting new ones when possible
+- **Never run `make` in parallel with other heavy processes** (builds already use multiple threads internally)
+- **Clean up**: Kill background shells when they're no longer needed
+
+---
+
 ## Project Rules
 
 ### Progress Tracking for Multi-Phase Work
@@ -60,6 +72,10 @@ Example format at the end of a design doc:
 - Keep docs updated as implementation progresses
 - Reference related docs and skills at the end
 
+### Sandbox Tests
+
+- `dev/sandbox/destroy_weaken/` — Tests for DESTROY and weaken behavior (cascading cleanup, scope exit timing, blessed-without-DESTROY, etc.). Run with `./jperl` or `perl` for comparison.
+
 ### Partially Implemented Features
 
 | Feature | Status |

build.gradle

@@ -229,9 +229,10 @@ tasks.withType(JavaCompile).configureEach {
     options.compilerArgs << '-Xlint:deprecation'
 }
 
-// Test execution configuration with native access
+// Test execution configuration with native access and adequate heap
 tasks.withType(Test).configureEach {
     jvmArgs += '--enable-native-access=ALL-UNNAMED'
+    maxHeapSize = '1g'
 }
 
 // Enable native access for all Java execution tasks

dev/patches/cpan/DBIx-Class-0.082844/README.md

@@ -0,0 +1,55 @@
+# DBIx::Class 0.082844 Patches for PerlOnJava
+
+## Problem
+
+DBIx::Class uses `TxnScopeGuard` which relies on `DESTROY` for automatic 
+transaction rollback when a scope guard goes out of scope without being 
+committed. On PerlOnJava (JVM), `DESTROY` does not fire deterministically, 
+so:
+
+1. Failed bulk inserts leave `transaction_depth` permanently elevated
+2. Subsequent transactions silently nest instead of creating new top-level transactions
+3. `BEGIN`/`COMMIT` disappear from SQL traces
+4. Failed populates don't roll back (partial data left in DB)
+
+## Fix
+
+Wrap `txn_scope_guard`-protected code in `eval { ... } or do { rollback; die }` 
+to ensure explicit rollback on error, instead of relying on guard DESTROY.
+
+## Files Patched
+
+### Storage/DBI.pm — `_insert_bulk` method (line ~2415)
+- Wraps bulk insert + query_start/query_end + guard->commit in eval block
+- On error: sets guard inactivated, calls txn_rollback, re-throws
+
+### ResultSet.pm — `populate` method
+- **List context path** (line ~2239): wraps map-insert loop + guard->commit in eval
+- **Void context with rels path** (line ~2437): wraps _insert_bulk + children rels + guard->commit in eval
+
+## Applying Patches
+
+Patches must be applied to BOTH locations:
+1. Installed modules: `~/.perlonjava/lib/DBIx/Class/Storage/DBI.pm` and `ResultSet.pm`
+2. CPAN build dir: `~/.cpan/build/DBIx-Class-0.082844-*/lib/DBIx/Class/Storage/DBI.pm` and `ResultSet.pm`
+
+```bash
+# From the PerlOnJava project root:
+cd ~/.perlonjava/lib
+patch -p0 < path/to/dev/patches/cpan/DBIx-Class-0.082844/Storage-DBI.pm.patch
+
+# Also patch the active CPAN build dir (find the latest one):
+BUILDDIR=$(ls -td ~/.cpan/build/DBIx-Class-0.082844-*/lib | head -1)
+cd "$BUILDDIR/.."
+patch -p0 < path/to/dev/patches/cpan/DBIx-Class-0.082844/Storage-DBI.pm.patch
+```
+
+## Tests Fixed
+
+- t/100populate.t: tests 37-42 (void ctx trace BEGIN/COMMIT), 53 (populate is atomic),
+  59 (literal+bind normalization), 104-107 (multicol-PK has_many trace)
+- Result: 108/108 real tests pass (was 98/108), only GC tests 109-112 remain
+
+## Date
+
+2026-04-11

dev/sandbox/destroy_weaken/destroy_no_destroy_method.t

@@ -0,0 +1,230 @@
+use strict;
+use warnings;
+use Test::More;
+use Scalar::Util qw(weaken isweak);
+
+# =============================================================================
+# destroy_no_destroy_method.t — Cascading cleanup for blessed objects
+# without a DESTROY method
+#
+# When a blessed hash goes out of scope and its class does NOT define
+# DESTROY, Perl must still decrement refcounts on the hash's values.
+# This is critical for patterns like DBIx::Class where intermediate
+# Moo objects (e.g. BlockRunner) hold strong refs to tracked objects
+# but don't define DESTROY themselves.
+#
+# Root cause: DestroyDispatch.callDestroy skips scopeExitCleanupHash
+# for blessed objects whose class has no DESTROY method, leaking the
+# refcounts of the hash's values.
+# =============================================================================
+
+# --- Blessed holder WITHOUT DESTROY should still release contents ---
+{
+    my @log;
+    {
+        package NDM_Tracked;
+        sub new     { bless {}, shift }
+        sub DESTROY { push @log, "tracked" }
+    }
+    {
+        package NDM_HolderNoDestroy;
+        sub new { bless { target => $_[1] }, $_[0] }
+        # No DESTROY defined
+    }
+    my $weak;
+    {
+        my $tracked = NDM_Tracked->new;
+        $weak = $tracked;
+        weaken($weak);
+        my $holder = NDM_HolderNoDestroy->new($tracked);
+    }
+    is_deeply(\@log, ["tracked"],
+        "blessed holder without DESTROY still triggers DESTROY on contents");
+    ok(!defined $weak,
+        "tracked object is collected when holder without DESTROY goes out of scope");
+}
+
+# --- Contrast: blessed holder WITH DESTROY properly releases contents ---
+{
+    my @log;
+    {
+        package NDM_TrackedB;
+        sub new     { bless {}, shift }
+        sub DESTROY { push @log, "tracked" }
+    }
+    {
+        package NDM_HolderWithDestroy;
+        sub new     { bless { target => $_[1] }, $_[0] }
+        sub DESTROY { push @log, "holder" }
+    }
+    my $weak;
+    {
+        my $tracked = NDM_TrackedB->new;
+        $weak = $tracked;
+        weaken($weak);
+        my $holder = NDM_HolderWithDestroy->new($tracked);
+    }
+    is_deeply(\@log, ["holder", "tracked"],
+        "blessed holder with DESTROY cascades to contents");
+    ok(!defined $weak,
+        "tracked object is collected when holder with DESTROY goes out of scope");
+}
+
+# --- Contrast: unblessed hashref properly releases contents ---
+{
+    my @log;
+    {
+        package NDM_TrackedC;
+        sub new     { bless {}, shift }
+        sub DESTROY { push @log, "tracked" }
+    }
+    my $weak;
+    {
+        my $tracked = NDM_TrackedC->new;
+        $weak = $tracked;
+        weaken($weak);
+        my $holder = { target => $tracked };
+    }
+    is_deeply(\@log, ["tracked"],
+        "unblessed hashref releases tracked contents");
+    ok(!defined $weak,
+        "tracked object is collected when unblessed holder goes out of scope");
+}
+
+# --- Nested: blessed-no-DESTROY holds blessed-no-DESTROY holds tracked ---
+{
+    my @log;
+    {
+        package NDM_TrackedD;
+        sub new     { bless {}, shift }
+        sub DESTROY { push @log, "tracked" }
+    }
+    {
+        package NDM_OuterNoDestroy;
+        sub new { bless { inner => $_[1] }, $_[0] }
+    }
+    {
+        package NDM_InnerNoDestroy;
+        sub new { bless { target => $_[1] }, $_[0] }
+    }
+    my $weak;
+    {
+        my $tracked = NDM_TrackedD->new;
+        $weak = $tracked;
+        weaken($weak);
+        my $inner = NDM_InnerNoDestroy->new($tracked);
+        my $outer = NDM_OuterNoDestroy->new($inner);
+    }
+    ok(!defined $weak,
+        "nested blessed-no-DESTROY chain still releases tracked object");
+}
+
+# --- Weak backref pattern (Schema/Storage cycle) ---
+#
+# Schema (blessed, has DESTROY) ──strong──> Storage
+# Storage (blessed, has DESTROY) ──weak────> Schema
+# BlockRunner (blessed, NO DESTROY) ──strong──> Storage
+#
+# When BlockRunner goes out of scope, Storage refcount must decrement.
+# Later when Schema goes out of scope, cascading DESTROY must bring
+# Storage refcount to 0.
+{
+    my @log;
+    {
+        package NDM_Storage;
+        use Scalar::Util qw(weaken);
+        sub new {
+            my ($class, $schema) = @_;
+            my $self = bless {}, $class;
+            $self->{schema} = $schema;
+            weaken($self->{schema});
+            return $self;
+        }
+        sub DESTROY { push @log, "storage" }
+    }
+    {
+        package NDM_Schema;
+        sub new     { bless {}, $_[0] }
+        sub DESTROY { push @log, "schema" }
+    }
+    {
+        package NDM_BlockRunner;
+        sub new { bless { storage => $_[1] }, $_[0] }
+        # No DESTROY — like DBIx::Class::Storage::BlockRunner
+    }
+
+    my $weak_storage;
+    {
+        my $schema = NDM_Schema->new;
+        my $storage = NDM_Storage->new($schema);
+        $schema->{storage} = $storage;
+
+        $weak_storage = $storage;
+        weaken($weak_storage);
+
+        # Simulate dbh_do: create a BlockRunner that holds storage
+        my $runner = NDM_BlockRunner->new($storage);
+        undef $storage;
+
+        # Runner goes out of scope here — must release storage ref
+        undef $runner;
+        # Now only $schema->{storage} should hold storage
+    }
+    # After block: schema out of scope -> DESTROY schema -> cascade -> DESTROY storage
+    ok(!defined $weak_storage,
+        "Schema/Storage/BlockRunner pattern: storage collected after all go out of scope");
+    my @sorted = sort @log;
+    ok(grep({ $_ eq "schema" } @sorted) && grep({ $_ eq "storage" } @sorted),
+        "both schema and storage DESTROY fired");
+}
+
+# --- Explicit undef of blessed-no-DESTROY should release contents ---
+{
+    my @log;
+    {
+        package NDM_TrackedE;
+        sub new     { bless {}, shift }
+        sub DESTROY { push @log, "tracked" }
+    }
+    {
+        package NDM_HolderNoDestroyE;
+        sub new { bless { target => $_[1] }, $_[0] }
+    }
+    my $weak;
+    my $tracked = NDM_TrackedE->new;
+    $weak = $tracked;
+    weaken($weak);
+    my $holder = NDM_HolderNoDestroyE->new($tracked);
+    undef $tracked;  # only holder keeps it alive
+    ok(defined $weak, "tracked still alive via holder");
+    undef $holder;   # should cascade-release tracked
+    ok(!defined $weak,
+        "explicit undef of blessed-no-DESTROY holder releases tracked object");
+    is_deeply(\@log, ["tracked"], "DESTROY fired on tracked after holder undef");
+}
+
+# --- Array-based blessed object without DESTROY ---
+{
+    my @log;
+    {
+        package NDM_TrackedF;
+        sub new     { bless {}, shift }
+        sub DESTROY { push @log, "tracked" }
+    }
+    {
+        package NDM_ArrayHolder;
+        sub new { bless [ $_[1] ], $_[0] }
+        # No DESTROY
+    }
+    my $weak;
+    {
+        my $tracked = NDM_TrackedF->new;
+        $weak = $tracked;
+        weaken($weak);
+        my $holder = NDM_ArrayHolder->new($tracked);
+    }
+    ok(!defined $weak,
+        "array-based blessed-no-DESTROY releases tracked object");
+}
+
+done_testing;

src/main/java/org/perlonjava/app/scriptengine/PerlLanguageProvider.java

@@ -388,6 +388,24 @@ private static RuntimeList executeCode(RuntimeCode runtimeCode, EmitterContext c
 
             try {
                 if (isMainProgram) {
+                    // Flush deferred mortal decrements from file-scoped lexical cleanup.
+                    // The main script's apply() runs scopeExitCleanup for all my-variables
+                    // (deferring refCount decrements), but the MortalList is not flushed
+                    // inside the subroutine (flush=false for blockIsSubroutine). Process
+                    // those decrements now so objects reach refCount=0 and DESTROY fires
+                    // BEFORE END blocks run — matching Perl 5's destruct sequence where
+                    // file-scoped lexicals are destroyed before END block dispatch.
+                    MortalList.flush();
+
+                    // Process captured variables whose scope has exited but whose
+                    // refCount was deferred because captureCount > 0. The interpreter
+                    // captures ALL visible lexicals for eval STRING support, inflating
+                    // captureCount on variables that closures don't actually use.
+                    // Now that all scopes have exited, it's safe to decrement.
+                    // This must happen before END blocks so that DBIC's LeakTracer
+                    // (which runs in an END block) sees objects properly DESTROY'd.
+                    MortalList.flushDeferredCaptures();
+
                     CallerStack.push("main", ctx.compilerOptions.fileName, 0);
                     try {
                         runEndBlocks();
@@ -414,6 +432,8 @@ private static RuntimeList executeCode(RuntimeCode runtimeCode, EmitterContext c
             result = e.returnValue != null ? e.returnValue.getList() : new RuntimeList();
         } catch (Throwable t) {
             if (isMainProgram) {
+                MortalList.flush();  // Flush file-scoped lexical cleanup before END
+                MortalList.flushDeferredCaptures();  // Process captured vars (see above)
                 CallerStack.push("main", ctx.compilerOptions.fileName, 0);
                 try {
                     runEndBlocks(false);  // Don't reset $? on exception path