FEATURE-ci-iocp-close: Honor the socket close lvalue contract

Use the shared invalidating close helper for both IOCP socket kinds while preserving cancellation and packet lease ordering. Retain native compiler RED and focused local helper, lint and diff evidence; Windows compile and runtime remain CI-owned.

Author: etr

specs/tasks/FEATURE-ci-iocp-close.md

@@ -0,0 +1,79 @@
+# FEATURE-ci-iocp-close
+
+Status: Implementation complete; caller Groundwork validation and finalization
+pending. Native Windows results remain CI / v3 PR owned.
+
+Scope: repair the IOCP socket retirement call rejected by the Windows compiler.
+Base: v3 at `b5cd6cf06e39a1b0727c2614e5236ff00a59dbf1`.
+
+- [x] Create an isolated task worktree using the Groundwork identity helper.
+- [x] Read the actual native Windows compile failure and verify its source is
+      unchanged at the task base.
+- [x] Pass the registration socket lvalue to the shared close helper, preserving
+      handle invalidation, map erasure, cancellation and completion lease lifetime.
+- [x] Retain the existing native UDP cancellation/reuse test without adding
+      mirrored source-text or synthetic implementation tests.
+- [x] Build and run the focused existing local socket helper suite; run cpplint
+      on the changed production file and check the diff.
+- [x] Retain commands, raw results, original failure and causal assessment on disk.
+- [ ] Caller: complete Groundwork validation and finalization.
+- [ ] CI / v3 PR: obtain fresh native Windows compile and IOCP runtime results.
+
+## Failure evidence and causal assessment
+
+The original native Windows package job `120361073253` on `808f7fa` failed at
+`src/detail/io_iocp_backend.cpp:260`: the temporary returned by `std::exchange`
+cannot bind to `close_socket(native_socket_t&)`. The full original log is
+retained at `.debug/FEATURE-ci-iocp-close/windows-job-120361073253.log` in the
+main repository; lines 751–763 contain the compiler diagnostic. A recorded
+`git diff 808f7fa b5cd6cf -- src/detail/io_iocp_backend.cpp` is empty, tying that
+source-bound RED to this task base. The accepted plan uses the real compile
+failure as RED for this compile-only repair.
+
+`close_socket` already copies the closing handle, sets the caller's reference
+to `k_invalid_socket`, then closes the copied handle. Passing `record->socket`
+directly honors that contract for both stream and datagram registrations. A
+retained completion packet's eventual registration destructor sees the invalid
+handle, so it cannot close a socket that reused the old value. The now redundant
+datagram branch is removed; the lifetime comment remains. Connection map erasure
+and `CancelIoEx` still precede the helper call, with the same mutex and packet
+ownership. No other source or public interface changed.
+
+## Local verification and limits
+
+From the isolated task worktree, with `EVIDENCE` denoting the absolute main
+repository directory `.debug/FEATURE-ci-iocp-close`:
+
+```sh
+g++ -std=c++20 -O0 -g -Wall -Wextra -pthread -DHTTPSERVER_COMPILATION \
+  -Isrc -Itest test/unit/io_poll_sys_listener_test.cpp \
+  src/detail/io_poll_sys.cpp src/net/address.cpp src/detail/net_address.cpp \
+  -o "$EVIDENCE/io_poll_sys_listener"
+timeout 30s "$EVIDENCE/io_poll_sys_listener"
+cpplint src/detail/io_iocp_backend.cpp
+git diff --check
+```
+
+All commands exited 0. The existing listener/helper suite executed 12 tests,
+45 successful checks, no failures or skips. It compiles the actual shared socket
+helper and uses real local sockets; it supplies local helper coverage, not
+Windows IOCP proof. cpplint reported no errors. Exact expanded commands, working
+directories, output and exit codes are retained in `build-listener.log`,
+`run-listener.log`, `cpplint.log` and `diff-check.log` alongside `journal.md`.
+
+The bounded local capability check found no Windows crosscompiler or SDK.
+Native Windows compilation and
+`udp_cancelled_packet_keeps_native_storage_and_reuse_generation` execution remain
+incomplete until CI runs them. No substitute native pass is claimed. No broad
+baseline or unrelated repairs were run; previous task evidence and the unrelated
+bauth worktree remain unchanged.
+
+## Implementation notes
+
+General setup uses `./bootstrap`, an out-of-tree configure/build, and
+`make check`; this task needed only the dependency-free focused compile above.
+Tests use `test/littletest.hpp`, `LT_BEGIN_AUTO_TEST` and `LT_CHECK` assertions.
+Private implementations live in `src/detail`, owning headers in
+`src/httpserver/detail`; the socket helper takes a mutable lvalue reference and
+invalidates before closing. Git metadata writes required sandbox escalation.
+Task-local setup and test memory is retained in the evidence directory.

src/detail/io_iocp_backend.cpp

@@ -254,13 +254,9 @@ void io_iocp_backend::retire_locked(std::uint64_t id, completions& done) {
         const auto record = found->second;
         connections_.erase(found);  // invalidate before socket reuse
         ::CancelIoEx(reinterpret_cast<HANDLE>(record->socket), nullptr);
-        if (record->datagram) {
-            // The completion lease survives closure; do not let its destructor
-            // close a descriptor reused by a newly adopted UDP socket.
-            pollsys::close_socket(std::exchange(record->socket, pollsys::k_invalid_socket));
-        } else {
-            pollsys::close_socket(record->socket);
-        }
+        // close_socket invalidates the handle before closing; a surviving
+        // completion lease must not close a descriptor reused by a new socket.
+        pollsys::close_socket(record->socket);
     }
     std::vector<std::shared_ptr<op_state>> swept;
     for (const auto& entry : pending_) {