Sync bridge: request_sync/send_sync from plain-def handlers, with the sync-vs-async rationale documented

[acn-ericlaw]

What

1. Sync bridge — PostOffice.request_sync() / send_sync(): a plain def handler
   (which runs on an executor thread with no event loop of its own) can now call sibling
   or remote functions. The bus stamps the host loop into the handler's context at
   dispatch; the bridge submits the same coroutines onto that loop via
   run_coroutine_threadsafe, blocking only the handler's worker thread — never the
   event loop. The caller's trace context is re-established inside the submitted task
   (contextvars do not cross run_coroutine_threadsafe on their own), so the trace
   chain is unbroken end to end. Misuse teaches: calling the bridge on the event loop →
   "await request()/send() instead"; calling it outside a hosted function → points at
   asyncio.run(po.request(...)). Errors stay envelope-shaped (404/408/202), identical
   to the async path.
2. The sync-vs-async handler rationale is now documented (README function contract +
   the registry module docstring): plain def handlers are first-class because Python's
   synchronous ecosystem — requests, NumPy/pandas and most ML inference stacks,
   database drivers — must be wrappable without stalling the event loop that hosts every
   other function; the executor dispatch is the Python analog of the Java engine's
   virtual threads. async def serves asyncio-native I/O and composition. Detection
   stays automatic; a rule of thumb closes the section.
3. Demo: hello.sync.chain (plain def → request_sync → private sibling);
   PostOffice hoisted to the demo's module-level import.

Why

The design review ratified supporting both handler styles, but sync handlers had a
composition gap: PostOffice.request() is a coroutine and an executor thread cannot
await it — so the synchronous half of the ecosystem could wrap libraries yet not call
sibling functions. The bridge closes that gap with the same envelope contract, keeping
the two styles fully symmetric for developers.

Verification

• 54/54 pytest — 4 new pins: sync entry → request_sync → private helper with the full
  trace/cid chain; refused-on-event-loop teaching error; off-host teaching error;
  404/202 envelope shaping + send_sync delivery. ruff clean, basedpyright 0.
• Live wire proof: hello.sync.chain driven over /api/event →
  {'text': 'polyglot!', 'language': 'python'}; re-verified after each follow-up commit.
• Follow-ups from the IDE review folded: _run_sync static, demo import hoist,
  unshadowed test locals.

Co-Authored-By: Claude Code noreply@anthropic.com

🤖 Generated with Claude Code