@@ -126,6 +126,27 @@ jobs:
           args: "--no-progress --offline --root-dir ${{ github.workspace }}/docs docs/**/*.md *.md"
           fail: true
 
+  hosted-protocols:
+    # vgi-rpc's cross-SDK hosted-protocols group: the fixture workers must host
+    # vgi.v2 then conformance.Secondary.v1 on stdio, unix and HTTP, and pass the
+    # Identity.v1 groups over HTTP (vgi-fixture-http --identity).
+    name: Hosted-protocols conformance
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.2.0
+
+      - name: Set up Python 3.14
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --all-extras --python 3.14
+
+      - name: Run hosted-protocols group (stdio, unix, http)
+        run: scripts/hosted_protocols_conformance.sh
+
   s3-offload-localstack:
     name: S3 Offload Tests (LocalStack)
     runs-on: ubuntu-latest
 
@@ -428,9 +428,10 @@ caller's identity before it can authorize anything.
 
 Through vgi-rpc 0.45.x this was an HTTP JSON route, `POST
 {prefix}/__introspect_token__`, which meant it existed on exactly one
-transport. As of **vgi-rpc 0.46.0** identity lives at the RPC layer, so it
-reaches every transport, and a client discovers it through ordinary reflection
-(`list_protocols`) rather than by calling and reading an error.
+transport. As of **vgi-rpc 0.46.0** identity lives at the RPC layer, and a
+client discovers it through ordinary reflection (`list_protocols`) rather than
+by calling and reading an error. VGI hosts it on HTTP only — the transport that
+authenticates callers (see `build_rpc_server` in `vgi/rpc_server.py`).
 
 ```python
 from vgi.auth import AuthUnavailableError, TokenIdentity
@@ -469,7 +470,10 @@ credentials. Throttle untrusted traffic at the proxy, per client.
 
 Return `None` for "the store answered and this credential is unknown"; raise
 `AuthUnavailableError` for "the answer is not knowable". A caller that
-negative-caches the first must not cache the second. Never return claims — a
+negative-caches the first must not cache the second. Raising the same error
+an authenticator raises is correct here: vgi-rpc translates an
+`AuthUnavailableError` from either identity hook into `identity_unavailable`
+(code `UNAVAILABLE`) and carries its `retry_after` as `RetryInfo`. Never return claims — a
 pass-through claims field would let a worker choose its caller's tenant routing
 and policy branch.
 
@@ -480,6 +484,26 @@ sidecar outage raised as one is read as "not my credential, try the next" and
 ends up a 401 from the end of the chain, restarting every session in the fleet
 over a thirty-second blip.
 
+### Hosting Additional Protocols (`hosted_protocols`)
+
+Every transport (stdio, unix/named pipe, TCP, Iroh, HTTP) builds its `RpcServer`
+through one helper, `build_rpc_server(worker, *, transport, ...)` in
+`vgi/rpc_server.py`. Never call `RpcServer(...)` for a worker anywhere else.
+`tests/test_hosted_protocols.py` enforces this structurally. Only
+`vgi/secret_service.py` and `vgi/transactor/server.py` are exempt, because they
+serve other protocols.
+
+A worker hosts extra vgi-rpc protocols by overriding the classmethod
+`Worker.hosted_protocols() -> Sequence[tuple[type, object]]` (empty by
+default). It is called once per server build. Its pairs are hosted on every
+transport, after `vgi.v2` and before `vgi_rpc.Reflection.v1`, which is now
+hosted on every transport too. You cannot host part of a protocol: the
+protocol is the unit of optionality. Duplicate names, `vgi.v2` itself, and the
+reserved `vgi_rpc.` prefix all fail at startup with an error that names the
+hook. `MetaWorker` hosts its children's lists concatenated. Identity is not
+supplied through this hook. It stays opt-in via `resolve_token`/`mint_grant`
+and is hosted on HTTP only. See `docs/api/worker.md`.
+
 ### Access Log Sampling and Async Emission
 
 `--access-log-sample 0.05` keeps 5% of *successful* calls. Errors are always
 
@@ -19,8 +19,9 @@ require `pip install vgi-python[http]`; JWT authentication additionally requires
 re-exports it — a worker that implements `resolve_token` never has to name a private import path.
 
 As of vgi-rpc 0.46.0 introspection is the `vgi_rpc.Identity.v1` protocol hosted on the RPC server,
-not an HTTP JSON route, so it reaches every transport rather than only HTTP. `TokenIdentity` and
-`TokenResolver` are correspondingly no longer gated on the `[http]` extra.
+not an HTTP JSON route, so clients discover it through reflection. VGI hosts it on HTTP only, the
+transport that authenticates callers: its allowlist names principals, which stdin/stdout, AF_UNIX
+and TCP do not have. `TokenIdentity` and `TokenResolver` are no longer gated on the `[http]` extra.
 
 ## Secret protocol
 
 
@@ -14,10 +14,86 @@ class MyWorker(Worker):
 # vgi-serve my_module:MyWorker --http     # HTTP
 ```
 
+## Hosting additional protocols
+
+A worker can serve other [vgi-rpc](https://vgi-rpc.query.farm) protocols from the same process and
+the same listener as the VGI protocol. Override
+[`Worker.hosted_protocols`][vgi.worker.Worker.hosted_protocols] to return
+`(protocol, implementation)` pairs:
+
+```python
+from collections.abc import Sequence
+from typing import ClassVar, Protocol
+
+from vgi import Worker
+
+
+class Audit(Protocol):
+    protocol_name: ClassVar[str] = "acme.Audit.v1"
+
+    def record(self, event: str) -> int: ...
+
+
+class AuditImpl:
+    def record(self, event: str) -> int:
+        return len(event)
+
+
+class MyWorker(Worker):
+    functions = []
+
+    @classmethod
+    def hosted_protocols(cls) -> Sequence[tuple[type, object]]:
+        return [(Audit, AuditImpl())]
+```
+
+The rules:
+
+- **Every transport hosts the same list.** stdin/stdout, AF_UNIX (or a Windows named pipe), TCP,
+  the Iroh raw upstream and HTTP all build their server through one function,
+  [`build_rpc_server`][vgi.rpc_server.build_rpc_server].
+- **Called once per server.** The hook may read configuration or the environment, but its answer
+  is fixed for the life of the process, so reflection output and protocol hashes stay stable.
+- **The protocol is the unit of optionality.** There is no way to host part of a protocol. Make
+  an optional capability its own protocol, and include it or leave it out.
+- **Names are routing keys.** Each protocol needs a distinct `protocol_name`. A repeated name, the
+  worker's own `vgi.v2`, or the reserved `vgi_rpc.` prefix stops the worker at startup, and the
+  error names `hosted_protocols()`.
+- **`vgi.v2` is unaffected.** vgi-rpc routes each request on its `vgi_rpc.protocol` key and never
+  falls back to the primary protocol. A client that only speaks `vgi.v2`, such as the DuckDB
+  extension, sees exactly the behaviour it saw before.
+
+A `MetaWorker` (`vgi.meta_worker`) hosts the concatenation of its children's lists, in
+child order. Two children that list the same protocol name stop it at startup. Over HTTP it
+hosts Identity for the one child that overrides `resolve_token` or `mint_grant`; two children
+overriding the same hook stop it at startup.
+
+### What each transport hosts
+
+Reflection (`list_protocols`) reports protocols in this order:
+
+| Transport | `vgi.v2` | `hosted_protocols()` | `vgi_rpc.Reflection.v1` | `vgi_rpc.Identity.v1` |
+| --- | --- | --- | --- | --- |
+| stdin/stdout | yes | yes | yes | no |
+| AF_UNIX / named pipe | yes | yes | yes | no |
+| TCP | yes | yes | yes | no |
+| Iroh raw upstream | yes | yes | yes | no |
+| HTTP | yes | yes | unless `--no-describe` | when `resolve_token` or `mint_grant` is overridden |
+
+Identity stays framework-owned. You enable it by overriding
+[`resolve_token`][vgi.worker.Worker.resolve_token] or
+[`mint_grant`][vgi.worker.Worker.mint_grant], never through `hosted_protocols()`. It is hosted
+only on HTTP, which authenticates callers. Its introspection allowlist names principals, and the
+other transports have no principals to check.
+
 ## Worker
 
 ::: vgi.worker
 
+## Server construction
+
+::: vgi.rpc_server
+
 ## Serving
 
 ::: vgi.serve
@@ -34,7 +34,9 @@ classifiers = [
 # The fixture worker also builds statistics fixtures at import time, which
 # needs a DuckDB-compatible engine — vgi[duckdb] keeps the default dev env on
 # stock duckdb (the resolver prefers haybarn whenever it is installed too).
-dependencies = ["vgi-python[test-fixtures-writable]", "vgi-python[duckdb]"]
+# vgi-rpc is named directly because the fixture worker imports its conformance
+# fixtures (vgi_rpc.conformance.secondary, .identity_fixture), new in 0.48.0.
+dependencies = ["vgi-python[test-fixtures-writable]", "vgi-python[duckdb]", "vgi-rpc>=0.48.0"]
 
 [project.scripts]
 vgi-fixture-worker = "vgi._test_fixtures.worker:main"
 
@@ -40,7 +40,7 @@ dependencies = [
     "pyarrow",
     "typer>=0.9",
     "platformdirs",
-    "vgi-rpc>=0.47.2",
+    "vgi-rpc>=0.48.0",
     "httpx2>=2.12.0",
 ]
 
 
@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+#
+# Run vgi-rpc's hosted-protocols conformance group (vgi-rpc-test-hosted)
+# against this repo's fixture workers on all three transports it covers:
+#
+#   stdio  vgi-fixture-worker                       (MetaWorker.serve, pipe)
+#   unix   vgi-fixture-worker --unix <sock>         (the DuckDB launcher path)
+#   http   vgi-fixture-http --identity              (+ the Identity.v1 groups)
+#
+# Every worker must host, in order, vgi.v2 then conformance.Secondary.v1.
+#
+# Usage: scripts/hosted_protocols_conformance.sh [stdio|unix|http ...]
+# Default: all three. Runs from the project env (`uv run --no-sync`), which
+# must have vgi-rpc with the [http,conformance] extras (the dev group does).
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+EXPECT="vgi.v2,conformance.Secondary.v1"
+RUN=(uv run --no-sync)
+BIN="$(dirname "$("${RUN[@]}" python -c 'import sys; print(sys.executable)')")"
+TRANSPORTS=("$@")
+[ ${#TRANSPORTS[@]} -eq 0 ] && TRANSPORTS=(stdio unix http)
+
+# Short scratch dir: AF_UNIX paths are capped at ~104 bytes, and CI temp
+# dirs can be long.
+SCRATCH="$(mktemp -d /tmp/vgihp.XXXXXX)"
+PIDS=()
+cleanup() {
+  for pid in "${PIDS[@]}"; do kill "$pid" 2>/dev/null || true; done
+  rm -rf "$SCRATCH"
+}
+trap cleanup EXIT
+
+wait_for() {  # wait_for <description> <test command...>
+  local what="$1"; shift
+  for _ in $(seq 150); do "$@" && return 0; sleep 0.2; done
+  echo "timed out waiting for $what" >&2
+  return 1
+}
+
+run_stdio() {
+  echo "== hosted-protocols: stdio =="
+  "${RUN[@]}" vgi-rpc-test-hosted --cmd "$BIN/vgi-fixture-worker" --expect "$EXPECT" -- -rs
+}
+
+run_unix() {
+  echo "== hosted-protocols: unix =="
+  local sock="$SCRATCH/w.sock"
+  "$BIN/vgi-fixture-worker" --unix "$sock" --idle-timeout 300 >"$SCRATCH/unix.out" 2>"$SCRATCH/unix.err" &
+  PIDS+=($!)
+  wait_for "unix socket $sock" test -S "$sock" || { cat "$SCRATCH/unix.err" >&2; return 1; }
+  "${RUN[@]}" vgi-rpc-test-hosted --unix "$sock" --expect "$EXPECT" -- -rs
+}
+
+run_http() {
+  echo "== hosted-protocols: http (--identity) =="
+  local port
+  port="$("${RUN[@]}" python -c 'import socket; s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1])')"
+  "$BIN/vgi-fixture-http" --identity --host 127.0.0.1 --port "$port" >"$SCRATCH/http.out" 2>"$SCRATCH/http.err" &
+  PIDS+=($!)
+  wait_for "HTTP worker on :$port" curl -sf -o /dev/null "http://127.0.0.1:$port/health" \
+    || { cat "$SCRATCH/http.err" >&2; return 1; }
+  "${RUN[@]}" vgi-rpc-test-hosted --url "http://127.0.0.1:$port" --expect "$EXPECT" --identity -- -rs
+}
+
+for t in "${TRANSPORTS[@]}"; do
+  case "$t" in
+    stdio) run_stdio ;;
+    unix) run_unix ;;
+    http) run_http ;;
+    *) echo "unknown transport: $t (expected stdio, unix or http)" >&2; exit 2 ;;
+  esac
+done
@@ -0,0 +1,75 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""A worker that hosts two extra protocols through ``Worker.hosted_protocols``.
+
+Run as a script so each transport is exercised through its real entry point:
+
+- no flags: ``Worker.main`` -> ``Worker.run`` (stdin/stdout)
+- ``--unix PATH`` / ``--tcp HOST:PORT``: ``Worker.main``'s launcher paths
+- ``--meta`` (stripped before the rest is parsed): ``MetaWorker.serve``
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+from typing import ClassVar, Protocol
+
+from vgi.worker import Worker
+
+
+class EchoProtocol(Protocol):
+    """First extra protocol."""
+
+    protocol_name: ClassVar[str] = "vgi_test.Echo.v1"
+
+    def echo(self, text: str) -> str:
+        """Return *text*, tagged."""
+        ...
+
+
+class CounterProtocol(Protocol):
+    """Second extra protocol, to pin ordering."""
+
+    protocol_name: ClassVar[str] = "vgi_test.Counter.v1"
+
+    def count(self, text: str) -> int:
+        """Return the length of *text*."""
+        ...
+
+
+class EchoImpl:
+    """Implements `EchoProtocol`."""
+
+    def echo(self, text: str) -> str:
+        """Return *text*, tagged."""
+        return f"echo:{text}"
+
+
+class CounterImpl:
+    """Implements `CounterProtocol`."""
+
+    def count(self, text: str) -> int:
+        """Return the length of *text*."""
+        return len(text)
+
+
+class HostingWorker(Worker):
+    """Hosts `EchoProtocol` then `CounterProtocol` beside ``vgi.v2``."""
+
+    functions = []
+
+    @classmethod
+    def hosted_protocols(cls) -> Sequence[tuple[type, object]]:
+        """Return the two extra protocols, Echo first."""
+        return ((EchoProtocol, EchoImpl()), (CounterProtocol, CounterImpl()))
+
+
+if __name__ == "__main__":
+    if "--meta" in sys.argv:
+        sys.argv.remove("--meta")
+        from vgi.meta_worker import MetaWorker
+
+        MetaWorker.serve(HostingWorker)
+    else:
+        HostingWorker.main()
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@ dependencies = [`
`40`	`40`	`"pyarrow",`
`41`	`41`	`"typer>=0.9",`
`42`	`42`	`"platformdirs",`
`43`		`- "vgi-rpc>=0.47.2",`
	`43`	`+ "vgi-rpc>=0.48.0",`
`44`	`44`	`"httpx2>=2.12.0",`
`45`	`45`	`]`
`46`	`46`