winloop 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52ea4b37e9fbf3f00710317ae3ce66560b014a39103fcd731c825c77ec8367b5
-  data.tar.gz: c137e9507075259aaec8a604b5937bb305c8ed6134f33b54cecc8c19b756c21f
+  metadata.gz: 6920000bbfa8ee7b4ddb3a773e560ec9fd17ebf7912926fd47ea838b9ccf1ceb
+  data.tar.gz: 9c935d93743bf1858e5ab64326dbd3a2b32230a98672f4fbd76417095ceb2e1b
 SHA512:
-  metadata.gz: 5406ad357675a336f7fece41a9a4f986449a71d29324b40eb1b852851517d25310417c0e88026bd353de16dd9cf4c9bcc735c7c799a298da8e08937176ad86f2
-  data.tar.gz: fc833ec7d8d95317b010f9c25b5acae10db5366ce30ffb881c922ca05fb38fa480b928b14830758f1e4b4b02432b40d45dfb0cb7b06a31aa32db4693fcbd6059
+  metadata.gz: 3313cb9155d745caa65538b904b8615b6fd3f700c8d9d1d14028e0042fd3de2581acabfd126d783d22989c01d1cee28560f7231209ae6680f94561087e5e30dc
+  data.tar.gz: 6a7dda120d347e68e1dcd433eea90db639a7b9dcbfc15d47220b0503ee0ae8f29fc15b1e4a29cc3b8b79dda096e4ebc3607819e798b8339a9aefb15137f54ec3

data/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.2.0
+
+**Bring your own OVERLAPPED** — a generic OVERLAPPED/IOCP completion API, so any
+gem can associate a Windows handle with the loop's completion port, submit its
+own overlapped operation, and park the calling fiber until the completion packet
+arrives. Strictly additive: nothing in the 0.1 API changes signature or behavior,
+and all 34 pre-existing tests pass byte-unmodified.
+
+### Added
+
+* **`Winloop::Backend` op API** (the power layer; also works standalone, with no
+  scheduler): `#associate(handle)`, `#op_prepare(handle, tag:, capacity:)` →
+  `[op_id, ov_addr, buf_addr]` (backend-owned OVERLAPPED + 8-byte-aligned
+  embedded buffer), `#op_submitted`, `#op_abandon` (synchronous-failure path —
+  the only no-packet case), `#op_cancel` (`CancelIoEx`; **never frees** — the
+  cancelled op still posts a packet, which is reaped normally; CancelIoEx
+  failures warn and return `false`, never raise), `#op_result` →
+  `[bytes, error, data]`, `#op_free`, `#op_state`, and `#port_handle`
+  (tests/diagnostics only).
+* **`Winloop::Scheduler` op protocol** (the misuse-resistant cross-gem surface,
+  feature-gated by `Fiber.scheduler.respond_to?(:await_op)`): `op_associate`,
+  `op_prepare`, `op_submitted`, `op_abandon`, `op_cancel`, `op_state`, and
+  `await_op(op_id, timeout: nil)`, which parks the calling fiber until the
+  completion is reaped (returns the `[bytes, error, data]` triple, or `nil` on
+  timeout after auto-cancelling and orphaning the op). Loop-thread-only,
+  enforced.
+* Constants `Winloop::EXTERNAL_KEY` (the completion key carried by all generic
+  ops) and `Winloop::OP_CAPACITY_MAX` (16 MiB embedded-buffer ceiling).
+* **Completion errors are data, not exceptions**: the `error` element carries
+  the Win32 code mapped from the final NTSTATUS via `RtlNtStatusToDosError`
+  (`0` success, `995` cancelled, `1022` RDCW rescan, `38` EOF, …).
+* `op_prepare` rejects handles never passed to `#associate` — an op on a handle
+  that is not on the port never completes (a silent hang, not an error).
+* Defensive reap: unknown EXT packets and duplicate posts for already-completed
+  ops are skipped with a warning, never cast, never re-completed.
+* `ObjectSpace.memsize_of(backend)` now reports live op-buffer bytes.
+* Gemspec metadata tightened to suite grade: `bug_tracker_uri`,
+  `rubygems_mfa_required`.
+
+### Changed
+
+* `Backend#shutdown` (and the GC free hook) now also cancels every in-flight
+  generic op per op (`CancelIoEx(handle, ov)`), drains their packets — including
+  one bounded 100 ms wait taken **only** when generic ops are still in flight —
+  and frees retired records. Ops whose packet never surfaced inside the bounded
+  drain are deliberately leaked (the kernel may still write their
+  OVERLAPPED/IOSB; a use-after-free beats a bounded leak). Existing AFD-only
+  workloads see byte-identical shutdown.
+* `Backend#wait` may now return 4-element arrays `[op_id, bytes, error, tag]`
+  alongside the existing AFD 2-tuples — when, and only when, the new op API is
+  used in the process. Callers dispatch on tuple size; the AFD contract
+  (2-tuples, `[]` on timeout, wakeups skipped) is untouched.
+
 ## 0.1.0
 
 Initial release.

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Leiz
+Copyright (c) 2026 ned
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -86,6 +86,7 @@ Inside `Winloop.run { ... }` (and any `Fiber.schedule` started within it):
 | `Mutex`, `ConditionVariable`, `Queue`, `Thread#join` | `block`/`unblock` | waiter lists + `PostQueuedCompletionStatus` |
 | `Addrinfo.getaddrinfo`, DNS in `TCPSocket.new` | `address_resolve` | resolved on a worker thread        |
 | `Process.wait`                              | `process_wait`  | reaped on a worker thread              |
+| your own OVERLAPPED ops (any gem)           | `await_op`      | generic completion packets on the same IOCP |
 
 ## API
 
@@ -107,7 +108,144 @@ Fiber.schedule { ... }
 scheduler.close       # runs the event loop to completion
 ```
 
-## Scope and limitations (v0.1)
+The generic-op surface (winloop 0.2 — see the next section):
+
+```ruby
+# Scheduler (the cross-gem protocol; loop-thread-only):
+sched.op_associate(handle)                        # => true   (permanent; handle stays yours)
+sched.op_prepare(handle, tag: 0, capacity: 0)     # => [op_id, ov_addr, buf_addr]
+sched.op_submitted(op_id)                         # => true   (native call returned TRUE or ERROR_IO_PENDING)
+sched.op_abandon(op_id)                           # => true   (native call failed synchronously)
+sched.op_cancel(op_id)                            # => true | false (false: already completed, or CancelIoEx failed — warned, never raised)
+sched.op_state(op_id)                             # => :prepared | :submitted | :completed
+sched.await_op(op_id, timeout: nil)               # => [bytes, error, data] | nil (timeout; op auto-cancelled)
+
+# Backend (the power layer; also the standalone-embedding layer):
+backend.associate(handle)                         # => true
+backend.op_prepare(handle, tag: 0, capacity: 0)   # => [op_id, ov_addr, buf_addr]
+backend.op_submitted(op_id)                       # => true
+backend.op_abandon(op_id)                         # => true
+backend.op_cancel(op_id)                          # => true | false
+backend.op_result(op_id)                          # => [bytes, error, data] (frees the record)
+backend.op_free(op_id)                            # => true (retire a completion nobody wants)
+backend.op_state(op_id)                           # => :prepared | :submitted | :completed
+backend.port_handle                               # => Integer (read-only; tests/diagnostics)
+backend.wait(timeout_ms)                          # => [[id, events], ..., [op_id, bytes, error, tag], ...]
+Winloop::EXTERNAL_KEY                             # => 0x45585431 — completion key of all generic ops
+Winloop::OP_CAPACITY_MAX                          # => 16 MiB — op_prepare capacity ceiling
+```
+
+## Bring your own OVERLAPPED (generic completions)
+
+**winloop 0.2 lets any gem associate a Windows handle with the loop's completion
+port, submit its own overlapped operation, and park the calling fiber until the
+completion packet arrives — cancel and synchronous-completion semantics done
+right, with zero change to everything winloop already does.** This is a seam for
+**gem authors** (file watchers, named pipes, mailslots…), not app code.
+
+The contract loop: `op_associate` → `op_prepare` → your native submit →
+`op_submitted` (success **or** `ERROR_IO_PENDING` — both queue a packet) /
+`op_abandon` (synchronous failure — the only no-packet case) → `await_op` →
+`[bytes, error, data]`.
+
+A real overlapped file read driven from plain Ruby via Fiddle (stdlib):
+
+```ruby
+require "winloop"
+require "fiddle/import"
+
+module K32
+  extend Fiddle::Importer
+  dlload "kernel32.dll"
+  extern "void* CreateFileW(void*, unsigned long, unsigned long, void*, unsigned long, unsigned long, void*)"
+  extern "int ReadFile(void*, void*, unsigned long, void*, void*)"
+  extern "int CloseHandle(void*)"
+end
+
+GENERIC_READ         = 0x8000_0000
+FILE_SHARE_READ      = 0x1
+OPEN_EXISTING        = 3
+FILE_FLAG_OVERLAPPED = 0x4000_0000
+ERROR_IO_PENDING     = 997
+
+Winloop.run do
+  sched = Fiber.scheduler                 # a Winloop::Scheduler
+  wpath = (File.expand_path(__FILE__) + "\0").encode("UTF-16LE")
+  h = K32.CreateFileW(wpath, GENERIC_READ, FILE_SHARE_READ, nil,
+                      OPEN_EXISTING, FILE_FLAG_OVERLAPPED, nil).to_i
+  sched.op_associate(h)
+  op_id, ov, buf = sched.op_prepare(h, capacity: 4096)
+  ok = K32.ReadFile(h, buf, 4096, nil, ov)
+  if ok != 0 || Fiddle.win32_last_error == ERROR_IO_PENDING
+    sched.op_submitted(op_id)             # success AND pending both queue a packet
+    bytes, error, data = sched.await_op(op_id, timeout: 5)   # fiber parks HERE
+    raise Winloop::Error, "read failed (#{error})" unless error.zero?
+    puts "read #{bytes} bytes: #{data[0, 40].inspect}"
+  else
+    sched.op_abandon(op_id)               # synchronous failure: no packet will come
+    raise Winloop::Error, "ReadFile failed (#{Fiddle.win32_last_error})"
+  end
+  K32.CloseHandle(h)
+end
+```
+
+### Rules (read this twice)
+
+* **Handles stay yours.** winloop owns the op memory (OVERLAPPED + buffer, one
+  backend-owned heap allocation); you open and close your handles — winloop
+  never calls `CloseHandle` on them.
+* **Association is permanent** — one port per handle, no disassociation (Win32
+  rule). After the loop shuts down an associated handle can never join another
+  winloop loop; re-open per `Winloop.run` session.
+* **Associate before prepare.** `op_prepare` rejects handles it has never seen,
+  because an op on a handle that is not on the port never completes: not an
+  error, a **silent hang**. The one case the check cannot catch — closing a
+  handle mid-flight so the OS recycles its value — is on you: cancel → await →
+  only then `CloseHandle`.
+* **Use `await_op` timeouts while first integrating a new native API**; switch
+  to `nil` once the submit path is proven.
+* Never set `FILE_SKIP_COMPLETION_PORT_ON_SUCCESS` on an associated handle (it
+  is irreversible and per-handle): winloop's invariant is exactly one packet per
+  submitted op, always. Don't use `ReadFileEx`/`WriteFileEx` (APC I/O) on
+  associated handles, and don't duplicate/inherit them.
+* **Cancel never frees** — the cancelled op still posts a packet (usually error
+  995), which is reaped normally.
+* **After `await_op` returns — value or `nil` — the op id is dead.** Don't use
+  it again.
+* Loop thread only: ops are submitted on the loop thread (fibers run there
+  anyway); the scheduler wrappers enforce it.
+* **Completion errors are values, not exceptions**: `995` cancelled, `1022`
+  RDCW rescan, `38` EOF, … A zero-byte successful completion is a real signal
+  (RDCW overflow ⇒ rescan), delivered verbatim.
+* No PQCS injection — out of scope in v1. `Backend#port_handle` exists for
+  tests and diagnostics only.
+
+### Standalone (no scheduler)
+
+Client gems never hard-depend on winloop. The protocol is duck-typed on the
+scheduler:
+
+```ruby
+sched = Fiber.scheduler
+if sched&.respond_to?(:await_op)
+  # winloop (or compatible) IOCP path: op_associate / op_prepare / native
+  # submit / op_submitted / await_op — as above.
+else
+  # the client gem's own standalone mechanism, e.g. the winipc pattern:
+  # stack OVERLAPPED + manual-reset hEvent, WaitForSingleObject without the
+  # GVL with ubf = CancelIoEx, GetOverlappedResult; or a gem-owned wait thread
+  # for continuous streams.
+end
+```
+
+winloop ships **no** shared standalone wait thread or service (dependency
+direction, irreversible association, ownership — clients own their threads).
+`Winloop::Backend` itself does work standalone — create, `associate`,
+prepare/submit, `wait`-poll (dispatch on tuple size: AFD 2-tuples vs op
+4-tuples in the same array), `op_result`, `shutdown` — which is how an embedder
+or a test drives it deterministically.
+
+## Scope and limitations (v0.2)
 
 * **Sockets are the focus.** TCP/UDP sockets get the full IOCP/AFD path. Pipes and
   regular files fall back to a blocking read inside `io_read` (async file I/O on
@@ -117,6 +255,15 @@ scheduler.close       # runs the event loop to completion
   itself is not a multi-threaded worker pool.
 * `IOCTL_AFD_POLL` is undocumented; winloop resolves its `ntdll` entry points at
   runtime and degrades by raising a clear error if `\Device\Afd` is unavailable.
+* **The ops API is for gem authors.** Buffers are backend-owned only (no
+  IO::Buffer/String pinning — copy-out removes the whole lifetime/compaction bug
+  class). Ops still in flight at shutdown are cancelled and drained for a
+  bounded interval; stragglers may be deliberately leaked rather than freed
+  under possible kernel ownership.
+* **x64 only.** arm64-mswin is expected to work (all code is `_WIN64`/
+  `uintptr_t`-clean, no arch-specific anything — AFD + IOCP are
+  production-proven on arm64 via libuv/Node and mio/Rust) but is untested and
+  unsupported until an arm64-mswin Ruby distribution exists.
 
 ## How it compares
 

data/ext/winloop/winloop.c

@@ -58,8 +58,14 @@
 
 #define WAKE_KEY ((ULONG_PTR)0x57414B45ull) /* "WAKE" — PostQueuedCompletionStatus marker */
 #define AFD_KEY  ((ULONG_PTR)0x41464430ull) /* "AFD0" — the AFD handle's completion key */
+#define EXT_KEY  ((ULONG_PTR)0x45585431ull) /* "EXT1" — ALL generic client ops (winloop 0.2) */
 #define REAP_CAP 64
 
+/* Generic op state machine: prepare -> submit -> complete (reaped) -> retire (freed).
+ * Only a reaped completion ends kernel ownership of the OVERLAPPED + buffer; the
+ * sole exception is op_abandon on a PREPARED op the kernel never saw. */
+enum { OP_PREPARED = 0, OP_SUBMITTED = 1, OP_COMPLETED = 2 };
+
 typedef struct _AFD_POLL_HANDLE_INFO {
     HANDLE   Handle;
     ULONG    Events;
@@ -77,10 +83,12 @@ typedef NTSTATUS (NTAPI *PFN_NtCreateFile)(PHANDLE, ACCESS_MASK, POBJECT_ATTRIBU
 typedef NTSTATUS (NTAPI *PFN_NtDeviceIoControlFile)(HANDLE, HANDLE, PIO_APC_ROUTINE,
     PVOID, PIO_STATUS_BLOCK, ULONG, PVOID, ULONG, PVOID, ULONG);
 typedef VOID (NTAPI *PFN_RtlInitUnicodeString)(PUNICODE_STRING, PCWSTR);
+typedef ULONG (NTAPI *PFN_RtlNtStatusToDosError)(NTSTATUS);
 
-static PFN_NtCreateFile          pNtCreateFile;
-static PFN_NtDeviceIoControlFile pNtDeviceIoControlFile;
-static PFN_RtlInitUnicodeString  pRtlInitUnicodeString;
+static PFN_NtCreateFile           pNtCreateFile;
+static PFN_NtDeviceIoControlFile  pNtDeviceIoControlFile;
+static PFN_RtlInitUnicodeString   pRtlInitUnicodeString;
+static PFN_RtlNtStatusToDosError  pRtlNtStatusToDosError;
 
 #ifndef InitializeObjectAttributes
 #define InitializeObjectAttributes(p, n, a, r, s) do { \
@@ -97,11 +105,33 @@ typedef struct {
     AFD_POLL_INFO out;
 } winloop_req;
 
+/* One generic op (winloop 0.2). OVERLAPPED MUST be first: a completion's
+ * lpOverlapped casts back to the record — the same proven pattern as winloop_req. */
+typedef struct {
+    OVERLAPPED ov;        /* zeroed at prepare; kernel writes Internal/InternalHigh   */
+    uint64_t   id;        /* Ruby-visible op id (shares next_id with AFD reqs)        */
+    uint64_t   tag;       /* user value, echoed in the completion tuple               */
+    HANDLE     handle;    /* associated client handle for CancelIoEx; never NULL      */
+    int        state;     /* OP_PREPARED -> OP_SUBMITTED -> OP_COMPLETED              */
+    DWORD      bytes;     /* filled at reap                                           */
+    DWORD      error;     /* Win32 code at reap (RtlNtStatusToDosError(ov.Internal))  */
+    size_t     cap;       /* embedded buffer capacity (0 = none)                      */
+    /* unsigned char buf[cap] co-allocated at OP_BUF_OFFSET (8-byte aligned)          */
+} winloop_op;
+
+#define OP_BUF_OFFSET ((sizeof(winloop_op) + 7) & ~(size_t)7)
+
 typedef struct {
     HANDLE     iocp;
     HANDLE     afd;
     uint64_t   next_id;
-    st_table  *reqs;   /* id -> winloop_req* */
+    st_table  *reqs;          /* id -> winloop_req* */
+    st_table  *ops_by_id;     /* id -> winloop_op*  (Ruby-facing op methods)          */
+    st_table  *ops_by_addr;   /* OVERLAPPED addr -> winloop_op* (defensive reap)      */
+    st_table  *assoc_handles; /* set of HANDLE values passed to #associate (op_prepare
+                                 validation ONLY — never used for blanket cancels, so
+                                 a recycled handle value can't trigger a wrong cancel) */
+    size_t     op_bytes;      /* live op allocations, reported by backend_memsize     */
     int        closed;
 } winloop_backend;
 
@@ -114,7 +144,9 @@ static int resolve_ntdll(void) {
     pNtCreateFile          = (PFN_NtCreateFile)          GetProcAddress(nt, "NtCreateFile");
     pNtDeviceIoControlFile = (PFN_NtDeviceIoControlFile) GetProcAddress(nt, "NtDeviceIoControlFile");
     pRtlInitUnicodeString  = (PFN_RtlInitUnicodeString)  GetProcAddress(nt, "RtlInitUnicodeString");
-    return pNtCreateFile && pNtDeviceIoControlFile && pRtlInitUnicodeString;
+    pRtlNtStatusToDosError = (PFN_RtlNtStatusToDosError) GetProcAddress(nt, "RtlNtStatusToDosError");
+    return pNtCreateFile && pNtDeviceIoControlFile && pRtlInitUnicodeString &&
+           pRtlNtStatusToDosError;
 }
 
 static HANDLE afd_open(void) {
@@ -159,6 +191,45 @@ static int free_req_i(st_data_t key, st_data_t val, st_data_t arg) {
     xfree((void *)val);
     return ST_CONTINUE;
 }
+/* Shutdown sweep step 1: cancel every still-SUBMITTED generic op, per op
+ * (CancelIoEx(handle, ov) — precise; a blanket per-handle cancel would be exposed
+ * to the recycled-handle-value hazard if a client closed a handle early). */
+static int cancel_submitted_op_i(st_data_t key, st_data_t val, st_data_t arg) {
+    winloop_op *op = (winloop_op *)val;
+    (void)key; (void)arg;
+    if (op->state == OP_SUBMITTED) CancelIoEx(op->handle, &op->ov);
+    /* failures ignored: ERROR_NOT_FOUND = already completed; a (contract-
+     * violating) closed handle simply fails the lookup */
+    return ST_CONTINUE;
+}
+static int count_submitted_op_i(st_data_t key, st_data_t val, st_data_t arg) {
+    winloop_op *op = (winloop_op *)val;
+    (void)key;
+    if (op->state == OP_SUBMITTED) (*(size_t *)arg)++;
+    return ST_CONTINUE;
+}
+/* Shutdown sweep step 4: free every op the kernel can no longer touch. Ops still
+ * OP_SUBMITTED (their packet never surfaced inside the bounded drain) are
+ * DELIBERATELY LEAKED — the kernel may still write their OVERLAPPED/IOSB, and a
+ * use-after-free beats a bounded leak (the libuv tradeoff). In practice the
+ * per-op CancelIoEx + the 100 ms drain retires them. */
+static int free_op_unless_submitted_i(st_data_t key, st_data_t val, st_data_t arg) {
+    winloop_op *op = (winloop_op *)val;
+    (void)key; (void)arg;
+    if (op->state != OP_SUBMITTED) xfree(op);
+    return ST_CONTINUE;
+}
+/* During the shutdown drain, mark reaped EXT packets' ops OP_COMPLETED so the
+ * sweep may free them. Pure C — also runs from the GC free hook (no Ruby calls). */
+static void drain_mark_ext(winloop_backend *b, OVERLAPPED_ENTRY *ents, ULONG n) {
+    ULONG i;
+    for (i = 0; i < n; i++) {
+        st_data_t val;
+        if (ents[i].lpCompletionKey != EXT_KEY || ents[i].lpOverlapped == NULL) continue;
+        if (!st_lookup(b->ops_by_addr, (st_data_t)(uintptr_t)ents[i].lpOverlapped, &val)) continue;
+        ((winloop_op *)val)->state = OP_COMPLETED;
+    }
+}
 static void backend_drain_and_close(winloop_backend *b) {
     if (b->closed) return;
     b->closed = 1;
@@ -166,16 +237,36 @@ static void backend_drain_and_close(winloop_backend *b) {
         /* Cancel everything still pending so the kernel stops owning our OVERLAPPEDs. */
         if (b->afd != INVALID_HANDLE_VALUE) CancelIoEx(b->afd, NULL);
     }
+    if (b->ops_by_id) st_foreach(b->ops_by_id, cancel_submitted_op_i, 0);
     /* Drain queued completions (best-effort) so no packet references freed memory. */
     if (b->iocp) {
         OVERLAPPED_ENTRY ents[REAP_CAP]; ULONG n = 0; int spins = 0;
         while (GetQueuedCompletionStatusEx(b->iocp, ents, REAP_CAP, &n, 0, FALSE) && n && spins++ < 4096) {
-            /* drop them; the requests are freed below from the table */
+            if (b->ops_by_addr) drain_mark_ext(b, ents, n);
+        }
+        /* One bounded 100 ms drain — ONLY when generic ops are still in flight
+         * (their cancel completions are usually instants away). Existing AFD-only
+         * workloads never take this branch; the GVL stays held (this also runs
+         * from the GC free hook, where releasing the GVL is not an option). */
+        if (b->ops_by_id) {
+            size_t still = 0;
+            st_foreach(b->ops_by_id, count_submitted_op_i, (st_data_t)&still);
+            if (still &&
+                GetQueuedCompletionStatusEx(b->iocp, ents, REAP_CAP, &n, 100, FALSE) && n) {
+                drain_mark_ext(b, ents, n);
+                spins = 0;
+                while (GetQueuedCompletionStatusEx(b->iocp, ents, REAP_CAP, &n, 0, FALSE) && n && spins++ < 4096)
+                    drain_mark_ext(b, ents, n);
+            }
         }
     }
     if (b->afd != INVALID_HANDLE_VALUE) { CloseHandle(b->afd); b->afd = INVALID_HANDLE_VALUE; }
     if (b->iocp) { CloseHandle(b->iocp); b->iocp = NULL; }
     if (b->reqs) { st_foreach(b->reqs, free_req_i, 0); st_free_table(b->reqs); b->reqs = NULL; }
+    if (b->ops_by_id) { st_foreach(b->ops_by_id, free_op_unless_submitted_i, 0); st_free_table(b->ops_by_id); b->ops_by_id = NULL; }
+    if (b->ops_by_addr) { st_free_table(b->ops_by_addr); b->ops_by_addr = NULL; }
+    if (b->assoc_handles) { st_free_table(b->assoc_handles); b->assoc_handles = NULL; }
+    b->op_bytes = 0;
 }
 static void backend_free(void *p) {
     winloop_backend *b = (winloop_backend *)p;
@@ -183,7 +274,10 @@ static void backend_free(void *p) {
     backend_drain_and_close(b);
     xfree(b);
 }
-static size_t backend_memsize(const void *p) { (void)p; return sizeof(winloop_backend); }
+static size_t backend_memsize(const void *p) {
+    const winloop_backend *b = (const winloop_backend *)p;
+    return sizeof(winloop_backend) + (b ? b->op_bytes : 0);
+}
 static const rb_data_type_t backend_type = {
     "Winloop::Backend", { 0, backend_free, backend_memsize }, 0, 0, RUBY_TYPED_FREE_IMMEDIATELY
 };
@@ -195,6 +289,14 @@ static winloop_backend *get_backend(VALUE self) {
     return b;
 }
 
+/* The op methods additionally need the op tables, which only #initialize creates
+ * (a Backend.allocate'd-but-never-initialized object must raise, not crash). */
+static winloop_backend *get_backend_ops(VALUE self) {
+    winloop_backend *b = get_backend(self);
+    if (!b->ops_by_id) rb_raise(eError, "winloop: backend is closed");
+    return b;
+}
+
 static VALUE backend_alloc(VALUE klass) {
     winloop_backend *b;
     VALUE obj = TypedData_Make_Struct(klass, winloop_backend, &backend_type, b);
@@ -219,6 +321,11 @@ static VALUE backend_initialize(VALUE self) {
     }
     b->next_id = 0;
     b->reqs = st_init_numtable();
+    /* st_data_t is pointer-sized; numtables hold ids/addresses/handles arm64-clean. */
+    b->ops_by_id     = st_init_numtable();
+    b->ops_by_addr   = st_init_numtable();
+    b->assoc_handles = st_init_numtable();
+    b->op_bytes = 0;
     b->closed = 0;
     return self;
 }
@@ -268,6 +375,197 @@ static VALUE backend_cancel(VALUE self, VALUE vid) {
     return Qnil;
 }
 
+/* ===== Generic OVERLAPPED ops — "bring your own OVERLAPPED" (winloop 0.2) =====
+ *
+ * The whole feature is Integer-in/Integer-out: handles, addresses and ids cross
+ * the API as Ruby Integers (the cross-gem ABI — other gems never link winloop).
+ * winloop owns op memory (OVERLAPPED + embedded buffer, one heap allocation);
+ * clients own their handles — winloop NEVER calls CloseHandle on them. */
+
+static const char *op_state_name(int state) {
+    switch (state) {
+      case OP_PREPARED:  return "prepared";
+      case OP_SUBMITTED: return "submitted";
+      default:           return "completed";
+    }
+}
+
+static winloop_op *op_lookup(winloop_backend *b, uint64_t id) {
+    st_data_t val;
+    if (!st_lookup(b->ops_by_id, (st_data_t)id, &val))
+        rb_raise(eError, "winloop: unknown op id %llu", (unsigned long long)id);
+    return (winloop_op *)val;
+}
+
+/* Remove an op from both tables and free it (the ONLY free path besides the
+ * shutdown sweep). Callers must have established the kernel no longer owns it. */
+static void op_retire(winloop_backend *b, winloop_op *op) {
+    st_data_t key = (st_data_t)op->id;
+    st_delete(b->ops_by_id, &key, NULL);
+    key = (st_data_t)(uintptr_t)&op->ov;
+    st_delete(b->ops_by_addr, &key, NULL);
+    b->op_bytes -= OP_BUF_OFFSET + op->cap;
+    xfree(op);
+}
+
+/* Associate `handle` (opened FILE_FLAG_OVERLAPPED) with the backend's IOCP under
+ * EXT_KEY. Permanent for the handle's lifetime (Win32: one port per handle, no
+ * disassociation); the caller keeps ownership. */
+static VALUE backend_associate(VALUE self, VALUE vhandle) {
+    winloop_backend *b = get_backend_ops(self);
+    uint64_t hv = NUM2ULL(vhandle); /* coercion first: a raise here owns nothing */
+    DWORD gle;
+    if (hv == 0 || hv == UINT64_MAX)
+        rb_raise(rb_eArgError, "winloop: %llu is not a usable HANDLE value",
+                 (unsigned long long)hv);
+    if (!CreateIoCompletionPort((HANDLE)(uintptr_t)hv, b->iocp, EXT_KEY, 0)) {
+        gle = GetLastError(); /* captured before any Ruby allocation */
+        rb_raise(eError, "winloop: could not associate handle %llu with the completion "
+                 "port (error %lu: already associated with a completion port, or not "
+                 "opened with FILE_FLAG_OVERLAPPED)", (unsigned long long)hv, gle);
+    }
+    st_insert(b->assoc_handles, (st_data_t)hv, (st_data_t)1);
+    return Qtrue;
+}
+
+/* Private primitive behind Winloop::Backend#op_prepare (lib/winloop/ops.rb owns
+ * the kwargs + range validation). Allocates one op record: zeroed OVERLAPPED +
+ * tag + optional embedded buffer; returns [op_id, ov_addr, buf_addr]. */
+static VALUE backend__op_prepare(VALUE self, VALUE vhandle, VALUE vtag, VALUE vcap) {
+    winloop_backend *b = get_backend_ops(self);
+    /* All coercion before any allocation (raise hygiene). */
+    uint64_t hv  = NUM2ULL(vhandle);
+    uint64_t tag = NUM2ULL(vtag);
+    uint64_t cap = NUM2ULL(vcap);
+    size_t total;
+    winloop_op *op;
+    if (cap > 16ull * 1024 * 1024) /* defensive twin of OP_CAPACITY_MAX (send bypass) */
+        rb_raise(rb_eArgError, "winloop: capacity %llu exceeds OP_CAPACITY_MAX",
+                 (unsigned long long)cap);
+    /* The anti-hang check (§3.4 rule 8): an op on a handle that is not on the
+     * port never completes — not an error, a silent loop freeze. Honestly: a
+     * handle that was associated, closed and recycled to the same value passes. */
+    if (!st_lookup(b->assoc_handles, (st_data_t)hv, NULL))
+        rb_raise(eError, "winloop: handle %llu was never associated with this backend "
+                 "— call #associate first", (unsigned long long)hv);
+
+    total = OP_BUF_OFFSET + (size_t)cap;
+    op = (winloop_op *)xmalloc(total); /* a raise above this line leaks nothing */
+    memset(op, 0, total); /* zeroed OVERLAPPED (offset 0 reads); buffer never leaks heap */
+    op->id     = ++b->next_id;
+    op->tag    = tag;
+    op->handle = (HANDLE)(uintptr_t)hv;
+    op->state  = OP_PREPARED;
+    op->cap    = (size_t)cap;
+    st_insert(b->ops_by_id, (st_data_t)op->id, (st_data_t)op);
+    /* An OOM longjmp from this second insert leaks one record until the shutdown
+     * sweep — the identical, accepted exposure as backend_poll's st_insert. */
+    st_insert(b->ops_by_addr, (st_data_t)(uintptr_t)&op->ov, (st_data_t)op);
+    b->op_bytes += total;
+    return rb_ary_new_from_args(3, ULL2NUM(op->id), ULL2NUM((uintptr_t)&op->ov),
+                                cap ? ULL2NUM((uintptr_t)((char *)op + OP_BUF_OFFSET))
+                                    : ULL2NUM(0));
+}
+
+/* Call after the client's native call returned success OR ERROR_IO_PENDING —
+ * both queue exactly one completion packet (no skip-on-success, ever). */
+static VALUE backend_op_submitted(VALUE self, VALUE vid) {
+    winloop_backend *b = get_backend_ops(self);
+    winloop_op *op = op_lookup(b, NUM2ULL(vid));
+    if (op->state != OP_PREPARED)
+        rb_raise(eError, "winloop: op %llu is %s; op_submitted is only legal on a "
+                 "prepared op", (unsigned long long)op->id, op_state_name(op->state));
+    op->state = OP_SUBMITTED;
+    return Qtrue;
+}
+
+/* For a native call that failed SYNCHRONOUSLY (GetLastError != ERROR_IO_PENDING):
+ * the kernel never saw the op, no packet will ever arrive — free immediately. */
+static VALUE backend_op_abandon(VALUE self, VALUE vid) {
+    winloop_backend *b = get_backend_ops(self);
+    winloop_op *op = op_lookup(b, NUM2ULL(vid));
+    if (op->state == OP_SUBMITTED)
+        rb_raise(eError, "winloop: op %llu is submitted; a submitted op is retired by "
+                 "its completion, not op_abandon", (unsigned long long)op->id);
+    if (op->state == OP_COMPLETED)
+        rb_raise(eError, "winloop: op %llu is completed; retire it with op_result or "
+                 "op_free, not op_abandon", (unsigned long long)op->id);
+    op_retire(b, op);
+    return Qtrue;
+}
+
+/* CancelIoEx(handle, ov) — targeted, cross-thread-safe. NEVER frees: a cancelled
+ * op still posts a packet (usually error 995) which #wait reaps. Returns true if
+ * a cancel was issued; false on ERROR_NOT_FOUND (already completed — benign) or
+ * ANY other CancelIoEx failure (rb_warn'ed, never raised: await_op's ensure path
+ * must never mask an in-flight Timeout/Fiber#raise unwind with a Winloop::Error). */
+static VALUE backend_op_cancel(VALUE self, VALUE vid) {
+    winloop_backend *b = get_backend_ops(self);
+    winloop_op *op = op_lookup(b, NUM2ULL(vid));
+    DWORD gle;
+    if (op->state == OP_PREPARED)
+        rb_raise(eError, "winloop: op %llu is prepared; only a submitted op can be "
+                 "cancelled (a prepared op is retired with op_abandon)",
+                 (unsigned long long)op->id);
+    if (CancelIoEx(op->handle, &op->ov)) return Qtrue;
+    gle = GetLastError(); /* captured immediately, before any Ruby call */
+    if (gle != ERROR_NOT_FOUND)
+        rb_warn("winloop: CancelIoEx for op %llu failed (error %lu) — treated as "
+                "no-cancel, never an exception", (unsigned long long)op->id, gle);
+    return Qfalse;
+}
+
+/* [bytes, error, data] for a COMPLETED op; frees the record. The String is built
+ * BEFORE the free so an OOM raise leaves the op intact and retryable. `data` is
+ * clamped to min(bytes, capacity): a stray packet's bogus byte count cannot make
+ * winloop read past its own buffer. */
+static VALUE backend_op_result(VALUE self, VALUE vid) {
+    winloop_backend *b = get_backend_ops(self);
+    winloop_op *op = op_lookup(b, NUM2ULL(vid));
+    VALUE data = Qnil, result;
+    if (op->state != OP_COMPLETED)
+        rb_raise(eError, "winloop: op %llu is %s; op_result is only legal once its "
+                 "completion has been reaped by #wait",
+                 (unsigned long long)op->id, op_state_name(op->state));
+    if (op->cap) {
+        size_t n = (size_t)op->bytes < op->cap ? (size_t)op->bytes : op->cap;
+        data = rb_str_new((const char *)op + OP_BUF_OFFSET, (long)n); /* ASCII-8BIT */
+    }
+    result = rb_ary_new_from_args(3, ULONG2NUM(op->bytes), ULONG2NUM(op->error), data);
+    op_retire(b, op);
+    return result;
+}
+
+/* Retire a COMPLETED op without materializing its data (orphaned completions). */
+static VALUE backend_op_free(VALUE self, VALUE vid) {
+    winloop_backend *b = get_backend_ops(self);
+    winloop_op *op = op_lookup(b, NUM2ULL(vid));
+    if (op->state != OP_COMPLETED)
+        rb_raise(eError, "winloop: op %llu is %s; op_free is only legal once its "
+                 "completion has been reaped by #wait",
+                 (unsigned long long)op->id, op_state_name(op->state));
+    op_retire(b, op);
+    return Qtrue;
+}
+
+static VALUE backend_op_state(VALUE self, VALUE vid) {
+    winloop_backend *b = get_backend_ops(self);
+    winloop_op *op = op_lookup(b, NUM2ULL(vid));
+    switch (op->state) {
+      case OP_PREPARED:  return ID2SYM(rb_intern("prepared"));
+      case OP_SUBMITTED: return ID2SYM(rb_intern("submitted"));
+      default:           return ID2SYM(rb_intern("completed"));
+    }
+}
+
+/* The raw IOCP HANDLE value — read-only, for tests and diagnostics. Hard rules:
+ * never wait on it, never close it, never associate handles behind winloop's
+ * back, never post after shutdown, at most ONE post per op. */
+static VALUE backend_port_handle(VALUE self) {
+    winloop_backend *b = get_backend_ops(self);
+    return ULL2NUM((uintptr_t)b->iocp);
+}
+
 /* Reap completions in one GetQueuedCompletionStatusEx. Returns an Array of
    [id, ready_events]; wakeup packets are skipped. Empty array on timeout. */
 /* The blocking GQCSEx call, run WITHOUT the GVL so other threads (and the very
@@ -311,6 +609,45 @@ static VALUE backend_wait(VALUE self, VALUE vtimeout_ms) {
     }
     for (ULONG i = 0; i < n; i++) {
         if (ents[i].lpCompletionKey == WAKE_KEY || ents[i].lpOverlapped == NULL) continue;
+        if (ents[i].lpCompletionKey == EXT_KEY) {
+            /* Generic-op path (winloop 0.2). Defensive dispatch: verify membership
+             * in ops_by_addr AND op state before acting — an unknown lpOverlapped
+             * is never cast, an already-COMPLETED op (double post) is never
+             * re-completed and never yields a second tuple. The only accepted
+             * anomaly is a packet for a still-PREPARED op (a standalone embedder
+             * called #wait between the native submit and op_submitted): the packet
+             * is real and the memory is ours, so accept it with a warning. */
+            st_data_t val;
+            winloop_op *op;
+            if (!st_lookup(b->ops_by_addr, (st_data_t)(uintptr_t)ents[i].lpOverlapped, &val)) {
+                rb_warn("winloop: dropped a completion packet for an unknown OVERLAPPED "
+                        "0x%llx (stray or duplicate post)",
+                        (unsigned long long)(uintptr_t)ents[i].lpOverlapped);
+                continue;
+            }
+            op = (winloop_op *)val;
+            if (op->state == OP_COMPLETED) {
+                rb_warn("winloop: dropped a duplicate completion packet for op %llu "
+                        "(already completed; bytes/error preserved)",
+                        (unsigned long long)op->id);
+                continue;
+            }
+            if (op->state == OP_PREPARED)
+                rb_warn("winloop: completion packet reaped for op %llu before "
+                        "op_submitted (protocol violation; accepting the packet)",
+                        (unsigned long long)op->id);
+            op->state = OP_COMPLETED;
+            op->bytes = ents[i].dwNumberOfBytesTransferred;
+            /* Status lives in the OVERLAPPED's Internal (an NTSTATUS), readable
+             * only after the packet left the port; map it to a familiar Win32
+             * code (0 ok, 995 cancelled, 1022 rescan, 38 EOF, ...). */
+            op->error = pRtlNtStatusToDosError((NTSTATUS)op->ov.Internal);
+            rb_ary_push(result, rb_ary_new_from_args(4, ULL2NUM(op->id),
+                        ULONG2NUM(op->bytes), ULONG2NUM(op->error), ULL2NUM(op->tag)));
+            continue;
+        }
+        /* AFD path — byte-for-byte the pre-0.2 code (only the AFD handle carries
+         * AFD_KEY on this port). */
         winloop_req *req = (winloop_req *)ents[i].lpOverlapped;
         st_data_t key = (st_data_t)req->id;
         st_delete(b->reqs, &key, NULL);
@@ -348,6 +685,11 @@ void Init_winloop(void) {
     rb_define_const(mWinloop, "WRITABLE", INT2NUM(RB_WRITABLE));
     rb_define_const(mWinloop, "PRIORITY", INT2NUM(RB_PRIORITY));
 
+    /* The completion key winloop assigns to ALL generic ops on the port
+     * (internal dispatch; exposed for tests and a possible future injection
+     * protocol — PQCS injection is NOT a v1 protocol). */
+    rb_define_const(mWinloop, "EXTERNAL_KEY", ULL2NUM(0x45585431ull));
+
     rb_define_alloc_func(cBackend, backend_alloc);
     rb_define_method(cBackend, "initialize", RUBY_METHOD_FUNC(backend_initialize), 0);
     rb_define_method(cBackend, "poll",       RUBY_METHOD_FUNC(backend_poll), 2);
@@ -355,4 +697,16 @@ void Init_winloop(void) {
     rb_define_method(cBackend, "wait",       RUBY_METHOD_FUNC(backend_wait), 1);
     rb_define_method(cBackend, "wakeup",     RUBY_METHOD_FUNC(backend_wakeup), 0);
     rb_define_method(cBackend, "shutdown",   RUBY_METHOD_FUNC(backend_shutdown), 0);
+
+    /* Generic OVERLAPPED ops (winloop 0.2). `_op_prepare` is the private bridge
+     * behind the validated Winloop::Backend#op_prepare in lib/winloop/ops.rb. */
+    rb_define_method(cBackend, "associate",    RUBY_METHOD_FUNC(backend_associate), 1);
+    rb_define_method(cBackend, "_op_prepare",  RUBY_METHOD_FUNC(backend__op_prepare), 3);
+    rb_define_method(cBackend, "op_submitted", RUBY_METHOD_FUNC(backend_op_submitted), 1);
+    rb_define_method(cBackend, "op_abandon",   RUBY_METHOD_FUNC(backend_op_abandon), 1);
+    rb_define_method(cBackend, "op_cancel",    RUBY_METHOD_FUNC(backend_op_cancel), 1);
+    rb_define_method(cBackend, "op_result",    RUBY_METHOD_FUNC(backend_op_result), 1);
+    rb_define_method(cBackend, "op_free",      RUBY_METHOD_FUNC(backend_op_free), 1);
+    rb_define_method(cBackend, "op_state",     RUBY_METHOD_FUNC(backend_op_state), 1);
+    rb_define_method(cBackend, "port_handle",  RUBY_METHOD_FUNC(backend_port_handle), 0);
 }

data/lib/winloop/ops.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Winloop
+  # Upper bound for Backend#op_prepare's `capacity:` — 16 MiB. Fits a DWORD with
+  # huge margin (and is far past ReadDirectoryChangesW's 64 KiB network ceiling).
+  OP_CAPACITY_MAX = 16 * 1024 * 1024
+
+  # The validated, keyword-argument face of the generic-op preparation primitive.
+  # Suite convention: validated kwargs live in Ruby; the C bridge (_op_prepare)
+  # is underscore-private so the checks can't be skipped.
+  class Backend
+    # Allocate one backend-owned op record (state :prepared): a zeroed OVERLAPPED,
+    # a `tag` echoed back in the completion tuple, and an optional embedded data
+    # buffer. Returns [op_id, ov_addr, buf_addr] (all Integers; buf_addr is 0 when
+    # capacity is 0). `handle` must have been passed to #associate on this backend
+    # first — an op on a handle that is not on the port never completes (a silent
+    # hang, not an error), so unknown handles raise Winloop::Error up front.
+    def op_prepare(handle, tag: 0, capacity: 0)
+      raise TypeError, "handle must be an Integer (got #{handle.class})"   unless handle.is_a?(Integer)
+      raise TypeError, "tag must be an Integer (got #{tag.class})"         unless tag.is_a?(Integer)
+      raise TypeError, "capacity must be an Integer (got #{capacity.class})" unless capacity.is_a?(Integer)
+      if handle.zero? || handle == 0xFFFF_FFFF_FFFF_FFFF || !handle.between?(1, 2**64 - 1)
+        raise ArgumentError, "#{handle} is not a usable HANDLE value"
+      end
+      unless tag.between?(0, 2**64 - 1)
+        raise ArgumentError, "tag must be in 0..2**64-1 (got #{tag})"
+      end
+      unless capacity.between?(0, OP_CAPACITY_MAX)
+        raise ArgumentError, "capacity must be in 0..#{OP_CAPACITY_MAX} (got #{capacity})"
+      end
+      _op_prepare(handle, tag, capacity)
+    end
+
+    private :_op_prepare
+  end
+end

data/lib/winloop/scheduler.rb

@@ -49,6 +49,16 @@ module Winloop
       @lock    = Thread::Mutex.new # guards @ready + @parked (the cross-thread path)
       @loop    = Fiber.current     # the thread's root fiber == the loop
       @closed  = false
+
+      # ---- generic OVERLAPPED op state (winloop 0.2) ----
+      @thread     = Thread.current # the op API is loop-thread-only (enforced)
+      @op_waiters = {} # op_id => Waiter        (a fiber parked in await_op)
+      @op_orphans = {} # op_id => true          (timed-out/unwound awaits; the late
+                       #                         packet is retired without waking anyone)
+      @op_done    = {} # op_id => [bytes, error] (completed before anyone awaited)
+      @op_shut    = false # true once the loop has fully finished (backend shut down).
+                          # NOT @closed: under Winloop.run, #close IS the event loop,
+                          # so @closed is true while op-protocol fibers still run.
     end
 
     def monotonic
@@ -242,6 +252,99 @@ module Winloop
       await_on_thread { Process::Status.wait(pid, flags) }
     end
 
+    # ---- generic OVERLAPPED completions (the cross-gem op protocol) ---------
+    #
+    # Client gems feature-detect with `Fiber.scheduler.respond_to?(:await_op)`
+    # and talk ONLY to these wrappers (never the Backend — they cannot reach
+    # #wait/#shutdown and corrupt the loop). The contract loop:
+    #
+    #   op_associate(h)                            # once, at handle-open time
+    #   op_id, ov, buf = op_prepare(h, capacity: n)
+    #   ok = <the client's own native submit using ov/buf>
+    #   if ok # native call returned TRUE or GetLastError == ERROR_IO_PENDING
+    #     op_submitted(op_id)
+    #     bytes, error, data = await_op(op_id, timeout: t)  # fiber parks here
+    #   else  # synchronous failure: no packet will ever arrive
+    #     op_abandon(op_id)
+    #   end
+    #
+    # All of these are loop-thread-only and raise once the scheduler has shut down.
+
+    def op_associate(handle)
+      op_guard!
+      @backend.associate(handle)
+    end
+
+    def op_prepare(handle, tag: 0, capacity: 0)
+      op_guard!
+      @backend.op_prepare(handle, tag: tag, capacity: capacity)
+    end
+
+    def op_submitted(op_id)
+      op_guard!
+      @backend.op_submitted(op_id)
+    end
+
+    def op_abandon(op_id)
+      op_guard!
+      @backend.op_abandon(op_id)
+    end
+
+    def op_cancel(op_id)
+      op_guard!
+      @backend.op_cancel(op_id)
+    end
+
+    def op_state(op_id)
+      op_guard!
+      @backend.op_state(op_id)
+    end
+
+    # Park the calling fiber until op_id's completion packet is reaped by the
+    # loop, then return [bytes, error, data] (op_result is pulled HERE, in the
+    # woken fiber, so orphaned completions never allocate Strings). On timeout:
+    # returns nil, auto-cancels and orphans the op. Either way the op is retired:
+    # after await_op returns — value or nil — the op_id must not be used again.
+    #
+    # timeout: nil (wait forever — safe provided the op was submitted on a handle
+    # that is still the associated handle) or a positive Numeric in seconds.
+    # Recommendation: pass a real timeout while first integrating a new native
+    # API; switch to nil once the submit path is proven.
+    def await_op(op_id, timeout: nil)
+      op_guard!
+      validate_op_timeout!(timeout)
+      if @op_done.delete(op_id)              # early completion: no yield
+        return @backend.op_result(op_id)
+      end
+      raise Error, "winloop: op #{op_id} already has a waiter" if @op_waiters.key?(op_id)
+      raise Error, "winloop: op #{op_id} has not been submitted" if @backend.op_state(op_id) == :prepared
+      waiter = Waiter.new(Fiber.current, false)
+      @op_waiters[op_id] = waiter
+      @timers.push(Timer.new(monotonic + timeout, waiter, nil, nil)) if timeout
+      completed = Fiber.yield                # [bytes, error] or nil (timer fired)
+      completed ? @backend.op_result(op_id) : nil
+    ensure
+      # NOTHING in this ensure may raise — it runs during Timeout::Error /
+      # Fiber#raise / Fiber#kill unwinds and must never mask the in-flight
+      # exception (op_cancel's no-raise-on-CancelIoEx contract exists for this).
+      if waiter
+        waiter.settled = true
+        if @op_waiters.delete(op_id)         # loop did NOT deliver: timeout or unwind
+          @op_orphans[op_id] = true
+          begin
+            @backend.op_cancel(op_id)        # late packet -> orphan path retires it
+          rescue Error
+            # backend already shut down mid-unwind: nothing left to cancel
+          end
+        elsif !completed                     # loop DID deliver, but we were unwound
+          # (Fiber#kill, or a sibling raise) before resuming with the value: the
+          # record sits OP_COMPLETED with nobody left to op_result it — free it
+          # now. Guarded: the loop's settled/timer branch may have retired the id.
+          @backend.op_free(op_id) if op_completed_unconsumed?(op_id)
+        end
+      end
+    end
+
     # ---- lifecycle ---------------------------------------------------------
 
     # MRI calls this automatically at thread/program exit. It IS the event loop.
@@ -250,6 +353,7 @@ module Winloop
       @closed = true
       run
     ensure
+      @op_shut = true # the op protocol is over; op_* / await_op raise from here on
       @backend.shutdown
       # NEVER call Fiber.set_scheduler(nil) here — it raises SystemStackError
       # during MRI's implicit close at thread exit.
@@ -270,7 +374,10 @@ module Winloop
       # #unblock that is moving a waiter into @ready right now.
       @lock.synchronize do
         drop_settled_timers
-        @ready.empty? && @timers.empty? && @ops.empty? && @parked.empty?
+        @ready.empty? && @timers.empty? && @ops.empty? && @parked.empty? &&
+          @op_waiters.empty?
+        # @op_orphans/@op_done deliberately do NOT keep the loop alive —
+        # shutdown's cancel+drain+sweep retires whatever is left.
       end
     end
 
@@ -321,40 +428,66 @@ module Winloop
         elsif (t = @timers.peek)
           ms = ((t.deadline - monotonic) * 1000).ceil
           timeout_ms = ms < 0 ? 0 : ms
-        elsif @ops.empty? && @parked.empty?
+        elsif @ops.empty? && @parked.empty? && @op_waiters.empty?
           idle = true # nothing to wait for
         else
-          timeout_ms = nil # INFINITE — pending I/O or parked fibers wake us
+          timeout_ms = nil # INFINITE — pending I/O, parked fibers or awaited ops
+          # wake us. An awaited op pending => INFINITE is correct for contract-
+          # abiding ops: its completion (or its cancel's completion) wakes the
+          # port — guaranteed because op_prepare verified the handle is on it.
         end
       end
       return if idle
 
-      # (d) one GetQueuedCompletionStatusEx; fan each completion out to the
-      #     io waiters whose interest the ready mask satisfies.
-      @backend.wait(timeout_ms).each do |id, ready_events|
-        entry = @ops.delete(id)
-        next unless entry # stale: a superseded/cancelled poll
-        entry.id = nil
-        entry.armed = 0
-        to_wake = []
-        entry.waiters.reject! do |w|
-          if w.settled
-            true
-          elsif (got = w.events & ready_events) != 0
-            w.settled = true
-            to_wake << [w.fiber, got]
-            true
-          else
-            false # this waiter's direction didn't fire; keep it
+      # (d) one GetQueuedCompletionStatusEx; dispatch per entry on tuple size:
+      #     AFD readiness completions are 2-tuples [id, ready_events]; generic
+      #     op completions (winloop 0.2) are 4-tuples [op_id, bytes, error, tag].
+      @backend.wait(timeout_ms).each do |entry|
+        if entry.size == 4
+          op_id, bytes, error, _tag = entry
+          if (w = @op_waiters.delete(op_id))
+            if w.settled                     # its timer fired this same turn: orphan
+              @backend.op_free(op_id)
+            else
+              w.settled = true
+              @lock.synchronize { @ready << [w.fiber, [bytes, error]] }
+            end
+          elsif @op_orphans.delete(op_id)    # await timed out / unwound earlier
+            @backend.op_free(op_id)
+          else                               # completed before anyone awaited
+            @op_done[op_id] = [bytes, error]
           end
+        else
+          fan_out_afd(entry[0], entry[1])
         end
-        @lock.synchronize { @ready.concat(to_wake) } unless to_wake.empty?
-        if entry.waiters.empty?
-          @polls.delete(entry.key)
+      end
+    end
+
+    # Fan one AFD readiness completion out to the io waiters whose interest the
+    # ready mask satisfies (the pre-0.2 body of run_once step (d), unchanged).
+    def fan_out_afd(id, ready_events)
+      entry = @ops.delete(id)
+      return unless entry # stale: a superseded/cancelled poll
+      entry.id = nil
+      entry.armed = 0
+      to_wake = []
+      entry.waiters.reject! do |w|
+        if w.settled
+          true
+        elsif (got = w.events & ready_events) != 0
+          w.settled = true
+          to_wake << [w.fiber, got]
+          true
         else
-          arm_poll(entry) # re-arm for the still-waiting fibers
+          false # this waiter's direction didn't fire; keep it
         end
       end
+      @lock.synchronize { @ready.concat(to_wake) } unless to_wake.empty?
+      if entry.waiters.empty?
+        @polls.delete(entry.key)
+      else
+        arm_poll(entry) # re-arm for the still-waiting fibers
+      end
     end
 
     # Ensure at most one AFD poll is outstanding for `entry`'s socket, covering
@@ -403,6 +536,33 @@ module Winloop
       @timers.pop while (t = @timers.peek) && t.waiter.settled
     end
 
+    # ---- generic-op helpers (winloop 0.2) ----------------------------------
+
+    # The op protocol is loop-thread-only (ops are submitted on the loop thread —
+    # fibers run there anyway; Ruby worker threads must not submit) and over once
+    # the loop has shut down.
+    def op_guard!
+      unless Thread.current == @thread
+        raise Error, "winloop: op API must be called on the scheduler's thread"
+      end
+      raise Error, "winloop: scheduler is closed" if @op_shut
+    end
+
+    def validate_op_timeout!(timeout)
+      return if timeout.nil?
+      return if timeout.is_a?(Numeric) && timeout.positive?
+      raise ArgumentError, "timeout must be nil or a positive Numeric (got #{timeout.inspect})"
+    end
+
+    # true iff the id is still live and in :completed state; false for retired ids
+    # (op_state raises "unknown op id" — swallowed here, never re-raised: this
+    # probe runs inside await_op's must-not-raise ensure).
+    def op_completed_unconsumed?(op_id)
+      @backend.op_state(op_id) == :completed
+    rescue Error
+      false
+    end
+
     # Enqueue a fiber to resume, honouring the one-shot guard. Caller holds @lock.
     def wake_locked(waiter, value)
       return if waiter.settled

data/lib/winloop/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Winloop
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/winloop.rb

@@ -35,6 +35,7 @@ module Winloop
   end
 
   require_relative "winloop/scheduler"
+  require_relative "winloop/ops" # generic-op validation layer (OP_CAPACITY_MAX, op_prepare)
 
   module_function
 

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: winloop
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
-- Leiz
+- ned
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -69,16 +69,19 @@ files:
 - ext/winloop/extconf.rb
 - ext/winloop/winloop.c
 - lib/winloop.rb
+- lib/winloop/ops.rb
 - lib/winloop/scheduler.rb
 - lib/winloop/version.rb
-homepage: https://github.com/leiz/winloop
+homepage: https://github.com/main-path/winloop
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/leiz/winloop
-  source_code_uri: https://github.com/leiz/winloop
-  changelog_uri: https://github.com/leiz/winloop/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/main-path/winloop
+  source_code_uri: https://github.com/main-path/winloop
+  changelog_uri: https://github.com/main-path/winloop/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/winloop/issues
   allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib