Fix regressions: goto in map/grep hang, parsimonious dup closes, glob-based handle lookup

Three fixes and comprehensive documentation:

1. op/array.t hang (176->0->176 FIXED): map/grep/all/any in ListOperators.java
   were missing control flow checks after RuntimeCode.apply(). When goto LABEL
   was used inside a map block, the RuntimeControlFlowList marker was silently
   discarded, causing an infinite loop (unshift grew the array each iteration).
   Added isNonLocalGoto() checks that propagate the marker to the caller.

2. io/dup.t regression (25->20->23 IMPROVED): Parsimonious dup (>&= / <&=)
   was returning the same RuntimeIO object, so close F on a parsimonious dup
   of STDOUT closed STDOUT itself. Created BorrowedIOHandle -- a non-owning
   wrapper that delegates all I/O but only flushes on close (never closes the
   delegate), matching Perl fdopen() semantics.

3. Named handle lookup via glob table: openFileHandleDup() now resolves
   named handles (STDIN/STDOUT/STDERR and user-defined) via GlobalVariable
   getGlobalIO() instead of a switch on static RuntimeIO fields. This is
   essential because standard handles can be redirected at runtime via
   open(STDOUT, ">file"). The glob table always reflects the current handle.

4. Thorough documentation added to all IO dup-related code including
   DupIOHandle, BorrowedIOHandle, FileDescriptorTable, and IOOperator methods.

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: fglock

src/main/java/org/perlonjava/core/Configuration.java

@@ -33,7 +33,7 @@ public final class Configuration {
      * Automatically populated by Gradle/Maven during build.
      * DO NOT EDIT MANUALLY - this value is replaced at build time.
      */
-    public static final String gitCommitId = "116d88c7a";
+    public static final String gitCommitId = "69c74c914";
 
     /**
      * Git commit date of the build (ISO format: YYYY-MM-DD).

src/main/java/org/perlonjava/runtime/io/BorrowedIOHandle.java

@@ -0,0 +1,200 @@
+package org.perlonjava.runtime.io;
+
+import org.perlonjava.runtime.runtimetypes.RuntimeScalar;
+
+import java.nio.charset.Charset;
+
+import static org.perlonjava.runtime.runtimetypes.RuntimeIO.handleIOException;
+import static org.perlonjava.runtime.runtimetypes.RuntimeScalarCache.scalarTrue;
+
+/**
+ * A non-owning IOHandle wrapper for Perl's parsimonious dup semantics ({@code >&=} / {@code <&=}).
+ *
+ * <h3>Background: parsimonious dup in Perl</h3>
+ * <p>When Perl executes {@code open(F, ">&=STDOUT")}, it performs an {@code fdopen()} —
+ * creating a new FILE* that shares the same fd as STDOUT. The key semantic difference
+ * from a full dup ({@code >&}) is:</p>
+ * <ul>
+ *   <li>Both handles share the <em>same</em> file descriptor (same fileno).</li>
+ *   <li>Closing the new handle ({@code close F}) does <em>not</em> close the underlying
+ *       resource — the original handle (STDOUT) remains fully operational.</li>
+ *   <li>This is a lightweight alias — no new OS-level file descriptor is allocated.</li>
+ * </ul>
+ *
+ * <h3>Implementation</h3>
+ * <p>BorrowedIOHandle delegates all I/O operations to the underlying delegate IOHandle,
+ * but overrides {@link #close()} to only flush — never closing the delegate. This
+ * ensures that after {@code close F}, the original handle (e.g. STDOUT) keeps working.</p>
+ *
+ * <p>Unlike {@link DupIOHandle}, this wrapper:</p>
+ * <ul>
+ *   <li>Does NOT allocate a new fd number (shares the delegate's fileno)</li>
+ *   <li>Does NOT use reference counting (the delegate is never closed by us)</li>
+ *   <li>Is much simpler — just a thin delegation layer with a close-guard</li>
+ * </ul>
+ *
+ * @see DupIOHandle  for full dup semantics ({@code >&}) with reference counting
+ * @see IOOperator#openFileHandleDup(String, String)  where this is created
+ */
+public class BorrowedIOHandle implements IOHandle {
+
+    /** The underlying handle we're borrowing — never closed by us. */
+    private final IOHandle delegate;
+    /** Per-instance closed flag. Once true, all I/O operations on THIS wrapper fail. */
+    private boolean closed = false;
+
+    /**
+     * Creates a BorrowedIOHandle wrapping the given delegate.
+     *
+     * @param delegate the underlying IOHandle to borrow (not owned — will not be closed)
+     */
+    public BorrowedIOHandle(IOHandle delegate) {
+        this.delegate = delegate;
+    }
+
+    /**
+     * Returns the underlying delegate IOHandle.
+     */
+    public IOHandle getDelegate() {
+        return delegate;
+    }
+
+    // ---- Delegated I/O operations (check closed state first) ----
+
+    @Override
+    public RuntimeScalar write(String string) {
+        if (closed) return handleClosed("write");
+        return delegate.write(string);
+    }
+
+    @Override
+    public RuntimeScalar flush() {
+        if (closed) return scalarTrue;
+        return delegate.flush();
+    }
+
+    @Override
+    public RuntimeScalar sync() {
+        if (closed) return scalarTrue;
+        return delegate.sync();
+    }
+
+    @Override
+    public RuntimeScalar doRead(int maxBytes, Charset charset) {
+        if (closed) return handleClosed("read");
+        return delegate.doRead(maxBytes, charset);
+    }
+
+    @Override
+    public RuntimeScalar fileno() {
+        if (closed) return handleClosed("fileno");
+        // Return the delegate's fileno — parsimonious dup shares the same fd
+        return delegate.fileno();
+    }
+
+    @Override
+    public RuntimeScalar eof() {
+        if (closed) return scalarTrue;
+        return delegate.eof();
+    }
+
+    @Override
+    public RuntimeScalar tell() {
+        if (closed) return handleClosed("tell");
+        return delegate.tell();
+    }
+
+    @Override
+    public RuntimeScalar seek(long pos, int whence) {
+        if (closed) return handleClosed("seek");
+        return delegate.seek(pos, whence);
+    }
+
+    @Override
+    public RuntimeScalar truncate(long length) {
+        if (closed) return handleClosed("truncate");
+        return delegate.truncate(length);
+    }
+
+    @Override
+    public RuntimeScalar flock(int operation) {
+        if (closed) return handleClosed("flock");
+        return delegate.flock(operation);
+    }
+
+    @Override
+    public RuntimeScalar bind(String address, int port) {
+        if (closed) return handleClosed("bind");
+        return delegate.bind(address, port);
+    }
+
+    @Override
+    public RuntimeScalar connect(String address, int port) {
+        if (closed) return handleClosed("connect");
+        return delegate.connect(address, port);
+    }
+
+    @Override
+    public RuntimeScalar listen(int backlog) {
+        if (closed) return handleClosed("listen");
+        return delegate.listen(backlog);
+    }
+
+    @Override
+    public RuntimeScalar accept() {
+        if (closed) return handleClosed("accept");
+        return delegate.accept();
+    }
+
+    @Override
+    public boolean isBlocking() {
+        if (closed) return true;
+        return delegate.isBlocking();
+    }
+
+    @Override
+    public boolean setBlocking(boolean blocking) {
+        if (closed) return blocking;
+        return delegate.setBlocking(blocking);
+    }
+
+    @Override
+    public RuntimeScalar sysread(int length) {
+        if (closed) return handleClosed("sysread");
+        return delegate.sysread(length);
+    }
+
+    @Override
+    public RuntimeScalar syswrite(String data) {
+        if (closed) return handleClosed("syswrite");
+        return delegate.syswrite(data);
+    }
+
+    // ---- Close: flush only, do NOT close the delegate ----
+
+    /**
+     * Closes this borrowed handle.
+     *
+     * <p>Only flushes the delegate — does NOT close the underlying resource.
+     * This matches Perl's fdopen semantics where closing an fdopen'd FILE*
+     * does not invalidate the original handle.</p>
+     */
+    @Override
+    public RuntimeScalar close() {
+        if (closed) {
+            return handleIOException(
+                    new java.io.IOException("Handle is already closed."),
+                    "Handle is already closed.");
+        }
+        closed = true;
+        // Only flush — never close the delegate. The original handle still owns it.
+        delegate.flush();
+        return scalarTrue;
+    }
+
+    private RuntimeScalar handleClosed(String operation) {
+        return handleIOException(
+                new java.io.IOException("Cannot " + operation + " on a closed handle."),
+                operation + " on closed handle failed");
+    }
+}

src/main/java/org/perlonjava/runtime/io/DupIOHandle.java

@@ -9,23 +9,74 @@
 import static org.perlonjava.runtime.runtimetypes.RuntimeScalarCache.*;
 
 /**
- * A reference-counted IOHandle wrapper that enables proper filehandle duplication.
+ * A reference-counted IOHandle wrapper that enables proper filehandle duplication
+ * semantics — the Java equivalent of POSIX {@code dup(2)}.
  *
- * <p>When Perl does {@code open(SAVE, ">&STDERR")}, it creates a new file descriptor
+ * <h3>Background: Perl's filehandle duplication</h3>
+ * <p>When Perl executes {@code open(SAVE, ">&STDERR")}, it creates a new file descriptor
  * (via dup()) that shares the same underlying file description. Both fds are independent:
- * closing one does not affect the other. The underlying resource is only released when
- * ALL duplicates are closed.
+ * closing one does not affect the other. The underlying OS resource (file, pipe, socket)
+ * is only released when ALL duplicates are closed.</p>
  *
- * <p>This class implements that semantic by wrapping a delegate IOHandle with a shared
- * reference count. Each DupIOHandle tracks its own closed state. When close() is called,
- * the refcount is decremented; the delegate is only actually closed when the last
- * DupIOHandle is closed.
+ * <p>Java doesn't expose POSIX file descriptors, so we simulate this behavior with
+ * reference-counted wrappers around an underlying {@link IOHandle} delegate.</p>
+ *
+ * <h3>Architecture</h3>
+ * <pre>
+ *   ┌──────────────────────┐     ┌──────────────────────┐
+ *   │ DupIOHandle (fd=1)   │     │ DupIOHandle (fd=5)   │
+ *   │ closed=false         │     │ closed=false         │
+ *   │ refCount ─────────────┼─────┼─▶ AtomicInteger(2)  │
+ *   │ delegate ─────────────┼─────┼─▶ StandardIO         │
+ *   └──────────────────────┘     └──────────────────────┘
+ *                                      (shared)
+ * </pre>
+ *
+ * <h3>Lifecycle</h3>
+ * <ol>
+ *   <li><b>Creation via {@link #createPair(IOHandle, int)}</b>: Called the first time
+ *       a handle is duplicated. Creates two DupIOHandles sharing the same delegate and
+ *       a new {@code AtomicInteger(2)} refCount. The first wrapper preserves the
+ *       original's fd; the second gets a new fd from {@link FileDescriptorTable}.</li>
+ *   <li><b>Subsequent dups via {@link #addDup(DupIOHandle)}</b>: Increments the shared
+ *       refCount and creates a new DupIOHandle with a new fd. No limit on how many
+ *       dups can be created.</li>
+ *   <li><b>Close</b>: Each DupIOHandle tracks its own {@code closed} flag. On close:
+ *       <ul>
+ *         <li>Marks itself as closed (further I/O operations will fail)</li>
+ *         <li>Unregisters its fd from {@link FileDescriptorTable}</li>
+ *         <li>Decrements the shared refCount</li>
+ *         <li>If refCount reaches 0 (last dup closed), actually closes the delegate</li>
+ *         <li>If refCount > 0 (other dups still open), just flushes the delegate</li>
+ *       </ul>
+ *   </li>
+ * </ol>
+ *
+ * <h3>Thread safety</h3>
+ * <p>The refCount uses {@link AtomicInteger} for thread-safe decrement. The {@code closed}
+ * flag is per-instance and not synchronized — this matches the Perl model where each
+ * filehandle is used by a single thread. If concurrent access is needed in the future,
+ * the closed flag should be made volatile or synchronized.</p>
+ *
+ * <h3>fd number management</h3>
+ * <p>Each DupIOHandle holds a synthetic fd number assigned by {@link FileDescriptorTable}.
+ * The {@link #fileno()} method returns this fd (not the delegate's fd), so each duplicate
+ * has a unique fileno as Perl expects. This fd is registered in FileDescriptorTable for
+ * lookup by select() and in RuntimeIO for lookup by {@code findFileHandleByDescriptor()}.</p>
+ *
+ * @see IOOperator#duplicateFileHandle(RuntimeIO)  where DupIOHandles are created
+ * @see IOOperator#openFileHandleDup(String, String)  entry point for Perl's open() dup modes
+ * @see FileDescriptorTable  synthetic fd allocation and lookup
  */
 public class DupIOHandle implements IOHandle {
 
+    /** The underlying I/O implementation (StandardIO, FileIOHandle, etc.) — never another DupIOHandle. */
     private final IOHandle delegate;
+    /** Shared across all dups of the same delegate. Decremented on close; delegate closed at zero. */
     private final AtomicInteger refCount;
+    /** Per-instance closed flag. Once true, all I/O operations on THIS dup return errors. */
     private boolean closed = false;
+    /** Synthetic fd number unique to this dup, assigned by FileDescriptorTable. */
     private final int fd;
 
     /**
@@ -202,6 +253,19 @@ public RuntimeScalar syswrite(String data) {
 
     // ---- Close with reference counting ----
 
+    /**
+     * Closes this duplicate handle.
+     *
+     * <p>Semantics:
+     * <ol>
+     *   <li>If already closed, returns an error (matches Perl's "close on closed fh").</li>
+     *   <li>Marks this instance as closed — subsequent I/O operations will fail.</li>
+     *   <li>Unregisters this fd from {@link FileDescriptorTable}.</li>
+     *   <li>Decrements the shared refCount atomically.</li>
+     *   <li>If this was the <em>last</em> duplicate (refCount → 0), closes the delegate.</li>
+     *   <li>Otherwise, just flushes the delegate to ensure buffered data is written.</li>
+     * </ol>
+     */
     @Override
     public RuntimeScalar close() {
         if (closed) {

src/main/java/org/perlonjava/runtime/io/FileDescriptorTable.java

@@ -6,29 +6,60 @@
 import org.perlonjava.runtime.runtimetypes.RuntimeIO;
 
 /**
- * Maps simulated file descriptor numbers to IOHandle objects.
+ * Maps simulated file descriptor numbers to {@link IOHandle} objects.
  *
- * <p>Java doesn't expose real POSIX file descriptors. This table assigns
- * sequential integers starting from 3 (0, 1, 2 are reserved for
- * stdin, stdout, stderr) and allows lookup by FD number.
+ * <h3>Why this exists</h3>
+ * <p>Java doesn't expose real POSIX file descriptors. Perl code, however, relies on
+ * numeric fd values for operations like {@code fileno()}, {@code select()}, and
+ * {@code open(FH, ">&=", $fd)}. This table assigns sequential integers starting
+ * from 3 (0, 1, 2 are reserved for stdin, stdout, stderr) and provides fd→IOHandle
+ * lookup.</p>
  *
- * <p>Used by:
- * <ul>
- *   <li>{@code fileno()} — to return a consistent FD for each handle</li>
- *   <li>4-arg {@code select()} — to map bit-vector bits back to handles</li>
- * </ul>
+ * <h3>Relationship to other fd registries</h3>
+ * <p>There are <b>three</b> fd-related registries in the system, each serving a
+ * different purpose:</p>
+ * <table border="1">
+ *   <tr><th>Registry</th><th>Maps</th><th>Used by</th></tr>
+ *   <tr>
+ *     <td>{@code FileDescriptorTable} (this class)</td>
+ *     <td>fd → {@link IOHandle}</td>
+ *     <td>{@code select()}, {@link DupIOHandle} registration</td>
+ *   </tr>
+ *   <tr>
+ *     <td>{@code RuntimeIO.filenoToIO}</td>
+ *     <td>fd → {@link RuntimeIO}</td>
+ *     <td>{@link IOOperator#findFileHandleByDescriptor(int)} fallback</td>
+ *   </tr>
+ *   <tr>
+ *     <td>{@code IOOperator.fileDescriptorMap}</td>
+ *     <td>fd → {@link RuntimeIO}</td>
+ *     <td>{@link IOOperator#findFileHandleByDescriptor(int)} first check</td>
+ *   </tr>
+ * </table>
  *
- * <p>Thread-safe: uses ConcurrentHashMap and AtomicInteger.
+ * <p>These registries are kept in sync via {@link #advancePast(int)} and
+ * {@link RuntimeIO#advanceFilenoCounterPast(int)} to prevent fd collisions between
+ * handles allocated by different subsystems (e.g., DupIOHandle vs. socket/pipe).</p>
+ *
+ * <h3>Thread safety</h3>
+ * <p>Uses {@link ConcurrentHashMap} and {@link AtomicInteger} for thread-safe access.</p>
+ *
+ * @see DupIOHandle        uses this table for fd allocation and registration
+ * @see IOOperator         uses this table indirectly via DupIOHandle
+ * @see RuntimeIO          parallel fd→RuntimeIO registry for higher-level lookups
  */
 public class FileDescriptorTable {
 
-    // Next FD number to assign.  0–2 are stdin/stdout/stderr.
+    /** Next fd to allocate. Starts at 3 (0=stdin, 1=stdout, 2=stderr are reserved). */
     private static final AtomicInteger nextFd = new AtomicInteger(3);
 
-    // FD number → IOHandle (for select() lookup)
+    /** Forward map: fd number → IOHandle. Used by select() to find handles from fd bits. */
     private static final ConcurrentHashMap<Integer, IOHandle> fdToHandle = new ConcurrentHashMap<>();
 
-    // IOHandle identity → FD number (to avoid assigning multiple FDs to the same handle)
+    /**
+     * Reverse map: IOHandle identity hash → fd number.
+     * Prevents assigning multiple fds to the same IOHandle object (identity, not equality).
+     */
     private static final ConcurrentHashMap<Integer, Integer> handleToFd = new ConcurrentHashMap<>();
 
     /**