fix: preserve CPAN runtime compatibility across threads

Implement B::SV address recovery for observed references, carry those
addresses through ithread snapshots, account for parser-installed named
subroutine stash ownership, and expose POSIX floating-point epsilon constants.

Generated with Codex (https://openai.com/codex)

Co-Authored-By: Codex <codex@openai.com>

Author: fglock

src/main/java/org/perlonjava/frontend/parser/SubroutineParser.java

@@ -1854,6 +1854,19 @@ private static List<Object> closureCapturesForMaterialization(
 
     private static void installClosureCaptureMetadata(
             RuntimeCode code, List<String> capturedNames, List<Object> capturedValues) {
+        // Named subs created through the parser populate an existing stash
+        // scalar in place rather than going through RuntimeGlob's CODE-slot
+        // assignment path. Account for that persistent stash owner so a
+        // temporary copy of \&name cannot release the named CV's pad.
+        if (code != null && code.stashRefCount == 0) {
+            for (RuntimeScalar installed : GlobalVariable.globalCodeRefs.values()) {
+                if (installed != null && installed.value == code) {
+                    code.hadStashRef = true;
+                    code.stashRefCount = 1;
+                    break;
+                }
+            }
+        }
         if (code == null || capturedValues == null || capturedValues.isEmpty()
                 || code.capturedScalars != null) {
             return;

src/main/java/org/perlonjava/runtime/perlmodule/Internals.java

@@ -37,6 +37,7 @@ public static void initialize() {
             // against native Perl. See dev/design/refcount_alignment_plan.md.
             internals.registerMethod("jperl_refstate", "jperl_refstate", "$");
             internals.registerMethod("jperl_refstate_str", "jperl_refstate_str", "$");
+            internals.registerMethod("jperl_reference_by_address", "jperlReferenceByAddress", "$");
             // Phase 4 (refcount_alignment_plan.md): On-demand reachability
             // sweep. Walks Perl-visible roots (globals, stashes, rescued
             // objects) and clears weak refs for unreachable objects. Returns
@@ -364,6 +365,13 @@ public static RuntimeList svRefcount(RuntimeArray args, int ctx) {
         return new RuntimeScalar(1).getList();
     }
 
+    /** Return a reference whose displayed address was observed in this runtime. */
+    public static RuntimeList jperlReferenceByAddress(RuntimeArray args, int ctx) {
+        long address = args.get(0).getLong();
+        RuntimeBase value = PerlRuntime.current().resolveReferenceAddress(address);
+        return value == null ? RuntimeScalarCache.scalarUndef.getList() : value.createReference().getList();
+    }
+
     /**
      * Phase 0 diagnostic: return a hashref describing the full internal
      * refcount state of the referent. Intended for differential testing

src/main/java/org/perlonjava/runtime/perlmodule/ScalarUtil.java

@@ -120,7 +120,9 @@ public static RuntimeList refaddr(RuntimeArray args, int ctx) {
             case FORMAT:
             case REGEX:
                 // Return identity of the underlying value object
-                return new RuntimeScalar(System.identityHashCode(scalar.value)).getList();
+                RuntimeBase referenced = (RuntimeBase) scalar.value;
+                PerlRuntime.current().registerReferenceAddress(referenced);
+                return new RuntimeScalar(PerlRuntime.referenceAddress(referenced)).getList();
             case GLOB:
             case GLOBREFERENCE:
                 if (scalar.value instanceof RuntimeGlob glob) {

src/main/java/org/perlonjava/runtime/runtimetypes/PerlRuntime.java

@@ -26,7 +26,9 @@
 import java.util.Set;
 import java.util.ArrayDeque;
 import java.util.Deque;
+import java.lang.ref.WeakReference;
 import java.util.concurrent.Callable;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.locks.ReentrantLock;
 import java.util.TreeSet;
 
@@ -79,6 +81,7 @@ public final class PerlRuntime implements AutoCloseable {
     public RuntimeArray libOriginalInc;
     public boolean storableLastOpInNetorder;
     public final Set<String> xsShimLoadingInProgress = new HashSet<>();
+    private final Map<Long, WeakReference<RuntimeBase>> referenceAddresses = new ConcurrentHashMap<>();
 
     RuntimeIO ioStdout;
     RuntimeIO ioStderr;
@@ -148,6 +151,39 @@ public static PerlRuntime currentOrNull() {
         return frame != null ? frame.runtime : null;
     }
 
+    /** Record the address exposed by Perl reference stringification for B introspection. */
+    public void registerReferenceAddress(RuntimeBase value) {
+        registerReferenceAddress(referenceAddress(value), value);
+    }
+
+    public static long referenceAddress(RuntimeBase value) {
+        return Integer.toUnsignedLong(System.identityHashCode(value));
+    }
+
+    /** Record an inherited address token for the corresponding cloned referent. */
+    public void registerReferenceAddress(long address, RuntimeBase value) {
+        referenceAddresses.put(address, new WeakReference<>(value));
+    }
+
+    /** Resolve an address previously exposed in this interpreter instance. */
+    public RuntimeBase resolveReferenceAddress(long address) {
+        WeakReference<RuntimeBase> reference = referenceAddresses.get(address);
+        RuntimeBase value = reference == null ? null : reference.get();
+        if (reference != null && value == null) {
+            referenceAddresses.remove(address, reference);
+        }
+        return value;
+    }
+
+    Map<Long, RuntimeBase> snapshotReferenceAddresses() {
+        Map<Long, RuntimeBase> snapshot = new HashMap<>();
+        referenceAddresses.forEach((address, reference) -> {
+            RuntimeBase value = reference.get();
+            if (value != null) snapshot.put(address, value);
+        });
+        return snapshot;
+    }
+
     /** Bind this runtime until the returned scope is closed. */
     public Binding bind() {
         if (closed) {
@@ -315,6 +351,7 @@ private ThreadSnapshot snapshotCloneInternal(PerlThreadRegistry registry, long t
                 runtimeCodeState.snapshotCompiledMetadataInto(child.runtimeCodeState);
                 regexState.snapshotInto(child.regexState);
             }
+            cloner.finishSnapshot();
             child.currentDirectory = currentDirectory;
             child.initialized = true;
             try (Binding ignored = child.bind()) {
@@ -390,6 +427,7 @@ public void close() {
                 flipFlopState.clear();
                 scalarGlobState.clear();
                 pointerPackState.clear();
+                referenceAddresses.clear();
             }
             closed = true;
         } finally {

src/main/java/org/perlonjava/runtime/runtimetypes/RuntimeArray.java

@@ -1574,7 +1574,8 @@ public Iterator<RuntimeScalar> iterator() {
      * @return A string representing the array reference.
      */
     public String toStringRef() {
-        String ref = "ARRAY(0x" + Integer.toHexString(this.hashCode()) + ")";
+        registerReferenceAddress();
+        String ref = "ARRAY(0x" + referenceAddressHex() + ")";
         return (blessId == 0
                 ? ref
                 : NameNormalizer.getBlessStr(blessId) + "=" + ref);

src/main/java/org/perlonjava/runtime/runtimetypes/RuntimeBase.java

@@ -442,9 +442,21 @@ public RuntimeScalar getFirst() {
     }
 
     public String toStringRef() {
+        registerReferenceAddress();
         return this.toString();
     }
 
+    protected final String referenceAddressHex() {
+        return Long.toHexString(PerlRuntime.referenceAddress(this));
+    }
+
+    protected final void registerReferenceAddress() {
+        PerlRuntime runtime = PerlRuntime.currentOrNull();
+        if (runtime != null) {
+            runtime.registerReferenceAddress(this);
+        }
+    }
+
     public double getDoubleRef() {
         return this.hashCode();
     }

src/main/java/org/perlonjava/runtime/runtimetypes/RuntimeCode.java

@@ -5716,7 +5716,8 @@ private static RuntimeList forkOpenResult(ForkOpenCompleteException exception, i
      * @return a string representing the CODE reference
      */
     public String toStringRef() {
-        String ref = "CODE(0x" + Integer.toHexString(this.hashCode()) + ")";
+        registerReferenceAddress();
+        String ref = "CODE(0x" + referenceAddressHex() + ")";
         return (blessId == 0
                 ? ref
                 : NameNormalizer.getBlessStr(blessId) + "=" + ref);

src/main/java/org/perlonjava/runtime/runtimetypes/RuntimeGlob.java

@@ -1232,7 +1232,8 @@ public String toString() {
      * @return A string representation of the typeglob reference.
      */
     public String toStringRef() {
-        String ref = "GLOB(0x" + Integer.toHexString(this.hashCode()) + ")";
+        registerReferenceAddress();
+        String ref = "GLOB(0x" + referenceAddressHex() + ")";
         return (blessId == 0
                 ? ref
                 : NameNormalizer.getBlessStr(blessId) + "=" + ref);

src/main/java/org/perlonjava/runtime/runtimetypes/RuntimeGraphCloner.java

@@ -56,7 +56,7 @@ public <T extends RuntimeBase> T cloneGraph(T value) {
         try {
             return (T) cloneValue(value);
         } finally {
-            if (--publicDepth == 0) finishWeakReferences();
+            if (--publicDepth == 0) finishCloneBoundary();
         }
     }
 
@@ -68,10 +68,37 @@ public List<RuntimeBase> cloneRoots(List<? extends RuntimeBase> roots) {
             for (RuntimeBase root : roots) result.add(cloneValue(root));
             return result;
         } finally {
-            if (--publicDepth == 0) finishWeakReferences();
+            if (--publicDepth == 0) finishCloneBoundary();
         }
     }
 
+    private void finishCloneBoundary() {
+        Map<Long, RuntimeBase> observed = sourceRuntime.snapshotReferenceAddresses();
+        // A stringified object can remain visible only through a weak Perl
+        // edge. ithreads still clone that live SV before invoking CLONE, so
+        // ensure it participates in this graph even when no strong root led
+        // to it during the ordinary traversal.
+        for (RuntimeBase source : observed.values()) {
+            if (!source.threadShared && !clones.containsKey(source)) {
+                cloneValue(source);
+            }
+        }
+        finishWeakReferences();
+        for (Map.Entry<Long, RuntimeBase> entry : observed.entrySet()) {
+            RuntimeBase source = entry.getValue();
+            RuntimeBase target = source.threadShared
+                    ? source : (RuntimeBase) clones.get(source);
+            if (target != null) {
+                targetRuntime.registerReferenceAddress(entry.getKey(), target);
+            }
+        }
+    }
+
+    /** Complete a runtime snapshot before any child CLONE hooks execute. */
+    void finishSnapshot() {
+        finishCloneBoundary();
+    }
+
     /** Package/runtime snapshot entry point that retains the shared graph map. */
     RuntimeBase cloneValue(RuntimeBase value) {
         if (value == null) return null;

src/main/java/org/perlonjava/runtime/runtimetypes/RuntimeHash.java

@@ -1306,6 +1306,7 @@ public String dump() {
      * @return A string in the format "HASH(hashCode)".
      */
     public String toStringRef() {
+        registerReferenceAddress();
         // Check if this is a Perl 5.38+ class instance
         String refType = "HASH";
         if (blessId != 0) {
@@ -1315,7 +1316,7 @@ public String toStringRef() {
             }
         }
 
-        String ref = refType + "(0x" + Integer.toHexString(this.hashCode()) + ")";
+        String ref = refType + "(0x" + referenceAddressHex() + ")";
         return (blessId == 0
                 ? ref
                 : NameNormalizer.getBlessStr(blessId) + "=" + ref);