Release v0.10.0

[lchoquel]

Release v0.10.0

Bumps version from 0.9.0 to 0.10.0. Promotes dev -> main. The number is a minor because [Unreleased] carried breaking changes and the project is pre-1.0. The release exists now because pipelex-starter-python#70 cannot merge without it: it imports write_codegen_tree from pipelex_sdk.codegen_writer and the request envelope from pipelex_sdk.crate_models, and neither exists in the published 0.9.0, where the envelope is still pipelex_sdk.build_models and there is no codegen_writer at all.

Changelog

Added

• run_codegen_check, the offline codegen drift check: pipelex_sdk.codegen_check.run_codegen_check(root=…) verifies a generated tree against its codegen.lock by hashing alone — no engine boot, no network, no API key, and no dependency on pipelex. That last point is the reason it exists: until now the only offline gate a Python project could use was the pipelex CLI, the whole runtime, which is exactly the dependency a hosted-API consumer took this SDK to avoid, so the same integration advice left a TypeScript project with a CI drift gate and a Python one without. It is the counterpart of write_codegen_tree and takes the directory that writer wrote into. The verdict rides a structured CodegenCheckReport — lock_found, is_current, and a drifts list whose categories are missing, modified, hand-edited and orphan, at most one per locked artifact, locked drifts first in ascending path order and then orphans — with the lock header's crate_fingerprint and engine_version surfaced so a caller can ask the one question the offline check cannot, whether the tree still matches what the method resolves to. A lock that cannot be read, or a tree whose paths are not safe and canonical, raises CodegenLockError: the absence of a verdict rather than a drift. It is a mirror of pipelex's own run_codegen_check down to the drift sentences, so a consumer reads the same report from either, and the agreement was established by running both over scenario trees derived from real pipelex codegen types output, one drift class at a time. Two divergences are deliberate and documented: a relaxation inherited from @pipelex/sdk, which accepts a well-formed projection line whose axes are outside this SDK's vocabulary rather than report a tree generated by a newer engine as entirely hand-edited; and a tightening of this reader's own, which refuses a Python artifact declaring a PEP 263 source encoding, because that declaration chooses the codec CPython decodes the file with and so makes the header's comment-prefix gate unsound — a tree can otherwise read as current while importing it executes a statement hidden in the unhashed header. Unlike the JS export, which is pure because it must stay browser-bundleable, this one owns the tree walk and the decoding, so none of that SDK's caller obligations carry over; an unreadable file or directory under the root is therefore a CodegenLockError rather than the reference's bare PermissionError, leaving a CI caller one class to catch.
• pipelex_sdk.codegen_stamp gains the stamp reader the check needs — parse_stamped, compute_content_hash, is_stampable_artifact_path and the ParsedStamp model, beside the ownership predicate and stampable suffixes it already carried — and CodegenLock gains hash_by_path(). A codegen.lock is now read in text mode, so universal-newline translation folds a CRLF away before the TOML parser sees it, as pipelex's reader does; the writer still compares raw bytes, deliberately, because translation there would make one response two different trees across platforms.
• write_codegen_tree, the verbatim codegen tree writer: pipelex_sdk.codegen_writer.write_codegen_tree(report, output_dir=…) writes a valid codegen() response to disk byte for byte — every artifact at its path, the lock as codegen.lock — so a Python project regenerates a tree identical to a local pipelex codegen types run without installing pipelex. Like that command it validates every path before writing, raises CodegenError rather than overwrite a file codegen does not own, rewrites only what changed, and prunes stamped artifacts the previous lock tracked; unlike it, it also checks the paths it is about to prune and requires the response's lock to track exactly its artifacts before the first write; the lock format and path rules it reads are public in pipelex_sdk.codegen_lock and pipelex_sdk.codegen_stamp.
• prepare_inputs takes the method three ways. Beside inline files, it accepts a method_ref address (resolved by the runner) or a stored method_id (resolved by the hosted platform) — exactly one per call, all three server-resolved, nothing expanded client-side. Empty is absent (files=[], a blank method_ref / method_id) but the wrong type is not: none, several, or a non-string selector raises InputPreparationError before any request leaves the process — reading a mistyped selector as absent would let the exclusivity check pass and prepare against the wrong method. A non-string pipe_ref is refused on the same boundary, rather than being absorbed by the pipe defaulting. A method addressed by URL that declares a file input now has an input-preparation path; previously it had none, even though the request beneath accepted the address.
• PipelexValidationReport.default_pipe_ref — the qualified pipe_ref a caller gets by omitting the pipe selector, or null when the closure declares none or several. Optional and read leniently: a runner that predates the field sends nothing, and prepare_inputs falls back to the opaque bundle_blueprint.main_pipe.

Changed

• Breaking: prepare_inputs reads its signature from the input-form descriptor, not the inputs template. It composes one POST /v1/validate with views: ["input_form"] and allow_signatures=True, and walks the standard's InputForm artifact — document / image mark a file position, object recurses through fields, list through item, everything else passes through. Source-compatible for every caller passing files; the SDK no longer calls /v1/build/inputs at runtime. A valid report carrying no descriptor is an error naming the pipelex-api floor, never a silent degrade to "no uploads".
• Breaking: build_inputs and its models are removed. client.build_inputs, BuildInputsRequest, BuildInputsValidReport, BuildInputsResponse, BuildInputsResponseAdapter and InputsTemplateFormat are gone — the route wrapper existed only to be the signature source prepare_inputs read, and nothing calls it now. This is the Python SDK's step of the workspace program retiring /v1/build/*; a caller that still needs a fill-in template projects one from the descriptor with mthds.protocol.inputs_template (render_inputs_template / project_inputs_template, in both the compact and explicit shapes, as JSON or TOML), which is also where InputsTemplateFormat now lives. The wrapper is not a capability lost but one relocated to the standard's own package — and projected client-side, so a method reached by method_ref or method_id gets a template with no server round-trip at all.
• Breaking: the shared crate envelope moved to pipelex_sdk.crate_models. MthdsFileItem, CrateRequestBase and CrateInvalidReport now live beside the routes that use them (/v1/resolve, /v1/codegen) and pipelex_sdk/build_models.py is deleted — a module named for the build routes could not go on holding the envelope after they left. The models themselves are unchanged; update the import path.
• Breaking: a canonical file dict nested inside a Dynamic input is no longer uploaded. Such an input is kind: "unknown" in the descriptor — the standard's escape hatch — and the walk does not enter it. Uploading on the strength of a url key is the value-shape guess this change removes; a caller with a Dynamic input uploads with upload_file first and passes the storage URI, which docs/input-preparation.md has always prescribed.
• prepare_inputs accepts the explicit {concept, content} input envelope, not only compact values, closing a parity gap with the JS SDK. An agent that fills an explicit template — the shape the hosted console and MCP hand out — can now hand it straight back; previously every file-bearing envelope position raised InputPreparationError: Unsupported value at a file input … got dict. The envelope's content is interpreted identically and preserved on output, so the concept annotation rides through to the run.
• The documentation is rewritten around the descriptor. docs/input-preparation.md now describes the three call shapes, the signature call, pipe selection and its manifest-only main_pipe gap, the envelope, and why the template was the wrong signature source; docs/architecture.md follows the removal. It also catches up with v0.9.0, which shipped output_form and the mthds 0.13.0 bump without touching the docs: the views list is no longer described as having one token, the report's typed fields now include output_form and default_pipe_ref, and the pipe I/O contracts no longer claim an output carries no schema — 0.13.0 made json_schema required there, reversing the reasoning the doc still quoted.
• Requires mthds 0.14.0 (breaking). The pin moves from 0.13.0. Nothing in this client changed with it: the release's substantive cut is MTHDS_STANDARD_VERSION going from 1.0.0 to 2.0.0, which this SDK never reads — it stamps no crates and ships no manifest — and the new is_mthds_version_satisfied helper and the parse_constraint whitespace fix sit in mthds.package.manifest.schema, which nothing here imports. PROTOCOL_VERSION stays at 0.6.0, so the routes and the wire contract are untouched. The move still matters to anyone installing this package: pipelex pins mthds exactly too and has already moved to 0.14.0, so two exact pins on different versions made the pair unresolvable — this is what lets pipelex and pipelex-sdk co-install again.

Security

• An optional nested file field is now uploaded. The required-only inputs template never rendered one, so its file position was invisible and the caller's local path travelled to the runner as a literal string. The descriptor states required: false and the walk enters it.
• A text field merely named url is no longer read from disk. The template marked a file position by rendering a url-bearing dict — a side effect of the field's name, not of its concept — so a path-shaped text value was uploaded. kind: "text" ends that.

Closes L-260913-4d710c

🤖 Generated with Claude Code

---

Summary by cubic

Releases v0.10.0, bumping pipelex-sdk from 0.9.0 to 0.10.0 and promoting dev to main. The minor bump carries breaking changes to prepare_inputs, new offline codegen tooling, and a mthds pin move; it is needed so pipelex-starter-python#70 can import write_codegen_tree and the crate envelope, neither of which exists in 0.9.0.

Breaking changes

• prepare_inputs now reads the target pipe's signature from the input-form descriptor and no longer calls /v1/build/inputs at runtime.
• build_inputs and its models are removed, and the crate envelope moves to pipelex_sdk.crate_models; update the import path.
• A nested file dict inside a Dynamic input is no longer uploaded — upload with upload_file first.
• mthds moves from 0.13.0 to 0.14.0 so pipelex and pipelex-sdk can co-install; the wire contract is unchanged.

New features

• prepare_inputs takes the method three ways — inline files, method_ref, or stored method_id — and accepts the explicit {concept, content} envelope.
• write_codegen_tree writes a codegen() response to disk byte for byte, so a Python project generates its typed tree without installing pipelex.
• run_codegen_check verifies a generated tree against its codegen.lock by hashing alone — no engine boot, no network, no API key.
• Optional nested file fields are now uploaded, and a text field merely named url is no longer read from disk.
• PipelexValidationReport gains default_pipe_ref, and the input-preparation and architecture docs are rewritten around the descriptor.

^{Written for commit f3401ee. Summary will update on new commits.}