Method selectors: method_ref run source + tooling-route method_id, crate routes added

Merged
LC
2mo ago
+1223-103

The addressing-methods Phase 4 leg for pipelex-sdk (design: workspace wip/addressing-methods/design.md), mirroring @pipelex/sdk v0.16.0 — both selectors in one release:

  • method_ref is a typed run source on execute / start / start_and_wait (layer 2 — the RUNNER resolves it: git fetch at the tag, package located by manifest identity; pipelex-api >= 0.21.0). It pairs with nothing: client-side guards mirror the server's 422s against inline mthds_contents and against method_id, while inline+method_id keeps its documented run-history-linkage exception and pipe_code beside method_ref stays legal (it overrides the manifest's main_pipe). Provenance comes back typed: PipelexRunResultStart / PipelexExecuteResult carry method_provenance {address, tag, commit_sha}.
  • validate takes method selectors — method_ref= / method_id= keyword parameters under the strict tooling three-way XOR (exactly one of inline contents / address / id; no linkage exception; mthds_sources legal only beside inline contents; a selector body carries no mthds_contents key at all). A selector-resolution failure is a non-2xx, never an is_valid: false verdict.
  • The crate routes are added: resolve() and codegen() (pipelex_sdk/crate_models.py) with the typed method_id pass-through and the three-way XOR enforced at request construction — closing the JS-parity gap the architecture doc carried for the two routes.
  • build_inputs gains the shared closure envelope (files XOR method_ref) and refuses method_id with a teaching error — the /v1/build/* projections are deliberately excluded from the hosted tooling selector. This SDK never had client-side by-id expansion legs, so the JS release's deletions have no Python counterpart.
  • Fetch-sized budget: a method_ref-carrying build_inputs / resolve / codegen uses an internal 3-minute budget instead of the 30s management one, so a cold-cache server clone is not misreported as an unreachable server. The run routes and validate already ride the 20-min blocking ceiling and need no change (unlike the JS SDK's short start budget).
  • Release prep in the same PR: version 0.8.0, changelog heading dated 2026-08-29, lock refreshed.

Hosted availability of the new selectors on api.pipelex.com follows the platform deploy (pipelex-server#47's dev deploy); tests pin the wire bodies and guards against mocks, per repo style.

Closes L-260828-12fa7b

🤖 Generated with Claude Code

https://claude.ai/code/session_01WoLcQhnFiPgVmDzHqPkRmQ

Summary by cubic

Adds the addressing-methods Phase 4 leg to pipelex-sdk so both method selectors ship in one release, mirroring @pipelex/sdk v0.16.0 (Closes L-260828-12fa7b).

Method selectors

  • method_ref (a published method's address, resolved by the server) becomes a typed run source on execute / start / start_and_wait, pairing with nothing; provenance ({address, tag, commit_sha}) comes back typed on both the durable and blocking run paths.
  • validate takes method_ref= / method_id= keyword selectors under a strict three-way XOR — exactly one of inline contents, address, or id — and a selector-resolution failure is a non-2xx, never an is_valid: false verdict.
  • The crate routes resolve() and codegen() are added with the same XOR enforced at request construction.
  • build_inputs gains the shared closure envelope (files XOR method_ref) and refuses method_id with a teaching error.
  • Empty selectors normalize to absent before the XOR: an empty value alone is zero selectors (teaching error), and beside a real one it is never sent.
  • A method_ref-carrying build_inputs / resolve / codegen gets a 3-minute fetch budget instead of the 30s management one, so a cold-cache server clone is not misreported as unreachable.

Release

  • Version bumps to 0.8.0 with changelog dated 2026-08-29 and refreshed lock; hosted availability follows the platform deploy (pipelex-api >= 0.21.0).