Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature: round-trip every projected template through the input shaper at corpus-generation time (#1173)
Louis Choquelcb53920d7fda
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 22b1a58bc..d870e7161 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,7 @@### Added- **`pipelex-dev generate-projection-corpus`**: The generator of the shared fixture corpus that pins the two client-side inputs-template projections — the TypeScript one in `mthds` and its Python twin — against each other. Each client SDK now renders a pipe's fill-in template from the input-form descriptor it already has instead of asking a server for one, so the two renderings have to agree exactly, TOML `# concept:` comment lines included. The command pairs each pipe's descriptor with the expected template in both shapes (compact and explicit) and both formats (JSON and TOML), and records where that expectation deliberately differs from this engine's own inputs-template renderer: the expectation is authored from a reference projection that walks the descriptor, where the engine reflects the runtime content classes. Each class of difference is declared rather than discovered — an undeclared one fails the run, and so does a declared one that no longer occurs, so an engine fix retires its entry deliberately. A new corpus bundle covers what the existing probe bundles did not: a text field merely named `url` beside a real file position, optional file fields nested inside a structure, and both a fixed `[N]` and a variable `[]` slot over a structured concept. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).+- **The projection corpus round-trips every template it pins through the input shaper**: `pipelex-dev generate-projection-corpus` now hands each projected template straight back to the runtime — both shapes, assembled exactly as an entry-pipe run assembles a caller's inputs — because a fill-in template exists to be filled in and run, and nothing checked that before. Twice the corpus pinned slots the runtime rejects outright and a human review round caught it rather than the capture; the second time the divergence gate absorbed the broken sites into a declared class and exited zero, since "differs from the engine" and "the engine refuses this value" are different questions. The verdict follows the same declared-never-discovered discipline as the divergence record, through an `EXPECTED_UNSHAPEABLE` registry mapping a pipe and shape to the item tracking the gap: an undeclared refusal fails the command naming the pipe, shape and error, a declared entry whose template has started shaping fails it too so a fix retires its declaration deliberately, and a declared one is stated in the manifest as an `unshapeable` entry carrying the contract-stable error class and its ledger item — so a known-open gap is recorded rather than blocking the capture. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).- **Include a method by address — fetch-on-miss**: a bundle referencing another method by address (`github.com/...->domain.pipe`) that misses the installed methods now fetches the package by reference — honoring an `@<tag>` pin, through the same grammar, bounds, and tags-only rules as a direct fetch, with the same hosted-parity warning for Python structure classes locally and a hard refusal on sandbox-hosted deployments — installs it into `~/.mthds/methods/` (atomic staging write, `.git/` stripped, fetch provenance recorded beside the manifest in a `.provenance.json` sidecar: address, tag, and the resolved commit SHA), and loads it so resolution proceeds. Once installed, the method is reused and the network is never touched again — including for a reference pinning a different tag, which warns and uses the installed copy. The former silent-miss warning in the library manager is now a real diagnostic: a miss that cannot be bridged (fetch disabled via the new `[interpreter.methods] fetch_on_miss` config or the `PIPELEX_METHODS_FETCH_ON_MISS` environment variable, an unfetchable address, or a failed fetch) raises an error naming the address and the remedy, never a silent pass. The install target is guarded by identity: two packages sharing a bare directory name but coming from different addresses collide with a loud error naming both addresses (never a silent load of the wrong package, never an overwrite), a concurrent install of the same package is tolerated (each attempt stages under a unique dot-prefixed directory, and losing the final rename race to a matching occupant uses the winner's copy), and a fetched package containing a symlink is refused outright, since a link's target would bypass the content scans. Installed-method lookup by full address is now case-insensitive, matching GitHub's owner/repository semantics and the fetch path's manifest-identity matching, and discovery skips dot-prefixed directories. See [Packages → Include by Address](building-methods/packages.md) and [Methods Configuration](configuration/config-practical/methods-config.md).### Changeddiff --git a/docs/contribute/generate-projection-corpus.md b/docs/contribute/generate-projection-corpus.mdindex 480e19155..ad50cf5b1 100644--- a/docs/contribute/generate-projection-corpus.md+++ b/docs/contribute/generate-projection-corpus.md@@ -18,7 +18,7 @@ Bundle order is part of the capture: it fixes the key order of every emitted map- `input_form.json` and `pipe_io_contracts.json` — the descriptor and contract capture, keyed by namespaced `pipe_ref`. Byte for byte what `trace-input-semantics` dumps at hop 5, so migrating the existing committed copies to this command is a no-op diff.- `inputs_template/<pipe_ref>.<shape>.<format>` — the **expected** template each projection must produce, in both shapes (`compact`, `explicit`) and both formats (`json`, `toml`).-- `inputs_template/manifest.json` — what the corpus covers (bundles, pipes, shapes, formats) plus the declared divergences, each with worked sites a consumer repo can check with no engine present.+- `inputs_template/manifest.json` — what the corpus covers (bundles, pipes, shapes, formats), the declared divergences, each with worked sites a consumer repo can check with no engine present, and the templates the input shaper refuses to take back.- `engine/` — the engine's own renderings of the same pipes. **Not committed.** It is what the divergence record is measured against, not part of the contract.A pipe declaring no inputs is captured from the projection alone: an empty input form is a valid form and the projection renders it as `{}` (an empty TOML document), but the engine's renderer refuses one with `NoInputsRequiredError`, so that pipe gets its templates and no `engine/` file, and nothing is compared for it.@@ -49,6 +49,23 @@ The walk visits both sides' keys, so a field the projection *stopped* renderingWhat it still cannot separate is a *wrong value at a site that already carries a class*: a projection inventing a field reads as `optional-field-included`, and a garbled placeholder at a url-named text field reads as `text-named-url`. Telling those apart needs each node's kind and presence carried through the whole walk, which is a redesign rather than a fix, and the two shipped projections are pinned against the committed bytes anyway.+## The shaping round-trip++A fill-in template exists to be filled in and handed back to the runtime, so surviving `InputShaper.shape` is part of what the corpus asserts — and until this gate existed, nothing checked it. Twice the corpus pinned slots the runtime rejects outright, and both times a human review round caught it rather than the capture; the second time the divergence gate absorbed the broken sites into a declared class and exited 0, because "differs from the engine" and "the engine refuses this value" are not the same question.++So every projected template goes straight back through the shaper, assembled exactly as an entry-pipe run assembles it: the pipe's own declared inputs as the signature, its domain as the search scope. Both shapes, both pipes' worth — the explicit template is as much a runnable scaffold as the compact one. The round-trip is offline: the file-ish arms wrap a mock URL without fetching it.++The verdict follows the same declared-never-discovered discipline as the divergence record, through the `EXPECTED_UNSHAPEABLE` registry in `generate_projection_corpus_cmd.py`, which maps a `(pipe_ref, shape)` to the ledger item tracking the gap:++- A refusal **not** in the registry fails the command, naming the pipe, the shape, the error class and the error's first line. This is the mechanism that would have caught both prior escapes at capture time.+- A registry entry whose template **now shapes** fails the command too — *delete the entry, the gap closed* — so a fix retires its declaration deliberately rather than leaving the manifest claiming a defect that no longer exists.+- A registry entry this capture **never walked at all** fails it as well, and is worded apart from the one above because the two call for opposite actions: a key addressing no pipe and shape the run produced is a renamed pipe or a run over a subset of the bundles, so it wants re-keying or the full bundle list — deleting it would drop a gap that is still open.+- A declared entry is recorded in the manifest as an `unshapeable` entry (`pipe_ref`, `shape`, `error_type`, `ledger_item`) and printed, and generation proceeds. A known-open gap therefore never blocks the capture; it is simply stated.++The manifest holds the error's **class name**, never its message. The class name is contract-stable — the error-identity snapshot makes a rename a reviewable diff — while the message is wording that would churn these committed bytes across pydantic versions, so it goes to the console and to the refusal only. Passing verdicts are printed as a count, never committed: a template the shaper takes back is the state every entry is working towards, not a fact worth pinning.++The entries declared today are all one descriptor gap — a nested list inside a structure — which takes both shapes of the two probe pipes that reach it. Closing it deletes the four entries; the lapse rule fails the command until somebody does.+## The bundles`tests/data/input_semantics/` holds the corpus bundles. `probe_bundle.mthds` exercises every construct the language accepts and `hinted_bundle.mthds` the intent hints; `scaffold_bundle.mthds` was added for this corpus and covers what the other two do not — a text field merely named `url` beside a real file position, an optional nested structure, optional `native.Image` and `native.Document` fields inside a structure, and both a fixed `[N]` and a variable `[]` slot over a structured concept.@@ -57,4 +74,4 @@ What it still cannot separate is a *wrong value at a site that already carries aRerun and re-commit the capture in both consumer repos whenever the descriptor derivation changes, a `kind` is added to the standard, or a bundle changes. The per-repo harness asserts that the set of kinds appearing across the corpus **equals** the closed `FieldKind` vocabulary, so a kind added without a fixture fails by name rather than passing silently.-`tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py` keeps the capture complete and byte-stable, `test_projection_divergence_gate.py` states the gate's guarantee as the regressions it must not absorb, and `test_projection_reference.py` pins the projection's rules one at a time, so a rule that changed fails by name instead of as a wall of differing bytes.+`tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py` keeps the capture complete and byte-stable and measures the registry against the real round-trip, `test_projection_divergence_gate.py` and `test_projection_shaping_gate.py` state each gate's guarantee as the regressions it must not absorb, and `test_projection_reference.py` pins the projection's rules one at a time, so a rule that changed fails by name instead of as a wall of differing bytes.diff --git a/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py b/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.pyindex 0e5ba9f50..ce2b7045e 100644--- a/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py+++ b/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py@@ -20,14 +20,20 @@ What this command writes into the output directory:The divergences are declared here, not discovered: a class that stops occurring fails this commandrather than quietly disappearing, so an engine fix retires its entry deliberately.++Every template is also handed straight back to the runtime — `InputShaper.shape`, assembled the way+an entry-pipe run assembles it — because a fill-in template exists to be filled in and run. A refusal+no `EXPECTED_UNSHAPEABLE` entry declares fails this command too, on the same declared-never-discovered+discipline: the corpus must not pin bytes the engine rejects."""import asyncioimport jsonimport shutilimport sys+from copy import deepcopyfrom pathlib import Path-from typing import Any, cast+from typing import TYPE_CHECKING, Any, castfrom pydantic import BaseModel, ConfigDict, Field@@ -42,10 +48,12 @@ from pipelex.cli.dev_cli.commands.projection_reference import (from pipelex.cli.error_handlers import ErrorContextfrom pipelex.interpreter_hub import (clear_current_library,+ get_concept_library,get_current_library_id_or_none,get_library_manager,set_current_library,)+from pipelex.kernel.memory_ops import shape_inputsfrom pipelex.pipe_machinery.pipe_abstract import PipeAbstractfrom pipelex.pipe_machinery.rendering.input_renderer import (build_inputs_template,@@ -61,6 +69,9 @@ from pipelex.pipeline.validate_bundle import validate_bundlefrom pipelex.runtime_hub import get_consolefrom pipelex.tools.typing.pydantic_utils import empty_list_factory_of+if TYPE_CHECKING:+ from mthds.protocol.pipeline_inputs import PipelineInputs+INPUT_FORM_FILE_NAME = "input_form.json"PIPE_IO_CONTRACTS_FILE_NAME = "pipe_io_contracts.json"TEMPLATES_DIR_NAME = "inputs_template"@@ -113,6 +124,22 @@ DIVERGENCE_ITEMS: dict[str, str] = {}+# The templates the input shaper refuses today, each against the workspace-ledger item tracking the+# gap that makes it refuse. Declared here for the same reason the divergences are: a refusal with no+# entry fails the capture rather than reaching two consumer repos as contract bytes, and an entry+# whose template has started shaping fails it too — so closing the gap retires its declaration+# deliberately instead of leaving the manifest claiming a defect that no longer exists.+#+# Every entry below is the one nested-list descriptor gap (`matrix` in `Widget`), which takes both+# shapes of both pipes that reach it. Its fix deletes these four entries and regenerates.+EXPECTED_UNSHAPEABLE: dict[tuple[str, str], str] = {+ ("input_semantics_probe.probe_markers", COMPACT_SHAPE): "L-260830-191719",+ ("input_semantics_probe.probe_markers", EXPLICIT_SHAPE): "L-260830-191719",+ ("input_semantics_probe.probe_single", COMPACT_SHAPE): "L-260830-191719",+ ("input_semantics_probe.probe_single", EXPLICIT_SHAPE): "L-260830-191719",+}++class DivergenceExample(BaseModel):"""One worked site of a declared divergence, checkable in a consumer repo with no engine present.@@ -147,6 +174,24 @@ class DeclaredDivergence(BaseModel):examples: list[DivergenceExample] = Field(default_factory=empty_list_factory_of(DivergenceExample))+class UnshapeableEntry(BaseModel):+ """One template this capture pins that the input shaper refuses to take back.++ A fact of the capture, stated so a consumer repo reads it off the manifest rather than+ discovering it by running the template. `error_type` is the error's class name, which is+ contract-stable — the error-identity snapshot makes a rename a reviewable diff — while the+ message is wording that would churn these committed bytes across pydantic versions, so it stays+ on the console. `ledger_item` names the workspace-ledger item whose fix retires this entry.+ """++ model_config = ConfigDict(extra="forbid")++ pipe_ref: str+ shape: str+ error_type: str+ ledger_item: str++class CorpusManifest(BaseModel):"""The corpus's own description of what it covers and where it departs from the engine."""@@ -157,6 +202,7 @@ class CorpusManifest(BaseModel):shapes: list[str] = Field(default_factory=list)formats: list[str] = Field(default_factory=list)divergences: list[DeclaredDivergence] = Field(default_factory=empty_list_factory_of(DeclaredDivergence))+ unshapeable: list[UnshapeableEntry] = Field(default_factory=empty_list_factory_of(UnshapeableEntry))def _write_json(*, path: Path, payload: Any) -> None:@@ -331,15 +377,121 @@ class DivergenceCollector:]-def _render_projection(*, descriptor: PipeInputFormDescriptor, explicit: bool) -> tuple[str, str]:- """The projected template for one pipe and shape, as the JSON and TOML bytes the corpus holds."""+class ShapingGate:+ """Hands every projected template back to the runtime and refuses one nobody declared unshapeable.++ A template is pinned to be filled in and run, so surviving `InputShaper.shape` is part of what the+ corpus asserts — and nothing else checks it. Twice the corpus committed bytes the runtime rejects+ outright, and both times a human review round caught it rather than the capture; the second time+ the divergence gate absorbed the broken sites into a declared class and exited 0, because a+ difference from the engine and a value the engine refuses are not the same question.++ The verdicts are collected against an injected registry so the whole decision can be put to cases+ no corpus bundle produces. The rule is symmetric, exactly as `DivergenceCollector.declared()` is:+ an undeclared refusal fails the capture, and a declaration whose template has started shaping+ fails it too.+ """++ def __init__(self, *, registry: dict[tuple[str, str], str] | None = None) -> None:+ self.registry = EXPECTED_UNSHAPEABLE if registry is None else registry+ self.verdicts: dict[tuple[str, str], Exception | None] = {}++ @property+ def failures(self) -> dict[tuple[str, str], Exception]:+ """The refusals, by the `(pipe_ref, shape)` key the registry is written in."""+ return {key: error for key, error in self.verdicts.items() if error is not None}++ @property+ def passing_count(self) -> int:+ """How many templates went back through the shaper cleanly — printed, never committed."""+ return len(self.verdicts) - len(self.failures)++ def record(self, *, pipe_ref: str, shape: str, error: Exception | None) -> None:+ """Record one round-trip's verdict, `None` being the template the shaper took back."""+ self.verdicts[pipe_ref, shape] = error++ def round_trip(self, *, pipe: PipeAbstract, shape: str, template: dict[str, Any]) -> None:+ """Shape one projected template the way an entry-pipe run shapes a caller's inputs.++ The same assembly as `execution_seams`: the pipe's own declared inputs as the signature and+ its domain as the search scope. Offline — the file-ish arms wrap a URL without fetching it —+ and the template is copied first, so nothing the shaper does can reach the bytes just written.+ """+ try:+ shape_inputs(+ inputs=cast("PipelineInputs", deepcopy(template)),+ concept_provider=get_concept_library(),+ input_specs=pipe.inputs,+ search_scope=pipe.domain_code,+ )+ except Exception as exc: # ruff: ignore[blind-except]+ # (2) Unbounded surface: the shaper's explicit arm hands values straight to pydantic on+ # a generated structure class, so a raw ValidationError escapes untyped today+ # (L-260831-1e1a71). Enumerating the surface would make this gate blind to exactly the+ # refusals it exists to catch — any refusal at all is the verdict it records.+ self.record(pipe_ref=pipe.pipe_ref, shape=shape, error=exc)+ else:+ self.record(pipe_ref=pipe.pipe_ref, shape=shape, error=None)++ def declared(self) -> list[UnshapeableEntry]:+ """The unshapeable record, refusing an undeclared refusal and a declaration that has lapsed."""+ failures = self.failures+ undeclared = sorted(key for key in failures if key not in self.registry)+ if undeclared:+ # Parenthesised, not bracketed: this message is printed through the Rich console, which+ # reads a `[compact]` as markup and eats it — leaving two shapes of one pipe as two+ # identical lines, each missing the half of the address that says which one failed.+ listed = "\n ".join(+ f"{pipe_ref} ({shape}): {type(failures[pipe_ref, shape]).__name__}: {str(failures[pipe_ref, shape]).splitlines()[0]}"+ for pipe_ref, shape in undeclared+ )+ msg = (+ "The input shaper refuses template(s) with no EXPECTED_UNSHAPEABLE entry declaring them — "+ f"fix the projection, or declare the gap and name the item tracking it:\n {listed}"+ )+ raise ValueError(msg)+ # Two ways a declaration can go stale, and they call for opposite actions, so they are worded+ # apart rather than lumped into one "delete the entry". A template that started shaping is a+ # closed gap; one this capture never walked at all is a key that no longer addresses anything+ # — a renamed pipe, or a run over a subset of the bundles — and deleting it there would drop+ # a gap that is still open.+ shaping_now = sorted(key for key in self.registry if key in self.verdicts and key not in failures)+ if shaping_now:+ msg = f"Declared unshapeable template(s) {shaping_now} now shape — delete the EXPECTED_UNSHAPEABLE entry, the gap closed."+ raise ValueError(msg)+ unwalked = sorted(key for key in self.registry if key not in self.verdicts)+ if unwalked:+ msg = (+ f"Declared unshapeable template(s) {unwalked} were never walked by this capture — "+ "the key names no pipe and shape this run produced. Re-key the EXPECTED_UNSHAPEABLE entry "+ "if the pipe was renamed, or pass every bundle the corpus is generated from; deleting it "+ "would drop a gap that is still open."+ )+ raise ValueError(msg)+ return [+ UnshapeableEntry(+ pipe_ref=pipe_ref,+ shape=shape,+ error_type=type(failures[pipe_ref, shape]).__name__,+ ledger_item=self.registry[pipe_ref, shape],+ )+ for pipe_ref, shape in sorted(failures)+ ]+++def _render_projection(*, descriptor: PipeInputFormDescriptor, explicit: bool) -> tuple[dict[str, Any], str, str]:+ """The projected template for one pipe and shape, with the JSON and TOML bytes the corpus holds.++ The template itself is returned beside its renderings because both gates read it: the divergence+ collector compares it against the engine's, and the shaping gate hands it back to the runtime.+ """template = project_inputs_template(descriptor=descriptor, explicit=explicit)json_text = json.dumps(template, indent=2, ensure_ascii=False)if explicit:toml_text = serialize_inputs_template_to_toml(template)else:toml_text = serialize_inputs_template_to_toml(template, light=True, concept_comments=project_concept_comments(descriptor=descriptor))- return json_text, toml_text+ return template, json_text, toml_textdef _capture_pipe(@@ -348,6 +500,7 @@ def _capture_pipe(descriptor: PipeInputFormDescriptor,output_dir: Path,collector: DivergenceCollector,+ shaping_gate: ShapingGate,) -> None:"""Write one pipe's four projected renderings, the engine's four, and bucket the differences."""templates_dir = output_dir / TEMPLATES_DIR_NAME@@ -355,9 +508,12 @@ def _capture_pipe(collector.register_fixed_counts(pipe_ref=pipe.pipe_ref, descriptor=descriptor)for explicit in (False, True):shape = EXPLICIT_SHAPE if explicit else COMPACT_SHAPE- json_text, toml_text = _render_projection(descriptor=descriptor, explicit=explicit)+ template, json_text, toml_text = _render_projection(descriptor=descriptor, explicit=explicit)_write_text(path=templates_dir / f"{pipe.pipe_ref}.{shape}.json", content=json_text)_write_text(path=templates_dir / f"{pipe.pipe_ref}.{shape}.toml", content=toml_text)+ # Before the empty-form skip below: an empty descriptor projects to `{}`, which the shaper+ # takes back trivially, and a verdict recorded there is what keeps the pipe in the walk.+ shaping_gate.round_trip(pipe=pipe, shape=shape, template=template)if not descriptor.fields:# An empty input form is a valid form — `PipeInputFormDescriptor` says so — and the# projection renders it as `{}`. Only the engine's own renderer refuses one, raising@@ -368,7 +524,7 @@ def _capture_pipe(_write_text(path=engine_dir / f"{pipe.pipe_ref}.{shape}.toml", content=render_inputs_toml(pipe, explicit=explicit))collector.compare(engine_value=build_inputs_template(pipe, explicit=explicit),- projected_value=project_inputs_template(descriptor=descriptor, explicit=explicit),+ projected_value=template,path=[pipe.pipe_ref, shape],)@@ -386,7 +542,9 @@ async def generate_projection_corpus(*, bundle_paths: list[Path], output_dir: PaRaises:ValidateBundleError: When a bundle is invalid — the corpus requires valid bundles.- ValueError: When a difference from the engine is undeclared, or a declared one has lapsed.+ ValueError: When a difference from the engine is undeclared, or a declared one has lapsed;+ likewise when the input shaper refuses an undeclared template, or takes back one the+ registry still declares unshapeable."""mthds_contents = [bundle_path.read_text(encoding="utf-8") for bundle_path in bundle_paths]mthds_sources = [str(bundle_path) for bundle_path in bundle_paths]@@ -402,6 +560,7 @@ async def generate_projection_corpus(*, bundle_paths: list[Path], output_dir: Paprev_library_id = get_current_library_id_or_none()validation_library_id: str | None = Nonecollector = DivergenceCollector()+ shaping_gate = ShapingGate()try:result = await validate_bundle(mthds_contents=mthds_contents, mthds_sources=mthds_sources)validation_library_id = get_current_library_id_or_none()@@ -417,7 +576,13 @@ async def generate_projection_corpus(*, bundle_paths: list[Path], output_dir: Papayload={pipe_ref: contract.model_dump(mode="json") for pipe_ref, contract in io_contracts.items()},)for pipe in result.pipes:- _capture_pipe(pipe=pipe, descriptor=input_form[pipe.pipe_ref], output_dir=output_dir, collector=collector)+ _capture_pipe(+ pipe=pipe,+ descriptor=input_form[pipe.pipe_ref],+ output_dir=output_dir,+ collector=collector,+ shaping_gate=shaping_gate,+ )finally:if validation_library_id is not None and validation_library_id != prev_library_id:if prev_library_id is not None:@@ -437,6 +602,7 @@ async def generate_projection_corpus(*, bundle_paths: list[Path], output_dir: Pashapes=[COMPACT_SHAPE, EXPLICIT_SHAPE],formats=["json", "toml"],divergences=collector.declared(),+ unshapeable=shaping_gate.declared(),)_write_json(path=output_dir / TEMPLATES_DIR_NAME / MANIFEST_FILE_NAME, payload=manifest.model_dump(mode="json"))return manifest@@ -457,7 +623,7 @@ def generate_projection_corpus_cmd(*, bundle_paths: list[Path], output_dir: Pathconsole.print(f"[red]Bundle validation failed — the corpus requires valid bundles:[/red]\n{exc}")sys.exit(1)except ValueError as exc:- console.print(f"[red]Divergence record is out of date:[/red]\n{exc}")+ console.print(f"[red]The corpus's own record is out of date:[/red]\n{exc}")sys.exit(1)except PipelexError as exc:console.print(f"[red]Corpus generation failed:[/red]\n{exc}")@@ -469,4 +635,11 @@ def generate_projection_corpus_cmd(*, bundle_paths: list[Path], output_dir: Pathconsole.print(f" pipes: {len(manifest.pipes)}, each in {len(manifest.shapes)} shapes × {len(manifest.formats)} formats")for divergence in manifest.divergences:console.print(f" divergence {divergence.divergence_id}: {divergence.occurrences} site(s)")+ # The passing verdicts are a count rather than a list: the corpus is almost entirely passing+ # verdicts, and a template the shaper takes back is the state every entry below is working towards.+ round_trips = len(manifest.pipes) * len(manifest.shapes)+ console.print(f" round-tripped through the input shaper: {round_trips - len(manifest.unshapeable)}/{round_trips} shape cleanly")+ for entry in manifest.unshapeable:+ # Parenthesised, not bracketed: the console renders Rich markup, which eats a `[compact]`.+ console.print(f" unshapeable {entry.pipe_ref} ({entry.shape}): {entry.error_type} — tracked by {entry.ledger_item}")console.print(f" the engine's own renderings are under {ENGINE_DIR_NAME}/ — for review, not for committing")diff --git a/tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py b/tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.pyindex d412c0151..fc39e5c5a 100644--- a/tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py+++ b/tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py@@ -13,10 +13,14 @@ that corpus trustworthy, and both are checked here against the corpus bundles th- **A pipe with no inputs is captured from the projection alone.** An empty input form is a validform, but the engine's own renderer refuses one, so the capture takes the projected half and skipsthe comparison. No corpus bundle declares such a pipe, so the case is put to the generator here.--The gate that measures the divergences is checked at the collector itself, in-`test_projection_divergence_gate.py`: the corpus is exactly the case where the projection is right,-so nothing here can state what happens when it is wrong.+- **Every template the shaper refuses is exactly one the registry declares.** The templates are+ pinned to be filled in and handed back to the runtime, so the capture round-trips each one through+ `InputShaper.shape`. This is where that round-trip actually runs, against real descriptors and the+ real concept library, and states that its verdicts meet `EXPECTED_UNSHAPEABLE` on the nose.++The two gates that measure the capture are checked at their own collectors, in+`test_projection_divergence_gate.py` and `test_projection_shaping_gate.py`: the corpus is exactly the+case where the projection is right, so nothing here can state what happens when it is wrong."""from __future__ import annotations@@ -28,6 +32,7 @@ import pytestfrom pipelex.cli.dev_cli.commands.generate_projection_corpus_cmd import (ENGINE_DIR_NAME,+ EXPECTED_UNSHAPEABLE,INPUT_FORM_FILE_NAME,MANIFEST_FILE_NAME,PIPE_IO_CONTRACTS_FILE_NAME,@@ -101,6 +106,26 @@ class TestGenerateProjectionCorpus:# The manifest round-trips: it is what the consumer repos parse.assert CorpusManifest.model_validate_json((template_dir / MANIFEST_FILE_NAME).read_text(encoding="utf-8")) == manifest+ async def test_every_unshapeable_template_is_one_the_registry_declares(self, tmp_path: Path) -> None:+ """The round-trip runs for real here, so the registry is measured rather than restated."""+ manifest = await generate_projection_corpus(bundle_paths=CORPUS_BUNDLES, output_dir=tmp_path)++ # Exactly the declared set, in both directions: an undeclared refusal fails the capture, and+ # a declaration whose gap closed fails it too. Stating it here is what makes the registry a+ # measurement of the corpus rather than a list somebody keeps in their head.+ assert {(entry.pipe_ref, entry.shape): entry.ledger_item for entry in manifest.unshapeable} == EXPECTED_UNSHAPEABLE++ for entry in manifest.unshapeable:+ assert entry.pipe_ref in manifest.pipes+ assert entry.shape in manifest.shapes+ # The error class is contract-stable and belongs in the committed bytes; which class it+ # is today is not asserted, because typing the explicit arm's escaped pydantic error+ # (L-260831-1e1a71) will change it without changing anything this corpus pins.+ assert entry.error_type++ # The gap is a descriptor one, so it takes both shapes of the pipes it touches.+ assert {entry.shape for entry in manifest.unshapeable} == set(manifest.shapes)+async def test_a_rerun_writes_the_same_bytes(self, tmp_path: Path) -> None:"""The corpus is committed, so the capture has to be a function of the bundles alone."""first_dir = tmp_path / "first"diff --git a/tests/unit/pipelex/cli/dev_cli/test_projection_shaping_gate.py b/tests/unit/pipelex/cli/dev_cli/test_projection_shaping_gate.pynew file mode 100644index 000000000..0d0b39803--- /dev/null+++ b/tests/unit/pipelex/cli/dev_cli/test_projection_shaping_gate.py@@ -0,0 +1,169 @@+"""The corpus generator refuses a template the input shaper cannot take back.++A fill-in template exists to be filled in and handed to the runtime, so every slot it pins must+survive `InputShaper.shape`. Twice the corpus committed bytes the runtime rejects outright, and both+times a human review round caught it rather than the capture — the second time the divergence gate+absorbed the broken sites into a declared class and exited 0. This states the gate that catches the+next one, and it follows the declared-never-discovered discipline the divergence record already has:+an unshapeable template no registry entry declares refuses the capture, and a declared entry that has+started shaping refuses it too, so a fix retires its declaration deliberately rather than leaving the+manifest claiming a gap that closed.++The round-trip itself — the shaper actually running against the corpus bundles — is stated in+`test_generate_projection_corpus.py`. The verdicts here are injected, which is what lets the decision+logic be put to the cases no corpus bundle produces: the corpus is exactly where every template is+either declared or shapes cleanly.+"""++from __future__ import annotations++from io import StringIO+from typing import cast++import pytest+from rich.console import Console++from pipelex.cli.dev_cli.commands.generate_projection_corpus_cmd import (+ COMPACT_SHAPE,+ EXPLICIT_SHAPE,+ ShapingGate,+)+from pipelex.core.memory.exceptions import WrongScalarKindError++GAP_ITEM = "L-260830-191719"+DECLARED_PIPE = "probe.probe_single"+CLEAN_PIPE = "probe.probe_native_inputs"+++def _shaping_error(*, variable_name: str) -> WrongScalarKindError:+ """A refusal of the shape the corpus's own escapes took: a bare value the declared concept rejects."""+ return WrongScalarKindError.make(+ variable_name=variable_name,+ declared_concept_ref="probe.Widget",+ expected_kind="an object",+ provided_description="a string",+ expected_shape="{...}",+ )+++class TestTheShapingGateRefusesWhatTheRuntimeWouldReject:+ def test_an_undeclared_unshapeable_template_refuses_the_capture(self) -> None:+ """The mechanism that would have caught both prior escapes at generation time."""+ gate = ShapingGate(registry={})++ gate.record(pipe_ref=CLEAN_PIPE, shape=COMPACT_SHAPE, error=_shaping_error(variable_name="icon"))++ with pytest.raises(ValueError, match="no EXPECTED_UNSHAPEABLE entry") as refusal:+ gate.declared()+ # The refusal names the pipe, the shape and the error class: enough to go straight to the site.+ assert CLEAN_PIPE in str(refusal.value)+ assert COMPACT_SHAPE in str(refusal.value)+ assert "WrongScalarKindError" in str(refusal.value)++ def test_a_failure_that_is_not_an_input_shaping_error_still_refuses(self) -> None:+ """The round-trip wraps `Exception`: the explicit arm lets a raw pydantic error escape untyped."""+ gate = ShapingGate(registry={})++ gate.record(pipe_ref=CLEAN_PIPE, shape=EXPLICIT_SHAPE, error=ValueError("1 validation error for probe__Widget"))++ with pytest.raises(ValueError, match="no EXPECTED_UNSHAPEABLE entry"):+ gate.declared()++ def test_a_declared_entry_that_now_shapes_refuses_the_capture(self) -> None:+ """The lapse rule: a closed gap retires its declaration deliberately, or the capture stops."""+ gate = ShapingGate(registry={(DECLARED_PIPE, COMPACT_SHAPE): GAP_ITEM})++ gate.record(pipe_ref=DECLARED_PIPE, shape=COMPACT_SHAPE, error=None)++ with pytest.raises(ValueError, match="now shape") as refusal:+ gate.declared()+ assert DECLARED_PIPE in str(refusal.value)++ def test_a_declared_entry_never_walked_at_all_refuses_the_capture(self) -> None:+ """Symmetric with the divergence record: a registry keyed on a pipe this capture never met.++ Worded apart from the lapse above, because the two call for opposite actions. A key that+ addresses nothing this run produced is a renamed pipe or a run over a subset of the bundles,+ and telling whoever hits it that the gap closed would have them delete a gap still open.+ """+ gate = ShapingGate(registry={(DECLARED_PIPE, COMPACT_SHAPE): GAP_ITEM})++ gate.record(pipe_ref=CLEAN_PIPE, shape=COMPACT_SHAPE, error=None)++ with pytest.raises(ValueError, match="never walked by this capture") as refusal:+ gate.declared()+ assert DECLARED_PIPE in str(refusal.value)+ # Never the retire instruction: the entry is not stale, its key is.+ assert "now shape" not in str(refusal.value)++ def test_a_declared_failure_is_stated_in_the_manifest_with_its_ledger_item(self) -> None:+ """Generation is never blocked by the known-open gap: it is declared, recorded and printed."""+ gate = ShapingGate(registry={(DECLARED_PIPE, COMPACT_SHAPE): GAP_ITEM})++ gate.record(pipe_ref=DECLARED_PIPE, shape=COMPACT_SHAPE, error=_shaping_error(variable_name="widget"))+ gate.record(pipe_ref=CLEAN_PIPE, shape=COMPACT_SHAPE, error=None)++ entries = gate.declared()++ assert len(entries) == 1+ entry = entries[0]+ assert entry.pipe_ref == DECLARED_PIPE+ assert entry.shape == COMPACT_SHAPE+ assert entry.error_type == "WrongScalarKindError"+ assert entry.ledger_item == GAP_ITEM++ def test_a_capture_where_every_template_shapes_declares_nothing(self) -> None:+ """The control, and the state this gate exists to reach: an empty registry and no failure."""+ gate = ShapingGate(registry={})++ gate.record(pipe_ref=CLEAN_PIPE, shape=COMPACT_SHAPE, error=None)+ gate.record(pipe_ref=CLEAN_PIPE, shape=EXPLICIT_SHAPE, error=None)++ assert gate.declared() == []++ def test_the_refusal_carries_the_error_message_the_manifest_deliberately_omits(self) -> None:+ """The message is wording that would churn committed bytes, so it stays out of the manifest.++ It is exactly what whoever hits the refusal needs, though, so the refusal itself carries it —+ which is also why the manifest can hold the contract-stable class name alone.+ """+ gate = ShapingGate(registry={})++ gate.record(pipe_ref=CLEAN_PIPE, shape=COMPACT_SHAPE, error=_shaping_error(variable_name="icon"))++ with pytest.raises(ValueError, match="no EXPECTED_UNSHAPEABLE entry") as refusal:+ gate.declared()+ assert "Input 'icon' declares concept" in str(refusal.value)++ def test_the_refusal_survives_the_console_that_prints_it(self) -> None:+ """The refusal is rendered through Rich, which reads a bracketed word as markup and drops it.++ Every other test here reads the exception object, where a swallowed shape is still present —+ so the suite stayed green while the printed diagnostic named a pipe twice and its shape never.+ This states the message at the surface a human actually reads it on.+ """+ gate = ShapingGate(registry={})++ gate.record(pipe_ref=CLEAN_PIPE, shape=COMPACT_SHAPE, error=_shaping_error(variable_name="icon"))+ gate.record(pipe_ref=CLEAN_PIPE, shape=EXPLICIT_SHAPE, error=_shaping_error(variable_name="icon"))++ with pytest.raises(ValueError, match="no EXPECTED_UNSHAPEABLE entry") as refusal:+ gate.declared()++ console = Console(file=StringIO(), width=200, no_color=True)+ console.print(f"[red]The corpus's own record is out of date:[/red]\n{refusal.value}")+ rendered = cast("StringIO", console.file).getvalue()++ # Both shapes reach the reader, so the two lines are told apart by the field that differs.+ assert COMPACT_SHAPE in rendered+ assert EXPLICIT_SHAPE in rendered++ def test_the_passing_count_is_kept_but_never_committed(self) -> None:+ """The corpus is almost entirely passing verdicts, so they are counted rather than listed."""+ gate = ShapingGate(registry={(DECLARED_PIPE, COMPACT_SHAPE): GAP_ITEM})++ gate.record(pipe_ref=DECLARED_PIPE, shape=COMPACT_SHAPE, error=_shaping_error(variable_name="widget"))+ gate.record(pipe_ref=CLEAN_PIPE, shape=COMPACT_SHAPE, error=None)+ gate.record(pipe_ref=CLEAN_PIPE, shape=EXPLICIT_SHAPE, error=None)++ assert gate.passing_count == 2diff --git a/wip/projection-roundtrip-gate/plan.md b/wip/projection-roundtrip-gate/plan.mdnew file mode 100644index 000000000..522dae28f--- /dev/null+++ b/wip/projection-roundtrip-gate/plan.md@@ -0,0 +1,76 @@+---+status: active+item: L-260830-216378+---++# Round-trip every projected template through the input shaper at corpus-generation time++The projection corpus generator (`pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py`) authors the fill-in templates the TypeScript and Python projections are pinned against, committed byte-identically in `mthds-js` and `mthds-python`. A template exists to be filled in and handed back to the runtime, so every slot it pins must survive `InputShaper.shape` — and the generator never checks that. Twice, corpus bytes pinned slots the runtime rejects outright (`WrongScalarKindError` on a bare date object, a bare string at a nested `TextContent` node), and both times a human review round caught it instead of the capture; the second time (L-260830-8695ba) the divergence gate actively absorbed the broken sites into a declared class and exited 0.++## The design decision: registry-gated, not report-only++The item's original note proposed a report-only verdict, because L-260830-191719 (a descriptor gap, not a projection error) makes `probe_single` unshapeable today and a hard refusal would block generation on a known-open defect. This plan refines that: the check follows the **declared-never-discovered** discipline the divergence record already has.++- An `EXPECTED_UNSHAPEABLE` registry maps `(pipe_ref, shape)` to the ledger item tracking the fix.+- A round-trip failure **not** in the registry fails the command, printing the pipe, shape and error. This is the mechanism that would have caught both prior escapes at generation time.+- A registry entry whose template **now shapes** also fails the command ("delete the entry, the gap closed"), so a fix retires its declaration deliberately — exactly the lapse rule `DivergenceCollector.declared()` applies.+- Generation is never blocked by the known-open gap: its entries are declared, recorded in the manifest, and printed.++Report-only would print a failure and still exit 0 with the broken bytes written; nothing forces anyone to read the output before committing them in two consumer repos. The registry keeps the item's stated goal (a stated fact, generation unblocked) while making the capture the thing that catches the next regression.++Measured ground truth (2026-08-31, `dev` at the projection-divergence-gate landing): over the three corpus bundles, the failing round-trips are exactly `input_semantics_probe.probe_single` and `input_semantics_probe.probe_markers`, each in **both** shapes, all four from the L-260830-191719 nested-list gap (`matrix` in `Widget`). Every other template shapes cleanly in both shapes — the file-ish mock-URL leaves and the fixed-count slots included. The check is offline: the shaper wraps URLs without fetching (`input_shaper.py`, file-ish arms) and the command already boots with `needs_inference=False`.++## Scope decisions++- **Both shapes round-trip, not just compact.** The item title says compact, but the explicit template is equally a runnable scaffold, it fails today for the same pipes, and the check is one extra call on a template already in memory. The registry key is `(pipe_ref, shape)`.+- **JSON form only.** Both serializations derive from the same in-memory template dict, so shaping the dict covers the values; TOML byte-fidelity is the consumer harnesses' concern.+- **The manifest records failures only, without the error message.** A new manifest field `unshapeable: [{pipe_ref, shape, error_type, ledger_item}]` — mirroring the divergence record, which lists departures, not conformances. The error **class name** is contract-stable (the error-identity snapshot discipline); the message is wording that would churn committed bytes across pydantic versions, so it goes to the console only. Passing verdicts are printed, not committed.+- **Catch broadly.** The round-trip wraps `Exception`, not `InputShapingError`: the explicit arm lets a raw pydantic `ValidationError` escape untyped today (filed as L-260831-1e1a71 — its fix will change the recorded `error_type` for the explicit entries, which the lapse-symmetric tests must not hardcode beyond the registry itself).++## Non-goals++- Fixing the descriptor gap that makes the registry non-empty — L-260830-191719. Its fix deletes the registry entries; the lapse rule forces that deletion.+- The projection's remaining unshapeable slot shapes (`native.Date[]`, class-backed date) — L-260830-8695ba. Landing this gate **first** is the point: that item's fix then proves itself against the round-trip instead of against a reviewer.+- Typing the explicit arm's escaped `ValidationError` — L-260831-1e1a71.+- Executing templates beyond shaping (no pipeline runs, no inference).++## Phase 1 — red tests++On `feature/Projection-roundtrip-gate` off `dev` (renew the claim on the branch). Tests first, failing:++- New `tests/unit/pipelex/cli/dev_cli/test_projection_shaping_gate.py`, in the style of `test_projection_divergence_gate.py` — the gate logic tested directly with an injected registry, no engine boot:+ - an undeclared failing `(pipe_ref, shape)` refuses the capture, naming the pipe, shape and error class;+ - a declared entry that now shapes refuses with the retire-it message;+ - a declared failing entry passes and yields the manifest record carrying its ledger item.+- Extend `tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py`:+ - the real corpus generates (the known gap is declared, so the command succeeds) and the manifest's `unshapeable` entries all cite L-260830-191719, cover both shapes, and name only pipes the registry declares;+ - the rerun byte-stability test still holds with the new manifest field.++## Phase 2 — implementation++All in `generate_projection_corpus_cmd.py` unless said otherwise:++- `EXPECTED_UNSHAPEABLE: dict[tuple[str, str], str]` beside `DIVERGENCE_ITEMS`, initially declaring `probe_single` and `probe_markers` in both shapes against `L-260830-191719`, with a comment stating the retire rule.+- `UnshapeableEntry` pydantic model (`pipe_ref`, `shape`, `error_type`, `ledger_item`), and `CorpusManifest.unshapeable: list[UnshapeableEntry]`.+- A small `ShapingGate` class (registry injected, module constant as the default) collecting one verdict per `(pipe_ref, shape)`; called from `_capture_pipe` with the already-projected template:+ `InputShaper.shape(template, concept_provider=get_concept_library(), input_specs=pipe.inputs, search_scope=pipe.domain_code)` — the same assembly as the entry-pipe run path in `pipeline_run_setup.py`. An empty descriptor's `{}` shapes trivially and is recorded as passing.+- After the walk, beside the unclassified-divergence check: raise on any undeclared failure and on any lapsed registry entry; otherwise emit the `unshapeable` manifest entries.+- Console output: one line per failing round-trip (error class + first message line), and a summary line for the passing count.++Gates: `make agent-check`, then `make agent-test` (new tests are unit-level and offline).++## Phase 3 — docs and changelog++- `docs/contribute/generate-projection-corpus.md`: a "The shaping round-trip" section — what is checked, the registry, the retire rule, and that the manifest states unshapeable templates as facts of the capture.+- `CHANGELOG.md` under `## [Unreleased]`: bold label + a few sentences.++**Checkpoint** — the pipelex half is complete and mergeable here. Open the PR against `dev` with `Closes L-260830-216378` in the body; the re-baseline below can hand off to another session.++## Phase 4 — re-baseline the committed corpus in the consumer repos++The only committed-bytes change is `inputs_template/manifest.json` gaining `unshapeable`. Regenerate with the documented bundle order and land the same bytes in `mthds-js/tests/fixtures/protocol/` and `mthds-python/tests/fixtures/protocol/`. Check each repo's manifest parser first — a strict model there must gain the field in the same change. If this session does not do it, file one ledger item per consumer repo linked to L-260830-216378 rather than leaving it implied.++## Interplay to keep in mind++- Land this before L-260830-8695ba's projection fixes: its new bundle slots then get verified by the gate at generation time.+- When L-260830-191719 closes, its fix must delete the registry entries and regenerate — the lapse rule fails the command until it does, which is the wanted loudness.