Skip to content

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.md
new file mode 100644
index 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.py
new file mode 100755
index 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.md
index 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.md
index 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 from
The 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 ta
Rerun 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.py
index 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, Field
from pipelex.base_exceptions import PipelexError
from pipelex.cli.cli_factory import make_pipelex_for_cli
from 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 Pipelex
from 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_form
from pipelex.pipeline.pipe_io_contracts import build_pipe_io_contracts
from pipelex.pipeline.validate_bundle import validate_bundle
from 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 changed
in 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_count
def _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)
return
if 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_NAME
engine_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_SHAPE
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)
+ 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: Pa
prev_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.py
index 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: bo
for 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.py
index 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 run
would show up as a diff nobody authored — and the enum placeholder is exactly where the engine's
own 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.py
new file mode 100644
index 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.unclassified
diff --git a/wip/projection-divergence-gate/plan.md b/wip/projection-divergence-gate/plan.md
new file mode 100644
index 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.