vgi-python 0.18.0__tar.gz → 0.19.0__tar.gz

{vgi_python-0.18.0 → vgi_python-0.19.0}/.github/workflows/integration.yml

@@ -45,8 +45,11 @@ jobs:
       matrix:
         include:
           # stdio:  the subprocess transport (whole suite — the primary lane).
-          # shm:    stdio + the POSIX shared-memory side channel.
-          # launch: the AF_UNIX launcher-only tests.
+          # launch: the whole suite over the AF_UNIX launcher transport.
+          # shm:    launch + the POSIX shared-memory side channel. Rides the
+          #         launcher, not raw subprocess: stdio already covers the
+          #         fork-per-connection path and spends most of its wall-clock
+          #         doing it, so re-paying that cost to test shm is waste.
           # http:   the whole suite over the stateless HTTP transport.
           - { lane: stdio }
           - { lane: shm, shm_bytes: '67108864' }

{vgi_python-0.18.0 → vgi_python-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.18.0
+Version: 0.19.0
 Summary: Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow
 Project-URL: Homepage, https://query.farm
 Project-URL: Repository, https://github.com/Query-farm/vgi-python

{vgi_python-0.18.0 → vgi_python-0.19.0}/ci/README.md

@@ -52,21 +52,47 @@ runs them as a matrix):
   Also boots the versioned and versioned-tables workers as background HTTP
   servers (`VGI_VERSIONED_HTTP_WORKER` / `VGI_VERSIONED_TABLES_HTTP_WORKER`) so
   the `attach/versioned_tables_*_http` and `versioning_http` tests run.
-- **`shm`** — `stdio` plus the POSIX shared-memory side channel
+- **`shm`** — the **`launch`** lane plus the POSIX shared-memory side channel
   (`VGI_RPC_SHM_SIZE_BYTES`); the whole suite. vgi-rpc-python attaches the
-  segment transparently, so the env var alone flips the transport.
-- **`launch`** — the AF_UNIX launcher transport; the launcher-only tests
-  (`launcher/*`), which the other lanes skip via `require-env`.
+  segment transparently, so the env var alone flips the side channel on.
+  This deliberately differs from the vgi Makefile's `test_shm`, which layers shm
+  on raw subprocess: `stdio` already covers the fork-per-connection path and
+  spends most of its wall-clock doing it, so paying that cost twice just to
+  exercise shm is waste. The side channel is transport-independent — negotiated
+  via the `__transport_options__` handshake and carried in POSIX shm rather than
+  in the pipe or socket — and engages identically over the launcher (verified:
+  the same 18 `[shm]` transfers under `VGI_RPC_SHM_DEBUG=1` on both).
+- **`launch`** — the AF_UNIX launcher transport; the whole suite, with *every*
+  `VGI_*_WORKER` fronted by `launch:` so traffic flows through the C++ launcher
+  (`ResolveLauncherSocketPath` → AF_UNIX → `UnixSocketWorker`). Mirrors the vgi
+  Makefile's `test_launcher`: the point is that the launcher path produces
+  identical query results to the subprocess path, which only a full-suite run
+  demonstrates. Setting `VGI_REQUIRE_LAUNCHER_TRANSPORT` additionally un-skips
+  the launcher-only tests (`launcher/*`), whose options apply solely to the
+  `launch:` dispatch path and which the other lanes skip via `require-env`.
+  The versioned / versioned-tables *http* worker vars are left unset (as in
+  `test_launcher`), so those tests skip here — stdio covers them. One deliberate
+  divergence from `test_launcher`: see `filter_echo_partitioned.test` below.
 - **`http`** — the whole suite over the stateless HTTP transport. Staging
   injects `LOAD httpfs` before each worker ATTACH (the prebuilt binary doesn't
   statically link httpfs).
 
 The `simple_writable/*.test` write-path tests (INSERT/UPDATE/DELETE/RETURNING)
-run on the subprocess lanes against `VGI_SIMPLE_WRITABLE_WORKER`
+run on **every** lane against `VGI_SIMPLE_WRITABLE_WORKER`
 (`vgi-fixture-simple-writable-worker`), in their own `haybarn-unittest`
 invocation so their warm pooled connections don't perturb the immediately
-following crash-recovery test. They self-skip on the http lane
-(skip-on-error `'HTTP'`).
+following crash-recovery test. That env var is always a spawned binary — a
+`launch:` path on the launch lane, a plain path elsewhere — so these tests run
+over subprocess even on the http lane rather than skipping.
+
+The crash / pool-recovery tests (`table_in_out/table_buffering_*`) are gated on
+`VGI_TEST_DEDICATED_WORKER`, which is set on the **`stdio` lane only**. Their
+`crash_on_process` fixture does `os.kill(getpid(), SIGKILL)`; that is a
+recoverable per-DuckDB-process child kill under subprocess transport, but under
+any shared-worker transport (`http://`, `launch:`) it kills the one process
+serving the whole suite and every later `ATTACH` fails. Because `shm` now rides
+the launcher, `stdio` is the only lane that can host them — worth knowing if you
+ever narrow the stdio lane.
 
 ### Excluded tests
 
@@ -95,8 +121,22 @@ Dropped on the **http** lane only:
   `CLAUDE.md`). `buffer_input/scale.test_slow` is a `.test_slow` file, which the
   harness never stages (it only finds `*.test`).
 
+Nothing is dropped on the **launch** lane. `test_launcher` upstream excludes two
+files, and neither applies:
+
+- `test/sql/vgi_worker_pool.test` lives outside `test/sql/integration`, so the
+  harness never stages it.
+- `table/filter_echo_partitioned.test` is excluded upstream for asserting >1
+  distinct `worker_pid`, which AF_UNIX socket pooling cannot satisfy. That
+  rationale is stale — the test now counts transport-neutral `conn=` ids instead
+  — and it passes over `launch:` against the Python fixture worker. Keeping it
+  preserves coverage of precisely what the launcher changes: connection
+  multiplexing.
+
 The HTTP-attach / bearer-auth / dynamic-code / schema-reconcile-only tests skip
 via their `require-env` gates when we don't set the corresponding worker.
+`bad_enum.test` skips on every lane — `VGI_BAD_ENUM_WORKER` is not wired up here
+even though the fixture (`vgi-fixture-bad-enum-worker`) is installed.
 
 ## Run it locally
 

{vgi_python-0.18.0 → vgi_python-0.19.0}/ci/run-integration.sh

@@ -16,8 +16,11 @@
 #   * No worker coverage (unlike vgi-go's GOCOVERDIR) — pass/fail only.
 #
 # This mirrors the env wiring of the vgi repo's Makefile `test_subprocess` /
-# `test_shm` / `test_launcher` / `test_http` targets (the canonical local way to
-# run this suite against the Python worker — see vgi-python/CLAUDE.md).
+# `test_launcher` / `test_http` targets (the canonical local way to run this
+# suite against the Python worker — see vgi-python/CLAUDE.md). The `shm` lane
+# deliberately differs from Makefile `test_shm`: it layers the shm side channel
+# on the LAUNCHER rather than on raw subprocess, to avoid re-forking a Python
+# worker per connection. See the shm|launch case below.
 #
 # Required environment:
 #   VGI_SRC           path to a Query-farm/vgi checkout (contains test/sql/integration)
@@ -59,6 +62,16 @@ done
 # ---------------------------------------------------------------------------
 AWK_HTTP=0
 EXTRA_SKIP=()
+# Nothing is dropped on the launch lane. The vgi Makefile's test_launcher
+# excludes two files, and neither applies here:
+#   * test/sql/vgi_worker_pool.test — outside test/sql/integration, so it is
+#     never staged by the find below.
+#   * table/filter_echo_partitioned.test — excluded upstream for asserting >1
+#     distinct worker_pid, which AF_UNIX socket pooling can't satisfy. That
+#     rationale is stale: the test now counts transport-neutral `conn=` ids
+#     instead (see its own comment), and it passes over launch: against the
+#     Python fixture worker. Keeping it preserves coverage of exactly what the
+#     launcher changes — connection multiplexing.
 if [ "$TRANSPORT" = "http" ]; then
   AWK_HTTP=1
   # Dropped on the http lane only:
@@ -120,20 +133,38 @@ export VGI_SYNC_INIT_GLOBAL=1
 SCHEMA_RECONCILE_DIR="$(mktemp -d)"
 export VGI_SCHEMA_RECONCILE_DB="$SCHEMA_RECONCILE_DIR/vgi_schema_reconcile.sqlite"
 
-# Presence gate for the crash / pool-recovery tests
-# (table_in_out/table_buffering_*). The value is not used as a worker spec —
-# the SQL attaches the normal pooled worker; this just un-skips the tests.
-export VGI_TEST_DEDICATED_WORKER=1
-
 # Background workers (http servers) are tracked in a file and SIGTERMed on exit.
+# Each line is "<pid>\t<logfile>".
 BG_PIDS_FILE="$(mktemp)"
 # shellcheck disable=SC2329  # invoked indirectly via `trap cleanup EXIT` below
 cleanup() {
   [ -f "$BG_PIDS_FILE" ] || return 0
-  while read -r p; do [ -n "$p" ] && kill "$p" 2>/dev/null || true; done < "$BG_PIDS_FILE"
+  while IFS="$(printf '\t')" read -r p _; do
+    [ -n "$p" ] && kill "$p" 2>/dev/null || true
+  done < "$BG_PIDS_FILE"
 }
 trap cleanup EXIT
 
+# assert_bg_workers_alive — fail if any background http worker died during a
+# run, dumping its log. A dead shared worker is otherwise near-invisible: the
+# runner's default error handling turns the resulting cascade of failed ATTACHes
+# into skips, so the lane still prints "All tests passed" having tested nothing
+# past the point of death (the failure mode that hid 136 voided files in run
+# 29979884253). Cheap insurance against a green-but-empty lane.
+assert_bg_workers_alive() {
+  local rc=0 p log
+  [ -s "$BG_PIDS_FILE" ] || return 0
+  while IFS="$(printf '\t')" read -r p log; do
+    [ -n "$p" ] || continue
+    kill -0 "$p" 2>/dev/null && continue
+    echo "::error::background http worker (pid $p) died during the run — everything" \
+         "attached to it after that point was not really tested. Its log follows."
+    [ -n "$log" ] && [ -f "$log" ] && sed -n '1,200p' "$log"
+    rc=1
+  done < "$BG_PIDS_FILE"
+  return "$rc"
+}
+
 # boot_http_worker <binary> — start it as an HTTP server on an ephemeral port and
 # set BOOTED_PORT to the port it reports (PORT:<n>, the worker's readiness
 # contract). Sets a global rather than echoing so the backgrounded worker stays a
@@ -156,7 +187,7 @@ boot_http_worker() {
   log="$(mktemp)"
   ( cd "$STAGE" && exec "$exe" --http --port 0 ) >"$log" 2>&1 &
   pid=$!
-  echo "$pid" >> "$BG_PIDS_FILE"
+  printf '%s\t%s\n' "$pid" "$log" >> "$BG_PIDS_FILE"
   for _ in $(seq 1 60); do
     kill -0 "$pid" 2>/dev/null || { echo "::error::http worker '$exe' exited" >&2; cat "$log" >&2; return 1; }
     port="$(sed -n 's/.*PORT:\([0-9]*\).*/\1/p' "$log" | head -1)"
@@ -167,20 +198,45 @@ boot_http_worker() {
   BOOTED_PORT="$port"
 }
 
+# On the launcher-family lanes EVERY worker is fronted by `launch:` so the C++
+# launcher serves it (ResolveLauncherSocketPath -> AF_UNIX -> UnixSocketWorker),
+# as the vgi Makefile's test_launcher does. A worker left unprefixed would
+# silently run over stdio inside a launcher lane. Empty on stdio and http.
+LAUNCH_PREFIX=""
+case "$TRANSPORT" in shm|launch) LAUNCH_PREFIX="launch:" ;; esac
+
 # version_mismatch.test attaches a worker that advertises an incompatible
 # protocol_version; set on the subprocess lanes (skips elsewhere via require-env).
-export VGI_BAD_PROTOCOL_WORKER="$BAD_PROTOCOL"
+export VGI_BAD_PROTOCOL_WORKER="${LAUNCH_PREFIX}${BAD_PROTOCOL}"
 
 # The simple_writable fixture worker un-skips the cross-language
-# simple_writable/*.test write-path tests. Set on every lane; they self-skip
-# over http (skip-on-error 'HTTP').
-export VGI_SIMPLE_WRITABLE_WORKER="$SIMPLE_WRITABLE"
+# simple_writable/*.test write-path tests. Set on every lane — on the http lane
+# it stays a binary path, so those tests run over subprocess there (they do NOT
+# self-skip: the http lane passes all 5 files).
+export VGI_SIMPLE_WRITABLE_WORKER="${LAUNCH_PREFIX}${SIMPLE_WRITABLE}"
 
 case "$TRANSPORT" in
-  stdio|shm)
-    # Subprocess transport (the primary lane). shm is identical plus the POSIX
-    # shared-memory side channel via VGI_RPC_SHM_SIZE_BYTES.
+  stdio)
+    # Subprocess transport (the primary lane) — the only lane that spawns a
+    # fresh worker process per DuckDB connection, and so the only one that can
+    # host the crash / pool-recovery tests below.
     export VGI_TEST_WORKER="$WORKER"
+    # Presence gate for the crash / pool-recovery tests
+    # (table_in_out/table_buffering_{worker_crash,pool_recovery}). The value is
+    # not a worker spec — the SQL attaches the normal pooled worker; this just
+    # un-skips the tests.
+    #
+    # DEDICATED (subprocess) LANE ONLY. Those tests call the `crash_on_process`
+    # fixture, which does os.kill(getpid(), SIGKILL). Under subprocess transport
+    # that kills the per-DuckDB-process worker child and the pool recovers —
+    # exactly what the tests assert. Under a SHARED-worker transport (http://,
+    # unix://, launch:) it kills the single process serving the whole suite, and
+    # every later ATTACH fails. Exporting it unconditionally silently voided 136
+    # of 286 files on the http lane while still printing "All tests passed"
+    # (run 29979884253) — the crash landed at file 132 and the runner's default
+    # error handling swallowed the cascade. Since shm now runs over the launcher
+    # (a shared worker), stdio is the ONLY lane that may set this.
+    export VGI_TEST_DEDICATED_WORKER=1
     export VGI_VERSIONED_WORKER="$VERSIONED"
     export VGI_VERSIONED_TABLES_WORKER="$VERSIONED_TABLES"
     export VGI_ATTACH_OPTIONS_WORKER="$ATTACH_OPTIONS"
@@ -192,12 +248,33 @@ case "$TRANSPORT" in
     export VGI_VERSIONED_HTTP_WORKER="http://localhost:${vh_port}"
     SUITE_GLOB="test/sql/integration/*"
     ;;
-  launch)
-    # AF_UNIX launcher transport. Only the launcher-only tests opt in here
-    # (the rest of the suite runs on the stdio lane); mirrors make test-launcher.
+  shm|launch)
+    # AF_UNIX launcher transport — the WHOLE suite with every worker fronted by
+    # `launch:`, mirroring the vgi Makefile's test_launcher. Validates that the
+    # launcher path produces identical query results to the subprocess path;
+    # running only launcher/* here would leave the transport almost untested.
+    # VGI_REQUIRE_LAUNCHER_TRANSPORT additionally un-skips launcher/*, whose
+    # options only apply to the launch: dispatch path (the other lanes skip them).
+    #
+    # `shm` is this same lane plus the POSIX shared-memory side channel
+    # (VGI_RPC_SHM_SIZE_BYTES, exported by the workflow). It rides the launcher
+    # rather than raw subprocess because stdio spends most of its wall-clock
+    # fork+exec'ing a fresh Python worker per connection; the launcher keeps one
+    # warm worker per argv and reuses it, so the lane exercises the same shm
+    # paths far faster. The side channel is transport-independent — it is
+    # negotiated via the __transport_options__ handshake and carried in POSIX
+    # shm, not in the pipe/socket — and engages identically here (verified: the
+    # same 18 [shm] transfers under VGI_RPC_SHM_DEBUG on stdio and on launch).
+    #
+    # The versioned / versioned_tables *http* worker env vars are deliberately
+    # left UNSET (as in test_launcher), so attach/versioned_tables_*_http and
+    # versioning_http skip — they're covered over http on the stdio lane.
     export VGI_TEST_WORKER="launch:${WORKER}"
+    export VGI_VERSIONED_WORKER="launch:${VERSIONED}"
+    export VGI_VERSIONED_TABLES_WORKER="launch:${VERSIONED_TABLES}"
+    export VGI_ATTACH_OPTIONS_WORKER="launch:${ATTACH_OPTIONS}"
     export VGI_REQUIRE_LAUNCHER_TRANSPORT=1
-    SUITE_GLOB="test/sql/integration/launcher/*"
+    SUITE_GLOB="test/sql/integration/*"
     ;;
   http)
     # Whole-suite-over-HTTP (mirrors make test_http). Every ATTACH goes over
@@ -253,8 +330,8 @@ rm -f "$STAGE/test/_warm.test"
 # pool). Its table-in-out write workers otherwise leave warm pooled connections
 # that perturb the immediately-following crash-recovery test
 # (table_in_out/table_buffering_pool_recovery). A separate process gives the
-# crash test a clean pool. The launcher lane runs only launcher/* (no
-# simple_writable); the http lane's writes self-skip.
+# crash test a clean pool. Every lane does the split: simple_writable always
+# attaches a spawned binary (VGI_SIMPLE_WRITABLE_WORKER), even on the http lane.
 echo "Running suite ($SUITE_GLOB, transport=$TRANSPORT) ..."
 suite_rc=0
 
@@ -288,12 +365,11 @@ run_unittest() {
   return "$rc"
 }
 
-if [ "$TRANSPORT" = "launch" ]; then
-  run_unittest "$SUITE_GLOB" || suite_rc=$?
-else
-  run_unittest "$SUITE_GLOB" "~test/sql/integration/simple_writable/*" || suite_rc=$?
-  echo "Running simple_writable (isolated process) ..."
-  run_unittest "test/sql/integration/simple_writable/*" || suite_rc=$?
-fi
+run_unittest "$SUITE_GLOB" "~test/sql/integration/simple_writable/*" || suite_rc=$?
+assert_bg_workers_alive || suite_rc=1
+
+echo "Running simple_writable (isolated process) ..."
+run_unittest "test/sql/integration/simple_writable/*" || suite_rc=$?
+assert_bg_workers_alive || suite_rc=1
 
 exit "$suite_rc"

{vgi_python-0.18.0 → vgi_python-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.18.0"
+version = "0.19.0"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [

{vgi_python-0.18.0 → vgi_python-0.19.0}/tests/test_schema_scoped_functions.py

@@ -10,6 +10,7 @@ same_name_schemas.test`` covers the same ground end-to-end through DuckDB.
 
 from __future__ import annotations
 
+import dataclasses
 from typing import Annotated
 
 import pyarrow as pa
@@ -154,7 +155,8 @@ class TestLegacyFunctionsList:
 class TestCrossCatalogResolution:
     """Two catalogs in one worker process, colliding on schema *and* function name.
 
-    Only ``attach_opaque_data`` names the catalog, so it is the routing key.
+    Only the catalog name sealed into ``attach_opaque_data`` distinguishes them,
+    so it is the routing key.
     ``vgi/test/sql/integration/scalar/same_name_catalogs.test`` drives the same
     scenario end-to-end through DuckDB.
     """
@@ -175,11 +177,29 @@ class TestCrossCatalogResolution:
         )
 
     def test_attach_opaque_data_selects_the_catalog(self) -> None:
-        """Each sub-worker's wrapped attach routes to that catalog's class."""
+        """The catalog name sealed into the attach routes to that catalog's class."""
         meta = self._meta()
-        for index, expected in ((0, TwinAFunction), (1, TwinBFunction)):
-            wrapped = meta._wrap_attach_opaque_data(index, b"\x00" * 16)
-            assert meta._resolve_function(self._request(wrapped)) is expected
+        for index, catalog, expected in ((0, "twin_a", TwinAFunction), (1, "twin_b", TwinBFunction)):
+            attach = meta._workers[index]._seal_attach_with_catalog(b"\x00" * 16, catalog)
+            assert meta._resolve_function(self._request(attach)) is expected
+
+    def test_routing_survives_the_strip_that_http_serialization_performs(self) -> None:
+        """A rehydrated attach still routes — the regression behind the twin bug.
+
+        HTTP stream state persists the attach the sub-worker was handed, then
+        ``rehydrate`` re-resolves against the MetaWorker. When routing lived in a
+        prefix that ``init`` stripped before the sub-worker saw it, that
+        round-trip lost the key and silently resolved to whichever sub-worker
+        declared the name first. The name is inside the sealed plaintext now, so
+        the value that gets persisted is itself routable.
+        """
+        meta = self._meta()
+        for index, catalog, expected in ((0, "twin_a", TwinAFunction), (1, "twin_b", TwinBFunction)):
+            worker = meta._workers[index]
+            attach = worker._seal_attach_with_catalog(b"\x00" * 16, catalog)
+            # What init() hands the sub-worker is what ends up serialized.
+            assert meta._maybe_worker_for_attach(attach) is worker
+            assert meta._resolve_function(self._request(attach)) is expected
 
     def test_both_catalogs_declare_the_same_schema_and_name(self) -> None:
         """The fixture is only meaningful if the collision is total."""
@@ -187,7 +207,33 @@ class TestCrossCatalogResolution:
         assert TwinAWorker._build_schema_registry()[key] == [TwinAFunction]
         assert TwinBWorker._build_schema_registry()[key] == [TwinBFunction]
 
-    def test_without_an_attach_the_scan_still_finds_a_host(self) -> None:
-        """No catalog is knowable (HTTP state rehydration) — resolve, don't crash."""
+    def test_without_an_attach_an_ambiguous_name_raises(self) -> None:
+        """No routing key and two declarers — refuse rather than guess.
+
+        This previously returned ``TwinAFunction``: whichever sub-worker declared
+        the name first. That is what made ``b.main.test_same_name_catalog(1)``
+        answer ``twin_a:1`` over HTTP instead of failing, so a routing bug read
+        as a plausible result. An attach-less call to an ambiguous name means the
+        key was lost upstream, which is worth surfacing.
+        """
         meta = self._meta()
+        with pytest.raises(ValueError, match="Cannot route"):
+            meta._resolve_function(self._request(None))
+
+    def test_without_an_attach_an_unambiguous_name_still_resolves(self) -> None:
+        """The legitimate attach-less path is untouched.
+
+        Non-catalog callers (``Worker.functions``) reach ``_resolve_function``
+        with no attach at all. With a single declarer there is no ambiguity to
+        refuse, so resolution must still succeed — the guard keys off the
+        candidate count, not off the attach being absent.
+        """
+        meta = MetaWorker([TwinAWorker()])
         assert meta._resolve_function(self._request(None)) is TwinAFunction
+
+    def test_an_unknown_name_reports_unknown_not_ambiguous(self) -> None:
+        """A name no sub-worker declares is still a plain 'unknown function'."""
+        meta = self._meta()
+        request = dataclasses.replace(self._request(None), function_name="no_such_function")
+        with pytest.raises(ValueError, match="Unknown function"):
+            meta._resolve_function(request)

{vgi_python-0.18.0 → vgi_python-0.19.0}/uv.lock

@@ -2228,7 +2228,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.18.0"
+version = "0.19.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

vgi_python-0.19.0/vgi/attach_header.py

@@ -0,0 +1,81 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+r"""Routing header that [`MetaWorker`][] encapsulates inside an attach envelope.
+
+When several [`Worker`][] instances are composed into one process, a call that
+carries an ``attach_opaque_data`` has to be routed back to the sub-worker whose
+catalog vended it. Nothing in the request identifies the catalog:
+``BindRequest`` carries only ``schema_name``, and the catalog's own opaque bytes
+are implementation-defined — the built-in read-only catalog returns the class
+constant ``b"readonly-catalog-"`` for *every* catalog it serves, so two catalogs
+in one process are byte-identical there.
+
+So ``MetaWorker`` records the catalog name itself. At ``catalog_attach`` it opens
+the sub-worker's sealed attach, prepends this header to the plaintext, and
+re-seals:
+
+    sealed( VGI\0MWC\0 || len(1) || name || uuid(16) || catalog_bytes )
+
+Two properties matter:
+
+* **Inside the seal.** The signing key is process-wide, so a header riding
+  *outside* the AEAD could be edited by a client to route an attach minted for
+  one catalog into another — every sub-worker's key would open it. Sealing the
+  name makes forging it equivalent to forging the envelope.
+* **Survives serialization.** The header is part of the plaintext, so it rides
+  along in whatever the sub-worker persists into an HTTP stream state. A
+  rehydrate landing on a different instance re-reads the name and routes
+  correctly — no process-local map, and no dependence on a positional index that
+  need not agree across deploys.
+
+``Worker`` strips the header when opening an envelope, so every existing consumer
+keeps seeing the framework plaintext (``uuid(16) || catalog_bytes``) unchanged.
+"""
+
+from __future__ import annotations
+
+# 8 bytes: long enough that a random uuid4 prefix colliding with it is not worth
+# reasoning about (a 6-byte marker would already be ~2^-48 per attach).
+_MAGIC = b"VGI\x00MWC\x00"
+_LEN_WIDTH = 1
+_MAX_NAME_BYTES = (1 << (8 * _LEN_WIDTH)) - 1
+
+
+def encode(catalog_name: str, plaintext: bytes) -> bytes:
+    """Prepend the routing header for ``catalog_name`` to an attach plaintext.
+
+    ``plaintext`` is the framework form the sub-worker minted
+    (``uuid(16) || catalog_bytes``); the result is meant to be sealed.
+    """
+    name = catalog_name.encode("utf-8")
+    if len(name) > _MAX_NAME_BYTES:
+        msg = f"catalog name too long to encode in an attach header: {len(name)} > {_MAX_NAME_BYTES} bytes"
+        raise ValueError(msg)
+    return _MAGIC + len(name).to_bytes(_LEN_WIDTH, "big") + name + plaintext
+
+
+def split(plaintext: bytes | None) -> tuple[str | None, bytes | None]:
+    """Split an opened attach plaintext into ``(catalog_name, inner_plaintext)``.
+
+    Returns ``(None, plaintext)`` unchanged when no header is present — the
+    single-``Worker`` case, and any attach minted before this header existed.
+    Malformed headers are treated the same way rather than raising: the value
+    still has to satisfy the AEAD, so a truncated header means a framework bug
+    on the mint side, and failing the *call* with a confusing error is worse than
+    falling back to the un-routed path (which raises a precise error of its own
+    when the function name turns out to be ambiguous).
+    """
+    if not plaintext or not plaintext.startswith(_MAGIC):
+        return None, plaintext
+    at = len(_MAGIC)
+    if len(plaintext) < at + _LEN_WIDTH:
+        return None, plaintext
+    name_len = int.from_bytes(plaintext[at : at + _LEN_WIDTH], "big")
+    at += _LEN_WIDTH
+    if len(plaintext) < at + name_len:
+        return None, plaintext
+    try:
+        name = plaintext[at : at + name_len].decode("utf-8")
+    except UnicodeDecodeError:
+        return None, plaintext
+    return name, plaintext[at + name_len :]