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.
fix: make the projection-corpus divergence gate see every engine/projection difference (#1170)
Louis Choquel4a8e9ad4957b
diff --git a/.claude/skills/bump-kajson/SKILL.md b/.claude/skills/bump-kajson/SKILL.mdnew file mode 100644index 000000000..64bb2fbb6--- /dev/null+++ b/.claude/skills/bump-kajson/SKILL.md@@ -0,0 +1,391 @@+---+name: bump-kajson+description: >+ Move this repo's exact `kajson` dependency pin to the latest release on PyPI+ (or a version you name), re-lock, adapt the engine to whatever the new release+ changed, retire any workaround the release makes unnecessary, run the checks,+ and write the CHANGELOG entry — stopping before the commit. Use whenever the+ user says "bump kajson", "update kajson", "upgrade kajson", "move to kajson+ 0.8.0", "get us on the latest kajson", "is our kajson pin stale", "what's the+ latest kajson", or asks to build against a newly published `kajson` release.+ Also use when a failure smells like a kajson version mismatch — a+ `KajsonDecoderError` or `UnijsonEncoderError` on a payload that used to+ round-trip, a `ClassRegistryNotFoundError` after an upstream change, a pyright+ `reportAttributeAccessIssue` on something under `kajson.`, or a `uv lock`+ reporting kajson unsatisfiable. This is the **`kajson` PyPI package** (the+ universal JSON encoder/decoder from the sibling `kajson` repo, which is the+ serialization layer this engine is built on) — not releasing kajson itself,+ which belongs in that repo, and not releasing pipelex, which is the `release`+ skill.+---++# Bump the `kajson` dependency++`kajson` is this engine's serialization layer: the universal encoder/decoder,+the `ClassRegistry` that resolves a payload's `__class__` back to a live type,+and the `KajsonManager` singleton that owns that registry for the process. It is+a repo we own, in the sibling `kajson/` checkout.++Two facts decide how this bump differs from bumping an ordinary dependency, and+they pull in opposite directions:++- **kajson's output is a wire format**, not just an API. What it encodes is what+ crosses the Temporal transport, what a working memory rehydrates from, and+ what `__kajson_class_source__` carries. A change to the *format* is a+ compatibility question between two processes, which a type checker cannot see+ and a single-process test suite will not fail on.+- **kajson does not reach this engine's public surface.** Nothing in+ `pipelex/**` re-exports a kajson symbol through an `__all__`, so an upstream+ rename is an internal adaptation here, not a breaking change to pipelex's API.+ (This is exactly where `bump-mthds` differs — verify rather than assume it, by+ grepping `__all__` for kajson symbols, since a future re-export would change+ the answer.)++The job is to land the new pin in a state a human can read and commit: pin+moved, lock regenerated, source adapted, workarounds retired, checks green,+changelog written, ledger squared. **Stop before committing** — the user stages+and commits.++## What the bump touches++| File | Why it moves |+|---|---|+| `pyproject.toml` | The pin itself, one line in `[project].dependencies` — `kajson==X.Y.Z` |+| `uv.lock` | Regenerated by `make li` |+| `pipelex/**` | Wherever the release renamed something this engine imports, **or made a local workaround unnecessary** |+| `tests/**` | Same, plus any test asserting on a serialized shape that moved |+| `CHANGELOG.md` | An entry under `## [Unreleased]` — always at least the pin line |+| `.badges/tests.json`, `.test_durations` | Only if the adaptation added, removed or renamed tests |++Do **not** touch `[project].version`. That is this package's own version and it+moves only at release time, via the `release` skill.++## The pin is exact, and this one has always been++The pin is `kajson==X.Y.Z`, not `>=`. Unlike the mthds pin — which was a floor+until recently — kajson has been pinned exactly since v0.1.5, and the changelog+recorded the reason at the time: to tolerate breaking changes from a dependency+we ourselves move quickly.++That reason still holds, and the wire format sharpens it. Two processes+exchanging a kajson payload must agree on the codec, and an installed-range+resolve is exactly how they end up not agreeing. **Never relax the `==` to `>=`+while bumping**, and never widen it to get a resolve unstuck.++**The standing policy is to move the pin to the latest release, every time**,+even when the release carries nothing this engine uses.++## The cascade is narrow — say so rather than hunting for it++`pipelex/` is the only repo in this workspace that names kajson in a+`pyproject.toml`. Everyone else — `pipelex-sdk-python`, every `pipelex-server`+member, every user install — receives kajson **transitively, through this exact+pin**. Confirm it rather than trusting this sentence, because a new direct+dependent would change the conclusion:++```bash+cd .. && grep -rn "kajson" --include="pyproject.toml" . | grep -v "^./kajson/" | grep -v "^./pipelex/"+```++Two consequences, and the first is the pleasant one:++- **No sibling repo has to move in step.** There is no second pin to make+ unsatisfiable, so unlike an mthds bump this one files no "bump your pin too"+ item — unless the grep above finds a new direct dependent.+- **But everyone still inherits it.** "pipelex now requires kajson X.Y.Z" *is*+ the user-visible change when the bump is otherwise uneventful, and a consumer+ that imports kajson directly (without depending on it) is now reading a+ different version's classes. Say so in the changelog.++## kajson is ours — so read the notes for what you can now delete++This is the habit that most distinguishes a kajson bump from a third-party one.+Because we file bugs into kajson and it fixes them, a release frequently+*retires* something in this repo rather than breaking it: a guard at a call+site, a defensive `try`, a locally declared dependency, a test asserting the old+broken behaviour.++Two examples from real releases, so the pattern is recognisable:++- **v0.7.0 declared `tzdata` as its own runtime dependency**, and its notes said+ outright that consumers who had added `tzdata` to work around the decode+ failure could drop it. This repo did.+- **v0.7.1 made `ClassRegistry.register_classes_dict({})` a no-op** instead of+ raising `IndexError`, and its notes said callers guarding the call site could+ drop the guard. Here the same fix removes a *latent* crash at the two+ unguarded seeding sites (`pipelex/runtime_bridge/primitives/rehydration.py`+ and the integration fixture that mirrors it) rather than freeing a guard.++So read each release's notes twice: once for "what must I adapt to", once for+"what can I now delete". The second pass is the one nobody remembers, and a+workaround that outlives its cause is the kind of code that confuses the next+reader for years.++## Workflow++### 1. Orient++Read the pin **from `pyproject.toml`**, not from the virtualenv:++```bash+grep -n '"kajson' pyproject.toml+.venv/bin/python -c "import importlib.metadata as m; print(m.version('kajson'))"+```++Under an exact pin these two must agree in both directions. Any disagreement+means the venv is stale — someone edited `pyproject.toml` without re-running+`make li`, or installed over it. Re-sync with `make li` before you measure+anything against the venv.++Check `git status` and note what was already dirty **before** you start.+Concurrent work in this worktree is normal, and at the end you must separate+your changes from theirs and never stage something that isn't yours.++Then ask the ledger, in both directions — this is a two-way relationship with a+repo we control:++```bash+ledger list --owner kajson --status open+ledger list --origin kajson --status open+```++The first is **what we asked kajson for**: an open item here whose fix ships in+the release you are adopting closes on this bump, with the bump as its evidence.+The second is what kajson filed at us. Claim (`ledger claim <id>`) anything you+are about to work.++### 2. Resolve the target version++If the user named a version, use it. Otherwise ask PyPI:++```bash+curl -s https://pypi.org/pypi/kajson/json \+ | python3 -c "import json,sys; print(json.load(sys.stdin)['info']['version'])"+```++`info.version` is the latest non-prerelease, which is what "latest" means for a+pin other people inherit exactly.++**Ask PyPI, never the sibling checkout.** `kajson/pyproject.toml` is a working+tree and can be ahead of what is published — a version sitting there under+`## [Unreleased]` is not installable, and a pin naming it makes `uv lock` fail.+If the sibling is ahead, that is worth mentioning in your report (it previews+the next bump) but it does not change the target.++If the resolved version equals the current pin, say so and stop: manufacturing+lock churn is worse than reporting "already current". If the venv disagrees,+mention it — `make li` is the fix there.++### 3. Digest the upstream changes — *before* editing anything++```bash+.venv/bin/python .claude/skills/bump-kajson/scripts/upstream_notes.py <old> <new>+```++The helper reads `../kajson/CHANGELOG.md` and prints the released sections+strictly after the old pin up to and including the new one. It skips+`## [Unreleased]`, which describes work that is *not* in the version you are+adopting. If the checkout predates the target release it says so; fall back to:++```bash+gh release view v<new> --repo Pipelex/kajson+```++kajson's changelog is unusually detailed about compatibility — read it for four+things specifically:++- **Wire-format changes**, and in which direction they are compatible. kajson's+ notes state this explicitly when it matters (v0.7.0's read "In a mixed-version+ fleet, upgrade consumers before producers"). See step 6.+- **Registry and singleton semantics** — `ClassRegistry`, `ClassRegistryAbstract`,+ `KajsonManager`, `MetaSingleton`. See step 5.+- **Workarounds this release retires**, per the section above.+- **Dependency changes of kajson's own** (it declared `tzdata` once already),+ since those arrive in this repo's lock without any edit here.++### 4. Move the pin++One line in `pyproject.toml`. Make it a substring edit — replace `==<old>` with+`==<new>` on that line, **keeping the `==`** — and leave every other character+alone. Use your editor rather than a shell one-liner: `sed -i` takes a separate+empty argument on macOS and an attached suffix on GNU/Linux, so no single+invocation is portable, and the `release` skill edits this same file the same+way. Confirm with `grep -n '"kajson' pyproject.toml`.++Then re-lock and install:++```bash+make li+```++That is `make lock` (`uv lock`) plus `make install` (`uv sync --all-extras`), so+it rewrites `uv.lock` *and* puts the new kajson in `.venv`.++**Do not reach for `make update`.** That is `uv lock --upgrade`, which moves+every dependency at once and turns a reviewable one-package bump into a diff+nobody can reason about. Moving the pin is enough to make plain `uv lock`+re-resolve kajson.++Verify the lock actually moved — a pin edit that didn't take is silent:++```bash+grep -A1 '^name = "kajson"' uv.lock+```++If `uv lock` reports the requirement unsatisfiable, the version is probably not+on PyPI yet; re-run step 2. If it genuinely isn't published, stop and tell the+user rather than inventing a git or path source — in uv a *source* outranks a+version specifier, so adding one quietly makes the pin decorative.++### 5. Adapt the source, and check the boot seam by hand++Run the type checker first — it is the fastest reader of an API break and costs+seconds where the suite costs minutes:++```bash+make pyright+```++Work from the step-3 notes and any ledger item, not from guesswork. Then look at+the one seam the type checker cannot judge: **`KajsonManager` is a+process-global singleton, and this engine's boot and teardown are built around+that fact.** `pipelex/runtime_boot.py` constructs it with the class registry and+tears it down explicitly, and the comments there warn that it is easy to get+backwards — because the singleton *silently discards* a fresh registry when one+already exists, a missed teardown poisons the next boot rather than raising.++So if the release touches singleton lifetime, `teardown`, or registry ownership,+re-read `runtime_boot.py`'s construction and teardown sites together and make+sure the invariant the comments describe still holds. The boot/teardown tests+(`tests/unit/pipelex/test_runtime_boot_teardown_resilience.py`,+`test_hub_lifecycle.py`, `test_class_registry_scoping.py`) are the ones that+would catch a regression here — run them early rather than at the end.++Adopt the new API where it moved; a bump whose failures were papered over is+worse than no bump.++### 6. Ask the wire-format question explicitly++The suite serializes and deserializes in one process, with one kajson. That+proves round-tripping and proves nothing about **two** processes on different+versions — which is the shape of a distributed run, where a payload encoded by+one pipelex is decoded by another.++If step 3 turned up any encode/decode change, answer both directions in your+report rather than leaving it implied:++- Can a payload produced by the **new** kajson be read by the **old** one?+ (Additive fields usually yes; a changed representation usually no.)+- Can a payload produced by the **old** kajson still be read by the new one?+ (kajson has been careful about this — its notes say when legacy payloads still+ decode — but confirm it from the notes rather than assuming.)++Where the answer is asymmetric, the upgrade has an *ordering* requirement, and+that belongs in the changelog in plain words. If nothing in the release touches+the format, say that in one sentence and move on.++### 7. Run the checks++```bash+make agent-check+make agent-test+```++`agent-check` includes `drift-check`, which reads the **git index**, not the+working tree — so `git add` your changes before you trust its verdict. If it+reports an open contract, resolve it with the `drift-review` skill rather than+acking it blind.++If the adaptation added, removed or renamed tests, two committed artifacts go+stale and neither is caught by a local aggregate:++```bash+make store-test-durations # .test_durations — keeps the CI shards balanced+make check-test-badge # .badges/tests.json — runs only in CI, so check it here+```++### 8. Write the changelog entry++Add to `CHANGELOG.md` under `## [Unreleased]`, creating that heading right after+`# Changelog` if it isn't there. Do not add a `## [vX.Y.Z]` heading yourself,+and do not bump `[project].version`.++Every bump gets at least the pin line, naming the release *by what it carries*:++```markdown+- **`kajson` version**: The pin moves to `kajson==X.Y.Z`, <the release that+ carries / the release fixing …>. Everyone downstream inherits that exact+ version.+```++Three things earn their own entry beyond the pin line, because a reader deciding+whether to upgrade cannot get them anywhere else:++- **A wire-format change**, with the compatibility direction from step 6.+- **A workaround this repo dropped**, with what it was working around — that is+ a real behaviour change here, even though the cause was upstream.+- **A fix that reaches users through this engine** (a payload that used to fail+ to decode, a crash that is now a no-op). Write it as the user experiences it,+ not as the upstream diff.++If the bump is genuinely uneventful, say so in one sentence and stop. Padding a+quiet bump with upstream detail that doesn't affect this repo makes the loud+ones harder to spot.++### 9. Square the ledger++- **Close what the release actually fixed.** An item we filed against kajson+ (`ledger list --owner kajson`) whose fix ships in this version closes here,+ with evidence: the version that carries it and the check that went green.+ `Closes <id>` goes in the PR body when the user opens one.+- **File anything the bump revealed**, in the right direction: a kajson defect+ is `ledger new --owner kajson …` naming the version and the reproducer; work+ this repo must do later is filed here. The `ledger` skill has the gesture.+- **Only file a cascade item if the step-3 grep found a new direct dependent.**+ Normally there is none.+- `ledger validate`, then `ledger commit`. Nothing else pushes the ledger.++### 10. Report and stop++Show the user:++- The pin move, old → new, and whether `uv.lock` actually followed.+- What the release **fixed for users of this engine**, and what it **let you+ delete** — the two things a kajson bump is most often actually about.+- The wire-format verdict from step 6, in both directions, or "format untouched".+- Every file you changed, separated from what was already dirty when you started.+- The check results, honestly — if `agent-test` failed, say so with the output+ rather than reporting a bump as done.+- Anything left for a human: an upstream change whose adaptation is a judgment+ call, or a version the sibling checkout has that PyPI doesn't yet.++Then stop. Do not commit, branch, or push unless the user asks. If they do,+**stage the files explicitly by path** — never `git add -A`. A working branch+here is `chore/<Topic>` (spelled out, from the closed prefix set) and PRs target+`dev`.++## Traps worth remembering++- **Nothing in this repo enforces the `==`.** No check fails if the pin is+ relaxed to `>=`; `pyproject.toml` is the only place the policy lives, so a+ widened pin ships silently.+- **The pin is not the lock.** Editing `pyproject.toml` without re-locking+ leaves `uv.lock` on the old version — which is what the venv and the suite+ actually use, giving a green run against the version you meant to leave+ behind. That is why step 4 verifies the lock moved.+- **The suite cannot see a wire-format break.** One process, one kajson: it+ round-trips against itself and passes. Step 6 is the only thing standing+ between a format change and a cross-version decode failure.+- **`KajsonManager` fails silently, not loudly.** It is a singleton that+ discards a fresh registry rather than complaining, so a lifetime regression+ shows up as a *later* boot behaving oddly, far from the change.+- **The sibling checkout can be ahead of PyPI.** Read `kajson`'s changelog for+ understanding, PyPI for the target version.+- **`## [Unreleased]` upstream is not in the version you adopted.** Never quote+ it as part of the release; the helper script skips it for you.+- **`make update` is not `make li`.** The former upgrades the whole tree.+- **`drift-check` reads the git index.** Unstaged changes give a false green.+- **`check-test-badge` runs in no local aggregate.** Green here, red in CI, on+ any commit that changes the test count.+- **`[project].version` is pipelex's own version.** Bumping it is the `release`+ skill's job, not this one's.diff --git a/.claude/skills/bump-kajson/scripts/upstream_notes.py b/.claude/skills/bump-kajson/scripts/upstream_notes.pynew file mode 100755index 000000000..1bb8ce182--- /dev/null+++ b/.claude/skills/bump-kajson/scripts/upstream_notes.py@@ -0,0 +1,132 @@+#!/usr/bin/env python3+"""Extract `kajson` release notes for the versions a bump crosses.++Reads the sibling `kajson` checkout's CHANGELOG.md and prints every+released section strictly after ``old_version`` up to and including+``new_version``.++Three boundaries this exists to get right:++- ``## [Unreleased]`` is never printed. It describes work that is *not* in the+ version being pinned, so quoting it in this repo's changelog is a plain+ factual error about what the upgrade contains. kajson is a repo we own and+ work in, so its checkout can hold an unreleased section describing changes+ nobody can install yet.+- The old pin's own section is excluded (it was already in effect) while the+ new one's is included.+- A checkout that predates the target release cannot answer, and says so instead+ of printing a plausible-looking short range.++Exits non-zero with an explanation when the checkout cannot answer. Fall back to+``gh release view v<new> --repo Pipelex/kajson`` in that case.+"""++from __future__ import annotations++import argparse+import re+import sys+from pathlib import Path++from packaging.version import InvalidVersion, Version++# .../pipelex/.claude/skills/bump-kajson/scripts/upstream_notes.py+# parents[4] is the pipelex repo root; its parent is the workspace root.+DEFAULT_CHANGELOG = Path(__file__).resolve().parents[4].parent / "kajson" / "CHANGELOG.md"+HEADING = re.compile(r"^## \[v?(?P<version>\d+\.\d+\.\d+[^\]]*)\]")+UNRELEASED = re.compile(r"^## \[Unreleased\]", re.IGNORECASE)+FALLBACK = "gh release view v{version} --repo Pipelex/kajson"+++def parse_version(raw: str) -> Version:+ """Parse a version string into a PEP 440 version.++ Ordering has to hold among prereleases as well as between a prerelease and+ the release it leads to, and equality here is normalization-aware, so a+ section is matched by the version it denotes rather than by how it was+ spelled in the heading.+ """+ try:+ return Version(raw.strip())+ except InvalidVersion as exc:+ msg = f"Not a version this script can compare: {raw!r}"+ raise SystemExit(msg) from exc+++def split_sections(text: str) -> list[tuple[str, str]]:+ """Return [(version, body)] for released sections, in file order."""+ sections: list[tuple[str, str]] = []+ current_version: str | None = None+ buffer: list[str] = []++ for line in text.splitlines():+ if UNRELEASED.match(line):+ if current_version is not None:+ sections.append((current_version, "\n".join(buffer).strip()))+ current_version, buffer = None, []+ continue+ match = HEADING.match(line)+ if match:+ if current_version is not None:+ sections.append((current_version, "\n".join(buffer).strip()))+ current_version, buffer = match.group("version"), [line]+ continue+ if current_version is not None:+ buffer.append(line)++ if current_version is not None:+ sections.append((current_version, "\n".join(buffer).strip()))+ return sections+++def main() -> int:+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ parser.add_argument("old_version", help="the version currently pinned, excluded from the output")+ parser.add_argument("new_version", help="the version being adopted, included in the output")+ parser.add_argument(+ "--changelog",+ type=Path,+ default=DEFAULT_CHANGELOG,+ help=f"path to kajson's CHANGELOG.md (default: {DEFAULT_CHANGELOG})",+ )+ args = parser.parse_args()++ if not args.changelog.is_file():+ print(+ f"No kajson changelog at {args.changelog}.\nFall back to: {FALLBACK.format(version=args.new_version)}",+ file=sys.stderr,+ )+ return 2++ low = parse_version(args.old_version)+ high = parse_version(args.new_version)+ if low >= high:+ print(f"{args.new_version} is not newer than {args.old_version} -- nothing to digest.", file=sys.stderr)+ return 2++ sections = split_sections(args.changelog.read_text(encoding="utf-8"))+ known = {parse_version(version) for version, _ in sections}+ if high not in known:+ print(+ f"The checkout at {args.changelog} has no section for {args.new_version} -- it likely predates that release.\n"+ f"Fall back to: {FALLBACK.format(version=args.new_version)}",+ file=sys.stderr,+ )+ return 3++ wanted = [(version, body) for version, body in sections if low < parse_version(version) <= high]+ if not wanted:+ print(f"No released sections between {args.old_version} (exclusive) and {args.new_version}.", file=sys.stderr)+ return 3++ print("\n\n".join(body for _, body in wanted))+ if low not in known:+ print(+ f"\nNote: no section for the old pin {args.old_version} in this checkout, so the range may start earlier than the true gap.",+ file=sys.stderr,+ )+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2f3756476..b0007aecc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -13,6 +13,7 @@### Fixed+- **The projection corpus's divergence gate sees every engine/projection difference**: `pipelex-dev generate-projection-corpus` states that every difference between the reference projection and the engine's own renderer lands in a declared class, and that an undeclared one fails the command — but the walk missed differences in one direction and absorbed regressions into existing classes in the other, so a projection defect could pass generation green and be committed into `mthds-js` and `mthds-python` as contract bytes. The dict walk iterated only the projected keys, so a field the projection stopped rendering was never compared at all; it is now recorded under an id deliberately absent from the declared reasons, which makes the record refuse rather than pass. The file-leaf arm returned on the expansion without ever comparing the URL both sides carry, where plain recursion would have handed a regressed placeholder to the url-named-text class that absorbs it; the shared keys are now compared strictly. And `fixed-count-honoured` fired on any list longer than the engine's single element, which cannot tell an honoured `Concept[N]` from a wrong count or from a variable `[]` slot wrongly duplicated; it now consults the slot's declared `item_count`, taken from the descriptor. Separately, a pipe declaring no inputs used to abort the whole capture — an empty input form is valid and the projection renders it as `{}`, but the engine's renderer refuses one — and is now captured from the projection alone, with no engine half and nothing compared. Re-measuring the same corpus produces bytes identical to the committed capture, with the same classes at the same counts. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).- **`--help` works again on every `method` subcommand**: `pipelex validate method`, `pipelex run method`, the three `pipelex build ... method` commands and their agent-CLI twins all crashed with a rich `MarkupError` traceback instead of printing their help. The method-address example in each command's `NAME` argument help — `github.com/owner/repo[/name][@tag]` — reaches rich's markup parser through typer, which read `[/name]` as a closing tag with no opening one. The brackets are escaped at each of the sites, so the example renders as written and the help exits zero.- **Class-backed concepts reflect field by field in the input-form descriptor**: a concept declaring `structure = "SomeClass"` used to collapse to `kind: "unknown"` the moment one field annotation could not be mapped, taking every sibling field with it — and a nested non-native pydantic model was reported as an opaque payload rather than walked into. Every `document` and `image` position beneath such a concept disappeared from the descriptor, so a consumer preparing inputs from it passed a local file path at one of those positions through un-uploaded and the run failed on the unresolved path. Reflection is now partial: each annotation is mapped on its own, an unmappable one is `unknown` at that field alone, a nested model is an `object` the reflection walks into, a `list[X]` reports its element node, and a class that holds itself is cut at the revisit instead of recursing. A `RootModel` is reported as its root annotation's node wherever it appears — as a field of a reflected class, and as the registered class backing the concept itself — because the value it accepts is the root value, so the descriptor no longer states an object over a synthetic `root` key that contradicts the `json_schema` derived beside it. The native consistency probe keeps its faithful-or-absent rule — it is compared against a normative pinned blueprint, where a plausible-looking partial answer would be the failure — and the two reflections now share one annotation vocabulary (`pipelex/core/concepts/annotation_shapes.py`) instead of one calling the other. See [Input-Form Descriptor](under-the-hood/input-form-descriptor.md).- **Generated-image storage key extension follows the actual mime type**: a generated image could be stored under a `.png` key while its bytes and reported `mime_type` were `image/jpeg`, because `GeneratedContentFactory` picked the key's extension from the *requested* image format while `mime_type` came from the provider's *actual* answer — and a provider may return a different format than requested. The factory now resolves the effective mime type once (provider-reported, then base64-extracted, then the requested format, then the `image/jpeg` default) and derives the storage-key extension from that same value, on every path (stored bytes and fetched remote content alike), so the key and the `mime_type` can no longer diverge and anything inferring a type from the extension sees the truth.diff --git a/docs/contribute/generate-projection-corpus.md b/docs/contribute/generate-projection-corpus.mdindex 1e1e4767e..480e19155 100644--- a/docs/contribute/generate-projection-corpus.md+++ b/docs/contribute/generate-projection-corpus.md@@ -21,6 +21,8 @@ Bundle order is part of the capture: it fixes the key order of every emitted map- `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.- `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.+## Where the expectation comes fromThe expected templates are not the engine's output. They come from the reference projection in `pipelex/cli/dev_cli/commands/projection_reference.py`, which walks the **descriptor** — the authored facts a method states — where the engine's renderer (`pipelex/pipe_machinery/rendering/input_renderer.py`) reflects the **runtime content classes**. That is the whole design: the shipped projections have only the descriptor, so the contract has to be authored from the descriptor too.@@ -41,6 +43,12 @@ The classes it declares today:Each is a `pipelex` defect filed in the workspace ledger, not a difference of taste; the manifest is what records that the corpus knowingly departs from the engine and why.+### What the gate can and cannot separate++The walk visits both sides' keys, so a field the projection *stopped* rendering is a difference like any other — it is recorded under an id with no entry in `DIVERGENCE_REASONS`, which makes the capture refuse rather than pass silently. Beyond that, each arm classifies on the two values' shapes plus one descriptor fact the shapes cannot supply: the declared `item_count` of a fixed-count slot. So `fixed-count-honoured` means the slot's declared count was met, not merely that the projection rendered more elements than the engine's one; a variable `[]` slot rendering two, or a `[2]` slot rendering four, is unclassified and fails the capture. Likewise the file-leaf arm compares the URL both sides carry instead of returning on the expansion alone.++What 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 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.@@ -49,4 +57,4 @@ Each is a `pipelex` defect filed in the workspace ledger, not a difference of taRerun 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, 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, `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.diff --git a/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py b/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.pyindex 11695a1e8..0e5ba9f50 100644--- a/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py+++ b/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py@@ -34,6 +34,8 @@ from pydantic import BaseModel, ConfigDict, Fieldfrom pipelex.base_exceptions import PipelexErrorfrom pipelex.cli.cli_factory import make_pipelex_for_clifrom pipelex.cli.dev_cli.commands.projection_reference import (+ ENVELOPE_CONTENT_KEY,+ keeps_envelope,project_concept_comments,project_inputs_template,)@@ -53,7 +55,7 @@ from pipelex.pipe_machinery.rendering.input_renderer import ()from pipelex.pipelex import Pipelexfrom pipelex.pipeline.exceptions import ValidateBundleError-from pipelex.pipeline.input_form import PipeInputFormDescriptor, build_input_form+from pipelex.pipeline.input_form import ListField, PipeInputFormDescriptor, build_input_formfrom pipelex.pipeline.pipe_io_contracts import build_pipe_io_contractsfrom pipelex.pipeline.validate_bundle import validate_bundlefrom pipelex.runtime_hub import get_console@@ -169,17 +171,55 @@ def _write_text(*, path: Path, content: str) -> None:path.write_text(content, encoding="utf-8")-class _DivergenceCollector:+class DivergenceCollector:"""Walks the engine's template beside the projection's and buckets every difference.Every difference must land in a declared class: an unclassified one means the projection changedin a way nobody wrote down, and the capture refuses rather than committing bytes no record explains.+ The walk meets *both* sides' keys — a field the projection stopped rendering is a difference as+ much as one it added — so nothing reaches the manifest by being skipped.++ **What the classification rests on, and where it stops.** Each arm reads the two values' shapes,+ plus the one descriptor fact shape cannot supply: the declared `item_count` of a fixed-count slot+ (`register_fixed_counts`). That is enough to keep a regression out of the two classes whose arms+ would otherwise swallow one whole — `file-leaf-not-expanded`, which used to return without ever+ comparing the URL both sides carry, and `fixed-count-honoured`, which used to fire on any list+ longer than the engine's one element. It is not enough to tell every *wrong* value at a site that+ already carries a class from the right one: a projection that invents a field still reads as+ `optional-field-included`, and a garbled placeholder at a url-named text field still reads as+ `text-named-url`. Separating those needs each node's kind and presence threaded through the whole+ walk, which is a redesign of the walk rather than a fix to it."""def __init__(self) -> None:self.counts: dict[str, int] = {}self.examples: dict[str, list[DivergenceExample]] = {}self.unclassified: list[str] = []+ self._fixed_counts: dict[tuple[str, ...], int] = {}++ def register_fixed_counts(self, *, pipe_ref: str, descriptor: PipeInputFormDescriptor) -> None:+ """Record where this pipe's descriptor declares a fixed element count, by the path the walk meets.++ The one descriptor fact the classification cannot do without: `fixed-count-honoured` has to+ separate a `Concept[N]` slot rendering its N elements from a projection rendering the wrong+ number, and the two are indistinguishable by value shape alone.++ Only a top-level slot can carry a count — `InputFormDeriver.derive_slot` is the sole site+ that passes `item_count`, and both nested `ListField` constructions leave it `None` — so the+ map holds one entry per fixed slot, at the exact path its list sits at in each shape. A+ nested list therefore matches nothing, which is the safe direction: a length mismatch there+ is unclassified rather than absorbed.+ """+ for field in descriptor.fields:+ if not isinstance(field, ListField) or field.item_count is None:+ continue+ # The explicit shape always wraps the slot; the compact shape unwraps unless the slot is+ # one the shaper cannot rebuild from a bare value, which keeps its envelope.+ self._fixed_counts[pipe_ref, EXPLICIT_SHAPE, field.name, ENVELOPE_CONTENT_KEY] = field.item_count+ if keeps_envelope(node=field):+ self._fixed_counts[pipe_ref, COMPACT_SHAPE, field.name, ENVELOPE_CONTENT_KEY] = field.item_count+ else:+ self._fixed_counts[pipe_ref, COMPACT_SHAPE, field.name] = field.item_countdef _record(self, *, divergence_id: str, path: list[str], engine: Any, expected: Any) -> None:self.counts[divergence_id] = self.counts.get(divergence_id, 0) + 1@@ -195,12 +235,16 @@ class _DivergenceCollector:))+ def _unclassify(self, *, path: list[str], engine: Any, projected: Any) -> None:+ """A difference no declared class explains — one of these fails the whole capture."""+ self.unclassified.append(f"{'.'.join(path)}: engine={engine!r} projected={projected!r}")+def compare(self, *, engine_value: Any, projected_value: Any, path: list[str]) -> None:"""Bucket every leaf difference between one engine value and its projected counterpart."""- # Handled before the dict/dict walk below, which iterates the *projected* keys and would- # therefore find nothing to say about an empty projection. Deliberately not declared in- # DIVERGENCE_REASONS: no bundle in the corpus reaches it today, so a capture that does must- # write the declaration rather than inherit one nobody reviewed.+ # Handled before the dict/dict walk below, which would report the same thing one key at a+ # time: a projection rendering nothing where the engine renders an object is one fact, not N.+ # Deliberately not declared in DIVERGENCE_REASONS: no bundle in the corpus reaches it today,+ # so a capture that does must write the declaration rather than inherit one nobody reviewed.if isinstance(engine_value, dict) and projected_value == {} and engine_value != {}:self._record(divergence_id="unknown-empty-object", path=path, engine=engine_value, expected=projected_value)return@@ -212,10 +256,28 @@ class _DivergenceCollector:and "url" in cast("dict[str, Any]", engine_value)):self._record(divergence_id="file-leaf-not-expanded", path=path, engine=engine_value, expected=projected_value)+ # The expansion is the declared difference; the URL both sides carry is not part of it,+ # and is compared strictly here rather than recursed into. Plain recursion would hand a+ # regressed placeholder to the `text-named-url` arm below, whose only test is that the+ # *engine* value is a mock URL — so the regression would be absorbed into a class that+ # then explains it away. Both sides derive the same URL today.+ for key in sorted(set(cast("dict[str, Any]", projected_value)) & set(cast("dict[str, Any]", engine_value))):+ engine_leaf = cast("dict[str, Any]", engine_value)[key]+ projected_leaf = cast("dict[str, Any]", projected_value)[key]+ if engine_leaf != projected_leaf:+ self._unclassify(path=[*path, key], engine=engine_leaf, projected=projected_leaf)returnif isinstance(engine_value, dict) and isinstance(projected_value, dict):engine_fields = cast("dict[str, Any]", engine_value)projected_fields = cast("dict[str, Any]", projected_value)+ # Walked before the projected keys, because the walk below iterates those and would+ # otherwise skip a field the projection stopped rendering entirely — a projection+ # regression that reached neither a class nor `unclassified`. Deliberately not declared+ # in DIVERGENCE_REASONS, like `unknown-empty-object` above: no bundle in the corpus+ # reaches it today, so a capture that does must write the declaration itself.+ for key in engine_fields:+ if key not in projected_fields:+ self._record(divergence_id="engine-only-field", path=[*path, key], engine=engine_fields[key], expected=None)for key in projected_fields:if key not in engine_fields:self._record(divergence_id="optional-field-included", path=[*path, key], engine=None, expected=projected_fields[key])@@ -225,8 +287,15 @@ class _DivergenceCollector:if isinstance(engine_value, list) and isinstance(projected_value, list):engine_items = cast("list[Any]", engine_value)projected_items = cast("list[Any]", projected_value)- if len(engine_items) == 1 and len(projected_items) > 1:- self._record(divergence_id="fixed-count-honoured", path=path, engine=engine_items, expected=projected_items)+ if len(engine_items) != len(projected_items):+ # `fixed-count-honoured` is the slot's *declared* count being met, which the lengths+ # alone cannot say: without the descriptor, a `[2]` slot rendering four elements and+ # a variable `[]` slot rendering two both read as "more than the engine's one".+ declared_count = self._fixed_counts.get(tuple(path))+ if len(engine_items) == 1 and declared_count is not None and len(projected_items) == declared_count:+ self._record(divergence_id="fixed-count-honoured", path=path, engine=engine_items, expected=projected_items)+ else:+ self._unclassify(path=path, engine=engine_items, projected=projected_items)for index in range(min(len(engine_items), len(projected_items))):self.compare(engine_value=engine_items[index], projected_value=projected_items[index], path=[*path, str(index)])return@@ -278,16 +347,23 @@ def _capture_pipe(pipe: PipeAbstract,descriptor: PipeInputFormDescriptor,output_dir: Path,- collector: _DivergenceCollector,+ collector: DivergenceCollector,) -> None:"""Write one pipe's four projected renderings, the engine's four, and bucket the differences."""templates_dir = output_dir / TEMPLATES_DIR_NAMEengine_dir = output_dir / ENGINE_DIR_NAME+ collector.register_fixed_counts(pipe_ref=pipe.pipe_ref, descriptor=descriptor)for explicit in (False, True):shape = EXPLICIT_SHAPE if explicit else COMPACT_SHAPEjson_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)+ 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+ # NoInputsRequiredError, so the projected half is the whole capture here and there is+ # nothing to compare it against.+ continue_write_text(path=engine_dir / f"{pipe.pipe_ref}.{shape}.json", content=render_inputs(pipe, explicit=explicit))_write_text(path=engine_dir / f"{pipe.pipe_ref}.{shape}.toml", content=render_inputs_toml(pipe, explicit=explicit))collector.compare(@@ -325,7 +401,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 = None- collector = _DivergenceCollector()+ collector = DivergenceCollector()try:result = await validate_bundle(mthds_contents=mthds_contents, mthds_sources=mthds_sources)validation_library_id = get_current_library_id_or_none()diff --git a/pipelex/cli/dev_cli/commands/projection_reference.py b/pipelex/cli/dev_cli/commands/projection_reference.pyindex 63329529f..da172e376 100644--- a/pipelex/cli/dev_cli/commands/projection_reference.py+++ b/pipelex/cli/dev_cli/commands/projection_reference.py@@ -44,6 +44,11 @@ MOCK_URL_PREFIX = "https://mock.invalid/"FILE_CONTENT_KEY = "url"TIME_FORMAT = "time"+# The two keys of the ceremonial envelope — the explicit shape's whole framing, and what a compact+# slot keeps when its value is not re-shapable from a bare one.+ENVELOPE_CONCEPT_KEY = "concept"+ENVELOPE_CONTENT_KEY = "content"+# The single wire key a native scalar's value sits inside. It is a fact about the *payload*, which# the descriptor deliberately does not carry — so the projection needs this table to build the# explicit `{concept, content}` envelope. It is the standard's to state, not the runtime's: the@@ -244,7 +249,7 @@ def _compact_slot(*, field: InputFormField) -> Any:template that no longer runs."""if keeps_envelope(node=field):- return {"concept": field.concept_ref, "content": _slot_content(node=field, name=field.name)}+ return {ENVELOPE_CONCEPT_KEY: field.concept_ref, ENVELOPE_CONTENT_KEY: _slot_content(node=field, name=field.name)}match field.kind:case FieldKind.LIST:item_value = _light_value(node=field.item, name=f"{field.name}_item")@@ -295,8 +300,8 @@ def project_inputs_template(*, descriptor: PipeInputFormDescriptor, explicit: bofor field in descriptor.fields:if explicit:template[field.name] = {- "concept": field.concept_ref,- "content": _slot_content(node=field, name=field.name),+ ENVELOPE_CONCEPT_KEY: field.concept_ref,+ ENVELOPE_CONTENT_KEY: _slot_content(node=field, name=field.name),}else:template[field.name] = _compact_slot(field=field)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 e973cac33..d412c0151 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@@ -10,6 +10,13 @@ that corpus trustworthy, and both are checked here against the corpus bundles th- **A rerun writes the same bytes.** The corpus is committed, so a capture that varied run to runwould show up as a diff nobody authored — and the enum placeholder is exactly where the engine'sown renderer varies.+- **A pipe with no inputs is captured from the projection alone.** An empty input form is a valid+ form, but the engine's own renderer refuses one, so the capture takes the projected half and skips+ the 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."""from __future__ import annotations@@ -35,6 +42,23 @@ CORPUS_BUNDLES = [Path("tests/data/input_semantics/scaffold_bundle.mthds"),]+# A pipe declaring no inputs at all, which no corpus bundle does: the descriptor is the empty form+# and the projection renders it as `{}`, while the engine's renderer raises NoInputsRequiredError.+NO_INPUT_BUNDLE = """domain = "no_input_probe"+description = "A throwaway bundle whose only pipe declares no inputs at all"+main_pipe = "no_input_pipe"++[pipe.no_input_pipe]+type = "PipeLLM"+description = "A pipe that takes no inputs, so its input form is the empty one"+output = "Text"+prompt = \"\"\"+Write a haiku about an empty form.+\"\"\"+"""++NO_INPUT_PIPE_REF = "no_input_probe.no_input_pipe"+def _corpus_files(*, corpus_dir: Path) -> dict[str, str]:"""Every committed file in the corpus, by path relative to its root — the engine's copies excluded."""@@ -86,3 +110,20 @@ class TestGenerateProjectionCorpus:await generate_projection_corpus(bundle_paths=CORPUS_BUNDLES, output_dir=second_dir)assert _corpus_files(corpus_dir=first_dir) == _corpus_files(corpus_dir=second_dir)++ async def test_a_pipe_with_no_inputs_is_captured_from_the_projection_alone(self, tmp_path: Path) -> None:+ """`PipeInputFormDescriptor` documents `{"fields": []}` as valid; only the engine refuses one."""+ bundle_path = tmp_path / "no_input_bundle.mthds"+ bundle_path.write_text(NO_INPUT_BUNDLE, encoding="utf-8")+ output_dir = tmp_path / "corpus"++ manifest = await generate_projection_corpus(bundle_paths=[*CORPUS_BUNDLES, bundle_path], output_dir=output_dir)++ assert NO_INPUT_PIPE_REF in manifest.pipes+ templates_dir = output_dir / TEMPLATES_DIR_NAME+ for shape in manifest.shapes:+ # The template is the empty object; its TOML rendering is the empty document, which is+ # the only way TOML has to say it.+ assert (templates_dir / f"{NO_INPUT_PIPE_REF}.{shape}.json").read_text(encoding="utf-8") == "{}"+ assert (templates_dir / f"{NO_INPUT_PIPE_REF}.{shape}.toml").read_text(encoding="utf-8") == ""+ assert not list((output_dir / ENGINE_DIR_NAME).glob(f"{NO_INPUT_PIPE_REF}.*"))diff --git a/tests/unit/pipelex/cli/dev_cli/test_projection_divergence_gate.py b/tests/unit/pipelex/cli/dev_cli/test_projection_divergence_gate.pynew file mode 100644index 000000000..ecf094385--- /dev/null+++ b/tests/unit/pipelex/cli/dev_cli/test_projection_divergence_gate.py@@ -0,0 +1,127 @@+"""The corpus generator's divergence gate sees every engine/projection difference.++The generator states one guarantee, in its module docstring and again in `DivergenceCollector`'s:+every difference between the reference projection and the engine's own renderer lands in a declared+class, and an undeclared one fails the command. Nothing in the committed corpus can check that — the+corpus is exactly the case where the projection is *right*. So each case here mutates one projected+value the way a real regression would, and states that the gate reports it rather than absorbing it+into a declared class that would then explain it away in `mthds-js` and `mthds-python` as contract+bytes. The controls beside them state the real divergences, which must keep their class.+"""++from __future__ import annotations++import pytest++from pipelex.cli.dev_cli.commands.generate_projection_corpus_cmd import (+ COMPACT_SHAPE,+ MOCK_URL_PREFIX,+ DivergenceCollector,+)+from pipelex.core.pipes.variable_multiplicity import PresenceMarker+from pipelex.pipeline.input_form import ListField, PipeInputFormDescriptor, TextItem+++def _list_slot_descriptor(*, name: str, item_count: int | None) -> PipeInputFormDescriptor:+ """A one-slot descriptor whose only field is a list, fixed-count (`[N]`) or variable (`[]`)."""+ return PipeInputFormDescriptor(+ fields=[+ ListField(+ name=name,+ required=True,+ presence=PresenceMarker.PLAIN,+ gating=item_count is not None,+ item=TextItem(required=True),+ item_count=item_count,+ )+ ]+ )+++class TestTheDivergenceGateSeesEveryDifference:+ def test_a_key_only_the_engine_renders_refuses_the_record(self) -> None:+ """A field the projection stopped rendering: the dict walk iterates the projected keys."""+ collector = DivergenceCollector()++ collector.compare(+ engine_value={"title": "title_value", "stamp": "stamp_value"},+ projected_value={"title": "title_value"},+ path=["probe.dossier", COMPACT_SHAPE],+ )++ assert collector.counts.get("engine-only-field") == 1+ # Undeclared on purpose: no bundle reaches it today, so a capture that does must write the+ # declaration rather than inherit one nobody reviewed.+ with pytest.raises(ValueError, match="Undeclared divergence class"):+ collector.declared()++ def test_a_regressed_file_leaf_url_is_not_absorbed_by_its_own_class(self) -> None:+ """The file-leaf arm returned without ever comparing the one key both sides carry."""+ collector = DivergenceCollector()++ collector.compare(+ engine_value={"url": f"{MOCK_URL_PREFIX}url", "width": 100, "mime_type": "image/png"},+ projected_value={"url": "WRONG"},+ path=["probe.probe_native_inputs", COMPACT_SHAPE, "icon"],+ )++ assert collector.counts.get("file-leaf-not-expanded") == 1+ # Nor re-absorbed one arm further down: plain recursion would hand the regressed placeholder+ # to `text-named-url`, whose only test is that the *engine* value is a mock URL.+ assert "text-named-url" not in collector.counts+ assert any("icon.url" in site for site in collector.unclassified), collector.unclassified++ def test_an_intact_file_leaf_stays_one_declared_divergence(self) -> None:+ """The control: the expansion is the declared difference, and it stands alone."""+ collector = DivergenceCollector()++ collector.compare(+ engine_value={"url": f"{MOCK_URL_PREFIX}url", "width": 100, "mime_type": "image/png"},+ projected_value={"url": f"{MOCK_URL_PREFIX}url"},+ path=["probe.probe_native_inputs", COMPACT_SHAPE, "icon"],+ )++ assert collector.counts == {"file-leaf-not-expanded": 1}+ assert not collector.unclassified++ def test_a_wrong_element_count_at_a_fixed_slot_is_not_absorbed(self) -> None:+ """`fixed-count-honoured` means the declared count, not merely more than one element."""+ collector = DivergenceCollector()+ collector.register_fixed_counts(pipe_ref="probe.probe_markers", descriptor=_list_slot_descriptor(name="two", item_count=2))++ collector.compare(+ engine_value=["gadget"],+ projected_value=["gadget", "gadget", "gadget", "gadget"],+ path=["probe.probe_markers", COMPACT_SHAPE, "two"],+ )++ assert "fixed-count-honoured" not in collector.counts+ assert collector.unclassified++ def test_a_duplicated_variable_list_is_not_misattributed(self) -> None:+ """A `Concept[]` slot declares no count, so a second element there is nobody's declared divergence."""+ collector = DivergenceCollector()+ collector.register_fixed_counts(pipe_ref="probe.probe_markers", descriptor=_list_slot_descriptor(name="many", item_count=None))++ collector.compare(+ engine_value=["widget"],+ projected_value=["widget", "widget"],+ path=["probe.probe_markers", COMPACT_SHAPE, "many"],+ )++ assert "fixed-count-honoured" not in collector.counts+ assert collector.unclassified++ def test_an_honoured_fixed_count_keeps_its_class(self) -> None:+ """The control: the engine emits one element whatever the count, and that is the declared difference."""+ collector = DivergenceCollector()+ collector.register_fixed_counts(pipe_ref="probe.probe_markers", descriptor=_list_slot_descriptor(name="two", item_count=2))++ collector.compare(+ engine_value=["gadget"],+ projected_value=["gadget", "gadget"],+ path=["probe.probe_markers", COMPACT_SHAPE, "two"],+ )++ assert collector.counts == {"fixed-count-honoured": 1}+ assert not collector.unclassifieddiff --git a/wip/projection-divergence-gate/plan.md b/wip/projection-divergence-gate/plan.mdnew file mode 100644index 000000000..f36fefecf--- /dev/null+++ b/wip/projection-divergence-gate/plan.md@@ -0,0 +1,62 @@+---+status: active+item: L-260830-2c75b3+---++# Make the projection-corpus divergence gate see every engine/projection difference++The corpus generator (`pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py`) promises that every difference between the reference projection and the engine's own renderer lands in a declared divergence class, and that an undeclared one fails the command. `_DivergenceCollector.compare` does not uphold that promise: engine-only keys are never walked at all, and the classification heuristics work by value shape alone, so a real projection regression is absorbed into an existing declared class and committed into `mthds-js` and `mthds-python` as contract bytes. A third, lesser defect in the same file: a pipe with no inputs crashes the whole capture, because the engine's renderer raises `NoInputsRequiredError` where the projection legitimately renders `{}`.++The ledger item carries the full evidence, including the fabricated-regression table showing which mutations the collector absorbs. Everything below was re-verified against the code on `dev` after the fix in pipelex#1168 merged.++## Non-goals++- Whether each compact template actually runs through `InputShaper` — that is L-260830-216378.+- The projection's own remaining unshapeable slots — L-260830-8695ba.+- Threading descriptor kind, presence and multiplicity through the entire walk. The item explicitly rejects that redesign; the fixes below stay local to the collector plus one precomputed lookup.++## Phase 0 — setup++Claim the item (`ledger claim L-260830-2c75b3`), branch `fix/Projection-divergence-gate` off `dev`.++## Phase 1 — red tests first++Extend `tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py` with collector-level tests in the shape of the item's mutation table, written before the fixes so each one is seen red:++- **Engine-only key.** A dict pair where the engine renders a key the projection lacks → `declared()` raises rather than the walk silently skipping.+- **File-leaf regression.** Engine `{"url": <mock>, "width": …}` against projected `{"url": "WRONG"}` → reported, not absorbed into `file-leaf-not-expanded` (nor re-absorbed into `text-named-url` by the leaf heuristics).+- **Fixed-count regressions.** At a slot declared `[2]`: projected renders the wrong number of elements → reported. At a variable `[]` slot: projected renders more than one element → reported, not misattributed to `fixed-count-honoured`. An honoured `[2]` (engine one element, projection two) → still classified `fixed-count-honoured`.+- **No-input pipe.** Generation over a throwaway bundle containing a no-input pipe succeeds: the projected fixtures are written, no engine files exist for that pipe, and the manifest still lists it.++## Phase 2 — the collector fixes++All in `generate_projection_corpus_cmd.py`.++1. **Engine-only keys.** In the dict/dict arm, walk `engine_fields` keys absent from `projected_fields` and record them under `engine-only-field` — deliberately *not* added to `DIVERGENCE_REASONS`, mirroring the existing `unknown-empty-object` pattern, so `declared()` refuses if it ever fires. Verified to fire at zero sites on the current corpus, so generation stays green today.+2. **`file-leaf-not-expanded` arm.** After recording the divergence, strict-compare the shared keys; any mismatch goes straight to `unclassified`, bypassing the leaf heuristics — plain recursion would hand a regressed URL placeholder to the `text-named-url` arm, which would absorb it. Safe today: both sides derive the same `https://mock.invalid/url` (engine via `concept_representation_generator.py`'s `https://mock.invalid/{field_name}`, projection via `MOCK_URL_PREFIX + FILE_CONTENT_KEY`).+3. **`fixed-count-honoured` gate.** Give the walk a lookup precomputed from the pipe's descriptor — normalized path → declared `item_count` — and classify `fixed-count-honoured` only when the engine renders one element and the projected length equals the declared count; any other length mismatch lands in `unclassified`. To settle at implementation: whether a nested authored list field can carry a fixed count (`pipelex/pipeline/input_form.py`, the nested `ListField` construction) — that decides whether the lookup is per-slot-name or a real path map with numeric index segments stripped.+4. **No-input pipe.** In `_capture_pipe`, when `descriptor.fields` is empty, write the projected templates and skip the engine renders and the compare. The projection is the contract and `PipeInputFormDescriptor` documents the empty form as valid; only the engine's `build_inputs_template` refuses it.++## Phase 3 — prove zero impact on the committed corpus++Regenerate over the corpus bundles (`tests/data/input_semantics/{hinted,probe,scaffold}_bundle.mthds`, in the order the corpus README records) into scratch and diff against the committed capture in `mthds-js/tests/fixtures/protocol/` and `mthds-python/tests/fixtures/protocol/`. Expected: byte-identical fixtures, same divergence classes and counts. Any moved count means the old gate was absorbing a live regression — stop and investigate rather than re-declare.++> **Checkpoint — reached.** The fixes are in, the mutation tests are green, and the corpus is proven byte-identical.++**The fixed-count lookup is an exact path map, not a per-slot-name one.** The open question resolved against nested counts: `item_count` is passed at exactly one site, `InputFormDeriver.derive_slot` (`pipelex/pipeline/input_form.py:209`), and both nested `ListField` constructions leave it at its `None` default — the reflected one at `input_form.py:492` and the structure-field `LIST` arm at `input_form.py:568`. So a nested authored list can never carry a fixed count, and the map holds one entry per fixed top-level slot at the exact path its list occupies in each shape: `(pipe_ref, "explicit", name, "content")` always, and `(pipe_ref, "compact", name)` unless `keeps_envelope` puts it under `content` there too. `register_fixed_counts` is a public method on the collector, called once per pipe from `_capture_pipe`. A nested list matches no entry, which is the safe direction: a length mismatch there is unclassified rather than absorbed.++Two smaller shapes the implementation settled. The collector lost its leading underscore — it is `DivergenceCollector` now, because the gate's guarantee is stated as unit tests against it and a tested unit is not private. And the envelope's two keys got one declaration, `ENVELOPE_CONCEPT_KEY` / `ENVELOPE_CONTENT_KEY` in `projection_reference.py`, since the path map and the projection must agree on where a wrapped slot's list sits.++**No divergence-count surprise.** Regenerating over the three corpus bundles produces bytes identical to the committed capture in both `mthds-js/tests/fixtures/protocol/` and `mthds-python/tests/fixtures/protocol/`, with the same five classes at the same counts (`optional-field-included` 163, `file-leaf-not-expanded` 6, `fixed-count-honoured` 4, `text-named-url` 4, `object-native-keeps-envelope` 1) and the engine renderings unchanged too. `engine-only-field` fires at zero sites, as the item predicted.++**Re-measuring the item's fabricated-regression table** through the fixed collector, against the real engine output: six of nine mutations are now caught (the item's baseline caught one of eight). Newly caught are the dropped required field — via the undeclared `engine-only-field`, which makes `declared()` refuse — the regressed file-leaf URL, a structured slot collapsing to a lone wrong `url` key, a `[2]` slot rendering four elements, and a variable `[]` slot rendering two.++**Three shapes remain absorbed, and all three are the redesign this item rejects.** A projection inventing a field still reads as `optional-field-included`; a garbled placeholder at a url-named text field still reads as `text-named-url`; a structure collapsing to a bare scalar still reads as `object-native-keeps-envelope`. Each is a *wrong value at a site that already carries a class*, which shape alone cannot separate from the right one — telling them apart needs each node's kind and presence carried through the whole walk. The limit is written down where a reader meets it: `DivergenceCollector`'s docstring and the "What the gate can and cannot separate" section of `docs/contribute/generate-projection-corpus.md`. Deliberately not filed as a ledger item — the parent item names that redesign as out of scope, and the two shipped projections are pinned against the committed bytes regardless.++## Phase 4 — wrap++- `make agent-check`, `make agent-test`.+- Update the module and `_DivergenceCollector` docstrings only if the guarantee's wording needs it — the point of the fix is that the stated guarantee becomes true as written.+- Touch `docs/contribute/generate-projection-corpus.md` if it describes the gate.+- Changelog under `[Unreleased]`.+- PR to `dev` with `Closes L-260830-2c75b3` in the body.