From 7d1e4462d4dfb5dfc84814f54c533fe27a06bc4b Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Fri, 8 May 2026 02:51:21 -0400
Subject: [PATCH] Adjust `subint_forkserver` docs to match stub impl
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comment/docstring updates: `subint_forkserver` is a clean
`NotImplementedError` stub — not an alias to variant-1
(`main_thread_forkserver`). Key reserved in-place (not aliased) so
the subint-hosted-child impl can flip without API churn once
jcrist/msgspec#1026 unblocks PEP 684 subints.

(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 tractor/spawn/_spawn.py             | 14 +++++++++-----
 tractor/spawn/_subint_forkserver.py | 21 ++++++++++++---------
 2 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/tractor/spawn/_spawn.py b/tractor/spawn/_spawn.py
index 1f2203d3..0345061e 100644
--- a/tractor/spawn/_spawn.py
+++ b/tractor/spawn/_spawn.py
@@ -83,11 +83,15 @@ SpawnMethodKey = Literal[
     # runtime, exactly like `trio_proc` but via fork instead
     # of subproc-exec. See `tractor.spawn._main_thread_forkserver`.
     'main_thread_forkserver',
-    # RESERVED for the future variant-2 subint-isolated-child
-    # runtime — gated on jcrist/msgspec#1026 + PEP 684. Today
-    # this key aliases to `main_thread_forkserver_proc`; once
-    # the upstream unblocks land it'll dispatch to the
-    # subint-hosted-trio impl. See
+    # Variant-2: same fork machinery as `main_thread_forkserver`
+    # but the child enters a sub-interpreter to host its
+    # `trio.run()`. Gated on jcrist/msgspec#1026 unblocking
+    # PEP 684 isolated-mode subints upstream — until then
+    # `subint_forkserver_proc` is a clean `NotImplementedError`
+    # stub pointing at variant-1 (`main_thread_forkserver`) +
+    # the upstream blocker. The key is reserved here (not just
+    # aliased to variant-1) so once upstream lands the impl can
+    # flip in-place without API churn. See
     # `tractor.spawn._subint_forkserver`.
     'subint_forkserver',
 ]
diff --git a/tractor/spawn/_subint_forkserver.py b/tractor/spawn/_subint_forkserver.py
index 07fbcf14..ff56900c 100644
--- a/tractor/spawn/_subint_forkserver.py
+++ b/tractor/spawn/_subint_forkserver.py
@@ -18,15 +18,18 @@
 Variant-2 (future) "subint forkserver" placeholder — reserved
 for the eventual subint-isolated-child runtime variant.
 
-> **Status:** placeholder. Today
-> `--spawn-backend=subint_forkserver` aliases to
-> `main_thread_forkserver_proc` (variant 1, see
-> `tractor.spawn._main_thread_forkserver`). A follow-up commit
-> in this PR series flips the alias to a `NotImplementedError`
-> stub reserving the `'subint_forkserver'` key for the literal
-> subint-hosted-child variant once
-> [jcrist/msgspec#1026](https://github.com/jcrist/msgspec/issues/1026)
-> unblocks PEP 684 isolated-mode subints upstream.
+> **Status:** reserved key, stub impl. Today
+> `--spawn-backend=subint_forkserver` raises a clean
+> `NotImplementedError` from `subint_forkserver_proc()`
+> below, pointing at variant-1
+> (`--spawn-backend=main_thread_forkserver`, see
+> `tractor.spawn._main_thread_forkserver`) and the upstream
+> blocker
+> ([jcrist/msgspec#1026](https://github.com/jcrist/msgspec/issues/1026)).
+> The key is reserved here (not aliased to variant-1) so the
+> literal subint-hosted-child impl can flip in-place once
+> msgspec#1026 unblocks PEP 684 isolated-mode subints
+> upstream — no API churn at the call site.
 
 Future arch — what subints would buy us
 ---------------------------------------