feat(runtime-python): cross-tool bridge — typed returns + q-orca invocation - #13
Merged
Conversation
…cation
Implements the orca side of the cross-tool bridge protocol (docs/cross-tool-invoke-and-returns.md)
in the Python runtime — a classical orca orchestrator can now invoke a q-orca quantum child.
- Parser: ## returns section -> ReturnDef; InvokeDef.returns/shots via inline
(`invoke: QForward input:{...} shots:1024 returns:{prob: prob_bits_0}`) and multi-line forms.
- bridge.py: the q-orca bridge-protocol contract mirrored at version 1.0 — descriptor / invocation /
result envelopes, BridgeError, and dispatch_foreign (invocation on stdin -> result on stdout).
- Runtime: OrcaMachine.register_foreign_runner() + outbound dispatch in start_child_machine
(foreign child -> bridge), binding the child's returns into parent context and firing on_done/on_error.
- Public API: ReturnDef, InvokeDef, and the bridge functions exported from the package.
- 12 tests (parser, protocol/conformance, dispatch over a real subprocess, and the end-to-end
runtime path with a mock foreign quantum child). Full runtime-python suite: 105 passed.
Docs: adds a "Multi-Runtime Adoption" section explaining the protocol is runtime-agnostic
(JSON + process boundary) and what TS/Go/Rust would each need, plus the shared-conformance-suite
rationale. Scoped to the outbound direction (orchestrator -> quantum child); inbound needs a
per-runtime auto-driver for reactive machines.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- dispatch_foreign: surface the foreign runner's stderr in BridgeError messages (both the non-zero-exit and exit-0-but-unusable-output cases). - Document the return-binding precedence: a bound value overwrites the parent field; a return the child did not produce is skipped (soft), leaving the field unchanged; a malformed envelope / bad version is a hard BridgeError. - Test: missing return field leaves the parent field at its default and on_done still drives the machine to final (13 bridge tests; full suite 106 passed). - Docs: add the binding-semantics note to the invoke-returns section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
jascal
added a commit
that referenced
this pull request
May 30, 2026
PyPI 0.1.27 was cut 2026-04-17, before the cross-tool bridge merged (#13), so the published 0.1.27 lacks `register_foreign_runner` / the `bridge` module even though main was still labeled 0.1.27. Bump to 0.1.28 so the bridge is actually released, and re-sync the lagging `__init__.__version__` (was 0.1.26). No code changes — version metadata only. 106 runtime-python tests pass. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the orca side of the cross-tool bridge (design doc
docs/cross-tool-invoke-and-returns.md, merged in #12) in the Python runtime — the first runtime to adopt the protocol. A classical orca orchestrator can now invoke a q-orca quantum child over the bridge.Full
runtime-pythonsuite: 105 passed (12 new), no regressions.What's here
## returnssection →ReturnDef;InvokeDef.returns/shotsvia inline (invoke: QForward input:{…} shots:1024 returns:{prob: prob_bits_0}) and multi-line forms.bridge.py: the q-orcabridge-protocolcontract mirrored at version1.0— descriptor / invocation / result envelopes,BridgeError, anddispatch_foreign(invocation on stdin → result on stdout over a process boundary).OrcaMachine.register_foreign_runner(...)+ outbound dispatch instart_child_machine— a foreign child is dispatched over the bridge, its returns bound into the parent context, andon_done/on_errorfired.ReturnDef,InvokeDef, and the bridge functions exported from the package.tests/test_bridge.py): parser, protocol/conformance, dispatch over a real subprocess, and the end-to-end runtime path (orca Trainer → mock foreign quantum child ⇒prob == 0.73, transitions to final). The mock runner keeps the suite free of a q-orca dependency.Docs
Adds a Multi-Runtime Adoption section: the protocol is runtime-agnostic (JSON + process boundary, no shared AST/FFI), what TS/Go/Rust would each need, the outbound-cheap / inbound-needs-auto-driver asymmetry, and the shared-conformance-suite rationale.
Scope
First cut is the outbound direction (classical orchestrator → quantum child — the motivating QPC workflow). Inbound (orca as the invoked child) is symmetric protocol-wise but needs a per-runtime auto-driver for reactive machines — noted as follow-up.
Pairs with q-orca's
bridge-protocolcapability (implemented + archived on that side).🤖 Generated with Claude Code